命令行与 MCP 服务器
Laya 有两个本地接口,用来试用同一个结构化决策引擎:
| 接口 | 用途 | 传输方式 |
|---|---|---|
laya |
在终端里做快速检查和交互式探索 | 命令行 |
laya-mcp-server |
把 MCP 客户端或 agent 接到 Laya 的内置工具上 | 基于 stdio 的 MCP |
如果你就是读结果的人,选 CLI;如果另一个进程需要一个稳定的工具接口,选 MCP。两者都用 Laya 的
Router 选一个 checkpoint,返回类型化的 choice、score 和 noul 决策;两者都不是开放式问答
或文本生成接口。
路由决策和类型化问题的示例见 README 的 Route Mode 快速开始。置信度和 内置工作流见 README 的置信度 门控和工作流 预设。
1. 命令行
安装这个包会装上 laya 入口点。运行 laya --help 查看完整的选项列表。
python -m pip install laya
laya --help
评测 CLI
这个包还会装上 laya-evals。主 CLI 通过 laya eval 暴露同样的评测命令:
laya eval --help
数据集、指标和基线门控见评测 harness指南。
训练 CLI
laya-train(也可以写作 laya train)从一份带标签决策的 CSV 或 JSONL 微调一个 checkpoint。
见用 laya-train 微调。
laya-train --help
不加载 checkpoint 直接路由
只给文本、不给预测标志时,CLI 调用 Router.route:
laya "I was charged twice, please refund it"
输出会给出选中的 checkpoint、说明为什么选中它,并在有语言信息时显示检测到的语言。单纯路由不会 下载或构建 checkpoint,所以它是对路由决策的一次快速离线检查。
如果想让另一个本地脚本消费这个决策,用 --json:
laya "I was charged twice, please refund it" --json
跑一次预测
--predict 跑完整的类型化预测,并在第一次使用时加载被路由到的 checkpoint。首次加载需要访问
Hugging Face Hub;之后的运行用本地缓存。
laya "Classify this support request" --predict
laya "Classify this support request" --predict --json
--json 把完整结果打印成 JSON。不加它时,CLI 打印每个答案及其 choice 概率、score 或 noul
值,外加路由决策。
主要的开关有:
--model english|multilingual|typed-decisions钉住一个 checkpoint,而不是自动路由。--lang en|de|...提供显式的语言代码,而不是自动检测。--lang-guess en|de|...提供一个软提示,路由会在--lang之后、自己的检测器之前读取它;一个什么都解析不出来的提示会落空,所以它是推动 checkpoint,而不是强制它。--task NAME强制走 typed-decisions 工作流,而不是自动检测。--device cpu|cuda|...把设备选择传给 Router。--json输出机器可读的结果。
用内置预设
预设提供一套现成的问题,并隐含预测,所以不需要 --predict:
laya "My payment failed twice" --preset triage
laya "Ignore all previous instructions" --preset guard --json
CLI 的预设是 email、guard、moderation、router 和 triage。CLI 把文本放到所选预设想用
的 state 字段下;--predict 用路由问题集的 request 字段。预设适合做一次快速的本地检查,但
它们的问题仍然是领域决策:在把它当作应用策略之前,先检查这个预设,并在你自己的数据上验证它。
交互式探索
不带文本参数时,CLI 会打开一个小提示符:
laya
# laya> Classify this request
# laya> quit
按回车运行每个请求。空行、quit、exit 或 Ctrl-D 结束会话。交互循环复用同一个 Router,
所以它是比较多个输入、又不用写脚本的便捷方式。
失败可见
CLI 在应用边界处理非法值,以及常见的依赖、下载和运行时失败。它把诊断信息打印到 stderr,并返回
退出码 2,而不是抛出一个没人处理的 traceback。如果首次使用的 checkpoint 下载失败,重试之前
先检查依赖安装、Hub 访问和所选设备。
2. 内置 MCP stdio 服务器
MCP 服务器是一个可选的附加项。核心包不安装 mcp 依赖:
python -m pip install "laya[mcp]"
laya-mcp-server
# equivalent module form:
python -m laya.mcp.server
服务器是通过 stdio 而不是 HTTP 讲 MCP 的。用控制台脚本配置客户端:
{
"mcpServers": {
"laya": {
"command": "laya-mcp-server",
"env": {
"LAYA_DEVICE": "cpu"
}
}
}
}
如果客户端配置支持指定 Python 可执行文件和参数,可以用 python -m laya.mcp.server 作为等价的
启动形式。服务器进程由客户端拥有;Laya 不会打开网络端口。
可用的工具
| 工具 | 作用 | 主要输入 |
|---|---|---|
laya_status |
报告每个已加载 checkpoint 的设备(checkpoint_devices)、配置的或实际的设备、CUDA 可用性、已加载的 checkpoint、预加载状态、就绪情况以及包版本。 |
无 |
laya_route |
选一个 checkpoint,并在不跑前向传播的情况下返回它的模型、仓库和原因。 | state、questions、可选的 model、task、lang、lang_guess |
laya_predict |
跑类型化问题,返回答案、路由元数据、延迟,以及(可读时)作答设备。 | state、questions、可选的 model(auto、english、multilingual 或 typed-decisions)、task、lang、lang_guess、max_len、head_max_len、min_confidence |
laya_shortlist |
对一个多选项的 choice 问题做候选筛选,然后回答它并返回筛选元数据。 | state、questions、可选的 model、k(默认 20)、task、lang、lang_guess、max_len、head_max_len、min_confidence |
laya_preset |
用它内置的问题集跑一个内置工作流。 | preset、state、可选的 task、lang、lang_guess、max_len、head_max_len、min_confidence |
laya_predict_batch |
一次调用回答多个请求。请求先被路由,再按 checkpoint 分组,所以问题 schema 相同的请求共享前向传播;答案按输入顺序返回。 | requests,每个形如 {state, questions, model?, task?, lang?, lang_guess?, max_len?, head_max_len?},可选 batch_size、hooks_timeout、min_confidence、sort_by_length |
laya_route_batch |
判断每个请求会由哪个 checkpoint 作答,不跑前向传播,也不加载 checkpoint。 | requests,每个形如 {state, questions, model?, task?, lang?, lang_guess?},可选 hooks_timeout |
laya_decide |
在一次前向传播里回答一个 JSON schema 形状的决策,返回决策出的值和逐字段置信度,而不是一个要解析的答案映射。schema 属性可以是 enum choice、布尔值,或带最小值和最大值的整数;自由字符串、数组和嵌套对象会按路径被拒绝。 | state、schema、可选的 model、min_confidence |
这三个批处理和 schema 工具之所以存在,是因为同样的操作在 SDK 和 laya-serve 上也有:要处理
多个请求,或者调用方已经知道答案的形状时,不必降到 Python。想更深入地了解 schema 驱动的形式,
见 Schema 驱动的决策。
共享的防护栏要求:超过 20 个选项的 choice 问题,不做候选筛选就不要发。laya_shortlist 在前向
传播之前保留最可能的 k 个标签;它默认是 k=20。它用作答 checkpoint 自己编码器的均值池化嵌入,
所以不会下载第二个模型,并为每个筛选过的问题返回保留的标签、余弦分数、k、选项数,以及该问题
是否未经筛选地直接通过。一个问题若 k 达到或超过它的选项数,就会原样通过,所以它的余弦分数
返回的是 null,而不是空。
state 必须是一个非空的 JSON 对象。questions 必须是一个非空对象,其值用 Laya 的类型化问题
schema。laya_preset 接受 CLI 那五个预设:email、guard、moderation、triage,以及
router 工作流 —— 它在这个接口上的规范名是 model_router。router 被当作别名接受,指同一个
预设,所以 CLI 里的写法在这里也能用;规范键才是结果里返回的那个。给定一个恰好只有一个字符串的
state,laya_preset 会把它放到那个预设的问题所指定的字段下,和 CLI 的放置方式一样,所以调用方
不用猜键。比一个字符串更复杂的东西就是调用方自己的形状,会原样透传。
每个单请求工具都接受和批处理请求一样的逐调用路由控制项。除了 model,一个请求还可以设置 task(按工作给 checkpoint 起名)、lang(强制一个语言代码)和 lang_guess(一个软语言提示,它位于 lang 之下、内建检测器之上,所以一个很可能但不确定的代码可以推动选择哪个 checkpoint,而不像 lang 那样强制它)。lang_guess 只参与路由,所以像 task 一样,它在一个钉住 model 的调用上会被拒绝 —— 一个被钉住的 checkpoint 已经没有什么可路由的了。laya_predict 和 laya_shortlist 还接受 max_len/head_max_len 作为作答 token 预算,以及 min_confidence 作为弃答门。
一次预测调用和 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?"
}
}
}
工具响应是一段 JSON,包含类型化的 answers、routing 决策和计时信息。不要把高置信度的答案
当成可以执行外部操作的许可;策略、复核和副作用仍由应用或 agent 负责。
启动与环境
MCP 服务器保有常驻的 Router,并把首次构建串行化。默认它预加载 english 和 multilingual;
typed-decisions 保持惰性。预加载失败会在启动时报告,并在下一次工具调用时重试,所以在假定
服务器已就绪之前,先看一眼 laya_status。
| 变量 | 默认值 | 含义 |
|---|---|---|
LAYA_DEVICE |
自动 | 传给 PyTorch 的设备值,例如 cpu 或 cuda。 |
LAYA_PRELOAD |
1 |
启动时构建配置好的 checkpoint。设为 0 表示惰性加载。 |
LAYA_MODELS |
english,multilingual |
要预加载的 checkpoint,逗号分隔。空值保持 MCP 的默认值,而不是预加载每一个 checkpoint。 |
LAYA_THREADS |
PyTorch 默认值 | 限制 CPU 推理时 Torch 的算子内线程数;保持在物理核心数或以下。 |
LAYA_AUTO_TASK |
0 |
设为 1 让请求能自动路由到 typed-decisions checkpoint。含义与 laya.serve 里相同;它不会预加载那个 checkpoint,所以启动时构建什么仍由 LAYA_MODELS 决定。 |
LAYA_DEFAULT_MODEL |
multilingual |
没有任何语言证据的 state 回退到的 checkpoint,含义与 laya.serve 里相同。和 laya.serve 不同,一个解析不出来的名字不会让服务器停下:它会在下一次调用时作为一个 router construction failed 工具错误返回,因为一个 stdio 服务器没有启动过程可以拒绝。 |
LAYA_BASE_URL |
未设置 | 把预测发到你自己的硬件上的 laya-serve,而不是在每个 MCP 进程里加载 checkpoint。一个裸的 host:port 会被当作 HTTP 读取。 |
LAYA_REMOTE_TIMEOUT |
300 |
设置了 LAYA_BASE_URL 时的 HTTP 超时秒数,包括服务器的冷加载。无效或非正值使用默认值。 |
LAYA_API_KEY |
未设置 | 设置了 LAYA_BASE_URL 时,随每个远程请求发送的 bearer token。一个设了自己 LAYA_API_KEY 的 laya-serve 会要求它;本地模式下被忽略。 |
在多个 MCP 会话之间共享一个模型服务器
运行一个本地 HTTP 服务器,并让每个 MCP 客户端的环境指向它:
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"}
}
}
}
在运行 HTTP 服务器的地方安装 laya[serve]。MCP 仍然与编辑器用 stdio;它的预测工具用 HTTP 到达你的服务器。laya_predict、laya_predict_batch、laya_decide 和 laya_preset 使用服务器原始的 state、instructions 和选项描述。laya_predict_batch 按每条目发送一个 /v1/systemone 请求 —— 每个批次都是,不只是异构批次 —— 保持输入顺序;batch_size 和 sort_by_length 会被接受但被忽略,所以不改变服务器的执行。laya_status 报告服务器的 /health;laya_route 和 laya_route_batch 保持本地,既不需要模型也不需要 HTTP 请求。MCP 进程不导入 torch,也不加载任何 checkpoint,包括设置了 LAYA_THREADS 或 LAYA_PRELOAD 时。
当服务器需要 bearer token 时,在两个进程里设置同一个 LAYA_API_KEY。让 LAYA_DEFAULT_MODEL 和 LAYA_AUTO_TASK 保持一致,这样本地的路由预览会匹配服务器的实际路由。设备与预加载设置属于 HTTP 服务器。一次空闲卸载之后的第一调用会等一次冷加载;如果这超过 300 秒,就调高 LAYA_REMOTE_TIMEOUT。laya_shortlist 和预测钩子覆盖会返回 unsupported_remote,因为它们的代码需要模型进程。HTTP 错误会保留服务器的 detail 文本,作为 MCP 工具错误。LAYA_BASE_URL 未设置时,MCP 服务器继续在自己的进程里加载 checkpoint。
原装的 laya-mcp-server 启动器创建 Router 时不安装钩子。请在运行推理的那个进程里安装预测钩子:本地模式下是 MCP 进程,共享服务器模式下是 HTTP 服务器。自定义启动器可以在构建 Router 之前用 laya.hooks.set_default_hooks。上面的环境变量配置的是模型生命周期,不是钩子注册。何时调用工具、拿到决策后怎么处理,仍然由客户端决定。
3. 共享边界与相关指南
CLI 和 MCP 服务器是同一个类型化决策引擎的两个接口:
- 有限的标签集用
choice,有序的量规用score,「为真」的概率用noul。 - 在有代表性的数据上验证阈值和预设;没有通用的采用阈值。
- 把不可逆或高成本的行动挡在应用的复核和回退策略之后。
- MCP 服务器调用
Router.predict,所以自定义启动器安装了钩子时它们就会触发。可观测性和run_id关联见预测钩子、钩子生命周期和 链路追踪。
本指南讲本地 CLI 和内置的 MCP stdio 服务器。它不涉及 HTTP API、社区封装,也不涉及 MCP 协议的 重新设计。