结构化输出

前面三节，我们都在教模型「怎么把话说好」。这一节换一个方向：怎么让模型把话说成程序能直接读的样子。你写一个应用，需要模型返回一个订单对象——里面有商品名、数量、单价、是否加急。模型很乐意帮你，可它今天返回 {"qty": 3}，明天返回 {"quantity": "三"}，后天在 JSON 前面加一句「好的，这是您要的结果：」。你的程序当场崩掉。这一节要讲的，就是把这件事从「求模型配合」变成「结构上不可能出错」的那套机制：JSON Schema、受约束解码、strict 模式、function calling 与 tool use。顺带我们还要拆一个流传很广的说法——「OpenAI 保证 100% 符合 schema」，这句话哪儿说对了，哪儿说漏了。

先把「结构化输出」这个词彻底说清

结构化输出（Structured Outputs）这个词听着玄，其实就是一句话：让模型返回的不是一段人读的话，而是一份程序能直接解析的数据。

什么叫「程序能直接解析」？举个最直白的对比。你让模型帮你分析一条用户评价，两种回答方式：

【方式一 · 自然语言】
这条评价整体偏正面，用户主要称赞了物流速度，
但对包装有些不满意。我判断情感倾向为 4 分（满分 5 分）。

【方式二 · 结构化】
{
  "sentiment": "positive",
  "score": 4,
  "aspects": [
    { "topic": "logistics", "polarity": "positive" },
    { "topic": "packaging",  "polarity": "negative" }
  ]
}

方式一读起来更亲切，但你的程序拿它没办法——你得写正则去抠「4 分」，抠出来还得判断是不是「4.5 分」，还得处理模型改口说「四分」的情况。方式二可以一行代码解决：json.loads(text)["score"]。换成大白话：方式一是手写的便签，方式二是填好的表格。人看便签方便，机器看表格方便。

这里要先纠正一个常见的理解偏差。很多人以为结构化输出是「模型的一个高级功能，让它变聪明了」。完全不是。结构化输出不会让模型的判断变准一点点——它判断这条评价是 4 分还是 3 分，跟有没有开结构化输出毫无关系。它保证的只有一件事：格式对。内容对不对，还是靠模型本身的能力，靠你前三节学的那些提示词技巧。

把这件事分清很重要，因为它决定了你排查问题的方向：程序解析报错，是格式问题，开结构化输出能治；模型把「加急」判断错了，是理解问题，得改提示词或换模型，开一百遍结构化输出也没用。

为什么「求模型配合」这条路走不通

在结构化输出这套机制出现之前，全世界的开发者都在用三种土办法，而这三种办法都有各自的死法。这段值得讲清，因为它解释了为什么后来要动到解码层去。

土办法一：在提示词里跪着求。「请只返回 JSON，不要有任何其他文字，不要加代码块标记，不要解释。」这句话大概是人类写给 AI 的话里重复次数最多的一句。它大部分时候有效——问题就在「大部分」。假设成功率 97%，听起来很高，可你一天处理十万条请求，就有三千条崩掉。打个比方：这就相当于一家餐厅在门口贴「请勿大声喧哗」，绝大多数人会遵守，但你没法靠这张纸保证今晚绝对安静。

土办法二：事后清洗 + 重试。拿到回复先把前后的废话切掉，把三个反引号加 json 这类代码围栏标记剥掉，然后 json.loads，失败就重新问一遍。这条路能把成功率推到 99.9%，代价是：每次重试都要重新付一遍钱、重新等一遍时间，而且你永远不知道那 0.1% 什么时候撞上一个关键用户。更麻烦的是「合法 JSON」和「我要的 JSON」是两回事——模型可能返回一个语法完全正确、但字段名写成 quantity 而不是 qty 的对象，json.loads 顺利通过，你的程序在下一行才炸。

土办法三：给一堆示例（Few-shot）。这招确实有用，我们在 §10.2 专门讲过——示例比说明书好使。但它治的是「模型不知道你想要什么样子」，治不了「模型偶发地想加一句客套话」。而且示例要占 token，格式复杂时示例得写好几个，成本不低。

看这张表的最后一行你就明白思路转向了哪里：既然「让模型配合」永远只能逼近 100%，那就换个思路——不让它有机会不配合。

JSON Schema：那张印好格子的表格

要让机器检查格式，先得有一份「格式说明书」，而且这份说明书本身也得是机器能读的。这就是 JSON Schema（JSON 模式，读作「JSON 斯基马」）。

