Línea de comandos y servidor MCP

Laya tiene dos interfaces locales para probar el mismo motor de decisiones estructuradas:

Interfaz	Úsala para	Transporte
`laya`	comprobaciones rápidas y exploración interactiva desde un terminal	línea de comandos
`laya-mcp-server`	conectar un cliente MCP o un agente a las herramientas integradas de Laya	MCP sobre stdio

Elige la CLI cuando seas tú la persona que lee el resultado. Elige MCP cuando otro proceso necesite una interfaz de herramientas estable. Ambas usan el Router de Laya para seleccionar un checkpoint y devolver decisiones tipadas choice, score y noul; ninguna es una interfaz abierta de preguntas y respuestas ni de generación de texto.

Para la decisión de enrutamiento y ejemplos de preguntas tipadas, consulta el Inicio rápido del modo Route del README. Para la confianza y los flujos de trabajo integrados, consulta el gating por confianza y los presets de flujo de trabajo del README.

1. Línea de comandos

Instalar el paquete instala el punto de entrada laya. Ejecuta laya --help para ver la lista completa de opciones.

python -m pip install laya
laya --help

CLI de evaluación

El paquete también instala laya-evals. La CLI principal expone los mismos comandos de evaluación a través de laya eval:

laya eval --help

Consulta la guía del Harness de evaluación para conjuntos de datos, métricas y puertas de línea base.

Enrutar sin cargar un checkpoint

Con texto y sin bandera de predicción, la CLI llama a Router.route:

laya "I was charged twice, please refund it"

La salida nombra el checkpoint seleccionado, explica por qué se seleccionó y muestra información del idioma detectado cuando está disponible. El enrutamiento por sí solo no descarga ni construye un checkpoint, así que es una comprobación offline rápida de la decisión de enrutamiento.

Usa --json cuando otro script local deba consumir la decisión:

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

Ejecutar una predicción

--predict ejecuta la predicción tipada completa y carga el checkpoint enrutado en el primer uso. La primera carga necesita acceso al Hugging Face Hub; las ejecuciones posteriores usan la caché local.

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

--json imprime el resultado completo como JSON. Sin él, la CLI imprime cada respuesta junto con su probabilidad de choice, su score o su valor noul, más la decisión de enrutamiento.

Los controles principales son:

--model english|multilingual|typed-decisions fija un checkpoint en lugar de enrutar automáticamente.
--lang en|de|... aporta un código de idioma explícito en lugar de la detección automática.
--lang-guess en|de|... aporta una pista suave que el enrutamiento lee después de --lang y antes de su propio detector; una pista que no resuelve a nada cae, así que empuja el checkpoint sin forzarlo.
--task NAME fuerza el flujo de trabajo typed-decisions en lugar de detectarlo.
--device cpu|cuda|... pasa una elección de unidad al Router.
--json emite salida legible por máquina.

Usar un preset integrado

Un preset aporta un conjunto de preguntas ya listo e implica predicción, así que no hace falta --predict:

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

Los presets de la CLI son email, guard, moderation, router y triage. La CLI coloca el texto bajo el campo de estado que espera el preset seleccionado; --predict usa el campo request del conjunto de preguntas del router. Los presets son útiles para una comprobación local rápida, pero sus preguntas siguen siendo decisiones de dominio: inspecciona el preset y valídalo con tus propios datos antes de usarlo como política de aplicación.

Explorar de forma interactiva

Sin argumento de texto, la CLI abre un pequeño prompt:

laya
# laya> Classify this request
# laya> quit

Pulsa Enter para ejecutar cada solicitud. Una línea vacía, quit, exit o Ctrl-D terminan la sesión. El bucle interactivo reutiliza un mismo Router, así que es una forma cómoda de comparar varias entradas sin escribir un script.

Los fallos son visibles

La CLI maneja valores inválidos y fallos comunes de dependencias, descargas y runtime en la frontera de la aplicación. Imprime un diagnóstico en stderr y devuelve el código de salida 2 en lugar de mostrar un traceback no controlado. Si falla una descarga de checkpoint en el primer uso, comprueba la instalación de las dependencias, el acceso al Hub y la unidad seleccionada antes de reintentar.

2. Servidor MCP stdio integrado

El servidor MCP es un extra opcional. El paquete principal no instala la dependencia mcp:

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

El servidor habla MCP sobre stdio, no HTTP. Configura el cliente con el script de consola:

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

Si la configuración del cliente admite un ejecutable de Python y argumentos, usa python -m laya.mcp.server como forma de lanzamiento equivalente. El cliente es dueño del proceso del servidor; Laya no abre ningún puerto de red.

Herramientas disponibles

