10分钟上手Jev决策模型:Jev Cookbook 快速开始教程(无需 API Key 也能跑通全部代码)

原创2026-11-13 10:34:402,274 阅读

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 把「判断」抽成一个可测试、可评测的组件——模型只负责给出答案和每个选项的概率,业务策略由你的代码确定性地执行。

传统软件、Agent 与 AI 驱动软件的三种架构对比图

三种问题原语覆盖绝大多数判断场景:

  • 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 与风险控制、结构化处理,按你的业务场景挑读即可。

用 Jev 决策模型驱动的 21 点牌桌实验:模型根据手牌概率输出 hit / double / stand 动作

后续进阶:从调用到训练

当你熟悉判断接口后,教程还有两条进阶支线:

RLCD 校准决策强化学习训练路径图,展示从预训练 LLM 到 Jev 类决策模型的分叉

语音驱动的 3D 智能家居实验界面:左侧打字或语音指令,右侧展示 Jev 判断决策追踪链路

常见问题

没有 API Key 能学多少? 全部 11 章的代码路径都能离线执行,概率、延迟等数字来自仓库内可复核的实测输出(人工演示数据有明确标注)。

密钥安全怎么保证? 密钥只放在启动 Jupyter 的进程环境变量 TYPESAFE_API_KEY 中,不要写入 Notebook、配置文件或日志。

离线输出和真实模型输出能混着看吗? 不能。离线响应只演示程序结构,真实结果以 live 模式复跑为准,评测纪律见 main/README.md「如何读实验结果」一节。

总结

Jev Cookbook 用「10 分钟可跑通」的低门槛设计,把 Jev 决策模型从概念带到工程落地:一条命令装好环境,一个环境变量切换离线/在线模式,三种原语覆盖绝大多数判断任务。建议从 第一章 Notebook 开始,改一改问题措辞、看看概率如何变化——你很快就能把「判断」从提示词技巧,变成系统里可测试、可评测的一等公民。

登录后查看全文
jev-cookbook