10分钟发出第一次Jev类型化决策调用:Awesome Jev快速上手教程(JS/Python官方SDK实战)
10分钟发出第一次Jev类型化决策调用:Awesome Jev快速上手教程(JS/Python官方SDK实战)
Jev 是 TypeSafe 推出的 System One 决策模型:它不写文章、不聊天,而是把一段上下文(state)变成带概率的类型化答案。本文是一份 Jev 快速上手指南,借助 Awesome Jev(awesome-typesafe-jev,Jev 生态社区资源指南)带你用 JavaScript 或 Python 官方 SDK 在 10 分钟内发出第一次 Jev 类型化决策调用,并讲透返回结果里的概率与阈值该怎么读。
🧠 30秒建立认知:Jev 类型化决策调用是怎么回事
一句话:Jev 负责判断,你的代码负责决定。 标准流程分四步:
- 把上下文(例如一条客户工单)作为
state发给 Jev; - 在同一次请求里问多个类型化问题(Choice / Score / Noul);
- Jev 返回每个问题的类型化答案,并附带概率;
- 你的应用代码按阈值决定路由、转人工或回退。
三种"题型"决定答案的形状,先记住这张对照表:
| 题型 | 适合的问题 | 返回什么 |
|---|---|---|
| Choice | 在多个命名选项中做选择(账单 / 技术 / 其他) | 选中项 + 每个选项的概率 + 置信度 |
| Score | 有序量表评分(平静 / 担忧 / 愤怒) | 量表位置 + 各级别概率 + 置信度 |
| Noul | 明确的"是/否"判断(是否明确要求退款?) | 0–1 之间的"是"概率 |
还有一条好记的选型原则——该用谁就用谁:
| 这个步骤需要什么 | 用什么 | 例子 |
|---|---|---|
| 对已知字段执行明确规则 | 代码 | 检查账户标志、执行路由阈值 |
| 在混乱上下文中做有界判断 | Jev | 把工单分到 billing / technical 并给出概率 |
| 生成文字或处理开放式任务 | 文本 LLM | 路由确定后,起草回复话术 |
📦 准备工作:API Key 与官方 SDK 安装
第一次 Jev 调用只需要三样东西:一个 API Key、一个官方 SDK、一段十几行的代码。
- 从 TypeSafe Console 创建你的 API Key;
- 把密钥写入环境变量
TYPESAFE_API_KEY(千万不要写进代码或提交到仓库); - 按语言安装官方 SDK:
# JavaScript(Node.js 20+)
npm install @typesafe-ai/sdk
# Python(Python 3.10+,也可 pip install typesafe-sdk)
uv add typesafe-sdk
💡 官方 SDK 会自动读取
TYPESAFE_API_KEY环境变量,代码里无需手写认证。
⚡ JavaScript 实战:发出第一次 Jev 类型化决策调用
把下面这段存为 first-decision.mjs,运行 node first-decision.mjs。它把一条合成工单连同两个问题一次性发给 Jev:一个 Choice(该归哪个团队)+ 一个 Noul(是否明确索要退款)。
import { choice, noul, TypeSafeClient } from '@typesafe-ai/sdk';
const { answers } = await new TypeSafeClient().systemOne({
state: { ticket: 'I was charged twice. Please refund the extra payment.' },
questions: {
team: choice('Which team should handle this ticket?', {
billing: 'Payments and refunds',
technical: 'Bugs and integrations',
other: 'None of the above',
}),
refund: noul('Does the customer explicitly request a refund?'),
},
});
const team = answers.team.choice;
const probability = answers.team.probabilities[team];
const action = team !== 'other' && probability >= 0.9
? `route to ${team}` : 'send to review';
console.log({ team, probability, refundProbability: answers.refund.noul, action });
运行后即可看到:Choice 选中了哪个团队、每个选项的概率、Noul 的概率,以及你的代码根据阈值计算出的动作:
{ team: 'billing', probability: 0.94, refundProbability: 0.99, action: 'route to billing' }
🐍 Python 实战:同一张工单,换一种写法
Python 官方 SDK 的写法几乎一一对应,存为 first_decision.py 后运行 python3 first_decision.py:
from typesafe_sdk import Choice, Noul, TypeSafeClient
with TypeSafeClient() as client:
result = client.system_one(
state={"ticket": "I was charged twice. Please refund the extra payment."},
questions={
"team": Choice(
instructions="Which team should handle this ticket?",
criteria={
"billing": "Payments and refunds",
"technical": "Bugs and integrations",
"other": "None of the above",
},
),
"refund": Noul(instructions="Does the customer explicitly request a refund?"),
},
)
team = result.choices["team"].choice
probability = result.choices["team"].probabilities[team]
action = f"route to {team}" if team != "other" and probability >= 0.9 else "send to review"
print({
"team": team,
"probability": probability,
"refund_probability": result.nouls["refund"].noul,
"action": action,
})
至此,你的第一次 Jev 类型化决策调用已经完成 🎉 记住两个关键细节:
- 一次请求可以问多个独立问题,比逐个调用更省成本,这也是 Jev 的典型用法;
- 示例里
0.9的路由阈值是你的业务代码定的,不是 Jev 的行为——模型只给概率,动作永远由你决定。
📊 读懂返回结果:概率、阈值与官方文档示例
TypeSafe 官方文档中的客服工单示例(jev-1.13.0 存档响应)展示了"一个输入、三个类型化答案"的完整形态:
| 输入或答案 | 文档记载的值 |
|---|---|
| 工单内容 | "连接 Stripe 三天一直失败,正在损失销售,请尽快帮忙" |
| Choice | technical,选中概率 0.85 |
| Score | 0–2 烦躁量表上的 1(烦躁但有礼貌) |
| Noul | 紧急程度概率 1.0 |
阈值策略可以直观地感受一下——同样的答案(technical,0.85),阈值不同,动作就不同:
| 策略输入 | 示例值 | 应用代码的动作 |
|---|---|---|
| 选中团队 | technical |
— |
| 选中概率 | 0.85 |
— |
| 起始阈值 | 0.90 |
概率未达标 → 转人工复核 |
| 阈值下调 | 0.80 |
概率达标 → 自动路由到 technical |
⚠️ 给生产环境的一句忠告:以上阈值都是教学示例,不是实测运行点。仓库里收录的社区独立测试(见 独立评测分类页)反复表明:Jev 的概率校准、弃权行为和排序能力都依赖具体任务与数据分布,上线前务必在自己的标注样本上量一遍错误率与弃权率。
🧭 下一步:用 Awesome Jev 继续深入
awesome-typesafe-jev 仓库里有一份完整"地图",按需求取用:
- 📚 README.md:官方资源清单 + 150 多个社区项目,按"客户端库 / Agent 工具 / 浏览器 Agent / 应用工作流 / 游戏与机器人 / 独立评测 / 案例笔记"七大类组织;
- 🗂 resources.json:由 README 生成的机器可读目录,适合脚本和 AI 编程助手直接消费;
- 🤖 用编程 Agent 开发?读 skills/awesome-jev/SKILL.md,让 Claude Code、Codex 等按这份技能清单来搭 Jev 工作流。
🎓 三个值得跟做的练习项目
Jev Cookbook——15 个可运行配方(客服分流、数据清洗、搜索、Gmail 打标),动作阈值全部留在代码里,是很好的"抄作业"起点:
→ 项目页:projects/gh-nexibeo-jev-cookbook.html
Learn Jev end to end——12 个 Python notebook 的完整课程,把 Jev 放进一个手写 Agent 循环,分别当路由器、工具调用守卫、完成度判断器:
→ 项目页:projects/gh-harshithsunku-learn-jev-end-to-end.html
Jev by Example——10 道 MIT 许可的 JavaScript 练习题,每题都是"类型化问题 + 显式应用策略"配对,离线演示连 API Key 都不需要:
→ 项目页:projects/gh-reallyartificial-jev-by-example.html
🛠 让编码 Agent 记住 Jev 的 API 形状
如果你用 Claude Code / Codex 这类 Agent 写 Jev 集成,可以看看 Building with TypeSafe Jev 这个 Agent Skill:它收录了 Choice / Score / Noul 的请求形状、cookbook 阈值与社区踩坑记录,纯 Markdown、自身不发请求:
✍️ 贡献你的 Jev 项目
做出了自己的 Jev 应用?按 CONTRIBUTING.md 的规范写一条 README 条目并提交即可——一次一条目、附上限制说明就能过审。
快速回顾:API Key → 官方 SDK → 一个 state + 若干类型化问题 → 概率回来 → 你的代码做决定。恭喜走完了 Jev 类型化决策调用的最小闭环,剩下的功课只有一个:把阈值调到你自己的数据上。





