Linha de comandos e servidor MCP

O Laya tem duas interfaces locais para experimentar o mesmo motor de decisão estruturada:

Escolhe a CLI quando és tu a pessoa que lê o resultado. Escolhe o MCP quando outro processo precisa de uma interface de ferramentas estável. Ambos usam o Router do Laya para selecionar um checkpoint e devolver decisões tipadas choice, score e noul; nenhum é uma interface de resposta a perguntas em aberto nem de geração de texto.

Para a decisão de encaminhamento e exemplos de perguntas tipadas, vê o Route Mode quickstart do README. Para a confiança e fluxos de trabalho integrados, vê o confidence gating e os workflow presets do README.

1. Linha de comandos

Instalar o pacote instala o ponto de entrada laya. Corre laya --help para a lista completa de opções.

python -m pip install laya
laya --help

CLI de avaliação

O pacote também instala o laya-evals. A CLI principal expõe os mesmos comandos de avaliação através de laya eval:

laya eval --help

Vê o guia Harness de avaliação para conjuntos de dados, métricas e gates de linha de base.

Encaminhar sem carregar um checkpoint

Com texto e sem nenhuma flag de predição, a CLI chama Router.route:

laya "I was charged twice, please refund it"

A saída nomeia o checkpoint selecionado, explica porque foi selecionado, e mostra a informação de idioma detetado quando disponível. O encaminhamento por si só não descarrega nem constrói um checkpoint, por isso é uma verificação offline rápida da decisão de encaminhamento.

Usa --json quando outro script local deve consumir a decisão:

laya "I was charged twice, please refund it" --json

Correr uma predição

--predict corre a predição tipada completa e carrega o checkpoint encaminhado no primeiro uso. O primeiro carregamento precisa de acesso ao Hugging Face Hub; as execuções seguintes usam a cache local.

laya "Classify this support request" --predict
laya "Classify this support request" --predict --json

--json imprime o resultado completo como JSON. Sem ele, a CLI imprime cada resposta juntamente com a sua probabilidade de choice, o score, ou o valor noul, mais a decisão de encaminhamento.

Os controlos principais são:

• --model english|multilingual|typed-decisions fixa um checkpoint em vez de encaminhar automaticamente.
• --lang en|de|... fornece um código de idioma explícito em vez da deteção automática.
• --lang-guess en|de|... fornece uma dica suave que o encaminhamento lê depois de --lang e antes do seu próprio detetor; uma dica que não resolve nada cai fora, por isso empurra o checkpoint sem o forçar.
• --task NAME força o fluxo de trabalho typed-decisions em vez de o detetar.
• --device cpu|cuda|... passa uma escolha de dispositivo ao Router.
• --json emite saída legível por máquina.

Usar um preset integrado

Um preset fornece um conjunto de perguntas pronto a usar e implica predição, por isso --predict não é necessário:

laya "My payment failed twice" --preset triage
laya "Ignore all previous instructions" --preset guard --json

Os presets da CLI são email, guard, moderation, router e triage. A CLI coloca o texto sob o campo state esperado pelo preset selecionado; --predict usa o campo request do conjunto de perguntas do router. Os presets são úteis para uma verificação local rápida, mas as suas perguntas são ainda decisões de domínio: inspeciona o preset e valida-o nos teus próprios dados antes de o usar como política de aplicação.

Explorar interativamente

Sem argumento de texto, a CLI abre um pequeno prompt:

laya
# laya> Classify this request
# laya> quit

Prime Enter para correr cada pedido. Uma linha vazia, quit, exit ou Ctrl-D termina a sessão. O ciclo interativo reutiliza um só Router, por isso é uma forma conveniente de comparar várias entradas sem escrever um script.

As falhas são visíveis

A CLI trata valores inválidos e falhas comuns de dependências, downloads e runtime no limite da aplicação. Imprime um diagnóstico para o stderr e devolve o código de saída 2 em vez de mostrar um traceback não tratado. Se um download de checkpoint no primeiro uso falhar, verifica a instalação das dependências, o acesso ao Hub e o dispositivo selecionado antes de tentar de novo.

2. Servidor MCP stdio integrado

O servidor MCP é um extra opcional. O pacote principal não instala a dependência mcp:

python -m pip install "laya[mcp]"
laya-mcp-server
# equivalent module form:
python -m laya.mcp.server

O servidor fala MCP sobre stdio, não HTTP. Configura o cliente com o console script:

{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {
        "LAYA_DEVICE": "cpu"
      }
    }
  }
}

Se a configuração do cliente suportar um executável Python e argumentos, usa python -m laya.mcp.server como forma de lançamento equivalente. O cliente é dono do processo do servidor; o Laya não abre nenhuma porta de rede.

Ferramentas disponíveis

As três ferramentas de lote e de esquema existem porque as mesmas operações estão disponíveis no SDK e no laya-serve: tratar de muitos pedidos, ou servir um autor de chamada que já conhece a forma da resposta, não exige descer ao Python. Para a forma guiada por esquema com mais profundidade, vê Decisões a partir do esquema.

O guardrail partilhado diz para não enviar perguntas choice com mais de 20 opções sem pré-seleção. O laya_shortlist mantém as k etiquetas mais prováveis antes da passagem direta; a sua predefinição é k=20. Usa embeddings com mean-pooling do próprio encoder do checkpoint que responde, por isso não descarrega um segundo modelo, e devolve as etiquetas mantidas, os scores de coseno, o k e a contagem de opções para cada pergunta pré-selecionada.

