Linha de comando e servidor MCP

O Laya tem duas interfaces locais para experimentar o mesmo motor de decisões estruturadas:

Escolha a CLI quando você for a pessoa que lê o resultado. Escolha o MCP quando outro processo precisar de uma interface de ferramenta estável. Ambos usam o Router do Laya para selecionar um checkpoint e devolver decisões tipadas choice, score e noul; nenhum é uma interface aberta de perguntas e respostas ou de geração de texto.

Para a decisão de roteamento e exemplos de perguntas tipadas, veja o Início rápido do modo Route do README. Para confiança e fluxos de trabalho integrados, veja o gating por confiança e os presets de fluxo de trabalho do README.

1. Linha de comando

Instalar o pacote instala o ponto de entrada laya. Rode 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 laya-evals. A CLI principal expõe os mesmos comandos de avaliação através de laya eval:

laya eval --help

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

Rotear sem carregar um checkpoint

Com texto e sem 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 por que ele foi selecionado e mostra informação do idioma detectado quando disponível. O roteamento sozinho não baixa nem constrói um checkpoint, então é uma checagem offline rápida da decisão de roteamento.

Use --json quando outro script local for consumir a decisão:

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

Rodar uma predição

--predict roda a predição tipada completa e carrega o checkpoint roteado no primeiro uso. A primeira carga precisa de acesso ao Hugging Face Hub; execuções posteriores usam o 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 junto com sua probabilidade de choice, seu score ou seu valor noul, mais a decisão de roteamento.

Os controles principais são:

• --model english|multilingual|typed-decisions fixa um checkpoint em vez de rotear automaticamente.
• --lang en|de|... fornece um código de idioma explícito em vez da detecção automática.
• --lang-guess en|de|... fornece uma dica suave que o roteamento lê depois de --lang e antes de seu próprio detector; uma dica que não resolve nada cai fora, então ela empurra o checkpoint sem forçá-lo.
• --task NAME força o fluxo de trabalho typed-decisions em vez de detectá-lo.
• --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 e implica predição, então --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 de estado que o preset selecionado espera; --predict usa o campo request do conjunto de perguntas do router. Os presets são úteis para uma checagem local rápida, mas suas perguntas ainda são decisões de domínio: inspecione o preset e valide-o nos seus próprios dados antes de usá-lo como política de aplicação.

Explorar de forma interativa

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

laya
# laya> Classify this request
# laya> quit

Pressione Enter para rodar cada solicitação. Uma linha vazia, quit, exit ou Ctrl-D encerram a sessão. O laço interativo reutiliza um mesmo Router, então é 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ência, download e runtime na fronteira da aplicação. Ela imprime um diagnóstico no stderr e retorna 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, verifique 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. Configure o cliente com o script de console:

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

Se a configuração do cliente suportar um executável Python e argumentos, use 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: lidar com muitas solicitações, ou servir um chamador que já conhece o formato da resposta, não exige descer para Python. Para a forma orientada por esquema com mais profundidade, veja Decisões orientadas por esquema.

O guardrail compartilhado diz para não enviar perguntas choice com mais de 20 opções sem pré-seleção. laya_shortlist mantém os k rótulos mais prováveis antes da passada direta; seu padrão é k=20. Ele usa embeddings com mean-pooling do próprio codificador do checkpoint que responde, então não baixa um segundo modelo, e retorna os rótulos mantidos, as pontuações de cosseno, k e a contagem de opções de cada pergunta pré-selecionada.

state deve ser um objeto JSON não vazio. questions deve ser um objeto não vazio cujos valores usam o esquema de pergunta tipada 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 é aceito como alias e nomeia o mesmo preset, então a grafia da CLI também funciona aqui; a chave canônica é a que volta no resultado. Dado um estado de exatamente uma string, laya_preset a coloca sob o campo que as perguntas daquele preset nomeiam, a mesma colocação que a CLI faz, então um chamador não precisa adivinhar a chave. Qualquer coisa mais rica que uma string é a forma própria do chamador e é repassada intacta.

Toda ferramenta de solicitação única aceita os mesmos controles de roteamento por chamada que as solicitações em lote. Ao lado de model, uma solicitação 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 detector integrado, então um código provável mas incerto pode empurrar qual checkpoint é escolhido sem forçá-lo como lang faz). lang_guess só participa do roteamento, então como task ele é recusado em uma chamada que fixa model – um checkpoint fixado não tem mais nada a rotear. laya_predict e laya_shortlist também aceitam 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 contendo as answers tipadas, a decisão de routing e informação de tempo. Não trate uma resposta de alta confiança como permissão para executar uma ação externa; a aplicação ou o agente continua responsável pela política, pela revisão e pelos efeitos colaterais.

Inicialização e ambiente

O servidor MCP mantém um Router residente e serializa a construção pela primeira vez. Por padrão ele pré-carrega english e multilingual; typed-decisions fica preguiçoso. Uma falha de pré-carga é reportada na inicialização e tentada de novo na próxima chamada de ferramenta, então inspecione laya_status antes de supor que o servidor está pronto.

Compartilhar um servidor de modelo entre sessões MCP

Rode um servidor HTTP local e aponte 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"}
    }
  }
}

Instale laya[serve] onde o servidor HTTP roda. O MCP continua usando stdio com o editor; suas ferramentas de predição usam HTTP para chegar ao seu 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 uma solicitação /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 permanecem locais e não precisam de modelo nem de solicitação HTTP. O processo MCP não importa torch nem carrega nenhum checkpoint, inclusive quando LAYA_THREADS ou LAYA_PRELOAD estão definidos.

Defina o mesmo LAYA_API_KEY nos dois processos quando o servidor exigir um token de portador. Mantenha LAYA_DEFAULT_MODEL e LAYA_AUTO_TASK alinhados para que as prévias de roteamento local correspondam ao roteamento real do servidor. As configurações de dispositivo e pré-carregamento pertencem ao servidor HTTP. A primeira chamada após um descarregamento por ociosidade espera uma carga a frio; aumente LAYA_REMOTE_TIMEOUT se isso levar mais de 300 segundos. laya_shortlist e overrides de hooks de predição retornam unsupported_remote, já que 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 carregando checkpoints em seu próprio processo.

O lançador padrão laya-mcp-server cria seu Router sem instalar hooks. Instale hooks de predição no processo que roda a inferência: o processo MCP no modo local, ou o servidor HTTP no modo de servidor compartilhado. Um lançador personalizado pode usar laya.hooks.set_default_hooks antes de construir seu Router. As variáveis de ambiente acima configuram o ciclo de vida do modelo, não o registro de hooks. O cliente ainda decide quando chamar uma ferramenta e o que fazer com a decisão retornada.

3. Fronteiras compartilhadas e guias relacionados

A CLI e o servidor MCP são interfaces para o mesmo motor de decisões tipadas:

• Use choice para um conjunto finito de rótulos, score para uma rubrica ordenada, e noul para a probabilidade de verdadeiro.
• Valide limiares e presets em dados representativos; não há um limiar de adoção universal.
• Mantenha ações irreversíveis ou de alto custo atrás da política de revisão e fallback da aplicação.
• O servidor MCP chama Router.predict, então os hooks disparam quando um lançador personalizado os instala. Veja Hooks de predição, o ciclo de vida dos hooks e o Tracing para observabilidade e correlação por run_id.

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