命令行与 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指南。

不加载 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|... 提供显式的语言代码，而不是自动检测。
--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`	报告配置的或实际的设备、CUDA 可用性、已加载的 checkpoint、预加载状态、就绪情况以及包版本。	无
`laya_route`	选一个 checkpoint，并在不跑前向传播的情况下返回它的模型、仓库和原因。	`state`、`questions`
`laya_predict`	跑类型化问题，返回答案、路由元数据、延迟，以及（可读时）作答设备。	`state`、`questions`、可选的 `model`（`auto`、`english`、`multilingual` 或 `typed-decisions`）
`laya_shortlist`	对一个多选项的 choice 问题做候选筛选，然后回答它并返回筛选元数据。	`state`、`questions`、可选的 `model`、可选的 `k`（默认 `20`）
`laya_preset`	用它内置的问题集跑一个内置工作流。	`preset`、`state`
`laya_predict_batch`	一次调用回答多个请求。请求先被路由，再按 checkpoint 分组，所以问题 schema 相同的请求共享前向传播；答案按输入顺序返回。	`requests`，每个形如 `{state, questions, model?, task?, lang?}`，可选 `batch_size`
`laya_route_batch`	判断每个请求会由哪个 checkpoint 作答，不跑前向传播，也不加载 checkpoint。	`requests`，形状和 `laya_predict_batch` 相同
`laya_decide`	在一次前向传播里回答一个 JSON schema 形状的决策，返回决策出的值和逐字段置信度，而不是一个要解析的答案映射。schema 属性可以是 enum choice、布尔值，或带最小值和最大值的整数；自由字符串、数组和嵌套对象会按路径被拒绝。	`state`、`schema`、可选的 `model`

这三个批处理和 schema 工具之所以存在，是因为同样的操作在 SDK 和 laya-serve 上也有：要处理多个请求，或者调用方已经知道答案的形状时，不必降到 Python。想更深入地了解 schema 驱动的形式，见 Schema 驱动的决策。

共享的防护栏要求：超过 20 个选项的 choice 问题，不做候选筛选就不要发。laya_shortlist 在前向传播之前保留最可能的 k 个标签；它默认是 k=20。它用作答 checkpoint 自己编码器的均值池化嵌入，所以不会下载第二个模型，并为每个筛选过的问题返回保留的标签、余弦分数、k 和选项数。

state 必须是一个非空的 JSON 对象。questions 必须是一个非空对象，其值用 Laya 的类型化问题 schema。laya_preset 接受 CLI 那五个预设：email、guard、moderation、triage，以及 router 工作流 —— 它在这个接口上的规范名是 model_router。router 被当作别名接受，指同一个预设，所以 CLI 里的写法在这里也能用；规范键才是结果里返回的那个。给定一个恰好只有一个字符串的 state，laya_preset 会把它放到那个预设的问题所指定的字段下，和 CLI 的放置方式一样，所以调用方不用猜键。比一个字符串更复杂的东西就是调用方自己的形状，会原样透传。

一次预测调用和 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-mcp-server 启动器创建 Router 时不安装钩子。如果你需要预测钩子，就换一个会安装它们的自定义启动器，例如在服务器构建 Router 之前用 laya.hooks.set_default_hooks。上面的环境变量配置的是模型生命周期，不是钩子注册。何时调用工具、拿到决策后怎么处理，仍然由客户端决定。

3. 共享边界与相关指南

CLI 和 MCP 服务器是同一个类型化决策引擎的两个接口：

有限的标签集用 choice，有序的量规用 score，「为真」的概率用 noul。
在有代表性的数据上验证阈值和预设；没有通用的采用阈值。
把不可逆或高成本的行动挡在应用的复核和回退策略之后。
MCP 服务器调用 Router.predict，所以自定义启动器安装了钩子时它们就会触发。可观测性和 run_id 关联见预测钩子、钩子生命周期和链路追踪。

本指南讲本地 CLI 和内置的 MCP stdio 服务器。它不涉及 HTTP API、社区封装，也不涉及 MCP 协议的重新设计。