当答案是固定选项集合中的一项时，使用 Choice。例如，哪个团队处理这张工单、产品属于哪个类目、代码片段是用哪种语言写的。如果答案是连续区间上的一个位置，请使用 Score。如果是非题，请使用 Noul。选择问题类型对三者做了比较。
Choice 的答案是 choice 中选中的选项。模型还会在 probabilities 中返回每个选项的概率，并为选中的选项返回一个 confidence 值。
示例问题：
"What programming language is this code written in"
→ options: python, javascript, typescript, go, rust, other
"What type of meeting is this based on the title and description"
→ options: standup, planning, retrospective, one on one, brainstorm, none of the above
"Which product category does this item belong to"
→ options: electronics, clothing, home garden, food and beverage
请求结构
发往 TypeSafe API 的 POST 请求体具有特定的结构。顶层有三个字段：state，要评估的内容；model；以及 questions，一个从你选定的问题 ID 到问题对象的映射。每个 Choice 问题包含以下字段：
type：始终为"choice"。instructions：模型要回答的问题。criteria：答案选项，以映射表示。每个键是一个选项名，每个值是对该选项的描述。
下面这个请求的状态是一家线上鞋店的客服工单，问题是应该由哪个团队来处理：
{
"state": "My running shoes arrived in the wrong size. Can I swap them for a size 10?",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"returns": "Exchanges, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems"
}
}
}
}问题 ID 由你选定，本例中是 department。答案会以同样的 ID 返回。模型永远看不到问题 ID。选项名和它们的描述都会发送给模型，所以请写出能区分各选项的描述。
我们的客户端 SDK 提供类型化的问题。在 Python 中，同一个问题就是一个 Choice：
from typesafe_sdk import Choice, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state="My running shoes arrived in the wrong size. Can I swap them for a size 10?",
questions={
"department": Choice(
instructions="Which team should handle this?",
criteria={
"returns": "Exchanges, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems",
},
),
},
)
print(response.answers["department"].choice)
使用 system_one 方法或 https://api.typesafe.ai/v1/systemone 端点来调用 System One 模型。model 字段选择由哪个模型处理请求。如何用 TypeSafe 构建介绍了应在代码中的哪个位置调用它。
使用我们的客户端 SDK 之一，或直接调用 HTTP API。如果是编程代理在替你编写集成代码，请先安装 TypeSafe agent skill，让它了解请求和响应的结构。
instructions 和 criteria 中的每一项都可以是字符串、对象或数组。先用字符串。当一条描述需要多种指引时再使用对象，例如选项涵盖什么、不涵盖什么，以及一些示例。参见下文的结构化 instructions 与 criteria以及 API 参考。
响应结构
响应的 answers 中，每个问题各有一条记录，键为请求中的 ID。以下是对上面示例请求的响应：
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "returns",
"confidence": 1.0,
"probabilities": {
"shipping": 0.0,
"returns": 1.0,
"billing": 0.0
}
}
},
"usage": {
"input_tokens": 328,
"output_tokens": 34
}
}
除 type 外，每个 Choice 答案包含三个值：
choice：概率最高的选项。probabilities：所有选项上的完整概率分布。所有值之和为 1。confidence：一个 0 到 1 之间的数，由probabilities的分散程度计算得出。平坦的形状，即概率分散在多个选项上，意味着低置信度；单一选项上的尖峰则意味着高置信度。
这张工单很简单，因此所有概率都落在 returns 上，置信度为 1.0。如果一张工单既提到尺码错误又提到退款未到，概率就会分散到 returns 和 billing 之间，置信度也会随之下降。
最佳实践：每次调用提出多个问题
把代码可能用到的每个 Choice 问题都放进一次请求，而不是每个问题发一次请求。问题是并行评估的。增加问题几乎不会改变响应时间，代码可以忽略不需要的答案。额外的问题仍会消耗 token。一起提出多个问题对此有完整说明；下一节展示了在一次调用中提出五个 Choice 问题。
同样的逻辑也适用于单个 Choice 问题内部的选项。一个 Choice 问题最多接受 255 个选项，每增加一个选项只消耗少量 token，所以请把完整的团队、类目或产品列表交给模型，而不是只给一个精简名单。当列表可能无法覆盖所有输入时，添加一个 other 或 none of the above 选项，让模型能够表达“其他选项都不符合”。
要通过深层层级结构或大型分类体系对文档分类，可以逐级串联 Choice 问题。层级分类实战手册展示了如何基于 Choice 概率执行束搜索，在每一级保留最优的 K 条候选路径，而不是押注单一的贪心路径。
一个更复杂的示例
上面的基础示例把工单路由到一个团队。更大的客服系统可能还需要退货原因、物流问题、客户想要什么，以及客户的语气。
下面的请求就一张比第一张更含糊的工单提出五个 Choice 问题：它涉及三个团队，而且没有说明客户想要什么。
{
"state": "Shoes arrived two weeks late and in the wrong size. Also I see two charges of $120 on my card. What are you going to do about this?",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"returns": "Exchanges, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems"
}
},
"return_reason": {
"type": "choice",
"instructions": "If the customer wants to return something, why?",
"criteria": {
"wrong_size": "The item doesn't fit",
"wrong_item": "A different product was delivered",
"damaged": "The item arrived broken or faulty",
"changed_mind": "The item is fine, the customer no longer wants it",
"other": "A return reason that fits none of the above"
}
},
"shipping_issue": {
"type": "choice",
"instructions": "If this is a shipping problem, which kind is it?",
"criteria": {
"not_delivered": "The package never arrived",
"delayed": "The package is late but still on its way",
"wrong_address": "The package went to the wrong place",
"damaged_in_transit": "The package arrived damaged",
"other": "A shipping problem that fits none of the above"
}
},
"requested_resolution": {
"type": "choice",
"instructions": "What does the customer want to happen?",
"criteria": {
"exchange": "Swap the item for a different one",
"refund": "Money back",
"replacement": "The same item sent again",
"information": "Just an answer, no action needed"
}
},
"tone": {
"type": "choice",
"instructions": "What is the customer's tone?",
"criteria": {
"calm": null,
"frustrated": null,
"angry": null
}
}
}
}其中两个 Choice 问题是投机性的：return_reason 只在 department 为 returns 时才有意义，shipping_issue 只在为 shipping 时才有意义。tone 问题描述用了 null，因为选项名本身已经足够清楚。
TypeSafe 的响应：
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "returns",
"confidence": 0.42,
"probabilities": {
"shipping": 0.04,
"billing": 0.35,
"returns": 0.61
}
},
"return_reason": {
"type": "choice",
"choice": "wrong_size",
"confidence": 1.0,
"probabilities": {
"other": 0.0,
"wrong_size": 1.0,
"changed_mind": 0.0,
"damaged": 0.0,
"wrong_item": 0.0
}
},
"shipping_issue": {
"type": "choice",
"choice": "delayed",
"confidence": 0.67,
"probabilities": {
"wrong_address": 0.0,
"other": 0.26,
"not_delivered": 0.0,
"damaged_in_transit": 0.0,
"delayed": 0.74
}
},
"requested_resolution": {
"type": "choice",
"choice": "refund",
"confidence": 0.2,
"probabilities": {
"replacement": 0.34,
"refund": 0.4,
"information": 0.02,
"exchange": 0.24
}
},
"tone": {
"type": "choice",
"choice": "frustrated",
"confidence": 0.76,
"probabilities": {
"frustrated": 0.84,
"angry": 0.16,
"calm": 0.0
}
}
},
"usage": {
"input_tokens": 589,
"output_tokens": 212
}
}
每个问题都独立地针对工单作答：
department的答案是returns，概率 0.61，但由于重复扣款，billing拿到了 0.35。这张工单同时属于两个团队，0.42 这个被分散的置信度正反映了这一点。return_reason是wrong_size，置信度 1.0，这在意料之中，因为工单里写得很清楚。shipping_issue的答案分散在delayed和other之间。这是个投机性问题，而且department没有返回shipping，所以代码可以忽略它，如下面的示例代码所示。requested_resolution的答案倾向refund（0.40），replacement和exchange分掉了其余的大部分概率，置信度为 0.20。重复扣款指向退款，尺码错误指向换货，而客户自始至终没有说要哪一种。tone的答案是frustrated，概率 0.84，置信度 0.76。
下面的示例代码只读取需要的答案、忽略其余答案，并把低置信度的答案视为“先询问、后行动”的理由：
from typesafe_sdk import Choice, TypeSafeClient
TRIAGE_QUESTIONS = {
"department": Choice(
instructions="Which team should handle this?",
criteria={
"returns": "Exchanges, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems",
},
),
"return_reason": Choice(
instructions="If the customer wants to return something, why?",
criteria={
"wrong_size": "The item doesn't fit",
"wrong_item": "A different product was delivered",
"damaged": "The item arrived broken or faulty",
"changed_mind": "The item is fine, the customer no longer wants it",
"other": "A return reason that fits none of the above",
},
),
"shipping_issue": Choice(
instructions="If this is a shipping problem, which kind is it?",
criteria={
"not_delivered": "The package never arrived",
"delayed": "The package is late but still on its way",
"wrong_address": "The package went to the wrong place",
"damaged_in_transit": "The package arrived damaged",
"other": "A shipping problem that fits none of the above",
},
),
"requested_resolution": Choice(
instructions="What does the customer want to happen?",
criteria={
"exchange": "Swap the item for a different one",
"refund": "Money back",
"replacement": "The same item sent again",
"information": "Just an answer, no action needed",
},
),
"tone": Choice(
instructions="What is the customer's tone?",
criteria={"calm": None, "frustrated": None, "angry": None},
),
}
def triage(ticket: str) -> None:
with TypeSafeClient() as client:
response = client.system_one(
state=ticket,
questions=TRIAGE_QUESTIONS,
)
answers = response.answers
department = answers["department"]
if department.confidence < 0.3:
# Not clear which team to send to. Let a person decide.
send_to_manual_triage(ticket)
return
if department.choice == "returns":
# return_reason answer is only used here
assign(ticket, team="returns", issue=answers["return_reason"].choice)
elif department.choice == "shipping":
# shipping_issue answer is only used here
assign(ticket, team="shipping", issue=answers["shipping_issue"].choice)
else:
assign(ticket, team="billing")
# A second team with a real share of the probability gets a copy
for team, probability in department.probabilities.items():
if team != department.choice and probability > 0.25:
notify(ticket, team=team)
resolution = answers["requested_resolution"]
if resolution.confidence < 0.5:
# The customer hasn't said what they want. Ask, don't guess.
ask_customer_what_they_want(ticket)
elif resolution.choice == "refund":
flag_for_refund_approval(ticket)
if answers["tone"].choice == "angry":
flag_for_senior_agent(ticket)
对上面那张工单，这段代码把工单分给退货团队，问题标记为 wrong_size；由于 billing 的概率份额 0.35 超过了 0.25 的阈值，给计费团队抄送了一份；又由于解决方案的置信度 0.20 低于 0.5，转而询问客户想要什么。代码没有使用 shipping_issue 的答案。
一次请求，五个答案，而路由逻辑只是普通的 if 语句。如果之后你还需要知道客户的语言，或者工单涉及哪个产品，只需向 TRIAGE_QUESTIONS 再加一个 Choice 问题；请求数仍然保持为一次。
智能家居助手演示在一次调用中用一长串 Choice 问题评估每个用户请求：请求类别、房间、设备和动作。其中大多数问题与任何一个具体请求都无关，代码会忽略它们。
结构化 instructions 与 criteria
先从每个选项一行描述开始。当两个选项相近、模型总是混淆它们时，改用对象而不是字符串来描述每个选项。给对象一些字段：该选项涵盖什么、什么应归入相邻选项，以及几个示例输入。
下面的两个答案选项 return_policy 和 return_status 很容易混淆。关于其中任何一个的工单都可能提到退货和退款，因此每个选项都说明了它不用于什么。
{
"state": "I sent the shoes back a week ago. When do I get my money?",
"questions": {
"return_topic": {
"type": "choice",
"instructions": {
"question": "Which returns topic is the customer asking about?",
"focus": "Classify the information the customer wants."
},
"criteria": {
"return_policy": {
"what": "Whether and how an item can be returned",
"not_for": "Progress of a return already sent",
"examples": [
"Can I return shoes I've worn once?",
"How long do I have to return an order?"
]
},
"return_status": {
"what": "Progress of a return already sent",
"not_for": "Whether and how an item can be returned",
"examples": [
"Has my return arrived yet?",
"When will my refund be paid?"
]
}
}
}
}
}响应是 return_status，置信度 1.0：
{
"model": "jev-1.13.0",
"answers": {
"return_topic": {
"type": "choice",
"choice": "return_status",
"confidence": 1.0,
"probabilities": {
"return_policy": 0.0,
"return_status": 1.0
}
}
},
"usage": {
"input_tokens": 407,
"output_tokens": 32
}
}
字段名 question、focus、what、not_for 和 examples 不是 API 的一部分，也都不保留。它们由你来定，就像你选定选项名一样。模型会连同值一起看到这些名字，所以请使用能概括后续内容的简短名字。