JSON Schema 说白了就是：用 JSON 写的一份「这个 JSON 该长什么样」的规定。它规定有哪些字段、每个字段是什么类型（字符串还是数字）、哪些字段必须有、字符串只能从哪几个词里选、数组里装的是什么。

直接看一份完整实例。假设我们要从一段自然语言里抽出一个外卖订单：

{
  "type": "object",
  "properties": {
    "customer": {
      "type": "string",
      "description": "下单人姓名，从原文中原样抄出，不要编造"
    },
    "items": {
      "type": "array",
      "description": "订单里的所有商品行",
      "items": {
        "type": "object",
        "properties": {
          "name":  { "type": "string" },
          "qty":   { "type": "integer" },
          "price": { "type": "number" }
        },
        "required": ["name", "qty", "price"],
        "additionalProperties": false
      }
    },
    "urgent": {
      "type": "boolean",
      "description": "原文是否明确表达了加急需求"
    },
    "channel": {
      "type": "string",
      "enum": ["app", "phone", "walk_in"],
      "description": "下单渠道，只能是这三个值之一"
    }
  },
  "required": ["customer", "items", "urgent", "channel"],
  "additionalProperties": false
}

逐个字段翻译一遍，这些术语一个都不许留着不解释：

• "type": "object"最外面是一个「对象」——也就是用大括号包起来、里面是「键：值」成对出现的那种结构。好比一整张表格，而不是一句话。
• properties「有哪些格子」。这里列了四格：下单人、商品清单、是否加急、下单渠道。
• required「哪些格子必须填」。列进这个数组的字段，模型不许省略。相当于表格上打星号的必填项。
• additionalProperties: false「不许自己加格子」。没有这一句，模型可能热情地多给你一个 note 字段，你的程序未必扛得住。相当于表格背面写着「请勿在空白处另附说明」。
• "type": "array" 配 items「这一格里装的是一串同类东西，每一个又长这样」。商品清单里可以有一行也可以有十行，但每一行都必须有名称、数量、单价。
• enum「只能从我给的这几个词里挑」。渠道只能是 app、电话、到店三个值。这一条极其好用——它把「分类」问题从「模型自由发挥」变成了「从选项里选一个」，相当于把填空题改成了选择题。
• description写给模型看的说明。★这一栏被严重低估——它是 schema 里唯一能承载语义指令的地方，「原样抄出不要编造」这种话写在这里，比写在系统提示词里更贴近字段本身。

注意 description 那一条。很多人把 schema 当成纯粹的类型声明，只填 type 就交差了，这是浪费。schema 里的每个 description 都会随请求一起进入模型的上下文，它就是贴在格子旁边的小字提示。换成大白话：银行表格上「金额一栏请用阿拉伯数字大写不作数」这行小字，就是 description。

★ 受约束解码：把不合法的 token 直接屏蔽掉

这一段是本节技术含量最高、也最值得讲透的部分。OpenAI 在官方博文里明确说明，Structured Outputs 的实现机制是 constrained decoding（受约束解码）——不是靠提示，也不是靠重试，而是在生成的每一步直接干预可选的 token。

要理解它，先回忆 §8.2 讲过的生成过程。模型每生成一个 token，实际上是先算出「词表里每一个 token 接在这里的可能性有多大」，然后按某种采样策略挑一个。词表大约 20 万个 token，所以每一步都是一次「从 20 万个候选里选一个」。

受约束解码做的事，就是在「选一个」之前，把当前不可能合法的候选全部划掉——把它们的可能性直接压成零。走一遍例子你立刻就懂：

目标 schema： { "urgent": boolean }
模型已经生成了：   { "urgent":

现在这一步，词表里 20 万个 token 中，
在 JSON 语法 + 这份 schema 下，合法的只有极少数几个：

    合法：  true    false    （以及可能的前导空格变体）
    非法：  "       0        [        {       hello    好的    ...

于是解码器把所有非法 token 的概率强制置为 0（业内叫「掩码」，mask）。
模型现在哪怕内心极想写一句「好的，这是您要的结果」，
它也无从下笔——那些 token 已经不在候选里了。

再走一步：
模型已经生成了：   { "urgent": true
    合法：  }      ,（如果 schema 里还有别的必填字段）
    非法：  其余全部

所以最后一个字符必然是 }，JSON 不可能少一个括号。

