安装 Python SDK 并发出第一个请求：10 分钟跑通
钥匙在上一课已经拿到手了。这节课把它用起来：完成 typesafe-sdk 安装，跑通官方示例——一条客户工单，一次请求同时问三个问题，拿到「分给哪个组、客户多沮丧、是否紧急」三个答案。全程 10 分钟。
学完你能做什么
- 在独立虚拟环境里完成 typesafe-sdk 安装（Python 3.10+）
- 运行官方工单三问示例，看到
technical/0.67/0.99三行输出 - 读懂返回 JSON 里的
choice、score、noul，以及confidence、probabilities - 知道 SDK 自动读环境变量、自动处理限流重试，代码里不写密钥
- 跑不通时知道下一步去哪课排查
你现在的困境
- Key 拿到了，但 pip 装完 import 就报错，分不清是 Python 版本还是环境的问题
- 示例跑起来了，输出却是一坨 JSON，不知道哪个字段才是「答案」
- 想先跑通再说，不想一上来就啃完整本 API 文档
什么时候用这一招
当你需要：
- 在自己电脑上用 Python 调 Jev，跑通第一个真实请求
- 一个干净、不污染系统 Python 的安装方式
而且不想：
- 把 SDK 装进系统 Python，跟别的项目打架
- 一上来就手写 HTTP 请求、认证头和重试逻辑
🎒 开始前的准备
- 上一课的 Key 已存进环境变量
TYPESAFE_API_KEY - Python 3.10 或更高（官方 SDK 的版本要求；终端里
python3 --version可查） - pip 已安装（官方文档链接了 pip 官方安装页，没装的话先去装）
- 命令行用 Bash（macOS / Linux / Windows WSL——官方快速开始的命令按这个环境写）
核心思路
装什么。 官方 Python SDK 的 pip 包名是 typesafe-sdk，import 名是 typesafe_sdk。它把「拼 HTTP 请求、带认证、压缩、限流重试」都包好了，你只写 state 和问题。
为什么用 venv。 官方快速开始的 pip 路线就是「venv + pip」：虚拟环境把 SDK 装在项目目录的 .venv 里，不碰系统 Python，删掉文件夹就是干净卸载。
第一个请求长什么样。 官方示例把一条客户工单作为 state，一次请求问三个问题：
| 问题 | 题型 | 返回字段 |
|---|---|---|
| 这工单该哪个组处理 | Choice | choice + 每个选项的 probabilities + confidence |
| 客户听起来多沮丧 | Score | score（0–2，可落在两档之间）+ confidence |
| 是否紧急 | Noul | noul（0–1 的概率） |
三题对同一份 state 并行评估，一次全部返回——这是 Jev 的核心工作方式，后面 并行提问 课会把它用到极致。
SDK 替你做了三件事。
| 事 | SDK 的做法 |
|---|---|
| 认证 | 自动读环境变量 TYPESAFE_API_KEY |
| 选模型 | model="jev-latest"；不指定时 SDK 默认也是 jev-latest（当前指向 Jev 1.14） |
| 限流重试 | 遇 429 默认自动重试，等待时间逐次拉长，并遵循 retry-after |
跑通的标准。 官方示例的预期输出是三行：
technical
0.67
0.99官方同时提醒：这些是示例结果，数值可能随 Jev 版本变化。
跟我做
第 1 步：建项目目录并确认环境变量
为什么：官方快速开始从一个干净目录起步；Key 必须在环境变量里，SDK 才能自动读到。
mkdir typesafe-quickstart
cd typesafe-quickstart
export TYPESAFE_API_KEY="your-api-key"把 your-api-key 换成你的 Key（上一课存过的话，新开的终端里要重新 export 一次）。
你应该看到：三条命令都没有报错；echo $TYPESAFE_API_KEY 能打印出你的 Key。
第 2 步：完成 typesafe-sdk 安装（venv + pip）
为什么：venv 把 SDK 装进项目自己的 .venv 目录，不污染系统 Python——这是官方 pip 路线的标准做法。
python3 -m venv .venv
.venv/bin/pip install typesafe-sdk你应该看到：pip 列出要装的包并显示安装成功，包列表里有 typesafe-sdk。
- 项目文件夹里出现了
.venv目录
💡 习惯 uv 的同学
官方同样支持 uv 路线：uv init --bare 之后 uv add typesafe-sdk。uv、npm、curl 直连的完整走法在 安装备用方式 课。
第 3 步：写下官方示例 route_ticket.py
为什么：先原样跑通官方示例，再改成自己的内容——这样排错时永远有一个「已知正确」的基线。
用编辑器在项目目录新建 route_ticket.py，贴入官方快速开始的完整示例：
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
ticket = "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed."
with TypeSafeClient(model="jev-latest") as client: # Reads TYPESAFE_API_KEY.
response = client.system_one(
state=ticket,
questions={
"department": Choice(
instructions="Which team should handle this",
criteria={
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions",
},
),
"frustration": Score(
instructions="How frustrated the customer appears",
criteria=[
"Calm, just stating facts",
"Frustrated but civil",
"Very angry, strong language",
],
),
"is_urgent": Noul(
instructions="The message conveys urgency or time-sensitivity",
),
},
)
print(response.choices["department"].choice)
print(response.scores["frustration"].score)
print(response.nouls["is_urgent"].noul)你应该看到：文件保存在 typesafe-quickstart/route_ticket.py。
第 4 步：运行它，拿到三个答案
为什么：这一步是整课的目标——你的第一次真实 Jev 调用。
.venv/bin/python route_ticket.py用 .venv/bin/python 而不是系统的 python，确保用的是刚装好 SDK 的那个环境。
你应该看到：三行输出——
technical
0.67
0.99- 我看到了三行输出，第一行是
technical（工单分给技术组）
第 5 步：读懂完整返回
为什么：print 只打了三个值；真实项目里你大概率要用 probabilities 和 confidence 写分支逻辑。
官方快速开始给出的完整 JSON 返回（示例值，会随版本变化）：
官方示例的完整 JSON 返回
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "technical",
"confidence": 1.0,
"probabilities": {
"technical": 1.0,
"billing": 0.0,
"sales": 0.0
}
},
"frustration": {
"type": "score",
"score": 0.67,
"confidence": 0.5,
"legend": {
"0": "Calm, just stating facts",
"1": "Frustrated but civil",
"2": "Very angry, strong language"
},
"probabilities": {
"0": 0.33,
"1": 0.67,
"2": 0.0
}
},
"is_urgent": {
"type": "noul",
"noul": 0.99
}
},
"usage": {
"input_tokens": 428,
"output_tokens": 73
}
}三个值得注意的地方：
| 字段 | 在哪 | 含义 |
|---|---|---|
confidence | Choice / Score 的答案里 | 模型对这个答案的把握（Noul 答案没有这个字段） |
probabilities | 每个答案里 | 完整概率分布：department 是 100% 押 technical |
usage | 顶层 | 本次消耗：输入 428 token、输出 73 token（计费按输入算，输出免费） |
示例 JSON 里的 "model": "jev-1.13.0" 是官方文档示例录制时的值；你现在跑 jev-latest，返回的 model 字段取决于当前模型版本。怎么用 confidence 写分支，Confidence 置信度 课细讲。
检查点 ✅
- typesafe-sdk 装在
.venv里，不是系统 Python - 我的代码里没有出现 API Key（SDK 自动读环境变量）
- 我跑出了三行输出，知道它们分别是 Choice / Score / Noul 的答案
- 我知道答案按问题 ID 存在
response.choices/.scores/.nouls里 - 我知道示例数值可能随版本变化，不必纠结 0.67 还是 0.66
踩坑提醒
❌ ModuleNotFoundError: No module named 'typesafe_sdk'
包没装进你当前用的那个 Python。最常见原因：用系统 python 跑了装在 .venv 里的项目。正确做法：按官方示例用 .venv/bin/python route_ticket.py 运行；习惯先激活环境的同学，source .venv/bin/activate 之后用 python 也行（通用 venv 用法，官方示例没走这步）。
❌ Python 版本低于 3.10
官方 SDK 要求 Python 3.10 或更高。python3 --version 查一下；版本低了，先升级 Python，或用 3.10+ 的解释器重建 venv。
❌ 跑通了，但数值和 0.67 / 0.99 对不上
不是坏了——官方明确说示例结果会随 Jev 版本变化。看结构对不对：第一行是 billing / technical / sales 之一，第二行是 0–2 的数，第三行是 0–1 的数。结构对，就是跑通了。
❌ 改了示例跑不通，不知道哪改坏了
回到基线：先原样跑通官方示例，再一小步一小步改——先换 state 文本，再换问题，最后换题型，每改一步跑一次。真卡住了，起步排错 课按报错逐个讲。
进阶技巧（可选）
同步与异步两套客户端。 SDK 同时提供 TypeSafeClient（同步，本课用的）和 AsyncTypeSafeClient（异步），接口同名（system_one）；高并发场景换异步版。
SDK 有可选附加组件。 安装时可以带 extras：http2 开 HTTP/2 支持，pil 发 Pillow 图像，zstd 在 Python 3.13 及更早版本上压缩请求体。图像相关玩法在 Box 与图像 课。
不想用 Python？ JavaScript / TypeScript SDK 和 curl 直连 API 的走法，都在 安装备用方式 课。
本课小结
✅ typesafe-sdk 安装完成：venv + pip，装在项目的 .venv 里，Python 3.10+。
✅ 第一个请求跑通：一条工单、三个问题、一次返回——technical / 0.67 / 0.99。
✅ 你已经会读返回：答案按问题 ID 存在 choices / scores / nouls 里，概率和 confidence 都在。
关键配置字段回顾：
| 字段 | 推荐值 | 说明 |
|---|---|---|
| 包名 | typesafe-sdk | pip 安装名；import 名是 typesafe_sdk |
model | jev-latest | 别名，当前指向 Jev 1.14；不指定时 SDK 默认也是它 |
state | 字符串 / JSON 对象 / 文本数组 | 本课用了一条工单字符串 |
questions | {ID: Choice/Score/Noul(...)} | ID 自取；答案按 ID 从 choices / scores / nouls 取 |
| 环境变量 | TYPESAFE_API_KEY | SDK 自动读取，代码里不写密钥 |
下一课预告
Python 不是唯一路线：安装备用方式：uv、npm 与 curl 直连 API。
你会学到：
- 用 uv 两三条命令装好同一个 SDK
- Node.js 20+ 用
@typesafe-ai/sdk跑通同一个示例 - curl 7.76+ 直连 API，看原始 JSON 长什么样
- 按你的项目情况选哪条路线