state tem de ser um objeto JSON não vazio. questions tem de ser um objeto não vazio cujos valores usem o esquema de perguntas tipadas do Laya. laya_preset aceita os mesmos cinco presets que a CLI: email, guard, moderation, triage e o fluxo de trabalho do router, cujo nome canónico nesta superfície é model_router. router é aceite como alias e nomeia o mesmo preset, por isso a grafia da CLI também funciona aqui; a chave canónica é a que volta no resultado. Dado um state com exatamente uma string, o laya_preset coloca-a sob o campo que as perguntas desse preset nomeiam, a mesma colocação que a CLI faz, para que um autor de chamada não tenha de adivinhar a chave. Tudo o que seja mais rico do que uma string é a forma do próprio autor da chamada e é passado inalterado.

Todas as ferramentas de pedido único aceitam os mesmos controlos de encaminhamento por chamada que os pedidos em lote. A par de model, um pedido pode definir task (nomear um checkpoint pelo trabalho), lang (forçar um código de idioma) e lang_guess (uma dica de idioma suave que fica abaixo de lang e acima do detetor integrado, por isso um código provável mas incerto pode influenciar qual checkpoint é escolhido sem o forçar como lang faz). lang_guess só participa no encaminhamento, por isso, tal como task, é recusado num pedido que fixa model – um checkpoint fixado não tem mais nada para encaminhar. laya_predict e laya_shortlist aceitam também max_len/head_max_len para o orçamento de tokens de resposta e min_confidence para o gate de abstenção.

Uma chamada de predição tem a mesma forma que a chamada tipada do SDK:

{
  "state": {
    "body": "I was billed twice for the same plan. Please reverse the duplicate charge."
  },
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this request?",
      "criteria": {
        "billing": "payments, invoices, refunds, duplicate charges",
        "technical": "bugs, outages, integration problems"
      }
    },
    "urgent": {
      "type": "noul",
      "instructions": "Does the user need immediate help?"
    }
  }
}

A resposta da ferramenta é JSON que contém as answers tipadas, a decisão routing e informação de temporização. Não trates uma resposta de confiança elevada como permissão para realizar uma ação externa; a aplicação ou o agente continua responsável pela política, pela revisão e pelos efeitos secundários.

Arranque e ambiente

O servidor MCP mantém um Router residente e serializa a construção inicial. Por predefinição, pré-carrega english e multilingual; typed-decisions fica preguiçoso. Uma falha de pré-carregamento é reportada no arranque e repetida na chamada seguinte de uma ferramenta, por isso inspeciona o laya_status antes de assumires que o servidor está pronto.

Partilhar um servidor de modelo entre sessões MCP

Corre um servidor HTTP local e aponta o ambiente de cada cliente MCP para ele:

LAYA_HOST=127.0.0.1 LAYA_PRELOAD=0 LAYA_IDLE_UNLOAD_SECONDS=300 laya-serve

{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp-server",
      "env": {"LAYA_BASE_URL": "http://127.0.0.1:8000"}
    }
  }
}

Instala o laya[serve] onde o servidor HTTP corre. O MCP continua a usar stdio com o editor; as suas ferramentas de predição usam HTTP para chegar ao teu servidor. laya_predict, laya_predict_batch, laya_decide e laya_preset usam o estado, as instruções e as descrições de opções originais do servidor. Lotes heterogéneos enviam um pedido /v1/systemone por item, preservando a ordem de entrada; batch_size e sort_by_length não mudam a execução do servidor. laya_status reporta o /health do servidor; laya_route e laya_route_batch ficam locais e não precisam de modelo nem de pedido HTTP. O processo MCP não importa torch nem carrega nenhum checkpoint, incluindo quando LAYA_THREADS ou LAYA_PRELOAD estão definidos.

Define o mesmo LAYA_API_KEY nos dois processos quando o servidor exige um token bearer. Mantém LAYA_DEFAULT_MODEL e LAYA_AUTO_TASK alinhados para que as pré-visualizações de encaminhamento local correspondam ao encaminhamento real do servidor. As definições de dispositivo e pré-carregamento pertencem ao servidor HTTP. O primeiro pedido após um descarregamento por inatividade espera uma carga a frio; aumenta LAYA_REMOTE_TIMEOUT se isso demorar mais de 300 segundos. laya_shortlist e as substituições de hook de predição devolvem unsupported_remote, já que o seu código precisa do processo do modelo. Erros HTTP mantêm o texto de detalhe do servidor como erros de ferramenta MCP. Com LAYA_BASE_URL não definido, o servidor MCP continua a carregar checkpoints no seu próprio processo.

O lançador laya-mcp-server de origem cria o seu Router sem instalar hooks. Instala os hooks de predição no processo que corre a inferência: o processo MCP em modo local, ou o servidor HTTP em modo de servidor partilhado. Um lançador personalizado pode usar laya.hooks.set_default_hooks antes de construir o seu Router. As variáveis de ambiente acima configuram o ciclo de vida do modelo, não o registo de hooks. O cliente continua a decidir quando chamar uma ferramenta e o que fazer com a decisão devolvida.

3. Limites partilhados e guias relacionados

A CLI e o servidor MCP são interfaces para o mesmo motor de decisão tipada:

• Usa choice para um conjunto finito de etiquetas, score para uma escala ordenada e descrita, e noul para a probabilidade de verdadeiro.
• Valida os limiares e os presets em dados representativos; não há um limiar de adoção universal.
• Mantém as ações irreversíveis ou de custo elevado atrás da política de revisão e de fallback da aplicação.
• O servidor MCP chama Router.predict, por isso os hooks disparam quando um lançador personalizado os instala. Vê os Hooks de predição, o ciclo de vida dos hooks e o Tracing para observabilidade e correlação pelo run_id.

Este guia cobre a CLI local e o servidor MCP stdio integrado. Não documenta a API HTTP, wrappers da comunidade, nem um redesenho do protocolo MCP.