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