10分钟上手Jev决策模型:Jev Cookbook 快速开始教程(无需 API Key 也能跑通全部代码)
10分钟上手Jev决策模型:Jev Cookbook 快速开始教程(无需 API Key 也能跑通全部代码)
Jev Cookbook 是 Datawhale 出品的 Jev 决策模型中文开源教程,用 Jupyter Notebook 手把手带你跑通 System One 判断模型的全部代码。它把「状态 state + 类型化问题 → 带概率的结构化答案」这套开发范式拆解成 11 章可运行实验:3 种问题原语(Choice / Score / Noul)、18 篇实战配方、语音智能家居、模型评测与本地微调。本教程最友好的地方在于——不配置 API Key 也能离线跑通全部代码路径,配置后同一套代码直连真实模型。
Jev 决策模型是什么?和普通大模型有什么区别?
一句话区分:
| 生成式 LLM | Jev(System One 模型) | |
|---|---|---|
| 输出 | 自由文本,需要解析 | 原生类型化答案 + 校准概率 |
| 典型任务 | 写作、开放式推理、创作 | 有限选项的分类、路由、打分、筛选 |
| 代码侧 | 解析 JSON / 正则校验 | 直接读概率,if 语句即可 |
传统软件的 if-else 决策树、以及让 Agent 自由发挥的编排,都各有痛点:前者规则爆炸、维护困难,后者判断不可控。Jev 把「判断」抽成一个可测试、可评测的组件——模型只负责给出答案和每个选项的概率,业务策略由你的代码确定性地执行。
三种问题原语覆盖绝大多数判断场景:
- Choice:从一组已定义选项中选一(如工单该给退货组还是账单组);
- Score:在一条光谱上打分(如客户语气从「平静」到「愤怒」);
- Noul:是 / 否判断(如「这条消息是否紧急」)。
提问纪律只有一条:一题只问一件事,组合交给代码。
环境一键配置:3 步跑起来
前置要求只有一个:Python ≥ 3.10。依赖清单见 main/requirements.txt(核心就是 typesafe-sdk + JupyterLab)。
第 1 步:获取教程代码
git clone https://gitcode.com/gh_mirrors/je/jev-cookbook
cd jev-cookbook/main
第 2 步:一键创建虚拟环境
main/setup_env.sh 会自动检测本机 Python 版本(优先用 uv,能自动下载 3.12),创建 .venv 并装好全部依赖:
./setup_env.sh
第 3 步:打开第一章 Notebook
.venv/bin/jupyter lab 01_认识Jev/01_认识Jev.ipynb
打开 01_认识Jev.ipynb,按顺序执行全部单元格即可完成第一次完整实验:安装依赖、连通性测试、三原语一次调用、场景地图、概率校准讲解,最后是一个「赛事指挥台」综合实验(医疗升级、补给路由、FAQ 分支)。
无需 API Key:离线模式如何跑通全部代码
教程的每个 Notebook 都内置了离线替身响应,运行模式由 JEV_RUN_MODE 环境变量控制(默认 auto):
| 模式 | 行为 | 适用场景 |
|---|---|---|
auto(默认) |
检测到 TYPESAFE_API_KEY 就调真实模型,否则回退离线示例 |
日常学习 |
offline |
强制离线,每个输出都标注「示例响应」 | 没 Key 也能完整学习 |
live |
无密钥直接报错,不回退 | 正式验收实验 |
想完整走一遍离线流程,在启动 Jupyter 前加一个环境变量即可:
JEV_RUN_MODE=offline .venv/bin/jupyter lab 01_认识Jev/01_认识Jev.ipynb
注意:离线数据用于理解响应结构和控制流,不是模型预测证据;配置 Key 后(export TYPESAFE_API_KEY=你的key,密钥不要写进 Notebook)再复跑一遍,对比真实概率分布——这正是教程推荐的核心学法:亲手改输入与问题措辞再重跑,观察概率怎么变。
第一次决策请求长什么样
教程第一章会引导你亲手发出第一次请求,结构极简:
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
client = TypeSafeClient()
response = client.system_one(
state="充电器冒烟,刚买两天,请尽快处理!",
questions={
"safety": Choice(
instructions="工单类型",
criteria={"safety": "安全隐患", "refund": "退款", "faq": "普通咨询"},
),
"urgent": Noul(instructions="消息是否紧急或有时效性"),
"frustration": Score(
instructions="客户情绪强度",
criteria=["平静陈述", "不满但礼貌", "非常愤怒"],
),
},
)
一次调用同时返回三种原语的答案,Choice 还附带完整概率分布和置信度(confidence 由概率分布形态计算:尖峰 = 高置信,分散 = 低置信)。低置信度时,你的代码应该「先询问而非行动」——这套判断门控模式是第 2、3 章的重点。响应字段详解可查阅官方文档中译版 content/introduction/quickstart.md 与 content/api.md。
跑完第一章:11 章学习地图怎么走
教程按「入门 → 实战 → 研究」分三段,各章 Notebook 均可独立运行,总导航见 main/README.md:
| 阶段 | 章节 | 你会获得什么 |
|---|---|---|
| 入门(必修) | 01 认识 Jev → 02 核心概念 → 03 架构模式 | state 设计、三原语纪律、置信度门控与扇出模式 |
| 动手(选做) | 04 实战指南(18 篇官方配方复刻)· 05 智能家居 · 06 模型评测 | 重排序、函数调用、引用核查、防护栏等配方,浏览器里语音指挥 3D 房间 |
| 深入(按需) | 07 实战应用 · 09 Agent 集成 · 10 本地模型 | 12 个可运行项目、Agent 工具调用门控、用 RLCD 微调开源同类模型 Laya |
第 4 章的 18 篇配方按任务分成四条路线:判断稳定性与分流、检索与证据、Agent 与风险控制、结构化处理,按你的业务场景挑读即可。
后续进阶:从调用到训练
当你熟悉判断接口后,教程还有两条进阶支线:
- 语音智能家居(main/05_智能家居实验/smart_home_demo/):投机提示 + 串并行编排 + 成本统计的完整应用,右侧面板展示每一次判断的概率与执行路径;
- 本地微调(main/10_本地模型/FINETUNING.md):从中文决策数据集构造到 RLCD 训练,部署一个本地 Jev 兼容服务。Jev 与 Laya 走的训练路径如下:
常见问题
没有 API Key 能学多少? 全部 11 章的代码路径都能离线执行,概率、延迟等数字来自仓库内可复核的实测输出(人工演示数据有明确标注)。
密钥安全怎么保证? 密钥只放在启动 Jupyter 的进程环境变量 TYPESAFE_API_KEY 中,不要写入 Notebook、配置文件或日志。
离线输出和真实模型输出能混着看吗? 不能。离线响应只演示程序结构,真实结果以 live 模式复跑为准,评测纪律见 main/README.md「如何读实验结果」一节。
总结
Jev Cookbook 用「10 分钟可跑通」的低门槛设计,把 Jev 决策模型从概念带到工程落地:一条命令装好环境,一个环境变量切换离线/在线模式,三种原语覆盖绝大多数判断任务。建议从 第一章 Notebook 开始,改一改问题措辞、看看概率如何变化——你很快就能把「判断」从提示词技巧,变成系统里可测试、可评测的一等公民。



