NandhaKishorM/laya · 上手攻略

仓库：NandhaKishorM/laya
链接：https://github.com/NandhaKishorM/laya
分类：AI 应用 · 决策引擎
作者：spark
更新：2026-09-25

1. 这是什么

Laya 是一个非自回归的 System 1 决策引擎：给定一段文本（邮件、工单、对话、JSON 文档），在一次前向传播内输出强类型的判断结果，而不是让 LLM 自由生成文本再做解析。

它支持三种「类型化决策」输出：

choice：从给定候选项里挑一个（如「部门路由」= billing / technical / other）
score：在有序等级上打一个分数（如「紧急度」= not urgent / soon / critical）
noul：是/否判断 + 一个校准后的概率（0~1），用于「流失风险」「退款请求」这类二元问句

仓库自带三个 Hub checkpoint + 一个自动路由的 Router：

Checkpoint	编码器	参数量	上下文	适用场景
laya	ModernBERT-large	421M	512 token	英文
laya-multilingual	mmBERT-base	322M	1024（最长 8192）	100+ 语言，约 2× 更快
laya-typed-decisions	ModernBERT-large	421M	1024	强类型决策工作流（路由后微调）

Router 内置脚本/语言检测，毫秒级判断后把请求分发给最合适的 checkpoint，调用方无需关心语言或分支逻辑。

⚠️ 上面 32.8 ms / 39.5 ms 等数字均来自仓库 README 自报，测试硬件为 T4 / Apple GPU；未做独立复现，引用时请标注来源。

2. 解决什么问题

把 LLM 当分类器用有三个常见痛点：

慢 + 贵：一次自回归生成动辄几百毫秒到几秒、几千 token，单条意图分类就要花掉 0.5~3 美分。
不可解析：模型吐出的「我认为是 billing 部门」还要再过一次正则/JSON 解析，失败率高。
幻觉：分类其实只要 1 个 token，但 LLM 容易长篇大论，事实性错误会顺着话术带出来。

Laya 的取舍是完全不做文本生成：单条推理 33 ms、批处理 7.2 ms/条（README 自报，T4 测得），返回的是强类型结构（带置信度），可直接喂给下游逻辑。

典型场景：客服工单路由、邮件优先级打分、UGC 风险识别、表单字段语义校验、低延迟意图识别。

3. 快速安装

系统要求

Python ≥ 3.10（依赖 huggingface_hub 1.x、transformers 5.x、torch 2.14，都强制 3.10+）
可选 PyTorch：根据 CPU/GPU 自行选 build

macOS / Linux

python3 -m venv .venv
.venv/bin/python -m pip install laya
.venv/bin/python -I -c "import laya; print(laya.__version__)"

-I 排除当前目录的 import 路径，避免本地源码覆盖包安装。⚠️ Debian/Ubuntu 的系统 Python 缺 venv 时先 sudo apt install python3-venv。

Windows PowerShell

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install laya
.\.venv\Scripts\python.exe -I -c "import laya; print(laya.__version__)"

可选 extras

pip install "laya[serve]"      # FastAPI 示例服务
pip install "laya[mcp]"        # MCP server
pip install "laya[langchain]"  # LangChain / LangGraph 集成
pip install "laya[onnx]"       # ONNX Runtime
pip install "laya[fast]"       # TileLang GPU fast path

第一次跑前的网络提示

Router(preload=True) 会在构造时下载全部三个 checkpoint，需要能访问 Hugging Face Hub。首次只下载不缓存到断网环境会卡住；如需离线使用，提前 huggingface-cli download 缓存到本地再传 local_dir。

4. 核心用法

4.1 最快上手：CLI

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       # 用内置工单分流预设
laya                                                 # 进入交互模式

⚠️ 不带 --predict 时不下载模型，纯路由本地跑完就返回；带 --predict 才会触发 HF 拉取。

4.2 Python SDK：Router + 类型化决策

from laya import Router

