JSON 工具箱

LLM 结构化输出翻车:strict 模式的 Schema 要这样写

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

实战约 8 分钟发布于 2026-11-19更新于 2026-11-19
LLM strict 模式 JSON Schema 改写规则示意图

结论: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 的写法直觉相反:

  1. 每个字段都必须写进 required。 strict 不接受可选字段这个概念。想表达「可选」,把字段留在 required 里,但类型写成可空联合 "type": ["string", "null"],缺省时让模型返回 null。这和一般 JSON Schema 实践(required 只列必要字段)完全相反。
  2. 每个对象都必须显式写 additionalProperties: false。 普通实践中这常常不设置(参考本站 additionalProperties 的三种运行时表现一文),但在 strict 模式下它是准入条件:没写就报错。原因很直白——状态机只能生成被声明的键,多出来的键在语法上就不可达。
  3. 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 前先用一条最小请求验证。

参考资料

相关文章

JSON Schema 契约测试:把校验规则焊进 CI

schema 写完不改就是坏的起点:一个 typo 让校验器静默放行,一次重构让 fixture 全线误报。本文给出一套可落地的契约测试方案——正例、负例、快照三件套,schema 本身先进 lint,编译一次复用,再把四道闸门焊进 CI,让契约坏了构建先红。

实战约 8 分钟更新于 2026-11-05

LLM 输出的 JSON 被截断了怎么办:先看停止原因,再谈修复

模型返回的 JSON 少了结尾,解析器只给一个列号,补上括号就能跑——但缺口被藏进了数据里。本文按停止原因判定、输出额度定容、schema 字段排序与部分恢复的诚实披露,划清截断场景下能修与必须重试的边界。

实战约 5 分钟更新于 2026-11-14

additionalProperties 不关,Schema 校验等于没校验

校验通过不代表数据干净。Pydantic 默认忽略未知字段,Zod 默认剥离,Ajv 默认放行——模型编造的参数、拼错的键都会静默穿过。本文用实测说明静默放行的三种形态,并给出关闭对象、控制强转、逐层收口的完整写法。

进阶约 8 分钟更新于 2026-11-02