JSON 模式不是结构化输出:一个被 90% 团队搞混的 API 差异
开了 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 字段”,那说明你需要的是严格模式,而不是更好的提示词。