这套机制的精妙之处在于：它不需要模型「理解」JSON 语法，也不需要模型「愿意」配合。约束在解码器那一层，是程序化的、确定的。好比考试用的答题卡——你想在选择题那一栏写作文也写不了，因为那里只有四个小方框。

技术上它是怎么知道「此刻合法的是哪些」的？OpenAI 博文里提到的做法是把 JSON Schema 先转成一种语法（可以理解成一台状态机——「现在处在哪个格子里、下一步允许出现什么」），然后在每一步查这台状态机，得到允许的 token 集合。第一次用某个新 schema 时需要做一次这样的预处理，所以官方也提到首次请求会有额外延迟，之后这份「语法」会被缓存复用。

把这个机制的价值换算成可感知的量：假设不用约束时格式成功率是 99%，你一天十万次调用就有一千次要重试；重试也可能失败，还有一百次要二次重试。上了受约束解码，这一千次重试的钱、时间和监控告警一起消失了。而且更关键的是，你的代码里可以删掉那一大坨「先切前缀再剥围栏再 try except」的清洗逻辑——省下的维护成本比省下的 token 钱更值。

JSON mode 与 Structured Outputs：一步之差，天壤之别

这两个名字长得像，很多人混着用，但它们保证的东西完全不是一回事。这是本节第二个必须记牢的点。

JSON mode（JSON 模式）是 OpenAI 在 2023 年 DevDay 开发者大会上推出的。它保证的是：输出是一段合法的 JSON。仅此而已。合法的意思是括号配对、引号成对、逗号位置对、能被 json.loads 顺利吃下。但它不保证这段 JSON 长成你要的样子。

Structured Outputs（结构化输出）是 2024 年 8 月 6 日随官方博文《Introducing Structured Outputs in the API》推出的。它保证的是：输出会 exactly match JSON Schemas provided by developers——严格匹配你给出的 JSON Schema。

差别有多大？看一个具体的翻车现场：

你的 schema 要求：
  { "qty": integer, "urgent": boolean }

【JSON mode 下可能出现的合法但错误的输出】
  { "quantity": 3, "is_urgent": "yes" }     ← 合法 JSON！字段名不对、类型不对
  { "qty": "three", "urgent": true }        ← 合法 JSON！数量成了字符串
  { "qty": 3 }                              ← 合法 JSON！少了一个必填字段
  { "qty": 3, "urgent": true, "note": "…" } ← 合法 JSON！多了一个字段

  这四种 json.loads 全都能过。
  你的程序在下一行 data["urgent"] 或 int(data["qty"]) 才炸。

【Structured Outputs 下】
  { "qty": 3, "urgent": true }              ← 只有这一种形状可能被生成出来

换成大白话：JSON mode 保证你交上来的是一张表格而不是一封信；Structured Outputs 保证你交上来的是我指定的那张表格，格子数一个不多一个不少。前者只管「有没有格式」，后者管「格式对不对」。

所以在能用 Structured Outputs 的场合，没有任何理由继续用 JSON mode。JSON mode 今天主要的价值是兼容老代码、以及在不支持新特性的模型上退而求其次。

★★ 那个「100%」：评测分数不等于产品承诺

这一段是本节最需要小心的地方，也是中文技术文章出错最集中的一处。

你会在无数篇介绍文章里看到「OpenAI 保证 100% 符合 schema」。这句话把两件不同的事混成了一件。让我们把官方原话拆开看。

第一件事 · 评测分数。官方博文的原文是：On our evals of complex JSON schema following, our new model gpt-4o-2024-08-06 with Structured Outputs scores a perfect 100%. In comparison, gpt-4-0613 scores less than 40%. 翻译过来：在 OpenAI 自家的「复杂 JSON schema 遵循」评测集上，开了 Structured Outputs 的 gpt-4o-2024-08-06 拿了满分 100%；作为对照，gpt-4-0613 不到 40%。

请盯住这句话的限定语：「在我们自己的评测集上」。这是一个 benchmark（基准测试）分数，是在一批特定题目上跑出来的结果，不是对所有情况的无条件承诺。好比一款车在厂家测试场的标准工况下跑出百公里油耗 4.9 升——这个数字是真的，也是可核对的，但你不能把它读成「这车在任何路况下油耗都是 4.9 升」。

第二件事 · 产品层的可靠性表述，它带两个明确前提。官方另一处原文是：When the response does not include a refusal and the model's response has not been prematurely interrupted (as indicated by finish_reason), then the model's response will reliably produce valid JSON matching the supplied schema.

