自托管 Laya：Jev 兼容 HTTP API、命令行、Docker 与 MCP Server

上游 laya Python 包不只能在你自己的脚本里调用。它还自带一个与 TypeSafe 托管版 Jev API 协议一致的自托管 HTTP 服务、一个用于快速测试的命令行工具，以及一个可选的 MCP Server，供 Agent 客户端调用。

本文把这些方式集中整理在一起。一手资料：Laya GitHub 仓库。

只想通过 HTTP 调用 Laya、不想自己部署？请看 Laya API 调用指南，里面有请求格式和托管服务对比。

方式一：兼容 Jev 的 HTTP 服务（`laya-serve`）

laya.serve 通过 POST /v1/systemone 对外提供 Router。上游说明 Laya 的返回结构与 Jev 完全一致（choice / score / noul 答案加上 {input_tokens, output_tokens} usage 字段），因此现有的 Jev 客户端只需要改一下 base URL。

pip install "laya[serve]"                     # 额外安装 fastapi、uvicorn、python-multipart
LAYA_DEVICE=cuda LAYA_PRELOAD=1 laya-serve    # 监听 0.0.0.0:8000，预加载全部 3 个 checkpoint

发送请求：

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"}}}
}'

0.3.22 起，服务还支持 POST /v1/systemone/batch：传一组 states（最多 64 条）加一份共用的 questions，每条 state 返回一个结果，另附 total_usage 合计。请求体里的 task、lang、lang_guess、min_confidence 也会生效了，旧版本会直接忽略它们。

配置项

环境变量	作用
`LAYA_HOST`、`LAYA_PORT`	监听地址与端口（默认 `0.0.0.0:8000`）
`LAYA_DEVICE`	`cuda`、`cpu` 或 `mps`，直接传给 torch
`LAYA_PRELOAD`	启动时就构建 checkpoint，而不是等第一次请求
`LAYA_MODELS`	需要预加载的 checkpoint，逗号分隔
`LAYA_THREADS`	限制 CPU 推理时 torch 的线程数（不超过物理核数）
`LAYA_AUTO_TASK`	开启自动任务识别
`LAYA_API_KEY`	设置后，客户端必须携带 `Authorization: Bearer <key>`
`LAYA_ROOT_PATH`	通过反向代理挂在某个路径下（比如 `/laya`）时的对外路径前缀（0.3.22 起）
`LAYA_IDLE_UNLOAD_SECONDS`	空闲这么多秒后卸载 checkpoint、释放内存；默认 `0`，一直保持加载（0.3.25 起）
`LAYA_DEFAULT_MODEL`	认不出语言的文本用哪个 checkpoint。不设置时沿用路由的默认值：0.4.0 起是 `multilingual`（以前是 `english`）；想保持原来的行为就设为 `english`
`LAYA_EXTRA_MODELS`	用 JSON 对象按名字注册自己的 checkpoint，比如 `{"tickets": "/models/tickets-checkpoint"}`，客户端用 `model=` 指定（0.4.1 起）
`LAYA_TOURNAMENT_GROUP`	选项数超过这个值的 `choice` 题按这个组大小分组淘汰来回答，选项上限也从 100 提高到 255；可设 2 到 255，不设为关闭（0.4.3 起）
`LAYA_JEV_STRICT`	设为 `1` 时只返回 Jev 响应格式里的字段，适合会拒绝多余字段的客户端（0.3.24 起）

如果客户端请求里的 model 字段是 Laya 的 checkpoint 名（english、multilingual、typed-decisions），就按指定的来；否则由 Router 根据文字脚本和语言自动选择。

安全默认值

从 0.3.11 起，服务端使用防时序攻击的 API Key 校验，限制请求大小和问题数量（超限返回 413），JSON 格式错误返回 400，报错信息不泄露路径；0.3.12 还对 chunked 上传也强制执行了大小限制。如果服务要暴露到 localhost 之外，务必设置 LAYA_API_KEY，并放在你常用的 TLS 反向代理之后。

方式二：Docker

上游在 docs/docker.md 维护了 Docker Compose 快速上手：在 CPU 上跑一个示例请求，并在多次运行之间保留已下载的模型。Compose 默认只把 laya-serve 绑定到 loopback，并带有健康检查。另外还提供原生 ARM64 和 DGX Spark 的容器构建。

仓库本身是一个 Nix flake。在带 NVIDIA GPU 的机器上执行 nix run .#laya-serve 即可构建并启动服务。NixOS 主机可以导入 laya.nixosModules.default 并启用 services.laya-serve：它会以加固过的 DynamicUser systemd 单元运行，权重缓存在 /var/lib/laya-serve，可选的 bearer token 通过 LoadCredential 读取。

方式四：本地 Web 界面

不想写客户端、只想手动测试的话，上游仓库里的 examples/server.py 是一个独立的 FastAPI 应用：提供请求构建器，把 choice / score / noul 结果渲染成进度条，同时提供 /predict 和 /predict/batch 两个 JSON 接口：

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

--no-preload 改为按需加载 checkpoint，--device cuda|cpu|mps 指定设备。

方式五：`laya` 命令行

安装包后会同时装上 laya 命令：

laya "I was charged twice, please refund"            # 只做路由判断；离线可用，不下载模型
laya "Refactor this service" --predict               # 完整预测（首次会下载 checkpoint）
laya "Mein Konto wurde zweimal belastet" --lang de   # 强制指定语言
laya "My payment failed twice" --preset triage       # 预设：triage、email、guard、moderation、router

只做路由判断时不会下载任何 checkpoint，毫秒级返回。

方式六：给 Agent 客户端用的 MCP Server

Laya 可以作为 MCP stdio server 运行，让 Claude Desktop、Cursor 等 MCP 客户端直接把 typed decision 当作工具调用（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" }
    }
  }
}

MCP Server 默认预加载 english,multilingual，typed-decisions 按需加载。和 SDK 一样，它只适合结构化决策，不适合开放式问答。

资源规划：延迟与内存

上游在 Router(preload=True) 下的实测：T4 GPU 每次请求 32.8 ms，CPU 上 193–464 ms。惰性的 Router() 默认常驻两个 checkpoint；设置 max_loaded=1 会在每次语言切换时重新加载，实测中位数 CPU 7.4 秒、T4 10.3 秒。部署服务时，需要用到的 checkpoint 都应预加载。

在普通 4 核服务器 CPU（AMD EPYC 9R14，v0.3.20，无 GPU）上，上游实测 laya-multilingual 每个问题 193 ms，英文和 typed-decisions checkpoint 约 580 ms。耗时基本随问题数量线性增长，所以在 CPU 上合并提问几乎不省时间。如果只用 CPU 部署，优先选多语言 checkpoint，并把 LAYA_THREADS 设为物理核数。完整数据见 Laya 基准测试，线程设置与部署规模建议见 Laya 在 CPU 上多快。

模型卡给出的下载体积：英文 checkpoint 约 808 MB，多语言 checkpoint 约 647 MB。

社区服务层

如果官方服务不够用，可以看看 Arbiter（checkpoint 路由、batch、metrics 和 Playground）或 macOS MPS 运行时。Runtimes 总览对比了所有方案。