JSON 模式不是结构化输出:一个被 90% 团队搞混的 API 差异

📅 2026/4/26 ✍️ 小文 📖 约 1 分钟

开了 response_format=json_object 却还是解析失败?JSON 模式只保证「是合法 JSON」,不保证「符合你的字段」。本文讲清约束解码、schema 校验、重试设计三层防线,附踩坑清单。

症状

接口文档写了支持 JSON 输出,代码里加上了 response_format={"type": "json_object"},上线后仍然偶尔报 KeyError: 'items'。

日志里的返回长这样:

{ "result": "以下是筛选出的商品列表:", "data": [...] }

JSON 是合法的,字段名却和你要的不一样。这就是 JSON 模式和结构化输出的区别:前者约束”语法”,后者约束”结构”。

三种模式,能力边界不同

各家命名不一样,但大体分三层:

第一层:纯提示词。 在 prompt 里写”请只输出 JSON”,没有任何强制力。模型可能加一句”好的,这是结果:“再接 JSON,也可能用 ```json 包裹。适合原型,不适合生产。

第二层:JSON 模式。 服务端保证输出能被 JSON.parse 解析,仅此而已。字段名、类型、嵌套、是否缺字段全凭模型。OpenAI 的 json_object、部分国内厂商的”JSON 输出开关”属于这层。

第三层:Schema 约束(严格模式)。 你给一份 JSON Schema,服务端在解码时对 token 施加约束——不符合 schema 的下一个 token 概率被压到零。字段必填、枚举值、类型都受控。OpenAI 的 json_schema + strict: true、Gemini 的 responseSchema、Anthropic 的工具调用参数、以及 vLLM/SGLang 提供的 guided_json 都属于这层。

只有第三层能让你安全地省掉大部分防御性代码。

严格模式的四个真实限制

即便用了第三层,也不能直接睡大觉:

1. 嵌套深度和可选字段限制。 多数实现的严格模式要求所有字段 required、additionalProperties: false,并且不支持任意递归。如果你的 schema 里有 optional 字段,通常的做法是改成 required 并允许 null。

2. 枚举写死会反噬。 把分类枚举锁死成 8 个值,业务加第 9 个类目时,模型只能强行塞进旧类目。留一个 other,并加一个 reason 字段记原因。

3. 约束不支持推理链。 强行约束输出 JSON,模型没有”打草稿”的空间,复杂判断的正确率可能下降。务实做法是分两步:第一步自由文本推理,第二步 schema 化提取(两步的输入输出都短,总成本通常更低)。

4. 长文本字段仍会幻觉。 Schema 保证了 summary 字段存在且是字符串,不保证内容对。结构校验和事实校验是两件事。

三层防线怎么搭

不要把宝押在某一层上。生产系统通常是三层:

LLM 调用(schema 约束)
  → 传输层:JSON.parse + zod/pydantic 校验
  → 业务层:语义校验(金额>0、日期可解析、引用 id 存在)
  → 失败时:带错误信息重试一次(最多一次)

关键细节在重试。重试时必须把校验错误原文回传给模型,例如:

你上一次的输出校验失败:
- items[2].price 必须是数字,实际是 "29.9元"
请修正后重新输出,不要解释。

这句”不要解释”很重要。不加的话,模型经常先道歉一大段再给 JSON,白白多花 token。

校验失败率该怎么看

一个健康的结构化输出链路,一次校验通过率应该在 98% 以上。低于这个数,通常是三个原因:

  • schema 太复杂(一次要 20 个字段、5 层嵌套)→ 拆成两次调用
  • 字段语义有歧义(“状态”到底是订单状态还是支付状态)→ 在字段描述里写清楚,或改成两个字段
  • 输入里根本没有这个信息(让模型从空内容里提取金额)→ 这是产品逻辑问题,不是模型问题

重试后的最终失败率应低于 0.5%。如果重试仍然大量失败,就落到兜底:写入死信队列 + 人工复核,不要让它静默变成空值流进下游。

选型建议

场景建议
内部工具、一次性提取提示词 + 校验即可
需要写入数据库的字段抽取严格 schema 模式
复杂判断 + 结构化输出两段式:先推理后提取
自托管模型用 vLLM/SGLang 的 guided decoding

最后一句提醒:schema 是你和模型之间的合同,不是给模型看的建议。 如果某天你发现自己在 prompt 里反复强调”一定要输出 xxx 字段”,那说明你需要的是严格模式,而不是更好的提示词。

📤 分享到