Choice

Choice

Choice 是 System One 的一种问题类型，用于从给定的一组选项中选出一个。答案包含选中的选项、每个选项的概率，以及置信度。

当答案是固定的一组选项之一时，就用 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 技能，它才知道请求和响应的形状。

响应结构

响应里每个问题在 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 问题逐层串起来。层级分类 cookbook展示了如何在 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；给账单团队也抄送一份，因为它 0.35 的份额超过了 0.25 的阈值；并去问客户想要什么，因为解决方案的置信度 0.20 低于 0.5。代码没有用到 shipping_issue 的答案。

一次请求，五个答案，而路由逻辑就是普通的 if 语句。以后如果需要知道客户的语言，或这张工单涉及哪个产品，就往 TRIAGE_QUESTIONS 里再加一个 Choice 问题；请求次数仍然是一次。

智能家居助手 demo在一次调用里用一长串 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 的一部分，也都不保留。它们由你自选，就像选项名一样。模型会连同值一起看到这些名字，所以用简短、能说明后面内容的字段名。