Autoalojar Laya: API compatible con Jev, CLI, Docker y MCP

El paquete oficial de Python laya sirve para mucho más que ejecutarse dentro de tu propio script. Incluye un servidor HTTP autoalojado que usa el mismo protocolo que la API alojada de Jev de TypeSafe, una herramienta de línea de comandos para pruebas rápidas y un servidor MCP opcional para clientes de agentes.

Esta guía reúne todas esas opciones. Fuente principal: Laya en GitHub.

Opción 1: el servidor HTTP compatible con Jev (`laya-serve`)

laya.serve expone el Router por HTTP en POST /v1/systemone. Según el proyecto, la respuesta de Laya tiene exactamente el mismo esquema que la de Jev (respuestas choice / score / noul más un bloque de uso {input_tokens, output_tokens}), así que a un cliente de Jev existente solo hay que cambiarle la URL base.

pip install "laya[serve]"                     # añade fastapi, uvicorn y python-multipart
LAYA_DEVICE=cuda LAYA_PRELOAD=1 laya-serve    # escucha en 0.0.0.0:8000 y precarga los 3 checkpoints

Envía una petición:

curl -s localhost:8000/v1/systemone -H 'content-type: application/json' -d '{
  "state": {"body": "billed twice, refund please or we cancel"},
  "questions": {"dept": {"type": "choice", "instructions": "which team?",
                "criteria": {"billing": "refunds", "tech": "bugs"}}}
}'

Configuración

Variable	Qué hace
`LAYA_HOST`, `LAYA_PORT`	Dirección y puerto de escucha (por defecto `0.0.0.0:8000`)
`LAYA_DEVICE`	`cuda`, `cpu` o `mps`; se pasa directamente a torch
`LAYA_PRELOAD`	Carga los checkpoints al arrancar en lugar de en la primera petición
`LAYA_MODELS`	Lista separada por comas de los checkpoints que se precargan
`LAYA_THREADS`	Limita los hilos de torch en CPU (no más que núcleos físicos)
`LAYA_AUTO_TASK`	Activa la detección automática de tareas
`LAYA_API_KEY`	Si se define, los clientes deben enviar `Authorization: Bearer <key>`

Si el campo model del cliente nombra un checkpoint de Laya (english, multilingual o typed-decisions), se respeta; si no, el router elige uno según el alfabeto y el idioma.

Seguridad por defecto

Desde la versión 0.3.11 el servidor compara las claves API de forma segura frente a ataques de tiempo, limita el tamaño de la petición y el número de preguntas (HTTP 413), devuelve 400 para JSON mal formado y no revela rutas en los errores. La 0.3.12 aplica también el límite de tamaño a las subidas por bloques (chunked). Si expones el servidor fuera de localhost, define LAYA_API_KEY y colócalo detrás de tu proxy TLS habitual.

Opción 2: Docker

El proyecto mantiene una guía rápida con Docker Compose en docs/docker.md. Ejecuta una petición de ejemplo en CPU y conserva los modelos descargados entre ejecuciones. El archivo Compose enlaza laya-serve solo a loopback por defecto e incluye un healthcheck. También hay imágenes nativas para ARM64 y DGX Spark.

Opción 3: NixOS

El repositorio es un flake de Nix. En una máquina con GPU NVIDIA, nix run .#laya-serve compila y sirve. En un host NixOS, importa laya.nixosModules.default y activa services.laya-serve, que ejecuta una unidad systemd DynamicUser reforzada, guarda los pesos en /var/lib/laya-serve y lee un token bearer opcional mediante LoadCredential.

Opción 4: la interfaz web local

Para pruebas manuales sin escribir un cliente, examples/server.py del repositorio oficial es una app FastAPI independiente con un constructor de peticiones que muestra las respuestas choice / score / noul como barras, además de los endpoints JSON /predict y /predict/batch:

pip install "laya[serve]"
python examples/server.py        # http://127.0.0.1:8000

--no-preload carga los checkpoints bajo demanda y --device cuda|cpu|mps fija el dispositivo.

Opción 5: el comando `laya`

Al instalar el paquete también se instala el comando laya:

laya "I was charged twice, please refund"            # solo decisión de enrutamiento; sin conexión ni descarga
laya "Refactor this service" --predict               # respuestas completas (descarga el checkpoint una vez)
laya "Mein Konto wurde zweimal belastet" --lang de   # forzar un idioma
laya "My payment failed twice" --preset triage       # presets: triage, email, guard, moderation, router

El enrutamiento por sí solo nunca descarga un checkpoint, así que responde en milisegundos.

Opción 6: servidor MCP para agentes

Laya puede ejecutarse como servidor MCP por stdio, para que clientes MCP como Claude Desktop o Cursor usen decisiones tipadas como herramientas (laya_predict, laya_route, laya_preset, laya_status):

pip install "laya[mcp]"
laya-mcp-server

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

El servidor MCP precarga english,multilingual por defecto y deja typed-decisions bajo demanda. Igual que con el SDK, úsalo para decisiones estructuradas, no para preguntas abiertas.

Dimensionamiento: latencia y memoria

Mediciones oficiales con Router(preload=True): 32,8 ms por petición en una GPU T4 y 193–464 ms en CPU. Un Router() perezoso mantiene dos checkpoints en memoria; con max_loaded=1 recarga en cada cambio de idioma, con una mediana medida de 7,4 s en CPU y 10,3 s en una T4. Para un servidor, precarga lo que vayas a servir.

En una CPU de servidor normal de 4 núcleos (AMD EPYC 9R14, v0.3.20, sin GPU), el proyecto midió 193 ms por pregunta con laya-multilingual y unos 580 ms con los checkpoints inglés y typed-decisions. El coste crece casi linealmente con el número de preguntas, así que agruparlas ahorra poco en CPU. Si sirves solo con CPU, elige el checkpoint multilingüe y fija LAYA_THREADS al número de núcleos físicos. Consulta los benchmarks de Laya para las cifras completas y Laya en CPU para la configuración de hilos y el dimensionamiento.

Tamaños de descarga según la ficha del modelo: unos 808 MB para el checkpoint inglés y 647 MB para el multilingüe.

Capas de servicio de la comunidad

Si necesitas más que el servidor oficial, mira Arbiter (enrutamiento de checkpoints, lotes, métricas y un Playground) o el runtime MPS para macOS. La vista general de runtimes compara todas las opciones.

Relacionado

Laya y Ollama: ejecuta Laya en local con ollaya
Instalar Laya
Laya vs Jev
Integraciones de Laya: MCP, agentes de navegador y agentes de código
Ajuste fino de Laya

Última verificación: 24 de septiembre de 2026.