Laya Model Python 实战：结构化决策推理与自建 HTTP API

Laya 是一组开放权重的决策模型，它的设计目标不是生成大段自然语言，而是接收一段状态（state）和若干带类型的提问，直接返回类别、评分或 Yes/No 概率。它适合用在工单分流、策略判定、优先级排序这类场景——应用程序需要的是一个格式固定的答案，而不是一段还要再解析一遍的文字。如果你正在用 Python 搭建这类判断环节，或者想在自己的服务器上跑一个结构化的决策接口，这篇教程会覆盖模型构成、SDK 调用、自建 HTTP 服务以及评测数据的解读方式。站内也有对应的 Jev 工具条目可供对照。

准备工作

环境要求

运行 Laya 的 Python SDK 需要 Python 3.10 或更高版本。建议在独立的虚拟环境中安装，避免与系统包冲突。首次执行推理时，SDK 可能会从 Hugging Face 下载对应的检查点文件，因此需要可用的网络连接和足够的磁盘空间。

硬件与运行成本

开放权重意味着可以在自己的机器或服务器上完成推理，但这并不等于没有成本。权重下载、推理环境搭建、内存占用、GPU 或 CPU 的算力、后续的监控与版本更新，都需要自行承担。选型时要把这些运维开销一并算进去，而不是只比较「是否收取调用费」。

许可证

Hugging Face 上标注 Apache-2.0 的是英语版权重。其他产物以及依赖库的许可证需要分别确认，不要默认整条链路都是同一套授权条款。具体条款以官方仓库当前显示的信息为准。

模型构成

「Laya」并不是单一检查点，而是一组用途不同的模型。公开的模型卡中列出的主要构成如下：

检查点	规模	主要用途
convaiinnovations/laya	约 4.21 亿参数	英语，基于 ModernBERT-large，512 token 上下文
convaiinnovations/laya-multilingual	约 3.22 亿参数	多语言，基于 mmBERT-base，标准 1,024 token 上下文
convaiinnovations/laya-typed-decisions	约 4.21 亿参数	面向 typed-decisions 评估调优的 ModernBERT-large，1,024 token

日常使用中，Python SDK 提供的 Router 会自动判断输入语言，在英语版和多语言版之间选择。但任务特化版本是独立的检查点，Router 不一定会为任何任务自动选中它，需要显式指定。

操作步骤

第一步：创建虚拟环境并安装 SDK

python3 -m venv .venv
source .venv/bin/activate
python -m pip install laya

Windows 环境下激活命令为 .venv\Scripts\activate。安装完成后即可在 Python 中导入 Router。

第二步：理解三种提问类型

Laya 的「提问」描述的是应用程序需要的答案形状。核心类型有三种：

• choice：从一组候选项中选一个，例如 billing、technical、other。
• score：按有序标准打分，例如 routine、time-sensitive、blocking。
• noul：返回某个明确命题为真的概率。

需要注意，返回概率并不等于判断本身正确。应当用自己标注过的数据检查错误率和不确定样本，如果要用阈值做自动决策，还要同时定义人工复核的触发条件。

第三步：用 Router 做一次预测

下面的例子把一条工单作为共享 state，一次性评估负责部门、紧急程度和是否明确要求退款三个问题。

from laya import Router

router = Router()  # 首次使用时加载所需语言模型

state = {
    "subject": "Duplicate charge",
    "body": "I was billed twice. Please refund the extra payment.",
}

questions = {
    "department": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": {
            "billing": "Payments, charges, and refunds",
            "technical": "Bugs and product errors",
            "other": "A different kind of request",
        },
    },
    "urgency": {
        "type": "score",
        "instructions": "How urgent is this request?",
        "criteria": ["routine", "time-sensitive", "blocking"],
    },
    "refund_requested": {
        "type": "noul",
        "instructions": "Does the customer explicitly request a refund?",
    },
}

result = router.predict(state, questions)
answers = result["answers"]
print(answers["department"]["choice"])
print(answers["urgency"]["score"])
print(answers["refund_requested"]["noul"])

predict 的第一个参数是共享上下文，第二个参数是提问定义。输出按提问 ID 分组，每个 ID 下对应其类型字段。这个例子只展示 API 的形态，正式使用前必须用自己业务中的样本验证预测质量。

第四步：单语言与批量场景

如果只处理一种语言，也可以直接加载对应检查点，绕开 Router 的语言判断环节。面对大量相似数据时，SDK 还提供了批量推理的接口，适合离线打分或周期性重跑。

第五步：启动本地 HTTP 服务

需要被其他服务调用时，可以用 serve 扩展启动一个自建的 HTTP 服务器。

python -m pip install "laya[serve]"
export LAYA_HOST="127.0.0.1"
export LAYA_API_KEY="replace-with-a-private-random-key"
export LAYA_DEVICE="cpu"
laya-serve

服务启动后，通过 POST /v1/systemone 发起请求。该请求格式与 Jev 的线协议兼容，但模型、结果、服务条款和商用条件并不因此等同。