拆成两个必须成立的条件：

• 前提一 · 模型没有拒答如果你的请求触发了安全策略，模型会拒绝回答。这时候它不会硬凑一个符合 schema 的假数据给你，而是走另一条路。为此 API 新增了一个 refusal 字段——拒答变成了一个可以用代码判断的状态，而不是让你去猜「这段自然语言是不是在拒绝我」。这个设计其实很贴心。
• 前提二 · 生成没有被提前打断如果输出撞上了 max_tokens 上限，或者触发了其他终止条件，JSON 就会在半路被切断——一个截断的 JSON 当然不是合法 JSON。判断依据是响应里的 finish_reason 字段：正常结束是 stop，撞上长度上限是 length。看到 length 就说明你拿到的是半截数据，必须当失败处理。

所以正确的措辞是什么？

这件事之所以值得单开一节，是因为它是「实验室基准 vs 日常使用」这个鸿沟的一个标准案例。你以后会在 AI 领域反复遇到同一个套路：某个能力在一份基准测试上刷到接近满分，然后被简化成「AI 已经解决了这个问题」，最后在你的真实业务里出问题。养成一个习惯：看到一个漂亮的百分比数字，先问三句——在哪个数据集上测的？谁测的？有没有附加前提？这三句话能帮你过滤掉一大半技术宣传噪音。

两条使用路径：function calling 与 response_format

官方博文里给了两种用法，很多人只知道其中一种，结果在选型时纠结错了方向。这两条路不是二选一的竞品，而是对应两种完全不同的场景。

路径一 · 给 function calling 装上 strict。在你定义的函数（tools）里加一句 strict: true。按发布时点的说明，这条路径支持所有支持 tools 的模型，从 gpt-4-0613、gpt-3.5-turbo-0613 那一批开始往后都行。

路径二 · 用 response_format 的 json_schema。response_format 这个参数新增了一个 json_schema 选项，配上 strict: true。按发布时点（2024 年 8 月）的说明，支持 gpt-4o-2024-08-06 和 gpt-4o-mini-2024-07-18。

★这里必须插一句时效提醒：上面这两串模型名单是 2024 年 8 月发布时点的信息。AI 领域一年就是一代，到你读这篇文章的时候支持范围早已扩大。具体支持哪些模型，请查 OpenAI 官方文档的 Structured Outputs 指南，本文列出的仅为发布时点快照，不要当成当前现状。本书在这类快速变化的事实上一律只写「有出处的时点信息 + 明确标注」，不写「据说现在支持全部模型」这种无法核实的话。

那两条路该怎么选？关键看结构化的结果要给谁用：

把 function calling 和 structured outputs 的关系彻底说清，因为这是初学者最容易搞混的一对概念：

• function calling 是什么一套「让模型调用你定义的函数」的机制。你把函数的名字、干什么用、需要哪些参数告诉模型，模型在觉得需要时返回一个「我要调用 check_stock，参数是 {"sku": "A17"}」的请求，你的代码去真的执行，再把结果喂回去。
• structured outputs 是什么一种「保证输出严格贴合 schema」的约束能力。它本身不调用任何东西，它只管形状。
• 两者的关系不是竞争关系，而是后者作为一种能力被施加到前者之上。在 tools 定义里加 strict: true，就等于给 function calling 装上了 structured outputs 这个保险。好比「快递」是一套送货机制，「保价」是一项施加在它上面的保障——你不会问「该选快递还是选保价」。
• 为什么还要 response_format 这条路因为有大量场景根本不需要调用任何工具，就是要一份结构化数据。为了这种场景硬定义一个假函数（业内曾经真的这么干过，叫「假 function 大法」）是别扭的，所以官方给了直接的路。

动手：OpenAI Structured Outputs 的完整可运行示例

先看 response_format 这条路。下面这段代码可以直接跑，它做的事是从一段乱糟糟的口语订单里抽出规整数据：

# pip install openai
import json
from openai import OpenAI

client = OpenAI()   # 从环境变量 OPENAI_API_KEY 读密钥

ORDER_SCHEMA = {
    "type": "object",
    "properties": {
        "customer": {"type": "string", "description": "下单人姓名，原文没提就填空字符串"},
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "qty":  {"type": "integer"},
                },
                "required": ["name", "qty"],
                "additionalProperties": False,
            },
        },
        "urgent":  {"type": "boolean", "description": "原文是否明确要求加急"},
        "channel": {"type": "string", "enum": ["app", "phone", "walk_in"]},
    },
    "required": ["customer", "items", "urgent", "channel"],
    "additionalProperties": False,
}

