命令列與 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|... 提供顯式的語言程式碼，而不是自動檢測。
--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`	報告配置的或實際的裝置、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`
`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 的放置方式一樣，所以呼叫方不用猜鍵。比一個字串更復雜的東西就是呼叫方自己的形狀，會原樣透傳。

每個單請求工具都接受和批處理請求一樣的逐呼叫路由控制項。除了 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`	`english`	沒有任何語言證據的 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 超時秒數，包括伺服器的冷載入。無效或非正值使用預設值。

在多個 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 和選項描述。異構批次按每條目傳送一個 /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 協議的重新設計。