结构化输出
与模型结果校验

路线12 章中的位置

S00结构化输出在 API 调用链中的位置

response = 模型SDK.生成(
    model = "支持结构化输出的模型",
    messages = [用户的退款描述],
    response_format = 退款意图Schema
)

result = 解析(response)
校验Schema(result)
校验订单数据库(result)
校验当前用户权限(result)

谁设置：AI 应用工程师在后端代码中设置。何时生效：每次模型生成答案时。输入：Prompt 加 Schema。输出：符合指定外形的 JSON，或者拒答、截断、API 错误。

一定分清：Schema 约束“表单外形”，不会去订单数据库核对“表单内容是否真实”。

S01固定字段与结构化输出的必要性

{
  "intent": "refund",
  "amount": 299,
  "create_ticket": true
}

表格类比：自然语言像顾客写的一段留言；结构化输出像填写固定表格。程序只有拿到稳定字段，才能继续查询订单、分配客服或创建工单。

S02用户语言到业务对象的转换

模型擅长把模糊语言转换为固定字段；程序擅长检查字段并执行确定规则。成熟系统让二者各做擅长的部分。

S03JSON 数据格式基础

JSON 不是三个不同的东西。JSON 是一种把信息写成“程序容易读取的固定表格”的文本格式；JSON Mode 和 JSON Schema 是围绕 JSON 的两种控制手段。

{
  "order_id": "A10086",
  "intent": "refund",
  "amount": 299,
  "need_human": true
}

快递单类比：JSON 就是一张填写好的快递单。左边的 order_id、amount 是栏目名称；右边的 A10086、299 是实际填写的值。

S04JSON、JSON Mode 与 JSON Schema 的边界

Schema 是“表格模板”，不是“事实审计员”。它能要求金额必须是数字，却不知道真实退款金额到底是不是 299 元。

S05结构化输出的三层约束

JSON 是填好的表　｜　JSON Mode 保证表能打开　｜　Schema 规定表的栏目　｜　业务校验核对内容真假

S06结构化输出完整示例

顾客说：“订单 A10086 的鞋子小了，我想退掉，花了 299 元。”程序希望模型把这句话整理成固定字段。

好的，整理结果如下：
{
  "order_id": "A10086",
  "intent": "refund",
  "amount": 299
}
希望能帮到你。

{
  "dingdan": "A10086",
  "what_to_do": "退货",
  "money": "二百九十九"
}

{
  "order_id": "A10086",
  "intent": "refund",
  "amount": 299
}

JSON = 填好的具体表单　｜　JSON Mode = 保证表单语法能打开　｜　Schema = 事先规定空白模板和填写规则

S07JSON Schema 字段约束

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "string",
      "enum": ["refund", "shipping", "other"]
    },
    "order_id": {"type": ["string", "null"]},
    "confidence": {"type": "number", "minimum": 0, "maximum": 1},
    "need_human": {"type": "boolean"}
  },
  "required": ["intent", "order_id", "confidence", "need_human"],
  "additionalProperties": false
}

S08可空字段与可选字段

{"order_id": null}

{"intent": "refund"}

工程建议：对于下游程序一定会读取的重要字段，通常让字段始终存在；未知时明确返回 null，比忽然消失更容易处理。

S09结构化配置位置与责任边界

“表格”只是类比。真实开发时，是你的后端程序通过模型厂商提供的 SDK 或 HTTP API 调用模型。开发者准备请求，模型生成响应，响应再回到你的程序。

JSON：通用数据格式，不是模型开关

JSON 不是 AI 独有的，也不是一个 API 参数。它是一种记录和传递数据的写法，可以出现在 API 请求和返回结果中。结构化输出讨论的是：让模型把答案用 JSON 格式交回程序。

{
  "intent": "refund",
  "order_id": "A10086",
  "amount": 299
}

JSON Mode：调用模型 API 时设置的响应格式选项

开发者调用模型时，除了传入模型名称和聊天消息，还可以选择希望模型用 JSON 格式返回。不同厂商和 SDK 的参数名称不同，下面是用于理解的伪代码：

response = 模型客户端.生成(
    model = "某个模型",
    messages = 聊天消息,
    response_format = "json"   // 在这次 API 调用中开启 JSON Mode
)

JSON Schema：开发者编写并随 API 请求传入的字段规则

开发者根据后续程序需要，先写出字段模板：

schema = {
  "type": "object",
  "properties": {
    "intent": {"type": "string", "enum": ["refund", "shipping", "other"]},
    "order_id": {"type": "string"},
    "amount": {"type": "number"}
  },
  "required": ["intent", "order_id", "amount"]
}

调用模型时，再把 Schema 放进结构化响应相关参数：

response = 模型客户端.生成(
    model = "某个模型",
    messages = 聊天消息,
    response_format = {
        "type": "json_schema",
        "schema": schema
    }
)

模型生成时按 Schema 填字段；返回后，程序还可以用同一份 Schema 再检查一次。随后必须查询真实订单、检查权限和业务规则。

所在位置一句话：JSON Mode 和 JSON Schema 都是在“你的程序调用模型 API”时由开发者设置的；它们控制模型怎样把答案交回程序，不是用户界面的按钮，也不负责证明答案为真。

S10Schema 的 API 参数配置

首选：放在模型 API 专门提供的结构化输出参数里。不同厂商可能把它叫做 response_format、structured_output 或其他名称，具体写法看所用 SDK，但它属于请求配置，不是普通聊天文字。

