Enrutamiento

Router elige un checkpoint para cada solicitud y carga su Agent cuando la predicción lo necesita. El router predeterminado envía el texto en inglés al checkpoint en inglés y los demás idiomas admitidos al checkpoint multilingüe. Puedes sobrescribir esa elección, aportar tu propia pista de idioma o seleccionar explícitamente el checkpoint typed-decisions.

Esta guía trata de la selección de modelo y del ciclo de vida. Para los tipos de pregunta que acepta la predicción, consulta Decisiones basadas en el esquema; para los callbacks del ciclo de vida, consulta Hooks de predicción.

Primeros pasos

from laya import Router

router = Router()

questions = {
    "department": {
        "type": "choice",
        "instructions": "Which department should handle this request?",
        "criteria": {
            "billing": "invoices, payments, refunds",
            "technical": "bugs, outages, system errors",
            "other": "everything else",
        },
    }
}

result = router.predict("We were billed twice. Please refund the duplicate charge.", questions)
print(result["answers"]["department"]["choice"])
print(result["routing"]["model"])

Crear Router() no descarga checkpoints de forma predeterminada. predict() enruta la solicitud y luego carga el checkpoint elegido en el primer uso. Por eso la primera predicción puede tardar más mientras se descargan los archivos y se inicializa el modelo; las predicciones posteriores reutilizan el agente ya cargado.

Cómo se elige un checkpoint

Router.route(state, questions, ...) devuelve un RouteDecision sin cargar un checkpoint ni ejecutar inferencia. La decisión contiene el modelo elegido, un motivo legible por humanos y detalles de detección de idioma cuando se usó la detección integrada.

El enrutamiento revisa las entradas en este orden:

model= elige un checkpoint directamente.
task= elige un checkpoint para la tarea indicada.
Si auto_task_detection=True, una coincidencia exacta con uno de los conjuntos de ID de pregunta typed-decisions conocidos elige typed-decisions.
Un valor lang= reconocido elige inglés o multilingüe.
Se consulta un lang_guess= por llamada o el lang_guess configurado del router.
Un análisis integrado de escritura e idioma elige un checkpoint. Si no hay una señal de idioma fiable, el router usa su default configurado (inglés de forma predeterminada).

Gana la primera regla que coincide. Por ejemplo, model="multilingual" anula lang="en". Los nombres de modelo no válidos lanzan ValueError en lugar de recaer en la detección.

decision = router.route(
    "La aplicación se cierra cada vez que abro la configuración.",
    questions,
)
print(decision.model)   # multilingual
print(decision.reason)  # why that checkpoint was selected

RouteDecision es compatible con dict, así que sus campos también están disponibles con claves como decision["model"] y decision["reason"]. Router.predict() incluye la misma decisión bajo la clave "routing" del resultado.

Sobrescribir el enrutamiento por idioma

Usa lang= cuando la aplicación ya conoce el idioma de la solicitud. Se aceptan etiquetas de idioma como "en", "en-US" y "en_US.UTF-8". El inglés enruta a english; otros códigos de idioma reconocidos enrutan a multilingual.

result = router.predict(state, questions, lang="de")
assert result["routing"]["model"] == "multilingual"

Si la aplicación tiene su propio detector de idioma, pasa su resultado como código de idioma con lang_guess=. Un invocable recibe el estado y puede devolver un código o None para abstenerse:

def detect_request_language(state):
    # Replace this with the application's detector.
    return "en" if "invoice" in str(state).lower() else None

router = Router(lang_guess=detect_request_language)

Una pista que se abstiene no fuerza un checkpoint; el enrutamiento continúa con la siguiente regla. Eso abarca None, una cadena en blanco y los códigos que no nombran ningún idioma (C, POSIX, C.UTF-8, und, zxx, mul), que es lo que devuelve un detector cuando no tiene nada que decir, así que una abstención no puede fijar en silencio las solicitudes al modelo equivocado.

Una pista no reconocida no es una abstención. Cualquier otro valor, incluidos "xx", False y 0, se lee como “no inglés” y enruta al checkpoint multilingüe. Así que un detector que devuelve un código inválido en lugar de None sí elige un checkpoint, y si eso importa, asigna su caso desconocido a None antes de pasarlo.

