结构化输出：让模型说机器能读的话

一句话定义

结构化输出是让模型严格按给定 JSON Schema（或等价格式）生成输出的能力，通常由 API 的约束解码保证合法，是 Agent 从"聊天"走向"驱动程序"的关键接口。

为什么重要

Agent 的每一步决策——调用哪个工具、传什么参数、路由到哪个分支——都需要机器可解析的输出。靠正则从散文里抠字段是 2023 年的噩梦；结构化输出把"概率文本"变成了可靠的程序接口。它也是路由（router）、意图识别、评测打分（LLM-as-judge，kp-024）、子 Agent 结果回传（kp-019）的共同底座。

前置知识

kp-004（提示工程）、了解 JSON 基本语法。

核心概念

三种保证层次

JSON Schema 一分钟

复制json{
  "type": "object",
  "properties": {
    "intent":  { "enum": ["refund", "consult", "complaint"] },
    "amount":  { "type": "number", "minimum": 0 },
    "reason":  { "type": "string", "maxLength": 200 }
  },
  "required": ["intent"],
  "additionalProperties": false
}

要点：enum 收窄选项、required 强制字段、additionalProperties: false 禁止编造字段。schema 本身就是提示——字段名、枚举值、描述都在引导模型。

什么时候不用 JSON

纯对话回复、长篇创作、需要思维链展开的推理，不要强行 JSON 化（会挤压推理质量）。模式是：决策用结构化，表达用自然语言。复杂页面可用"先自由推理、再结构化收尾"的两段式（先 reasoning 字段或分两次调用）。

原理与机制

约束解码（constrained decoding）：模型每步生成 token 前概率分布，约束解码在采样时把"会导致非法 JSON 的 token 概率置零——如对象还缺 required 字段时禁止生成 }。这是词法/语法层面的硬约束，所以合法率能到 100%（代价：偶尔因被逼着合规而内容质量略降，或在不兼容的提示下陷入循环）。

而提示约定只是软引导——采样仍可能选出破坏格式的 token，长输出尾部尤其容易漂。

工程细节两则：

1. 必填字段少而精：全字段 required 会让模型给不需要的字段硬编值（幻觉填空）。把"可选"真正标为可选。
2. 嵌套别超过 3 层：深层嵌套的错误率与修复成本陡增；能拆两次调用就拆。

直观类比

• 提示约定 = 口头嘱咐实习生"记得填表格"——他大概率填，但会漏字段、自创栏位
• Schema 约束 = 直接给他一张电子表单，必填项不填就提交不了，选项只能从下拉框选

实例与案例

客服路由器：需要把用户消息分类并决定走退款/人工/自动回复。

复制pythontools = [{
  "name": "route_ticket",
  "input_schema": {
    "type": "object",
    "properties": {
      "category": {"enum": ["refund", "technical", "other"]},
      "urgency":   {"enum": ["low", "high"]},
      "summary":   {"type": "string", "maxLength": 80}
    },
    "required": ["category", "urgency"],
    "additionalProperties": false
  }
}]

用函数调用接口携带 schema（kp-009），比"输出 JSON"提示稳得多；summary 设 maxLength 防止模型写小作文占窗口。

常见误区

• 误区一："提示里写了格式就够了"。长输出尾部漂移、换模型后崩坏，生产必须上 schema 约束。
• 误区二：让模型输出超复杂大 JSON。一次性生成整份报表 JSON，字段越多幻觉越多——拆步骤、拆调用。
• 误区三：把错误重试当灾难。约束解码偶发超时/循环，捕获后重试一次或降级到提示模式即可。
• 误区四：schema 里不留"逃生口"。分类任务没给 other 选项，模型只能硬塞错误类别——枚举要覆盖真实分布。

自测题

1. 约束解码为什么能做到 100% 合法？
2. additionalProperties: false 与 required 各防什么问题？
3. 为什么"全部字段 required"反而引入幻觉？

（参考答案：1. 每步把导致非法续写的 token 概率清零；2. 前者防编造字段，后者防漏字段；3. 模型被强制填空时会编造值。）

与其他知识点的关系

• 与函数调用的关系（结构化输出的工具化形态）→ kp-009
• 工具参数 schema 设计 → kp-010；MCP 的 schema → kp-011
• 评测打分输出 → kp-024

延伸阅读

• OpenAI, Introducing Structured Outputs in the API（2024.8 博客）
• JSON Schema 官方规范（learning.jsonschema.io）