Encaminhamento

Router escolhe um checkpoint para cada pedido e carrega o seu Agent quando a predição precisa dele. O encaminhador predefinido envia o texto em inglês para o checkpoint inglês e os restantes idiomas suportados para o checkpoint multilingue. Podes sobrescrever essa escolha, fornecer a tua própria dica de idioma ou selecionar explicitamente o checkpoint typed-decisions.

Este guia trata da seleção do modelo e do ciclo de vida. Para os tipos de pergunta aceites pela predição, consulta Decisões a partir do esquema; para callbacks de ciclo de vida, consulta Hooks de predição.

Início rápido

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"])

Criar Router() não descarrega checkpoints por predefinição. predict() encaminha o pedido e depois carrega o checkpoint escolhido no primeiro uso. Por isso a primeira predição pode demorar mais enquanto os ficheiros são descarregados e o modelo é inicializado; as predições seguintes reutilizam o agente carregado.

Como um checkpoint é selecionado

Router.route(state, questions, ...) devolve um RouteDecision sem carregar um checkpoint nem executar inferência. A decisão contém o modelo escolhido, um motivo legível por humanos e detalhes de deteção de idioma quando a deteção integrada foi usada.

O encaminhamento verifica as entradas nesta ordem:

1. model= seleciona um checkpoint diretamente.
2. task= seleciona um checkpoint para a tarefa nomeada.
3. Se auto_task_detection=True, uma correspondência exata com um dos conjuntos de ID de pergunta typed-decisions conhecidos seleciona typed-decisions.
4. Um valor lang= reconhecido seleciona inglês ou multilingue.
5. Um lang_guess= por chamada ou o lang_guess configurado do encaminhador é consultado.
6. Uma análise integrada de escrita e idioma seleciona um checkpoint. Se não houver sinal de idioma fiável, o encaminhador usa o seu default configurado (inglês por predefinição).

A primeira regra que corresponde vence. Por exemplo, model="multilingual" sobrepõe-se a lang="en". Nomes de modelo inválidos levantam ValueError em vez de recaírem na deteção.

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 é compatível com dict, por isso os seus campos também estão disponíveis com chaves como decision["model"] e decision["reason"]. Router.predict() inclui a mesma decisão sob a chave "routing" do resultado.

Sobrescrever o encaminhamento por idioma

Utiliza lang= quando a aplicação já conhece o idioma do pedido. Etiquetas de idioma como "en", "en-US" e "en_US.UTF-8" são aceites. O inglês encaminha para english; outros códigos de idioma reconhecidos encaminham para multilingual.

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

Se a aplicação tem o seu próprio detetor de idioma, passa o resultado dele como código de idioma com lang_guess=. Um callable recebe o estado e pode devolver um código ou None para se abster:

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)

Uma dica que se abstém não força um checkpoint; o encaminhamento continua para a regra seguinte. Isto abrange None, uma string em branco e os códigos que não nomeiam idioma algum (C, POSIX, C.UTF-8, und, zxx, mul), que é o que um detetor devolve quando não tem nada a dizer, por isso uma abstenção não pode fixar silenciosamente os pedidos ao modelo errado.

Uma dica não reconhecida não é uma abstenção. Qualquer outro valor, incluindo "xx", False e 0, é lido como «não inglês» e encaminha para o checkpoint multilingue. Assim, um detetor que devolve um código inválido em vez de None escolhe de facto um checkpoint, e se isso importar, mapeia o seu caso desconhecido para None antes de o repassar.

A deteção integrada é uma heurística leve de escrita e idioma, não um modelo de identificação de idioma de uso geral. Analisa valores de string em estados do tipo text, dict e list; as chaves de dicionário são ignoradas porque são muitas vezes nomes de campo em inglês. Texto curto ou ambíguo pode usar o checkpoint predefinido. Para cargas de trabalho conhecidas, um idioma explícito ou uma dica fornecida pela aplicação é mais previsível.

Selecionar typed-decisions

O checkpoint typed-decisions não é selecionado automaticamente por predefinição. Seleciona-o explicitamente:

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

Em alternativa, define auto_task_detection=True. O encaminhador verifica então se os ID de pergunta correspondem exatamente a um dos seus fluxos de trabalho typed-decision conhecidos. Não infere a tarefa a partir do texto da pergunta, e adicionar ID de pergunta não relacionados impede uma correspondência exata.

router = Router(auto_task_detection=True)

Inspecionar o encaminhamento sem carregar modelos

Utiliza route() para inspecionar uma única decisão ou route_batch() para inspecionar uma sequência. Nenhum dos dois métodos carrega checkpoints, por isso ambos são úteis para depurar regras de encaminhamento antes de executar inferência.

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 item de route_batch() precisa de state e questions; as substituições de encaminhamento opcionais (model, task, lang e lang_guess) são especificadas por item. As decisões mantêm a ordem de entrada.

Carregamento e memória

Por predefinição, o encaminhador carrega um checkpoint na primeira vez que é necessário e mantém no máximo dois agentes residentes. O encaminhamento automático por idioma normalmente precisa apenas dos checkpoints inglês e multilingue. Se os pedidos também puderem selecionar typed-decisions, um max_loaded pequeno pode expulsar outro agente e fazer com que seja carregado de novo na próxima vez que for necessário.

# 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) pré-carrega todos os checkpoints configurados. O pré-carregamento eleva o limite de modelos residentes para acomodar o conjunto pedido. Para controlar uma carga de trabalho de três checkpoints sem pré-carregar, define max_loaded=3. Utiliza unload() para libertar um agente ou router.unload() para libertar todos. Um encaminhador usado como gestor de contexto descarrega os seus agentes quando o bloco termina:

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

Também podes passar device="cpu", device="cuda" ou outro dispositivo PyTorch suportado ao construir o encaminhador. A disponibilidade e a memória determinam que dispositivos podem executar um determinado modelo.

Lotes mistos

predict_batch() aceita pedidos com estados, modelos, idiomas e esquemas de pergunta diferentes. O encaminhador toma primeiro uma decisão para cada pedido, agrupa o trabalho por checkpoint e esquema de pergunta compatível, e depois restaura os resultados à ordem 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 pedido requer state e questions; também pode incluir model, task, lang ou lang_guess. Pedidos que partilham um checkpoint e um esquema de pergunta podem partilhar uma passagem direta de lote do Agent. Esquemas ou checkpoints diferentes são tratados em grupos separados. batch_size limita o número de estados passados juntos ao Agent; os resultados continuam a corresponder à ordem dos pedidos.

Escolher um ponto de entrada

• Utiliza route() ou route_batch() quando precisares de inspecionar decisões sem carregar modelos.
• Utiliza predict() para um único pedido e predict_batch() para vários pedidos possivelmente heterogéneos.
• Utiliza Agent diretamente quando a aplicação já escolheu e carregou um checkpoint e não precisa de encaminhamento automático.

Consulta a referência da API de Router para detalhes do construtor e dos métodos.