Herramienta	Qué hace	Entradas principales
`laya_status`	Informa de la unidad configurada o real, la disponibilidad de CUDA, los checkpoints cargados, el estado de precarga, la preparación y las versiones del paquete.	ninguna
`laya_route`	Selecciona un checkpoint y devuelve su modelo, repositorio y motivo sin ejecutar una pasada hacia adelante.	`state`, `questions`, `model` opcional, `task`, `lang`, `lang_guess`
`laya_predict`	Ejecuta preguntas tipadas y devuelve respuestas, metadatos de enrutamiento, latencia y la unidad que responde cuando es legible.	`state`, `questions`, `model` opcional (`auto`, `english`, `multilingual` o `typed-decisions`), `task`, `lang`, `lang_guess`, `max_len`, `head_max_len`, `min_confidence`
`laya_shortlist`	Preselecciona una pregunta choice de muchas opciones, luego la responde y devuelve los metadatos de la preselección.	`state`, `questions`, `model` opcional, `k` (por defecto `20`), `task`, `lang`, `lang_guess`, `max_len`, `head_max_len`, `min_confidence`
`laya_preset`	Ejecuta un flujo de trabajo integrado usando su conjunto de preguntas integrado.	`preset`, `state`, `task` opcional, `lang`, `lang_guess`, `max_len`, `head_max_len`, `min_confidence`
`laya_predict_batch`	Responde muchas solicitudes en una sola llamada. Las solicitudes se enrutan primero y se agrupan por checkpoint, así que los esquemas de preguntas coincidentes comparten pasadas hacia adelante; las respuestas vuelven en el orden de entrada.	`requests`, cada una `{state, questions, model?, task?, lang?, lang_guess?, max_len?, head_max_len?}`, `batch_size` opcional
`laya_route_batch`	Decide qué checkpoint respondería cada solicitud, sin pasada hacia adelante y sin cargar ningún checkpoint.	`requests`, misma forma que `laya_predict_batch`
`laya_decide`	Responde una decisión con forma de esquema JSON en una sola pasada hacia adelante y devuelve los valores decididos con confianza por campo, en lugar de un mapa de respuestas que analizar. Las propiedades del esquema pueden ser opciones enum, booleanos o enteros con un mínimo y un máximo; las cadenas libres, los arrays y los objetos anidados se rechazan por ruta.	`state`, `schema`, `model` opcional

Las tres herramientas por lotes y de esquema existen porque las mismas operaciones están disponibles en el SDK y en laya-serve: manejar muchas solicitudes, o servir a un llamador que ya conoce la forma de la respuesta, no exige bajar a Python. Para la forma basada en el esquema con más profundidad, consulta Decisiones basadas en el esquema.

El guardarraíl compartido dice que no se envíen preguntas choice con más de 20 opciones sin preseleccionar. laya_shortlist conserva las k etiquetas más probables antes de la pasada hacia adelante; su valor por defecto es k=20. Usa embeddings con mean-pooling del propio codificador del checkpoint que responde, así que no descarga un segundo modelo, y devuelve las etiquetas conservadas, las puntuaciones coseno, k y el número de opciones de cada pregunta preseleccionada.

state debe ser un objeto JSON no vacío. questions debe ser un objeto no vacío cuyos valores usen el esquema de pregunta tipada de Laya. laya_preset acepta los mismos cinco presets que la CLI: email, guard, moderation, triage y el flujo de trabajo del router, cuyo nombre canónico en esta superficie es model_router. router se acepta como alias y nombra el mismo preset, así que la grafía de la CLI también funciona aquí; la clave canónica es la que vuelve en el resultado. Dado un estado de exactamente una cadena, laya_preset la coloca bajo el campo que nombran las preguntas de ese preset, la misma colocación que hace la CLI, así que un llamador no tiene que adivinar la clave. Cualquier cosa más rica que una cadena es la forma propia del llamador y se pasa sin tocar.

Toda herramienta de una sola solicitud acepta los mismos controles de enrutamiento por llamada que las solicitudes por lotes. Junto a model, una solicitud puede definir task (nombrar un checkpoint por el trabajo), lang (forzar un código de idioma) y lang_guess (una pista de idioma suave que se sitúa por debajo de lang y por encima del detector integrado, así que un código probable pero incierto puede empujar qué checkpoint se elige sin forzarlo como lo hace lang). lang_guess solo participa en el enrutamiento, así que como task se rechaza en una llamada que fija model – un checkpoint fijado no tiene nada que enrutar. laya_predict y laya_shortlist también aceptan max_len/head_max_len para el presupuesto de tokens de respuesta y min_confidence para la puerta de abstención.

Una llamada de predicción tiene la misma forma que la llamada tipada del 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?"
    }
  }
}

La respuesta de la herramienta es JSON con las answers tipadas, la decisión de routing y la información de tiempos. No trates una respuesta de alta confianza como permiso para realizar una acción externa; la aplicación o el agente sigue siendo responsable de la política, la revisión y los efectos secundarios.

Arranque y entorno

El servidor MCP mantiene un Router residente y serializa la construcción por primera vez. Por defecto precarga english y multilingual; typed-decisions queda perezoso. Un fallo de precarga se informa al arrancar y se reintenta en la siguiente llamada a herramienta, así que inspecciona laya_status antes de asumir que el servidor está listo.

