Roteamento

Router escolhe um checkpoint para cada solicitação e carrega seu Agent quando a predição precisa dele. O roteador padrão envia o texto em inglês para o checkpoint em inglês e os demais idiomas suportados para o checkpoint multilíngue. Você pode sobrescrever essa escolha, fornecer sua própria dica de idioma ou selecionar explicitamente o checkpoint typed-decisions.

Este guia trata da seleção de modelo e do ciclo de vida. Para os tipos de pergunta aceitos pela predição, veja Decisões orientadas por esquema; para callbacks de ciclo de vida, veja 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 baixa checkpoints por padrão. predict() roteia a solicitação e depois carrega o checkpoint escolhido no primeiro uso. Por isso a primeira predição pode demorar mais enquanto os arquivos são baixados e o modelo é inicializado; as predições seguintes reutilizam o agente carregado.

Como um checkpoint é selecionado

Router.route(state, questions, ...) retorna 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 detecção de idioma quando a detecção integrada foi usada.

O roteamento verifica as entradas nesta ordem:

model= seleciona um checkpoint diretamente.
task= seleciona um checkpoint para a tarefa nomeada.
Se auto_task_detection=True, uma correspondência exata com um dos conjuntos de ID de pergunta typed-decisions conhecidos seleciona typed-decisions.
Um valor lang= reconhecido seleciona inglês ou multilíngue.
Um lang_guess= por chamada ou o lang_guess configurado do roteador é consultado.
Uma análise integrada de escrita e idioma seleciona um checkpoint. Se não houver sinal de idioma confiável, o roteador usa seu default configurado (inglês por padrão).

A primeira regra que corresponde vence. Por exemplo, model="multilingual" sobrescreve lang="en". Nomes de modelo inválidos lançam ValueError em vez de recair na detecçã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, então 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 roteamento por idioma

Use lang= quando a aplicação já conhece o idioma da solicitação. Etiquetas de idioma como "en", "en-US" e "en_US.UTF-8" são aceitas. O inglês roteia para english; outros códigos de idioma reconhecidos roteiam para multilingual.

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

Se a aplicação tem seu próprio detector de idioma, passe o resultado dele como código de idioma com lang_guess=. Um callable recebe o estado e pode retornar 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 roteamento continua para a próxima regra. Isso cobre 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 detector retorna quando não tem nada a dizer, então uma abstenção não pode fixar silenciosamente as solicitações no 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 roteia para o checkpoint multilíngue. Assim, um detector que retorna um código inválido em vez de None de fato escolhe um checkpoint, e se isso importa, mapeie seu caso desconhecido para None antes de repassá-lo.

A detecção integrada é uma heurística leve de escrita e idioma, não um modelo de identificação de idioma de propósito geral. Ela analisa valores de string em estados do tipo text, dict e list; as chaves de dicionário são ignoradas porque muitas vezes são nomes de campo em inglês. Texto curto ou ambíguo pode usar o checkpoint padrão. 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 padrão. Selecione-o explicitamente:

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

Como alternativa, defina auto_task_detection=True. O roteador então verifica se os ID de pergunta correspondem exatamente a um de seus fluxos de trabalho typed-decision conhecidos. Ele 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 roteamento sem carregar modelos

Use route() para inspecionar uma única decisão ou route_batch() para inspecionar uma sequência. Nenhum dos dois métodos carrega checkpoints, então ambos são úteis para depurar regras de roteamento 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 sobrescritas de roteamento opcionais (model, task, lang e lang_guess) são especificadas por item. As decisões permanecem na ordem de entrada.

Carregamento e memória

Por padrão, o roteador carrega um checkpoint na primeira vez que ele é necessário e mantém no máximo dois agentes residentes. O roteamento automático por idioma normalmente precisa apenas dos checkpoints em inglês e multilíngue. Se as solicitações também puderem selecionar typed-decisions, um max_loaded pequeno pode expulsar outro agente e fazer com que ele 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 solicitado. Para controlar uma carga de trabalho de três checkpoints sem pré-carregar, defina max_loaded=3. Use unload() para liberar um agente ou router.unload() para liberar todos. Um roteador usado como gerenciador de contexto descarrega seus agentes quando o bloco termina:

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

Você também pode passar device="cpu", device="cuda" ou outro dispositivo PyTorch suportado ao construir o roteador. A disponibilidade e a memória determinam quais dispositivos podem executar um determinado modelo.

Lotes mistos

predict_batch() aceita solicitações com estados, modelos, idiomas e esquemas de pergunta diferentes. O roteador primeiro toma uma decisão para cada solicitação, 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 solicitação requer state e questions; ela também pode incluir model, task, lang ou lang_guess. Solicitações que compartilham um checkpoint e um esquema de pergunta podem compartilhar uma passada 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 ainda correspondem à ordem das solicitações.

Escolher um ponto de entrada

Use route() ou route_batch() quando precisar inspecionar decisões sem carregar modelos.
Use predict() para uma única solicitação e predict_batch() para várias solicitações possivelmente heterogêneas.
Use Agent diretamente quando a aplicação já escolheu e carregou um checkpoint e não precisa de roteamento automático.

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