router = Router()  # 首次使用按需下载；Router(preload=True) 一次性加载全部三个

state = "Hi, we were billed twice for March. Please refund the duplicate today or we will cancel our plan."

questions = {
    "department": {
        "type": "choice",
        "instructions": "Which department should handle this?",
        "criteria": {
            "billing": "invoices, payments, refunds",
            "technical": "bugs, outages, system errors",
            "other": "everything else",
        },
    },
    "urgency": {
        "type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["not urgent", "soon", "blocking"],
    },
    "churn_risk": {
        "type": "noul",
        "instructions": "Does the user threaten to cancel or leave?",
    },
}

result = router.predict(state, questions)

print(result["answers"]["department"]["choice"])   # -> billing
print(result["answers"]["churn_risk"]["noul"])     # -> 0.0~1.0 的概率
print(result["routing"]["model"])                  # -> english（自动选了英文 checkpoint）

4.3 多语言自动路由

同一段代码对 100+ 语言都能直接跑，Router 会自动识别脚本并把非英文文本送到 laya-multilingual：

for text in [
    "मुझसे मार्च में दो बार शुल्क लिया गया, कृपया डुप्लिकेट राशि वापस करें।",
    "La aplicación se cierra cada vez que abro la configuración.",
]:
    r = router.predict(text, {"department": questions["department"]})
    print(r["routing"]["model"], r["answers"]["department"]["choice"])
# multilingual billing
# multilingual technical

4.4 长文档

laya-multilingual 支持 max_len=8192，但默认只有 1024，长文档会被截断：

result = router.predict(long_document, questions, model="multilingual", max_len=8192)

仓库自带 bench_long_context.py，README 自报 20 条请求中 4K token 内 16~18 条正确，超过 4K 后掉到 8~17 条——强烈建议在自家数据上重测，长上下文是 Laya 的弱项，不是卖点。

⚠️ 长文档的「速度」是按真实输入长度算的，不是按 max_len：4K 输入约 1.7s（Apple GPU 实测）。

4.5 本地 HTTP 服务

仓库自带 examples/server.py（FastAPI），零代码就能起一个带 builder UI 的调试服务：

pip install "laya[serve]"
python examples/server.py            # 默认 http://127.0.0.1:8000
python examples/server.py --no-preload --device cpu   # 懒加载 + CPU

直接 curl 也行：

curl -s localhost:8000/predict \
  -H 'content-type: application/json' \
  -d '{
    "state": {"body": "We were billed twice for March. Please refund it today."},
    "questions": {
      "department": {"type": "choice",
        "instructions": "Which department should handle this?",
        "criteria": {"billing": "invoices, payments, refunds",
                     "other": "everything else"}},
      "urgency": {"type": "score",
        "instructions": "How urgent is this?",
        "criteria": ["not urgent", "soon", "critical"]}
    }
  }' | python -m json.tool

4.6 微调（可选）

零样本可用，但微调后效果跳一档：在 typed-decisions benchmark（2000 条决策 / 4 个工作流）上，微调后 laya-typed-decisions 准确率 0.766，base 英文 checkpoint 同任务只有 0.362（README 自报）。

官方 Kaggle 笔记本（laya_finetune_typed_decisions_2xT4_kaggle.ipynb）跑通了「建数据 → 训练 → 温度校准 → 评测 → 推 Hub」全流程，免费 2×T4 即可。

4.7 生态集成

文档站 nandhakishorm.github.io/laya 提供： - prediction hooks - schema-driven decisions - Docker 部署指南 - LangChain / LangGraph 集成 - 完整 API reference

5. 典型适用场景

场景	用 Laya 的理由
客服工单路由	多分类 + 置信度，低延迟；可微调到自家业务
邮件/工单优先级打分	`score` 类型天然适合有序等级
内容审核（违规/敏感）	`noul` 二元 + 概率，可设置阈值分级
表单字段语义校验	强类型输出可直接喂下游校验
多语言意图识别	Router 自动跨语言路由，单一调用
LLM 前的「分诊层」	把明显规则能搞定的分流走 Laya，只让复杂请求进 LLM，省钱省延迟

