Jev 入门：没有 API Key，先看懂三种原语和请求结构
打开 Jev 第一课的 Notebook，我有点头疼。
概念、代码、运行结果都摆在一起，但我没有真实 API，也没有自己部署的开源模型。面对一屏屏代码，很容易产生一个疑问：我到底是在理解 Jev，还是只是在把代码跑完？
所以，这篇第一课笔记，我想先把范围缩小：
- 一个任务适不适合交给 Jev？
- Choice、Noul、Score 三种原语怎么选？
- 在程序里，怎么把材料和问题组成一次请求？
这是我现阶段的入门重点。真实效果、概率校准和部署，后面再逐步补上。本文依据 Datawhale 第一章课程导读 和配套 Notebook 整理；下面换了一个例子，方便把概念串起来。
1. 先看答案长什么样，再决定用什么工具
假设收到这样一条客户消息：
导出报表一直失败，我今晚要交材料。请问什么时候能恢复？
如果任务是"帮客户写一封解释邮件"，我需要的是一段新内容。
但如果任务是：
- 这属于故障求助、退款，还是普通咨询？
- 这位客户是否急需处理？
- 处理紧迫程度处于哪个等级？
我需要的答案范围，其实已经能提前列出来了。
Jev 的类型化判断接口适合从这类问题入手：把材料交进去，把允许的答案定义好，再让程序读取判断结果。这里描述的是接口用法，不推断服务内部怎样计算，也不预设它一定比其他模型更准、更便宜。
我给自己留的判断方法是：先问"我需要一段新内容，还是一个范围明确的判断？"
2. 三种原语，分别在问什么
"原语"这个词看起来有点抽象，先把它理解成三种基础问题类型就够了。
| 原语 | 我会怎么问 | 同一个例子 |
|---|---|---|
| Choice | 属于哪一类？ | 故障求助 / 退款 / 普通咨询 |
| Noul | 这句话成立的概率是多少？ | 客户有紧急处理需求 |
| Score | 按这把尺子，程度是多少？ | 0 可稍后处理 / 1 需要尽快处理 / 2 存在明确近期截止时间 |
Choice：类别之间没有高低顺序
"故障求助""退款""普通咨询"是不同类别，不是谁比谁高一级。
Choice 适合这样的分类问题。程序可以查看各个选项的概率，再决定怎样处理。
设计选项时，我也需要考虑边界：如果一条消息既在报故障，又明确要求退款，该按主要诉求分类，还是拆成两个问题？选项怎么定义，本身就是业务设计。
Noul：判断一句话是否成立
Noul 可以先记成：给一个命题，得到它成立的概率。
例如，"客户有紧急处理需求"。
假设概率是 0.9，它表达的是这个命题成立的可能性，不能直接读成"紧急程度 9 分"。这正是它与 Score 容易混淆的地方。
Score：先定义尺子，再看程度
Score 用于有顺序的等级。不能只说"给紧急程度打个分"，却不解释每档意味着什么。
沿用表中的 0、1、2 三档，假设得到以下分布：
- 0 档：0.1
- 1 档：0.3
- 2 档：0.6
按档位值加权，分数就是：
0 × 0.1 + 1 × 0.3 + 2 × 0.6 = 1.5
这里的 1.5 是这把尺子上的分数，不是 150% 的概率。
以上数字都是我用来解释概念的假设值，没有实际调用 API。
3. 请求怎么构造：材料和问题分开写
看 Notebook 时，我最想先找出来的，其实就是两个东西：
- state：模型可以依据的材料。
- questions：希望它回答的问题，以及答案类型和范围。
下面用 Python 展示这个结构。示例依据课程使用的 SDK 接口编写，重点是看懂字段；本文没有进行真实服务调用。
python
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
state = {
"message": "导出报表一直失败，我今晚要交材料。请问什么时候能恢复？"
}
questions = {
"intent": Choice(
instructions="这条消息的主要诉求是什么？",
criteria={
"troubleshoot": "希望排查故障或恢复功能",
"refund": "要求退款或赔偿",
"inquiry": "一般信息咨询，不涉及故障处理",
},
),
"urgent": Noul(
instructions="客户有紧急处理需求。"
),
"urgency": Score(
instructions="这条消息的处理紧迫程度如何？",
criteria=[
"可以稍后处理", # 0 档
"需要尽快处理", # 1 档
"有明确的近期截止时间", # 2 档
],
),
}这里使用 SDK 的问题对象写法。Choice 的 criteria 是类别与说明的对应关系，Score 的 criteria 是从低到高的等级列表。Noul 直接描述待判断的命题。state 是普通 Python 字典，不需要额外导入一个 State 类。SDK 问题类型定义
上面只构造材料和问题，不会请求模型。前提是当前 Python 环境已经安装 typesafe-sdk。真正调用和读取结果的形状如下，为避免误触发联网调用，这一段全部注释了：
python
# 需要先按官方说明配置 TYPESAFE_API_KEY。
# 本文未执行以下调用，也没有真实响应可展示。
#
# with TypeSafeClient() as client:
# result = client.system_one(state=state, questions=questions)
#
# print(result.choices["intent"].choice) # 类别
# print(result.choices["intent"].probabilities) # 各类别概率
# print(result.nouls["urgent"].noul) # 命题成立的概率
# print(result.scores["urgency"].score) # 等级加权分数
# print(result.scores["urgency"].probabilities) # 各等级概率这些是 SDK 的 同步调用接口 与 结果访问方式。Notebook 中的 ts.call 则是课程自己写的包装，不能把它当作安装 SDK 后就直接存在的方法。
读这段代码时，我会依次看四处：
state里有没有判断所需的事实。"intent"等字典键如何标识问题，方便程序找到对应答案。- Choice、Noul 或 Score 选择了哪种原语。
criteria是否把类别或等级含义写清楚。
材料里应放客户实际说了什么、已经知道什么。不要为了让结果"好看"，直接塞入"正确答案是故障求助"之类的结论。
即使代码可以由 AI 帮忙生成，这几处也需要自己看得懂。代码写对，只能说明请求格式可能正确；问题问对，才有机会得到有用的判断。
4. 看懂返回值之后，还差一步
假设模型判断"故障求助"的概率最高，应用可以把它送进故障处理流程；如果紧急需求的概率较高，可以进入人工优先复核队列。
这里仍然需要程序规定：什么情况下分流、什么情况下复核、失败时怎么办。
模型提供判断，业务代码负责执行规则。涉及退款、权限或其他重要操作时，不能拿一个高概率直接替代授权。
还有一个容易忽略的点：输出带概率，不代表概率已经可靠。某次返回 0.9，也不保证这次一定判断正确。要知道它在自己的业务上是否好用，仍然需要真实数据和评测。这部分我先记住边界，不在第一篇里展开。
5. 没有 API Key，离线 Notebook 到底能学什么
这是我这次最需要弄清楚的地方。
课程的离线模式会提供预先写好的示例答案，用来演示后续程序怎么读取和处理结果。它没有在本机偷偷跑一个模型。
因此：
- 改了客户消息，固定答案不会因此自动完成一次新推理。
- 单元格运行成功，能帮助检查演示流程，不等于验证了 Jev 的判断能力。
- Notebook 中已有的输出，也不能当成自己刚刚完成的实测。
我现在仍然能做的，是沿着"材料 → 问题 → 答案 → 处理规则"把流程读通。等接上真实服务，再用不同输入检查输出是否符合预期。
如果一开始就被长 Notebook 淹没，可以先定位 EXP_STATE、EXP_QUESTIONS 和 EXP_OFFLINE。它们分别对应实验材料、问题配置和离线示例答案。辅助显示、统计和封装代码，可以先知道用途，再回头细看。
6. 第一课，我先带走这些
我暂时用这几组任务检查自己的理解：
| 任务 | 我的选择 |
|---|---|
| 判断消息属于哪种业务类别 | Choice |
| 判断"这段内容与项目有关"是否成立 | Noul |
| 按"不相关、部分相关、高度相关"评价内容 | Score |
| 根据会议内容写一份总结 | 生成式模型 |
| 判断订单金额是否大于 100 元 | 普通代码即可 |
同一份材料，可以因为问题不同而使用不同原语。先把任务拆清楚，再选择接口，思路会顺很多。
对我来说，第一课的阶段目标就是：能说清哪些判断适合 Jev，能读懂一次请求怎么构造，也知道离线跑通没有证明什么。
暂时不把每一行辅助代码都吃透，也可以开始形成自己的理解。接下来真正值得练习的，是拿一个自己的场景，写出清楚的问题、选项和处理规则。
参考资料
本文是第一课的阶段性学习笔记，示例场景与解释为重新组织；文中的概率、分数均为教学假设，不构成模型效果评测。