3.1 安装与第一次 predict

本节摘要：从零到第一次决策只要三步：pip 安装 laya（Python 3.10 以上，官方口径）、创建 Router、调一次 predict——检查点会在首次调用时自动下载（官方口径），无需手动拉模型。本节给出第一个 choice 调用的完整代码，然后把返回结果逐字段拆开：answer 是 argmax 的首选、probabilities 是完整分布（分级处置的原料）、confidence 是第 7 章门控的输入、checkpoint 是第 2 章路由行为的观测窗口。随后讲自动下载的幕后与离线环境的预下载问题，最后列三个「第一次」最常见的坑：下载等待被当成卡死、zero-shot 概率平平是官方声明过的正常现象、字段形态以实测版本为准。接口写法为示意，以官方仓库 README 为准。

学习目标

完成安装并发出第一次 predict，得到结构化返回。
逐字段解释返回结果，并说出每个字段的下游用途。
理解模型自动下载的时机，会为离线或容器环境做预下载。
提前避开三个最常见的「第一次」坑。

一、安装与验证


# bash —— 安装与验证（命令以官方仓库 README 为准）
python --version                  # 需要 3.10 以上（官方口径）
python -m pip install laya        # 基础 SDK
python -c "import laya; print('laya ok')"   # 验证导入

安装就这些。不需要 GPU、不需要 API Key、不需要提前下载模型文件——首次调用时 laya 会自动下载检查点（官方口径）。建议在虚拟环境里做以上操作，保持依赖隔离（第 0.2 节建过环境的话直接用）。

二、第一次 predict


# first_predict.py —— 第一次 laya 调用（写法示意，接口以官方仓库 README 为准）
from laya import Router

router = Router()   # 默认：交给 Router 按脚本检测自动分流

result = router.predict(
    context="客户邮件：我上周三下单的空气净化器到现在还没发货，客服电话也打不通，要求马上处理。",
    questions=[
        {
            "id": "intent",
            "type": "choice",
            "question": "这封邮件属于哪个类别？",
            "options": ["物流投诉", "产品咨询", "营销推广", "其他"],
        },
        {
            "id": "urgent",
            "type": "noul",
            "question": "这封邮件需要两小时内响应吗？",
        },
    ],
)

for item in result["results"]:
    print(item["id"], "->", item["answer"], "| confidence:", item["confidence"])

两个细节值得注意。其一，一次调用可以带多个问题（上面一个 choice 一个 noul），它们共享同一段 context 的编码——这本身就是最小化的批处理。其二，示例问题故意选了业务向的措辞：第 1.2 节说过，问题与选项的措辞就是提示工程，动手阶段就要按真实业务的口吻来写，别用「测试一下」这种废问题。

predict 的输入面（参数名以官方文档为准，此处讲语义）：

输入	语义	注意
context	状态文本：被判断的对象	邮件、工单、评论原文；超长文本走第 6 章 predict_long
questions	问题列表，每项含 id、type、question	同型可混装：一次调用 choice 加 score 加 noul
options	choice 的选项表	互斥、覆盖全、留兜底项（第 1.2 节）
检查点意图	显式指定或交给 Router	第 2.2 节两种模式

预期输出类似（数值为示意值，别当真实能力）：


# first_predict_output.txt —— 运行输出示意
intent -> 物流投诉 | confidence: 0.57
urgent -> yes | confidence: 0.44

三、逐字段解读返回

完整的单问题返回形态（示意）：


# predict_return.json —— choice 问题的完整返回示意
{
  "id": "intent",
  "type": "choice",
  "answer": "物流投诉",
  "probabilities": {
    "物流投诉": 0.57, "产品咨询": 0.22, "营销推广": 0.09, "其他": 0.12
  },
  "confidence": 0.57,
  "checkpoint": "laya-multilingual"
}

字段	是什么	下游怎么用
answer	概率最高者的原文	直接消费的决策值：路由目的地、标签
probabilities	所有选项的概率分布	分级处置：首选与次选接近时进复核；分布形状是质量信号
confidence	置信度	第 7 章门控输入：低于 min_confidence 走弃权
checkpoint	实际作答的检查点	第 2 章路由观测：进日志、算错配率