La detección integrada es una heurística ligera de escritura e idioma, no un modelo de identificación de idioma de propósito general. Analiza valores de cadena en estados de tipo text, dict y list; las claves de diccionario se ignoran porque a menudo son nombres de campo en inglés. El texto corto o ambiguo puede usar el checkpoint predeterminado. Para cargas de trabajo conocidas, un idioma explícito o una pista aportada por la aplicación es más predecible.

Seleccionar typed-decisions

El checkpoint typed-decisions no se selecciona automáticamente de forma predeterminada. Selecciónalo explícitamente:

result = router.predict(state, questions, model="typed-decisions")
# `task="typed_decisions"` is also accepted.

Como alternativa, establece auto_task_detection=True. El router comprueba entonces si los ID de pregunta coinciden exactamente con uno de sus flujos de trabajo typed-decision conocidos. No infiere la tarea a partir del enunciado de la pregunta, y añadir ID de pregunta no relacionados impide una coincidencia exacta.

router = Router(auto_task_detection=True)

Inspeccionar el enrutamiento sin cargar modelos

Usa route() para inspeccionar una sola decisión o route_batch() para inspeccionar una secuencia. Ninguno de los dos métodos carga checkpoints, así que ambos son útiles para depurar reglas de enrutamiento antes de ejecutar inferencia.

requests = [
    {"state": "Please refund the duplicate charge.", "questions": questions},
    {"state": "Necesito ayuda con mi factura.", "questions": questions},
]

decisions = router.route_batch(requests)
for decision in decisions:
    print(decision.model, decision.reason)

Cada elemento de route_batch() necesita state y questions; las anulaciones de enrutamiento opcionales (model, task, lang y lang_guess) se especifican por elemento. Las decisiones conservan el orden de entrada.

Carga y memoria

De forma predeterminada, el router carga un checkpoint la primera vez que se necesita y mantiene como máximo dos agentes residentes. El enrutamiento automático por idioma normalmente solo necesita los checkpoints en inglés y multilingüe. Si las solicitudes también pueden seleccionar typed-decisions, un max_loaded pequeño puede expulsar otro agente y hacer que se cargue de nuevo la próxima vez que se necesite.

# Load only the checkpoints this process serves, before accepting requests.
router = Router()
router.preload(["english", "multilingual"])

print(router.loaded)  # currently resident checkpoint names
router.unload("multilingual")

Router(preload=True) precarga todos los checkpoints configurados. La precarga eleva el límite de modelos residentes para ajustarse al conjunto solicitado. Para controlar una carga de trabajo de tres checkpoints sin precargar, establece max_loaded=3. Usa unload() para liberar un agente o router.unload() para liberarlos todos. Un router usado como gestor de contexto descarga sus agentes cuando sale del bloque:

with Router(preload=True) as router:
    result = router.predict(state, questions)

También puedes pasar device="cpu", device="cuda" u otro dispositivo PyTorch admitido al construir el router. La disponibilidad y la memoria determinan qué dispositivos pueden ejecutar un modelo dado.

Lotes mixtos

predict_batch() acepta solicitudes con estados, modelos, idiomas y esquemas de pregunta diferentes. El router primero toma una decisión para cada solicitud, agrupa el trabajo por checkpoint y esquema de pregunta compatible, y luego restaura los resultados al orden de entrada original.

requests = [
    {"state": "Please refund the duplicate charge.", "questions": questions},
    {"state": "Mi cuenta fue cobrada dos veces.", "questions": questions},
    {"state": "A third request", "questions": questions, "model": "typed-decisions"},
]

results = router.predict_batch(requests, batch_size=8)

Cada solicitud requiere state y questions; también puede incluir model, task, lang o lang_guess. Las solicitudes que comparten un checkpoint y un esquema de pregunta pueden compartir una pasada hacia adelante del lote del Agent. Los esquemas o checkpoints distintos se manejan en grupos separados. batch_size limita el número de estados que se pasan juntos al Agent; los resultados siguen correspondiendo al orden de las solicitudes.

Elegir un punto de entrada

Usa route() o route_batch() cuando necesites inspeccionar decisiones sin cargar modelos.
Usa predict() para una sola solicitud y predict_batch() para varias solicitudes posiblemente heterogéneas.
Usa Agent directamente cuando la aplicación ya haya elegido y cargado un checkpoint y no necesite enrutamiento automático.

Consulta la referencia de la API de Router para detalles del constructor y los métodos.