速查、配套文件与版本说明
本页把完成三个案例需要反复查阅的信息放在一起。下载 配套代码包，解压后先阅读其中的运行说明，再从项目根目录执行命令。
三条起跑命令
python -m examples.hello_jev tickets --mode offline
python -m examples.hello_jev content --mode offline
python -m examples.hello_jev route --mode offline
这些命令不需要 API Key。它们使用作者编写的响应，检查程序工作流程。准备好真实访问权限、环境变量并了解输入会发送给服务后，可将 offline 改成 live。不要把示例的模拟订单工具当成已经接入真实电商系统。
| 配置 | 作用 |
|---|---|
| TYPESAFE_API_KEY | 真实请求的认证信息，仅通过本地环境设置 |
| TYPESAFE_MODEL | 可选模型名；默认 jev-latest |
| --mode offline | 回放明确标注的教学响应 |
| --mode live | 向 TypeSafe 发送真实请求 |
| --output | 指定本地报告输出位置，详见命令帮助 |
不同系统可能使用 python3 或 py 启动 Python。选择同一个解释器执行安装、检查和运行。本书配套三个案例使用 Python 标准库；正文介绍的官方 SDK 是另一条可选接入路径。
类型与字段速查
| 类型 | 你需要定义 | 你需要读取 |
|---|---|---|
| Choice | 问题、选项与含义 | choice、probabilities、confidence |
| Score | 问题、有序等级与标准 | score、probabilities、confidence |
| Noul | 明确的真假命题 | noul |
所有问题都放在同一请求的 questions 中，材料放在 state 中。请求模型用 model 指定，响应中的模型名用于记录实际回答的版本。详细字段请查官方 API 参考。
中英术语对照
| 中文 | English | 在本书中的含义 |
|---|---|---|
| 状态／材料 | State | 判断时可以使用的输入证据 |
| 问题 | Question | 对材料提出的明确判断任务 |
| 标准 | Criteria / Rubric | 选项或等级的具体定义 |
| 选项概率 | Probability | 模型对一个候选或命题的概率判断 |
| 置信度 | Confidence | Choice/Score 分布的概括指标 |
| 复核 | Review | 由人工或另一处理流程继续确认 |
| 离线响应 | Fixture | 作者编写、用于测试程序的固定数据 |
| 留出集 | Holdout set | 未用于调参的验证样本 |
| 路由 | Routing | 为请求选择处理路径 |
| 回退 | Fallback | 正常路径不可用时的下一步 |
官方资料与用途
- Introduction：确认 Jev 的基本接口定位。
- Quick start：官方 Playground、HTTP 和 SDK 入门。
- API reference：逐字段核对请求、响应与错误状态。
- Choice、Score、Noul：三种问题的细节。
- Confidence：理解返回的置信度。
- Patterns：继续学习组合、评分与分流模式。
- Models：当前版本、价格、限制和语言支持。
本版的证据范围
本书由 CoolJev 独立制作，非 TypeSafe 官方出版物。接口事实依据官方公开文档；案例、样例数据、问题模板、业务政策和离线响应为本项目的教学设计。文档核对日为 2026 年 9 月 20 日。
本版未把离线执行结果报告成模型准确率。没有真实调用记录支持的速度、效果与费用，不写成实测结论。网页或书中明确标为“算术示例”“教学响应”的数值，仅用于解释。完整本地验证记录与配套包一起提供。
下一次更新应同时检查：接口字段、依赖说明、模型版本、价格、三条运行命令和所有下载链接。内容改变后更新版本与日期；只修改封面或排版时，不把旧实验重新标成新实验。
把第一例改成你的项目
先复制一个案例，替换输入材料，再写下你希望得到的明确结果。保留原始示例作为回归检查。用少量开发样本修改规则，在独立样本上验证后，才逐步增加任务量。
如果你还不能解释某个判断为什么应进入某条分支，先把业务规则补清楚。一个可说明、可检查、能处理失败的小流程，就是接下来扩展工作流的基础。