System Prompt：
请返回 JSON，必须有 intent 和 amount，
amount 必须是数字。

调用模型(
  messages = [...],
  response_format = {
    "type": "json_schema",
    "schema": schema
  }
)

Prompt 还负责什么

Prompt：
intent 表示用户真正想办理的业务；
只有明确要求退款时才填 refund；
没说金额就返回 null，不要猜。

Schema 负责什么

intent 必须是字符串，只能选 refund/shipping/other；
amount 必须是数字或 null；
两个字段必须存在。

为什么有些教程把 Schema 写进 Prompt？可能是所用模型/API 不支持原生结构化输出，只能退而求其次；也可能是在补充字段的业务含义。API 原生支持 Schema 时，应优先使用专门参数。

S11模型 API 兼容性

截至 2026-09-15，下面这些主流平台的官方 API 已提供 Schema 结构化输出。这里列的是适合建立认识的主流系列，不应把它当作永久不变的完整名单；模型版本和接口会更新，写项目时仍要查看所选模型的官方能力页。

同一厂商并非所有旧模型、实时语音模型、图片模型或每个端点都支持同一种 Schema 参数。选择模型时，不能只看模型名称，还要看“所用端点 + SDK 版本 + Structured Outputs 能力”。

“保证符合 Schema”究竟保证什么

用户说：“这个我不想要了。”

Schema 可以保证模型只能返回：
{"intent": "refund"} 或 {"intent": "other"}

但 Schema 不能保证模型一定选对 refund 还是 other。

还要处理的例外：模型可能拒绝回答；响应可能因长度或网络中断而不完整；Schema 使用了厂商不支持的关键字时，请求可能报错；API 本身也可能超时或限流。因此程序仍要检查响应状态、解析结果和失败分支。

原生 Schema 提高“机器可读性”　≠　消灭模型的理解错误

官方参考：OpenAI API · Gemini · Mistral · xAI · Cohere

S12五层结果校验

S13结构正确与业务正确的差异

{
  "action": "refund",
  "order_id": "A10086",
  "amount": 99999,
  "need_confirmation": false
}

这段 JSON 可以完美通过语法和类型校验，但仍可能同时存在四个问题：

铁律：模型输出只能成为“业务操作候选”，不能直接成为“已批准的业务操作”。

S14结构校验与业务校验

S15生产环境风险控制

你的判断是正确的：模型是概率系统，只要让它负责“理解用户意思”，就不可能仅靠 Schema 获得百分之百的语义正确率。高级工程的目标不是假装错误不会发生，而是让错误难以造成严重后果、能够被发现、可以恢复和追责。

核心边界：模型可以识别“他可能想退款”，但退款金额不让模型猜，用户身份不让模型判断，能不能退不让模型拍板，真正执行也不让模型直接完成。

S16模型置信度的可信边界

模型输出的 confidence: 0.95 仍然是模型生成的数字，不是天然准确的概率。模型可能很自信地判断错。

例如在历史 1,000 个真实问题上，模型自报 0.9 以上的案例实际只有 82% 正确，那么这个分数就没有达到“90%正确”的含义，需要校准或调整流程。

S17置信分数的解释与校准

假设模型读完顾客的话后输出：

{
  "intent": "refund",
  "confidence": 0.95
}

它表达的是：“我给自己的退款意图判断打了 0.95 分，我觉得很确定。”但这个数字可能只是模型根据语言生成的自评分数，并没有自动获得数学保证。

校准是怎样做的

举例：有 100 条问题，模型都给出了大约 0.95 的置信分数。人工核对后发现：

重要：即使真的达到 95% 正确，也意味着平均每 100 次仍可能错 5 次。用它自动给工单分类也许可以接受，但自动退款风险仍然太大，所以高风险操作还必须查数据库、走固定规则并人工或用户确认。

校准 = 比较“模型声称多确定”和“历史上实际上多正确”

S18校验失败处理策略

不要无限重试。模型连续收到相同信息，可能连续犯相同错误，只会增加延迟和费用。

S19JSON 修复的安全边界

有些系统会在解析失败后，再让另一个模型把坏 JSON 修好。这可以处理格式问题，但不能偷偷改变业务含义。

涉及钱、权限、身份、医疗或法律信息时，缺失字段通常应该追问或拒绝，而不是自动猜补。

S20完整结构化输出链路

可靠结构化输出 = 受约束的生成 + 确定性的程序校验 + 安全的失败处理

S21结构化输出工程原则

• 给人看的内容可以自然语言；给程序使用的内容要结构化。
• “请输出 JSON”只是提示，Schema 才能明确字段契约。
• JSON Mode 主要保证语法，Schema 主要保证结构，两者都不能证明业务事实。
• 模型输出是候选数据，而不是数据库真相或操作授权。
• 先做结构校验，再做业务、权限和实时状态校验。
• 缺少关键事实时追问，不要让模型猜补。
• 重试必须有上限，高风险操作必须走确定性规则或人工确认。
• 日志要记录原始输出、校验错误、重试次数和最终处理方式，便于以后回放。

下一章

第 03 课：Embedding、向量与语义检索基础

会用“在地图上找附近商店”的类比，详细解释向量、维度、余弦相似度、语义检索、关键词检索，以及向量数据库为什么能找到“意思相近但文字不同”的内容。