不适用的场景：

需要生成任何自然语言的任务（Laya 不做生成）
长上下文 (>4K) 的复杂推理（README 自报 4K 后准确率掉到 8~17/20）
极小样本冷启动且无法微调（base checkpoint 在自定义决策任务上 0.36 准确率不算可用）

6. 坑与注意

Python ≥ 3.10 是硬约束。huggingface_hub / transformers / torch 都要求；用 3.9 会直接装不上。
首次跑需要联网。Router 启动会下 checkpoint；CI / 离线环境必须先 huggingface-cli download。
max_len 默认 1024。长文档必须显式传 max_len=8192，否则会被截断。
CUDA OOM 后的行为：当前版本在 OOM 后会自动切到 CPU 并关掉 TileLang fast path，不再重试 CUDA——好行为，但意味着你在 GPU 满载时拿不到 CPU 兜底的 100% 性能。
长上下文准确率塌方。README 自陈：>4K token 后正确率波动 8~17/20。先在自己数据上验，别直接相信 README 给的 33 ms + 100% 准确率宣传。
AGENTS.md 给 AI 编码助手贡献规则。如果你用 Copilot/Cursor 改本仓库，注意它有专门的贡献约束。
CLI 的 --lang 是强制覆盖，不开启自动检测。Router 本身是自动路由，CLI 单命令模式默认走英文。
rl_agent_config.json 是 checkpoint 自带的，不要去源码里找；本地模型时把 checkpoint 目录路径传对就行。

7. 与同类对比

维度	Laya	LLM（自回归分类）	SetFit / sentence-transformers + 分类头
推理延迟	33 ms / 条（T4 README 自报）	0.5~3 s（取决于长度）	~10 ms（CPU 友好）
强类型输出	✅ choice/score/noul + 置信度	❌ 需要二次解析	✅ 但需自己接分类头
多语言	✅ 100+，自动路由	✅ 看底座模型	⚠️ 取决于 base embedding
长上下文	⚠️ 8K 但 4K 后掉精度	✅ 看底座	❌ 通常 512
微调数据需求	✅ 几千条即可跳一档	❌ 调不动底座	✅ 几十条即可（少样本）
价格	一次下载永久本地推理	按 token 计费	一次训练永久推理
适合「分类/打分」	✅ 主战场	⚠️ 大材小用	✅ 经典方案

核心差异：Laya 的卖点是「LLM 的输入语义理解力 + 传统分类器的速度和结构化输出」，适合「我不想让 GPT 替我做选择题，但也不想写规则」的场景。SetFit 在 CPU 上的延迟和零样本下限更好；LLM 在长上下文 + 复杂推理 + 少样本灵活 prompt 上仍是 Laya 的上位替代。

⚠️ 上面「33 ms」「0.766 准确率」等数字全部来自仓库 README 自报，未独立复现。引用前请用 bench_long_context.py 或类似脚本在自家硬件 + 业务数据上重测。

8. 一句话推荐

需要「毫秒级、强类型、可微调」的多语言文本分类 / 打分 / 二元判断时，Laya 是值得一试的轻量方案——但务必先在自家数据上跑通长上下文 benchmark，再决定能不能放进生产。

来源

GitHub README：https://github.com/NandhaKishorM/laya （fetched 2026-09-24, 200 OK）
PyPI：https://pypi.org/project/laya/
文档站：https://nandhakishorm.github.io/laya/
Hugging Face checkpoints：convaiinnovations/laya、laya-multilingual、laya-typed-decisions

不确定处

33 ms / 7.2 ms / 0.766 / 0.362 等基准数字均为仓库自报，未独立复现
长上下文 4K 后准确率 8~17/20 是 README 原话，没给出 std 或测试集分布
mmBERT-base 在 100+ 语言上的实际覆盖清单未在 README 明列，仅说「100+」