10分钟发出第一次Jev类型化决策调用:Awesome Jev快速上手教程(JS/Python官方SDK实战)

原创2026-11-15 18:35:221,427 阅读

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 负责判断,你的代码负责决定。 标准流程分四步:

  1. 把上下文(例如一条客户工单)作为 state 发给 Jev;
  2. 在同一次请求里问多个类型化问题(Choice / Score / Noul);
  3. Jev 返回每个问题的类型化答案,并附带概率;
  4. 你的应用代码按阈值决定路由、转人工或回退。

Jev 类型化决策调用流程图:输入上下文经 Jev 模型判断,输出 Noul、Choice、Score 概率,再由你的代码阈值转换为动作

三种"题型"决定答案的形状,先记住这张对照表:

题型 适合的问题 返回什么
Choice 在多个命名选项中做选择(账单 / 技术 / 其他) 选中项 + 每个选项的概率 + 置信度
Score 有序量表评分(平静 / 担忧 / 愤怒) 量表位置 + 各级别概率 + 置信度
Noul 明确的"是/否"判断(是否明确要求退款?) 0–1 之间的"是"概率

还有一条好记的选型原则——该用谁就用谁:

这个步骤需要什么 用什么 例子
对已知字段执行明确规则 代码 检查账户标志、执行路由阈值
在混乱上下文中做有界判断 Jev 把工单分到 billing / technical 并给出概率
生成文字或处理开放式任务 文本 LLM 路由确定后,起草回复话术

📦 准备工作:API Key 与官方 SDK 安装

第一次 Jev 调用只需要三样东西:一个 API Key、一个官方 SDK、一段十几行的代码。

  1. 从 TypeSafe Console 创建你的 API Key;
  2. 把密钥写入环境变量 TYPESAFE_API_KEY(千万不要写进代码或提交到仓库);
  3. 按语言安装官方 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 存档响应)展示了"一个输入、三个类型化答案"的完整形态:

Jev 快速上手存档响应示例:一条工单输入同时返回 Choice=technical、Score=1、Noul=1.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 打标),动作阈值全部留在代码里,是很好的"抄作业"起点:

Jev Cookbook 社区项目卡片:15 个可运行的类型化决策配方,覆盖客服分流、数据清洗与搜索

→ 项目页:projects/gh-nexibeo-jev-cookbook.html

Learn Jev end to end——12 个 Python notebook 的完整课程,把 Jev 放进一个手写 Agent 循环,分别当路由器、工具调用守卫、完成度判断器:

Learn Jev end to end 社区项目卡片:12 个 Python notebook 构成的 Jev 端到端教程

→ 项目页:projects/gh-harshithsunku-learn-jev-end-to-end.html

Jev by Example——10 道 MIT 许可的 JavaScript 练习题,每题都是"类型化问题 + 显式应用策略"配对,离线演示连 API Key 都不需要:

Jev by Example 社区项目卡片:10 道 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、自身不发请求:

Building with TypeSafe Jev 社区项目卡片:面向编码 Agent 的 Jev API 形状速查与 150+ 项目索引

✍️ 贡献你的 Jev 项目

做出了自己的 Jev 应用?按 CONTRIBUTING.md 的规范写一条 README 条目并提交即可——一次一条目、附上限制说明就能过审。


快速回顾:API Key → 官方 SDK → 一个 state + 若干类型化问题 → 概率回来 → 你的代码做决定。恭喜走完了 Jev 类型化决策调用的最小闭环,剩下的功课只有一个:把阈值调到你自己的数据上。

登录后查看全文
awesome-typesafe-jev