读返回的顺序建议从 checkpoint 开始（这次是谁在答），再看 probabilities 的形状（它笃定吗），最后才看 answer（它说了什么）。直接跳到 answer 是最常见也最危险的读法——你消费了决策却没消费它的可信度。

四、首次运行的幕后：自动下载

第一次 predict 会比后续慢一个量级，因为触发检查点下载（官方口径：首次调用自动下载）。三件事提前知道：

下载只发生一次。 之后从本地缓存读，延迟回到官方 README 口径的 32.8 毫秒量级（单次决策，官方环境）。
磁盘要留够。 可能用到的检查点（英语、多语言、typed 特化）加起来有可观的磁盘占用，按需下载可以少占——只跑中文流量就只会拉多语言检查点。
离线与容器环境要预下载。 服务器不通外网、或容器镜像不想在运行时下载，就在有网的环境先触发一次下载，再把缓存目录带到目标环境（缓存路径以官方文档为准；第 4.2 节给容器内的做法）。

五、三个「第一次」的坑

坑一：把首次下载当卡死。 第一次调用等上几十秒到几分钟（取决于网络）是正常的，程序没有挂。给第一次调用单独跑一遍、确认下载完成，再进正式流程。

坑二：zero-shot 概率平平就怀疑装错了。 底座检查点 zero-shot 接近随机猜是官方 README 白纸黑字的声明（第 0.1 节提过）。上面的示意输出看起来还算像样，但那是示意值——真实跑出来分布平淡、置信不高，恰恰说明一切正常。解药不是重装，是第 5 章的微调。

坑三：字段名对不上就硬套。 laya 在活跃开发期，返回字段可能随版本调整。本节的字段形态以「结构与语义」为教学目标，具体键名以你安装版本的官方文档为准——对不上时先查文档再查代码，不要照着教程硬改。

坑四：多进程同时首调。 几个进程同时发起第一次调用，可能同时触发下载（各自等待、磁盘多份缓存）。正确姿势：部署后先单进程跑一次预热，再放开并发；服务化场景由启动脚本统一预热（第 4 章的做法）。

六、环境变体与预期

第一次跑通之后，给自己校准一下预期（延迟均为量级示意，以自测为准）：

环境	首次调用	稳态单次	说明
笔记本（CPU）	下载加数十秒推理	数十毫秒级	开发与调试足够
服务器（多核 CPU）	同上	官方口径 32.8 毫秒量级	生产形态
容器（限额 CPU）	依赖预下载策略	受配额影响	第 4.2 节

七、可复现性三件套

第一个 predict 跑通后，建议立刻固定三样东西，后面所有实验与排错都受益：固定样本（挑五到十条有代表性的输入存成文件，别每次手敲新句子——变量不控住，现象就不可比）；固定问题表（问题与选项的任何改动都记版本，第 5 章微调对照时靠它对齐）；固定版本（pip 依赖清单锁版本，laya 与推理栈的升级单独做、单独验证）。这三样在第 7 章校准与第 10 章排陷阱时会反复回来谢你。

本节要点回顾

三步跑通：pip 安装、Router()、predict——检查点首调自动下载（官方口径），无需 GPU 与 API Key。
一次调用可带多个问题，共享 context 编码；问题措辞要按业务口吻写。
返回读法从 checkpoint 到 probabilities 到 answer：先看谁在答、再看它笃定吗、最后看它说什么。
三个坑：首调慢是下载、zero-shot 平淡是官方声明过的正常、字段以安装版本文档为准。

单次调用跑通了，接下来把它放大：一批样本怎么组织成一次 predict_batch，decide 又怎么把「分布加解读」直接封装成「决策加置信」——下一节讲这两个进阶入口。

作者与出处

原作者：灏天文库

整理：灏天文库整理

本站整理收录，版权归原作者/开源协议所有；欢迎通过原文链接访问源仓库。