curl \
  -H "Authorization: Bearer $LAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": {"body": "We were billed twice. Please refund the extra charge."},
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {"billing": "Payments and refunds", "other": "Everything else"}
      }
    }
  }'

API 密钥必须自己在本地生成，不要使用示例中的占位字符串。项目中的服务器示例有时会监听 0.0.0.0:8000，开发阶段建议限制在回环地址；如果要对外公开，需要补齐认证、网络访问限制、监控和容量规划。

一个完整示例

下面把前面的步骤串成一条最小可运行链路：安装依赖、定义提问、执行预测、打印结构化结果。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install laya

python - <<'PY'
from laya import Router

router = Router()

state = {
    "subject": "Cannot log in after password reset",
    "body": "I reset my password but the app still rejects it. This blocks my whole team.",
}

questions = {
    "department": {
        "type": "choice",
        "instructions": "Which team should handle this ticket?",
        "criteria": {
            "billing": "Payments, charges, and refunds",
            "technical": "Bugs and product errors",
            "other": "A different kind of request",
        },
    },
    "urgency": {
        "type": "score",
        "instructions": "How urgent is this request?",
        "criteria": ["routine", "time-sensitive", "blocking"],
    },
    "refund_requested": {
        "type": "noul",
        "instructions": "Does the customer explicitly request a refund?",
    },
}

result = router.predict(state, questions)
answers = result["answers"]

print("department:", answers["department"]["choice"])
print("urgency:", answers["urgency"]["score"])
print("refund_requested:", answers["refund_requested"]["noul"])
PY

这段脚本会输出三个字段：负责部门、紧急程度、以及是否明确要求退款。拿到结果之后，是否真的转交、是否升级、是否退款，仍然由应用程序自己的业务规则决定，模型只负责给出结构化的判断依据。

与托管式方案的取舍

Laya 与托管式的 Jev AI Model 在接口形态上相似：都是传入 state、拿回带类型的结果。区别在于模型访问方式和运维责任的归属。

维度	Laya	Jev AI Model
模型	可下载的开放权重	托管模型，服务不分发权重
运行位置	自己的电脑或服务器	浏览器 Playground 与 API
准备条件	需要 Python/PyTorch、权重、推理环境	只需账号与 API 密钥，无需维护模型服务器
费用	无托管调用费，但有算力与运维成本	登录后的 Web Playground 免费，API 使用付费额度
控制权	自行选择检查点与主机	推理基础设施交由托管服务

想先在浏览器里试一下效果，可以用托管方案的 Playground；登录后的 Web 使用是免费的，从应用程序调用 API 则需要付费额度。价格、免费额度与可用性请以官网当前信息为准。希望自己管理权重和运行环境的团队适合 Laya，不想维护模型服务器、想直接从 Web 或 API 起步的团队可以考虑托管方案。无论选哪一边，候选答案、测试数据、阈值以及最终的业务判断规则，都要在应用侧自行设计。

如何阅读公开评测数据

Laya 仓库中的 typed-decisions 评估报告显示：任务调优版 laya-typed-decisions 的准确率为 0.766，英语基础版为 0.362，多语言基础版为 0.352，同一份报告中的多数类基线为 0.461。这说明不存在一个可以笼统称为「Laya 精度」的单一数字，必须看清是哪个检查点在哪个任务上测得的。

仓库里同时列出了来自其他公开资料的 Jev 数值，但 Laya 方面并未自行测量 Jev，样本量和提示词也没有对齐，因此这不构成受控的直接对比。

另有一份 Hugging Face 社区比较，使用 100 条英语状态产生 310 次判断，在本地 CPU 上对比英语基础版 Laya 与 Jev 1.13 API。小规模集合上报告的分数为：Laya 在分流 0.800、护栏 0.883、内容审核 0.833；Jev 分别为 0.894、0.950、0.989。但这份数据由单人手工标注英语样本，只使用了部分预设，评估的是基础版而非推荐的 Laya Router，作者本人也指出了置信区间较宽、噪声影响明显的问题。

这些数字不能用来宣布谁是普遍意义上的赢家，它们更适合作为自行设计对比实验的参考。实际做法是：在计划使用的检查点、语言、候选标签、网络环境和硬件上，用同一份留出数据做评估，并记录误分流比例、概率校准情况、真实负载下的延迟、运维成本以及人工复核的占比。

注意事项

• 格式正确不等于判断正确。 即使输出结构符合预期，误判依然会发生。退款、访问控制这类关键操作，必须保留权限校验和人工确认环节。
• 概率需要用自己的数据校准。 在把阈值用于自动批准、拦截或退款之前，先用标注样本测量准确率。
• 重点评估选项较多的提问。 类别数量越多，判断难度越大，可以考虑拆成两阶段处理。
• 多语言 Router 要分语言验证。 输入较短时，语言和字符集判断本身就可能出错。
• 公开 HTTP 服务必须加固。 认证、网络规则、监控和容量规划缺一不可。
• 模型与接口会变化。 检查点、评测内容和接口细节都可能调整，落地前请查阅模型卡与仓库的最新版本，价格、配额、许可证等信息以官网当前显示为准。