raw = "喂？我是三号楼的王姐，来两份宫保鸡丁、一份米饭，麻烦快点儿啊，孩子等着吃"

resp = client.chat.completions.create(
    model="gpt-4o-2024-08-06",          # ← 支持范围请查官方文档，此处为发布时点示例
    messages=[
        {"role": "system", "content": "你是订单录入员。只按 schema 抽取原文里明确出现的信息，绝不编造。"},
        {"role": "user",   "content": raw},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "order",
            "schema": ORDER_SCHEMA,
            "strict": True,             # ★ 这一行才是开启严格约束的开关
        },
    },
)

msg = resp.choices[0].message

# ★ 两个前提都要检查，缺一个就是隐患
if getattr(msg, "refusal", None):                 # 前提一：模型有没有拒答
    raise RuntimeError("模型拒绝了这个请求：" + msg.refusal)
if resp.choices[0].finish_reason != "stop":       # 前提二：有没有被截断
    raise RuntimeError("输出未正常结束，finish_reason=" + resp.choices[0].finish_reason)

data = json.loads(msg.content)     # 到这里可以放心解析
print(json.dumps(data, ensure_ascii=False, indent=2))

这段代码里有三行是最容易被教程省略、而生产环境绝不能省的：

• "strict": True忘了这一行，你就退化成了 JSON mode——schema 只被当作提示参考，而不是硬约束。这是最常见的一个坑：schema 写得很认真，却忘了打开开关。
• 检查 refusal对应官方表述里的第一个前提。不检查它，拒答场景下你会拿到一个 None 去做 json.loads，报一个莫名其妙的错。
• 检查 finish_reason对应第二个前提。length 意味着 JSON 被切了半截。这个坑在 schema 里带长文本字段、或者数组可能很长时特别容易踩。

再看 function calling 加 strict 这条路。区别只在参数怎么传：

tools = [{
    "type": "function",
    "function": {
        "name": "check_stock",
        "description": "查询某个商品在某个仓库的实时库存",
        "parameters": {                 # ★ OpenAI 这里叫 parameters
            "type": "object",
            "properties": {
                "sku":       {"type": "string",  "description": "商品编码，形如 A17-BLK"},
                "warehouse": {"type": "string",  "enum": ["north", "south", "east"]},
            },
            "required": ["sku", "warehouse"],
            "additionalProperties": False,
        },
        "strict": True,                 # ★ 给 function calling 装上结构化输出
    },
}]

resp = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[{"role": "user", "content": "帮我看下 A17 黑色在北方仓还有货吗"}],
    tools=tools,
)

call = resp.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)   # 有 strict 兜着，这里的形状是确定的
print(args)          # {'sku': 'A17-BLK', 'warehouse': 'north'}

# 你的代码真正去执行，然后把结果以 tool 角色回传（★ OpenAI 用独立的 tool 角色）
result = {"sku": "A17-BLK", "warehouse": "north", "available": 42}
messages_next = [
    {"role": "user", "content": "帮我看下 A17 黑色在北方仓还有货吗"},
    resp.choices[0].message,                       # 把模型那条 tool_calls 消息原样带回
    {"role": "tool",
     "tool_call_id": call.id,
     "content": json.dumps(result, ensure_ascii=False)},
]

请留意最后那个 {"role": "tool", ...}。OpenAI 用一个独立的 tool 角色来回传工具执行结果——这是它和 Anthropic 的一个结构性差异，下一段马上对比。

Anthropic 那一边：Tool use 与 input_schema

Anthropic（Claude 的公司）把这套能力叫 Tool use（工具使用）。它的整体思路一致、细节处处不同，而这些不同恰好是最容易在迁移代码时踩坑的地方。

先把一次完整往返走一遍。换成大白话，整个流程就四步：你告诉模型手边有哪些工具 → 模型说「我要用某个工具，参数是这些」 → 你真的去执行 → 你把执行结果交回去，模型接着说人话。

# pip install anthropic
import json
import anthropic

client = anthropic.Anthropic()   # 从环境变量 ANTHROPIC_API_KEY 读密钥

