LLM 结构化输出翻车:strict 模式的 Schema 要这样写
结论:把一份普通 JSON Schema 直接开 strict 大概率 400:全字段必填、每个对象封死 additionalProperties、$ref 与 allOf 直接被拒。本文按供应商约束把宽松 schema 批量改写成 strict 可用版本,给出可空联合、硬上限与 refusal 分流的自检清单。

结论:strict: true 不是一个「更认真一点」的开关,而是一份只认子集的合同——全字段必填、每个对象封死 additionalProperties、$ref 和 allOf 直接被拒。schema 不改写就上 strict,得到的是一次 400,而不是更可靠的输出。
同一份 schema,校验器里跑得好好的,挂上 strict: true 发给模型 API 就被原样退回。这不是模型变笨了,是供应商把「约束解码」所需的 schema 子集划了一条硬边界——你的 schema 越界了。
一、strict 到底改了什么:把采样器锁进语法
普通模式下,模型生成的 JSON 只是「大概率」符合你的 schema,靠 prompt 里那句「请输出 JSON」兜底。OpenAI 官方 evals 里,gpt-4-0613 仅靠提示词的复杂 schema 遵循率不到 40%;开 strict 后,gpt-4o-2024-08-06 在同一组评测上做到 100%。
原理是约束解码(constrained decoding):API 在首次请求时把你的 schema 编译成一个有限状态机,解码阶段每个 token 都由状态机放行,模型「发不出」不符合 schema 的 token。这不是提醒模型,是物理上锁死。代价有两笔:新 schema 首次编译要额外耗时(典型 10 秒内,复杂 schema 可到 1 分钟),首个 token 有 5-8% 的延迟增量;编译产物会被缓存,后续请求不再付费。
但要清楚它保证什么、不保证什么:语法与形状被锁死,语义没有。模型照样可以自信地把 estimate_hours 填成 400,把错误的邮箱抽出来。形状是地板,不是天花板,语义质量仍要靠评测集兜底。2026 年的前沿模型在负载下仍有约 0.4% 的破形率残差,重试回路依然是必需品。
二、三条硬规则:全必填、封死多余键、可空当可选
strict 模式对 schema 的改造要求只有三条,但每一条都和普通 schema 的写法直觉相反:
- 每个字段都必须写进 required。 strict 不接受可选字段这个概念。想表达「可选」,把字段留在 required 里,但类型写成可空联合
"type": ["string", "null"],缺省时让模型返回 null。这和一般 JSON Schema 实践(required 只列必要字段)完全相反。 - 每个对象都必须显式写 additionalProperties: false。 普通实践中这常常不设置(参考本站 additionalProperties 的三种运行时表现一文),但在 strict 模式下它是准入条件:没写就报错。原因很直白——状态机只能生成被声明的键,多出来的键在语法上就不可达。
- Python 用户的坑:Pydantic 会把带默认值的字段从 required 里丢掉。 一个
priority: str = "low"会让生成的 schema 缺一个 required 项,strict 直接拒收。要么去掉默认值,要么用下面的脚本批量补。
三条规则要递归到每一层嵌套对象,顶层改了、子对象没改,一样 400。一个最小合规示例:
{
"type": "object",
"properties": {
"intent": { "type": "string", "enum": ["book", "cancel", "question", "other"] },
"note": { "type": ["string", "null"] }
},
"required": ["intent", "note"],
"additionalProperties": false
}
三、这些写法会直接 400:禁用与不生效的词汇
strict 模式只支持 JSON Schema 的一个子集。分两类处理:
| 类别 | 词汇 | strict 模式行为 |
|---|---|---|
| 直接拒绝 | $ref / $defs 引用、allOf、not、dependentRequired、dependentSchemas、if/then/else |
API 返回错误,请求失败 |
| 静默不生效 | pattern、minLength、maxLength、format、minimum、maximum、multipleOf(微调模型) |
不报错也不强制,正则约束要自己在应用层补 |
两类的处理方式不同:前者必须改写——把 $ref 内联展开、把 allOf 合并进 properties;后者可以保留(有的配置会收),但绝不能当防线用。依赖 "pattern": "^v\\d+\\.\\d+\\.\\d+$" 保证版本号格式的写法,在 strict 下是裸奔,拿到响应后要再跑一次显式校验。顶层还有一条:schema 根不能是数组或裸联合类型,包一层 object。
四、硬上限:5000 属性、10 层嵌套、12 万字符
即使词汇全合规,规模超限照样报错。OpenAI 官方给出的硬数字:
- 全 schema 最多 5000 个对象属性,嵌套最多 10 层(Anthropic 侧的嵌套上限约 6 层);
- 属性名、定义名、枚举值、const 值的字符串总长 120000 字符;
- 枚举值合计最多 1000 个,单个字符串枚举超过 250 个值时总长不能超 15000 字符。
这些上限平时碰不到,但「把整个字典当枚举」和「把三层对象图压进一层」是两类真实的翻车现场。遇到就拆:把巨型 schema 拆成多次调用,或压平结构。另外,输出键的顺序与 schema 里的键序一致,依赖固定顺序的下游解析器可以把这当特性用。
五、一段脚本把宽松 schema 批量改成 strict
手工逐层改容易漏。下面的递归脚本(DevToolLab 2026 指南给出的模式)把「每个对象封死、每个键必填」一次补齐:
def make_strict(schema: dict) -> dict:
"""additionalProperties:false + 每个键必填,递归到每一层。"""
if isinstance(schema, dict):
if schema.get("type") == "object" and "properties" in schema:
schema["additionalProperties"] = False
schema["required"] = list(schema["properties"].keys())
for value in schema["properties"].values():
make_strict(value)
elif isinstance(schema, dict):
for value in schema.values():
make_strict(value)
elif isinstance(schema, list):
for item in schema:
make_strict(item)
return schema
配套的工作流建议:先用样例 JSON 反推一个 schema 骨架(本站 /convert/schema 工具页做的是由 JSON 单向反推 Schema),把骨架当起点,再按 strict 三条硬规则收紧,最后拿 make_strict 兜底一遍。注意脚本只处理形状,可空联合、枚举、语义字段仍要人工定;带 $ref 的 schema 要先内联展开再喂给它。
六、Anthropic 的等价写法:tool-as-schema
Anthropic 没有对应的 strict: true 开关。2026 年的惯用模式是把响应 schema 挂成一个工具的 input_schema,再用 tool_choice 强制模型调用它:
await anthropic.messages.create({
model: "claude-sonnet-4-6",
tools: [{ name: "emit", description: "Emit final summary", input_schema: schema }],
tool_choice: { type: "tool", name: "emit" },
messages,
});
工具调用通道本身做 JSON 校验,效果与 strict 模式等价。差异在细节:Anthropic 的嵌套上限约 6 层、支持 .nullable() 而非 .optional();三家(OpenAI、Anthropic、Gemini)各自接受的 schema 子集不完全相同,一份 schema 无改动跨供应商复用不可靠,切模型要重验。
七、refusal、截断、超时先分流,再谈重试
strict 模式下拿到的东西不合法,原因就三种,处理方式完全不同:
- refusal:模型拒绝执行(不安全请求等)。响应里
refusal字段为真,这时读 JSON 没有意义,走人工或改写请求的路。 - 截断:
finish_reason为length,说明 max_tokens 不够,输出物理上不完整。schema 约束救不了截断,加预算或压缩输出结构,判定与部分恢复见截断 JSON 的判定与修复一文。 - 破形:供应商不支持该子集时仍可能拿到坏 JSON。重试时不要只说「再来一次」,把具体校验错误原文附回提示——「severity 必须是 low/medium/high/critical,你输出了 urgent,请修正后重新输出」——带错误上下文的重试能把平均重试次数从 3 次降到约 1.5 次。
给重试设硬上限(比如 2 次),超限降级到更小的模型做纠错或进人工队列,别让一条坏输出拖死整条流水线。
八、上线自检清单
| 检查项 | 通过标准 |
|---|---|
| required | 每个对象的全部字段都在 required 里 |
| additionalProperties | 每个对象显式 false,递归到最深层 |
| 可选语义 | 用 ["string", "null"] 联合模拟,没有裸 optional |
| 禁用词汇 | 无 $ref / allOf / if-then-else / dependentRequired |
| 不生效词汇 | pattern、format 类约束在应用层二次校验 |
| 规模 | 属性 ≤5000、嵌套 ≤10 层、字符串总量 ≤12 万字符 |
| 分流 | refusal / length / 解析失败三路分开处理 |
| 重试 | 带校验错误原文,上限 2 次,超限降级 |
| 语义 | schema 之外的 evals 或字段级断言兜底 |
这套清单过了,形状可靠性基本就锁死了;语义与契约演进(怎么给 schema 做版本化、怎么让坏 schema 在 CI 里先红)见把 Schema 契约焊进 CI。
FAQ
strict 模式能保证字段值正确吗?
不能。它只在解码期锁死语法和形状,保证「每个键都存在、类型对、枚举合法」,不保证值语义正确。模型仍可能输出格式合法但内容错误的数据,语义层要靠评测集或字段级断言兜底。
为什么可选字段也要写进 required?
strict 的状态机要求每个被声明的属性都可达。省略 required 项会在校验时被拒。可选语义用 ["string", "null"] 联合类型模拟:字段必然出现,值可以是 null,下游用 null 判断缺省。
pattern 和 minLength 完全没用吗?
在微调模型与多数 strict 配置下不被强制。它们不会让请求报错,所以最危险——你以为有防线,实际没有。依赖这些约束的输入要在拿到响应后用 ajv 或 jsonschema 再显式校验一次。
strict 会不会拖慢响应?
只有新 schema 的首次请求有编译开销(典型 10 秒内,复杂 schema 可到 1 分钟),编译产物缓存后,后续请求只有约 5-8% 的首 token 延迟增量。稳态下基本无感,schema 频繁变动才有成本。
换了模型版本要重测什么?
三件事:该版本对 schema 子集的支持有没有变化、 refusal 与 finish_reason 字段还在不在、嵌套与规模上限有没有收紧。供应商各接受的子集不同,跨模型复用 schema 前先用一条最小请求验证。