告别 Prompt 解析！用 Jev 让 AI 直接返回结构化决策 —— Python SDK 实战
你还在让 LLM “返回 JSON” 然后苦苦解析吗？TypeSafe 的 Jev 模型换了一种思路：不生成文本，直接返回类型化的决策结果。
一、Jev 是什么？
Jev 是 TypeSafe 推出的旗舰模型，也是首个 System One 模型。
它和 LLM 最大的区别：LLM 为人生成文本，Jev 为代码做决策。
你给它一段内容（称为 State），再提出类型化的问题（Choice / Score / Noul），它直接返回结构化答案 + 概率分布 + 置信度。不需要解析，不需要正则，代码拿来就用。
三种问题类型一览：
| 问题类型 |
用途 |
返回值 |
| Choice |
从固定选项中选一个 |
选中项 + 各选项概率 + 置信度 |
| Score |
按评分标准打分 |
分数 + 各级别概率 + 置信度 |
| Noul |
判断是否属实 |
概率值 (0-1) |
二、获取 API Key
在写代码之前，你需要先拿到 API Key。
步骤 1：注册账号
打开 TypeSafe 控制台：https://console.typesafe.ai
使用 GitHub 或邮箱注册登录。
步骤 2：创建 API Key
登录后进入 Keys 页面：https://console.typesafe.ai/keys
点击 “Create API Key” 按钮，生成一个新的密钥。
密钥只会显示一次，请务必妥善保存。
步骤 3：配置环境变量
将 API Key 设置为环境变量，SDK 会自动读取：
1
2
3
4
5
6
7
8
|
export TYPESAFE_API_KEY="tsk-your-api-key-here"
$env:TYPESAFE_API_KEY = "tsk-your-api-key-here"
set TYPESAFE_API_KEY=tsk-your-api-key-here
|
想先试试？
不想写代码也可以先体验：打开 Playground（https://console.typesafe.ai/playground），粘贴文本、添加问题，直接看结果。
三、安装 Python SDK
1
2
3
4
5
|
pip install typesafe-sdk
uv add typesafe-sdk
|
要求 Python >= 3.10。
四、初始化客户端
1
2
3
4
5
| from typesafe_sdk import TypeSafeClient
client = TypeSafeClient()
|
就这么简单，不需要手动传 API Key。
五、三种问题类型详解
1. Choice —— 从选项中选一个
场景：客服工单自动分配
1
2
3
4
5
6
7
8
9
10
| from typesafe_sdk import Choice
question = Choice(
instructions="这个工单应该由哪个团队处理？",
criteria={
"billing": "付款、发票、退款或订阅相关问题",
"technical": "Bug、集成失败或技术问题",
"sales": "定价、套餐咨询或账户问题",
},
)
|
2. Score —— 按标准打分
场景：评估客户愤怒程度
1
2
3
4
5
6
7
8
9
10
| from typesafe_sdk import Score
question = Score(
instructions="客户看起来有多生气？",
criteria=[
"平静，只是陈述事实",
"有些不满但态度文明",
"非常愤怒，使用了激烈言辞或威胁离开",
],
)
|
3. Noul —— 判断是或否
场景：检测客户是否要求转人工
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| from typesafe_sdk import Noul, NoulCriteria
question = Noul(
instructions="这条消息是否表达了紧急性？",
)
question = Noul(
instructions="客户之前是否联系过支持团队？",
criteria=NoulCriteria(
true="提到了之前的联系记录、工单号，或表示已经问过多次",
false="没有任何之前联系的迹象",
),
)
|
六、完整实战：中文客服工单分类系统
下面是一个完整的中文场景示例 —— 收到一条客户消息后，一次调用完成工单分类、紧急度判断和情绪评分：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
| from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
client = TypeSafeClient()
ticket = "我买的跑步鞋尺码发错了，大了两码。这已经是第二次出错了，上次换货等了两周。请尽快处理，不然我要申请退款了。"
response = client.system_one(
state=ticket,
questions={
"department": Choice(
instructions="这条消息应该由哪个团队处理？",
criteria={
"returns": "退换货、商品发错、质量问题",
"shipping": "物流状态、配送延迟、包裹丢失",
"billing": "扣款、发票、支付问题",
},
),
"frustration": Score(
instructions="客户看起来有多生气？",
criteria=[
"平静，只是陈述事实",
"有些不满但态度文明",
"非常愤怒，使用了激烈言辞或威胁离开",
],
),
"is_urgent": Noul(
instructions="这条消息是否表达了紧急性或时间敏感性",
),
},
)
answers = response.answers
print(f"分配团队: {answers['department'].choice}")
print(f"置信度: {answers['department'].confidence}")
print(f"愤怒评分: {answers['frustration'].score}")
print(f"紧急程度: {answers['is_urgent'].noul}")
|
预期输出类似：
1
2
3
4
| 分配团队: returns
置信度: 0.92
愤怒评分: 1.6
紧急程度: 0.85
|
七、进阶：结构化 State + 置信度路由
真实场景中，state 往往不是一段简单文本，而是包含多条信息的结构化 JSON。
下面是一个更贴近生产的例子 —— 传入工单、订单和退款政策的结构化数据，根据置信度决定是自动处理还是转人工：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
| from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
state = {
"ticket": {
"subject": "重复扣款",
"messages": [
{"from": "customer", "text": "订单 A-104 被扣了两次款，请退还多扣的那笔。"},
{"from": "support", "text": "我们正在核实扣款记录。"}
]
},
"order": {
"id": "A-104",
"charges": [
{"amount_usd": 49, "status": "captured"},
{"amount_usd": 49, "status": "captured"}
]
},
"refund_policy": "重复扣款符合退款条件。"
}
questions = {
"refund_requested": Noul(
instructions="`ticket.messages[0].text` 中客户是否请求了退款？",
),
"policy_supports": Noul(
instructions="`refund_policy` 是否支持 `ticket.messages[0].text` 中的退款请求？",
),
"department": Choice(
instructions="`ticket.messages[0].text` 应该由哪个团队处理？",
criteria={
"billing": "扣款、发票、退款相关",
"orders": "订单状态、配送、取消",
"account": "登录、权限、安全",
},
),
"frustration": Score(
instructions="`ticket.messages[0].text` 中客户看起来有多不满？",
criteria=[
"平静，只是陈述事实",
"不满但文明",
"非常愤怒，言辞激烈",
],
),
}
with TypeSafeClient() as client:
response = client.system_one(state=state, questions=questions)
answers = response.answers
if answers["department"].confidence < 0.5:
print("模型不确定，转人工处理")
elif answers["department"].choice == "billing":
if answers["refund_requested"].noul > 0.7 and answers["policy_supports"].noul > 0.7:
print("确认退款请求，且政策支持 → 自动发起退款流程")
else:
print("需要人工核实退款条件")
if answers["frustration"].score >= 1.5:
print("客户情绪较差，标记为高优先级")
else:
print("普通优先级")
|
这段代码展示了三个关键能力：
- 结构化 State：用 JSON 对象传入多条关联信息，问题中用
`path` 语法精确引用
- 一次调用，多个问题：4 个问题并行评估，一次 API 调用搞定
- 置信度路由：
confidence < 0.5 时转人工，> 0.7 时自动执行，让你的系统既智能又安全
八、核心要点回顾
- 不需要解析文本 —— Jev 返回的就是类型化的值，代码直接用
- 一次调用，多个问题 —— 问题并行评估，几乎不增加响应时间
- 置信度是安全阀 —— 不确定时转人工，确定时自动执行
- 代码保持控制权 —— 权重、阈值、路由逻辑全在你手里
- 投机性提问 —— 问所有可能需要的问题，代码决定用哪些
九、快速参考
如果这篇文章对你有帮助，欢迎点赞、在看、转发。有问题欢迎留言讨论。