tools = [{
    "name": "check_stock",
    "description": "查询某个商品在某个仓库的实时库存。需要商品编码和仓库代号。",
    "input_schema": {                    # ★ Anthropic 这里叫 input_schema（不是 parameters）
        "type": "object",
        "properties": {
            "sku":       {"type": "string", "description": "商品编码，形如 A17-BLK"},
            "warehouse": {"type": "string", "enum": ["north", "south", "east"]},
        },
        "required": ["sku", "warehouse"],
    },
    "strict": True,                      # ★ 严格等价物：保证参数严格贴合 schema
}]

question = "帮我看下 A17 黑色在北方仓还有货吗"

resp = client.messages.create(
    model="claude-sonnet-4-5",           # ← 模型名请查官方文档，随版本变化
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},        # 默认值：由模型自行判断要不要用工具
    messages=[{"role": "user", "content": question}],
)

# 响应的 content 是一个 block 列表，可能同时有 text block 和 tool_use block
tool_use = next(b for b in resp.content if b.type == "tool_use")
print(tool_use.name)    # 'check_stock'
print(tool_use.input)   # {'sku': 'A17-BLK', 'warehouse': 'north'}

# 真正执行
result = {"available": 42}

# ★ 把结果作为 tool_result block 回传，而且角色是 user（不是独立的 tool 角色）
followup = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user",      "content": question},
        {"role": "assistant", "content": resp.content},      # 原样带回模型那一轮
        {"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use.id,
            "content": json.dumps(result, ensure_ascii=False),
        }]},
    ],
)
print(followup.content[0].text)

把两家的差异列成表，这张表建议你收藏——迁移代码时一条条对着看：

其中结果回传方式那一行是结构性差异，值得再强调一遍。OpenAI 的设计是「对话里多了一种说话人：工具」；Anthropic 的设计是「工具结果是用户递进去的一份材料」。好比你在医院看病：OpenAI 的模型是检验科直接把化验单发到医生工作站（多了一个独立角色），Anthropic 的模型是你自己拿着化验单回诊室交给医生（还是你在说话，只是手里多了一张单子）。两种流程都能看好病，但你写代码时格式完全不同，混着写必然报错。

client tools 与 server tools：OpenAI 没有的那个二分

Anthropic 有一个 OpenAI 没有完全对应概念的划分，理解它能省你不少功夫。

• client tools（客户端工具）在你自己的应用里执行的工具。模型说「我要调 check_stock」，你的代码去连数据库、拿结果、回传。上面那段示例就是这一类。你负责实现，也负责它的一切——权限、超时、错误处理。
• server tools（服务端工具）在 Anthropic 自己的基础设施上执行的工具，直接把结果返回给模型，不经过你的代码。官方提供的有 web_search（网页搜索）、web_fetch（抓取网页内容）、code_execution（执行代码）、tool_search（在大量工具里检索合适的工具）。你只需要声明「允许它用」，剩下的整套往返在服务端就完成了。

换成大白话，这个区别就是「自己下厨」和「叫外卖」。client tools 是你在自家厨房炒菜——原料、火候、洗碗全是你的事，但你想放多少盐完全自己说了算。server tools 是叫外卖——你只说「一份宫保鸡丁」，谁买菜、谁炒、谁洗锅都不用你管，菜直接送到桌上；代价是你无法干预它怎么做的。

什么时候用哪种？凡是涉及你自己的数据、自己的业务动作（下单、退款、改数据库）——必须是 client tools，因为只有你的系统知道这些事怎么做、以及有没有权限做。凡是通用能力（搜网页、跑一段计算）——用 server tools 更省事，你不必自己维护一个搜索接口和一个沙箱。

怎么控制模型「要不要用工具」

定义了工具，不等于模型每次都会用。这里有一个参数和一个技巧。

参数：tool_choice。默认值是 {"type": "auto"}——由模型自己判断这次要不要调工具。这个默认值大多数时候是对的，但有两种情况你会想改它：

技巧：用一句轻量指令抬高调用率。官方给的例子是在提示词里加一句 Use the tools to investigate before responding.（回答之前先用工具查一下）。这一句不强制，但能明显提高模型主动查证的倾向。好比你对一个新来的实习生说「不确定的事先查一下再答」——不是命令他每件事都查，是把他的默认习惯往「查」的方向拨了一格。

