Laya 使用教程：从第一次调用到上线的完整步骤

本教程用一个真实任务——自动分派客服工单——从头到尾演示怎么使用 Laya：写结构化问题、读答案和概率、决定什么时候自动执行、批量处理工单，以及用自己的数据评估准确率。

本文假设你已经装好 Laya（pip install laya，需要 Python 3.10 或更高版本）。还没装的话，先看安装 Laya。

第 1 步：第一次调用

调用 Laya 需要两样东西：一个状态（你要它判断的文本或 JSON），和一组结构化问题。它一次前向计算就为每个问题返回答案和概率。

from laya import Router

router = Router()  # 第一次使用时会下载 checkpoint

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["routing"]["model"])                 # english

Router 会自动选模型：英文交给 laya，其他语言交给 laya-multilingual。部署成服务时，用 Router(preload=True) 一次性加载好，这样请求不用等模型加载。

第 2 步：把问题写好

问题怎么写，比任何参数都重要。Laya 有三种问题类型。

choice：多选一。 criteria 的键是返回给你的标签，值是模型真正读到的内容。给每个选项写几个词的描述，不要只写一个光秃秃的标签；再加一个 other 选项，让不寻常的工单有地方可去。

score：按等级打分。 criteria 写成从低到高的列表。返回的是期望等级，比如三级量表上得 1.8，意思是「接近阻塞」。

noul：回答是或否。 返回的是答案为「是」的概率。如果要加 criteria，键必须是 true 和 false。在英文 checkpoint 上，noul 的答案有时会受选项标签影响而不是看文本，所以请用自己的例子检查。上游给了两种办法：改写模型看到的标签，或者改成两个选项的 choice：

{"type": "choice", "instructions": "Is this review positive?",
 "criteria": {"A": "yes, the review is positive", "B": "no, the review is negative"}}

一个 choice 问题的选项最好控制在 20 个以内。所有选项共用一个固定的 token 预算（laya 是 192，另外两个 checkpoint 是 256），选项太多时每个都会被压缩，相似的选项就分不清了。

第 3 步：读懂返回结果

每个答案是一个小字典。choice 问题的答案长这样（数值仅作示意）：

{
    "type": "choice",
    "choice": "billing",
    "probabilities": {"billing": 0.91, "technical": 0.03, "other": 0.06},
    "confidence": 0.62,
    "answer_confidence": 0.91,
}

choice、score 或 noul 就是答案本身。
probabilities 列出每个选项的概率，适合记日志和排查问题。score 答案还有一个 legend，把等级编号对应回你写的标签。
answer_confidence 是返回答案的概率。做阈值判断用的就是它。 校准拟合的正是这个量，而且它在三种问题类型上含义一致。
confidence 衡量整个概率分布有多集中，没有经过校准，不要拿它和同一个阈值比较。

第 4 步：只在有把握时自动执行

有了概率，就可以只自动处理容易的情况，其余交给人工或更大的模型：

answer = result["answers"]["department"]

if answer["answer_confidence"] >= THRESHOLD:
    route_ticket(answer["choice"])
else:
    send_to_human(state, suggestion=answer["choice"])

THRESHOLD 没有通用的值。上游说明，发布的 checkpoint 置信度偏高，laya-multilingual 还没有拟合温度参数，所以阈值要用你自己的标注数据来定（第 6 步）。从 Jev 抄来的阈值也不能直接用，因为 Jev 对置信度的定义不同。

第 5 步：批量处理工单

有一批积压的工单时，用 predict_batch 对同一组问题一次性打分，结果顺序和输入一致：

import laya

agent = laya.load("convaiinnovations/laya")
states = [{"body": text} for text in ticket_texts]

results = agent.predict_batch(states, questions, batch_size=64)
for text, result in zip(ticket_texts, results):
    print(result["answers"]["department"]["choice"], text[:60])

在 GPU 上，批量处理能大幅提速；在 CPU 上提升不大，因为计算量随状态数量增长。实测数据见 Laya 在 CPU 上多快。

第 6 步：用自己的数据评估准确率

在让 Laya 处理真实工单之前，从你自己的流量里标注 50 到 200 条样本，测两个数：整体准确率，以及在你的阈值下会被自动处理的那部分的准确率。

labelled = [
    ("I was charged twice for my subscription", "billing"),
    ("The export button crashes the app", "technical"),
    # ... 你自己的样本
]
THRESHOLD = 0.8
question = {"department": questions["department"]}

correct = kept = kept_correct = 0
for text, gold in labelled:
    answer = router.predict(text, question)["answers"]["department"]
    correct += answer["choice"] == gold
    if answer["answer_confidence"] >= THRESHOLD:
        kept += 1
        kept_correct += answer["choice"] == gold

print(f"accuracy: {correct / len(labelled):.2f}")
print(f"automated: {kept / len(labelled):.0%} of tickets, "
      f"accuracy on those: {kept_correct / max(kept, 1):.2f}")

逐步调高阈值，直到自动处理部分的准确率达到你能接受的水平，再看这时还有多少比例的工单能被自动处理。如果结果不够好，先改写选项描述（第 2 步），或者用标注数据微调 Laya。

使用 Laya 时的常见错误

一个问题里选项太多。 超过 20 个左右时，调高 head_max_len，或者先用 predict_shortlist 缩小候选范围。
长文本被截断。 英文 checkpoint 默认只读 512 个 token，max_len 和 predict_long 的用法见上下文窗口。
把非英文文本交给英文 checkpoint。 用 Router，或者直接加载 laya-multilingual。
不检查就信任多语言模型的 score。 上游报告它有位置偏差：很少选第一个等级。
用 confidence 而不是 answer_confidence 做阈值判断。

浏览用例示例：工单分派、内容审核、安全防护、模型路由等
用你的标注数据微调 Laya
把 Laya 自托管成兼容 Jev 的接口
查看 Python 指南，了解每种问题类型的细节

最后对照上游仓库核验：2026 年 9 月 26 日。

Laya 使用教程：从第一次调用到上线的完整步骤

第 1 步：第一次调用

第 2 步：把问题写好

第 3 步：读懂返回结果

第 4 步：只在有把握时自动执行

第 5 步：批量处理工单

第 6 步：用自己的数据评估准确率

使用 Laya 时的常见错误

常见问题

Laya 是聊天机器人或大模型吗？

用 Laya 一定要有 GPU 吗？

不用 Python 能用 Laya 吗？

不安装能先试试吗？

下一步