Variable	Por defecto	Significado
`LAYA_DEVICE`	automático	Valor de unidad pasado a PyTorch, como `cpu` o `cuda`.
`LAYA_PRELOAD`	`1`	Construye los checkpoints configurados al arrancar. Ponlo a `0` para carga perezosa.
`LAYA_MODELS`	`english,multilingual`	Checkpoints a precargar separados por comas. Un valor vacío mantiene el valor por defecto de MCP en lugar de precargar todos los checkpoints.
`LAYA_THREADS`	valor por defecto de PyTorch	Limita los hilos intra-op de Torch para la inferencia en CPU; mantenlo en o por debajo del número de núcleos físicos.
`LAYA_AUTO_TASK`	`0`	Ponlo a `1` para dejar que una solicitud se enrute automáticamente al checkpoint `typed-decisions`. Mismo significado que en `laya.serve`; no precarga ese checkpoint, así que `LAYA_MODELS` sigue decidiendo qué se construye al arrancar.
`LAYA_DEFAULT_MODEL`	`english`	El checkpoint al que recurre un estado sin evidencia de idioma, mismo significado que en `laya.serve`. A diferencia de `laya.serve`, un nombre que no se puede resolver no detiene el servidor: vuelve como un error de herramienta `router construction failed` en la siguiente llamada, porque un servidor stdio no tiene un arranque que pueda rechazar.
`LAYA_BASE_URL`	sin definir	Envía las predicciones a un `laya-serve` en tu propio hardware en lugar de cargar checkpoints en cada proceso MCP. Un `host:port` sin más se lee como HTTP.
`LAYA_REMOTE_TIMEOUT`	`300`	Tiempo de espera HTTP en segundos cuando `LAYA_BASE_URL` está definido, incluida la carga en frío del servidor. Los valores inválidos o no positivos usan el valor predeterminado.

Compartir un servidor de modelos entre sesiones MCP

Ejecuta un servidor HTTP local y apunta el entorno de cada cliente MCP a él:

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 laya[serve] donde corre el servidor HTTP. MCP sigue usando stdio con el editor; sus herramientas de predicción usan HTTP para llegar a tu servidor. laya_predict, laya_predict_batch, laya_decide y laya_preset usan el estado, las instrucciones y las descripciones de opciones originales del servidor. Los lotes heterogéneos envían una solicitud /v1/systemone por elemento, preservando el orden de entrada; batch_size y sort_by_length no cambian la ejecución del servidor. laya_status informa del /health del servidor; laya_route y laya_route_batch se quedan locales y no necesitan modelo ni solicitud HTTP. El proceso MCP no importa torch ni carga ningún checkpoint, incluso cuando LAYA_THREADS o LAYA_PRELOAD están definidos.

Define el mismo LAYA_API_KEY en ambos procesos cuando el servidor requiere un token de portador. Mantén LAYA_DEFAULT_MODEL y LAYA_AUTO_TASK alineados para que las vistas previas de enrutamiento local coincidan con el enrutamiento real del servidor. Los ajustes de dispositivo y precarga pertenecen al servidor HTTP. La primera llamada tras una descarga por inactividad espera una carga en frío; sube LAYA_REMOTE_TIMEOUT si eso tarda más de 300 segundos. laya_shortlist y las anulaciones de hooks de predicción devuelven unsupported_remote, ya que su código necesita el proceso del modelo. Los errores HTTP conservan el texto de detalle del servidor como errores de herramienta MCP. Con LAYA_BASE_URL sin definir, el servidor MCP sigue cargando checkpoints en su propio proceso.

El lanzador estándar laya-mcp-server crea su Router sin instalar hooks. Instala hooks de predicción en el proceso que ejecuta la inferencia: el proceso MCP en modo local, o el servidor HTTP en modo de servidor compartido. Un lanzador personalizado puede usar laya.hooks.set_default_hooks antes de construir su Router. Las variables de entorno de arriba configuran el ciclo de vida del modelo, no el registro de hooks. El cliente sigue decidiendo cuándo llamar a una herramienta y qué hacer con la decisión devuelta.

3. Fronteras compartidas y guías relacionadas

La CLI y el servidor MCP son interfaces del mismo motor de decisiones tipadas:

Usa choice para un conjunto finito de etiquetas, score para una rúbrica ordenada, y noul para la probabilidad de verdadero.
Valida umbrales y presets con datos representativos; no hay un umbral de adopción universal.
Mantén las acciones irreversibles o costosas detrás de la política de revisión y respaldo de la aplicación.
El servidor MCP llama a Router.predict, así que los hooks se disparan cuando un lanzador personalizado los instala. Consulta Hooks de predicción, el ciclo de vida de los hooks y Tracing para observabilidad y correlación por run_id.

Esta guía cubre la CLI local y el servidor MCP stdio integrado. No documenta la API HTTP, los envoltorios de la comunidad ni un rediseño del protocolo MCP.