★关于并行工具调用那一行，有一个真实的坑必须点出来：Anthropic 默认是开启并行的，也就是模型可以一次性请求调用好几个工具。这在只读查询上是好事（三个查询同时发，更快），但如果你的工具带副作用就危险了——模型可能一次并行发起三笔扣款。这和 OpenAI 的默认行为不同，从 OpenAI 迁过来的代码最容易在这里出事。处理办法就是那行 disable_parallel_tool_use，或者在你自己的执行层加幂等保护（同一个请求重复执行只生效一次）。

schema 设计的六条实战经验

约束机制帮你把「格式对」这件事兜住了，但schema 本身设计得好不好，直接决定内容质量。下面这六条是踩过坑之后的经验，逐条给理由。

• 一 · 能用 enum 就别用自由字符串要分类，就把候选值全列进 enum。写成自由字符串，模型今天给你 "积极"，明天给 "正面"，后天给 "positive"，你的下游统计全乱。相当于把填空题改成选择题，出错空间直接归零。
• 二 · 每个字段都写 description字段名是给程序看的，description 是给模型看的。score 这个名字模型不知道是 1-5 还是 0-100，写清楚「1 到 5 的整数，5 表示最满意」就没有歧义。这是零成本提升准确率的地方，别偷懒。
• 三 · 给「不知道」留一个合法出口★这条最重要。原文里压根没提下单人姓名，而 schema 要求 customer 必填且是字符串——模型只能编一个。你用硬约束逼它必须填，它就必须给你幻觉。正确做法是允许空字符串、或加一个 found: boolean 字段、或把该字段从 required 里拿掉。好比问卷上必须有「不适用」这个选项，否则你收到的全是被迫瞎填的答案。
• 四 · 让推理字段排在结论字段前面JSON 对象里字段是有顺序的，而模型是从左到右一个 token 一个 token 生成的。把 reasoning（理由）放在 conclusion（结论）前面，模型就是先想后答；顺序倒过来，它是先拍结论再补理由。这和 §10.3 讲的思维链是同一个道理，只是换到了 schema 里。
• 五 · 别把 schema 嵌得太深嵌套五六层的 schema 不但模型容易搞乱，你自己的下游代码也难写。宁可拆成两次调用：第一次抽大结构，第二次针对每一项抽细节。可读性和准确率一起提升。
• 六 · 注意 schema 只支持 JSON Schema 的一个子集受约束解码要把 schema 编译成一台状态机，所以那些过于灵活的 JSON Schema 特性（复杂的条件分支、正则模式的完整支持等）通常不被允许，具体支持范围各家不同、且随版本变化。务必查当时的官方文档，别照着 JSON Schema 完整规范硬写。

反模式 vs 正确做法：一张对照表

把上面的经验反过来写成「常见错法」，对照着看更容易记住：

一个容易被忽略的收益：结构化让评测变得可能

前面讲的都是「不崩」。但结构化输出还有一个不那么显眼、长期价值更大的好处：它让「这个提示词到底有没有变好」这件事第一次变得可以量化。

想想自由文本的时代你怎么评测。你改了一版提示词，然后……人工读五十条回答，凭感觉判断「好像好一点」？这不是工程，这是玄学。换成大白话：这就好比学校里改作文——两个老师给同一篇打分能差二十分，你没法拿这个分数去比较两种教学法。

而结构化输出把答案变成了字段。字段可以直接和标准答案比对：

准备一份标注好的测试集（哪怕只有 100 条）：
    raw_text  →  期望的结构化结果

跑一遍，逐字段算准确率：
    channel 字段准确率     97%
    urgent  字段准确率     84%   ← 找到问题了
    items   数量完全一致   91%

现在你有了明确的改进方向：
    去看那 16% 判错「加急」的样本，
    发现原文说「孩子等着吃」这类隐含表达经常被漏掉，
    于是在 urgent 字段的 description 里补一句：
    「包括『快点』『等着用』这类隐含的紧急表达」

改完再跑一遍：urgent 准确率 84% → 93%。
这才叫工程——每一步改动都有一个可核对的数字支撑。

这是结构化输出最容易被低估的价值：它不只是让程序不崩，它把提示词工程从「凭感觉调」变成了「看数字调」。相当于做菜从「凭手感撒盐」变成了用厨房秤——不是味觉不重要，而是有了刻度你才能复现和改进。这条思路我们下一节（§10.5 迭代与反模式）还会继续展开。

下面这个小测验检验一下本节最关键的两个区分——「JSON mode 与 Structured Outputs 差在哪」以及「100% 这个数字该怎么读」。