Amazon Bedrock 10 月 20 日正式支援 Claude 結構化輸出後,output_config.format 和 strict 工具該怎麼寫 JSON Schema?

截至 2026 年 10 月 22 日:Bedrock 在 runtime 與 mantle 全面開放 Claude 結構化輸出。InvokeModel 在 output_config.format 傳 json_schema 物件;mantle 工具用 strict true。每個 object 要 additionalProperties false,並先讀 stop_reason 再 JSON.parse。

先給結論:10 月 20 日 Amazon Bedrock 把 Claude 的結構化輸出從公測推到正式可用,覆蓋 bedrock-runtime 和 bedrock-mantle 兩條入口。文字答案走 output_config.format,型別是 json_schema,schema 是嵌在請求體裡的 JSON 物件,不是字串。智慧體工具在 mantle 上把 strict: true 和 input_schema 一起傳。生成階段就約束 token,不等於響應裡永遠只有合法業務 JSON:stop_reason 仍是 end_turn、max_tokens 或安全拒答,要先讀再 JSON.parse。

這篇按 2026 年 10 月 22 日寫,依據 10 月 19–20 日 AWS 部落格與產品公告。昨天本站寫過《Responses API 12 小時快取的 usage 欄位》。那邊改 schema 會改快取字首;Bedrock 這邊改 schema 結構會觸發語法重新編譯,但只改欄位名或 description 通常仍用 24 小時內的快取。

10 月 20 日實際開放了什麼

公告寫的是:在模型可用的區域裡,所有 Anthropic Claude 模型都支援結構化輸出;既可以用 boto3 調 bedrock-runtime,也可以用 Messages API 走 bedrock-mantle。兩條路都能拿到符合你定義結構的 JSON,而不是先收一段自由文字再靠正則撈欄位。

機制請求裡寫什麼典型場景
JSON Schema 輸出格式output_config.format 裡 type: json_schema 加 schema抽取工單、合約欄位、報表行
Strict tool use工具定義裡 strict: true 加 input_schema多步 Agent、函式呼叫參數

實現方式是約束解碼:模型在生成 token 時就不能走出 schema 允許的集合。這和「生成完再用 JSON Schema 校驗、失敗就重試」不是同一套成本模型。Bedrock 還支援批次推理、跨區域推理(runtime),以及把結構化結果流式打成型別化事件。

bedrock-runtime:InvokeModel 怎麼帶 schema

InvokeModel 的請求體仍是 Anthropic 原生 JSON。anthropic_version 常見為 bedrock-2023-05-31。schema 放在 output_config.format,且必須是物件,不能寫成字串包一層。

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 512,
  "messages": [
    {"role": "user", "content": "Paulo Santos (paulo@example.com) 想了解 Enterprise 方案並預約下週二下午 2 點演示。"}
  ],
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"},
          "plan_interest": {"type": "string"},
          "demo_requested": {"type": "boolean"}
        },
        "required": ["name", "email", "plan_interest", "demo_requested"],
        "additionalProperties": false
      }
    }
  }
}

每個 object 都要寫 additionalProperties: false,否則 Bedrock 不接受這份 schema。欄位名和 description 會參與模型理解要抽什麼;分類場景裡用 enum 把標籤鎖在固定集合,比事後用 if 過濾更穩。

bedrock-mantle:strict 工具參數

mantle 面向帶服務端工具、後臺推理和有狀態對話的 Agent。工具塊里加 strict: true 後,tool_use 的 input 物件必須完全符合 input_schema,不能多欄位,enum 外的字串也不會出現。

{
  "name": "get_weather",
  "description": "查詢指定地點當前天氣",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {"type": "string"},
      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    },
    "required": ["location", "unit"],
    "additionalProperties": false
  }
}

文字結構化輸出管的是 content 裡 type: text 的那段 JSON 字串;strict 工具管的是 type: tool_use 的 input 物件(在 Bedrock 響應裡通常已是物件,不必再 parse 一層字串)。同一條流水線裡兩種合約可能同時出現,日誌要分欄位存。

從響應體到可校驗 JSON 的路徑

InvokeModel 返回的 body 先 json.loads 成訊息物件。先看 stop_reason:

  • end_turn:在 content 裡找 type: text 的塊,對其 text 再 JSON.parse,得到業務物件。
  • max_tokens:JSON 可能截斷,不能當成功抽取;應加大 max_tokens 重試。
  • 安全拒答:可能沒有符合 schema 的 text 塊,要走人工或降級策略,不能假設 JSON.parse 一定成功。
{
  "stop_reason": "end_turn",
  "content": [
    {
      "type": "text",
      "text": "{\"name\":\"Paulo Santos\",\"email\":\"paulo@example.com\",\"plan_interest\":\"Enterprise\",\"demo_requested\":true}"
    }
  ]
}

解析成功後,仍建議用 JSON Schema 或本站工具做一次二次校驗,確認必填鍵都在、型別沒被你下游改壞。Bedrock 保證的是模型輸出側符合你提交的子集 schema,不是你應用裡合併預設值之後的物件。

  • JSON 校驗 — 確認 text 塊裡的字串是合法 JSON。
  • JSONPath — 從批次響應裡取出 $.content[?(@.type=='text')].text。
  • JSON Diff — 對比兩次抽取結果,看是 schema 變了還是輸入變了。

Schema 子集與 additionalProperties

Bedrock 按 JSON Schema Draft 2020-12 的一個子集校驗你提交的 schema。支援 object、array、基本型別、enum、const、有限的 anyOf/allOf、內部 $ref,以及部分字串 format(如 email、uuid、date-time)。

明確不支援的有:遞迴 schema、外部 $ref、數值約束(minimum/maximum)、字串長度約束、以及把 additionalProperties 設成除 false 以外的值。陣列只支援 minItems 為 0 或 1。設計 schema 時先用最少必填欄位上線,再迭代;複雜巢狀會拉長首次編譯時間,也增大 Converse 類介面的請求體體積(schema 計入 payload)。

語法編譯與 24 小時快取

新 schema 第一次請求時,Bedrock 會編譯語法 artifact,首包延遲可能略高。編譯結果按帳號快取 24 小時,同一結構重複呼叫開銷很小。只改 property 的 title 或 description 一般不觸發重新編譯;改 properties 結構、required 或 enum 成員則會換一份語法。

應用層應儘量複用固定 schema 模板(例如「工單分類 v3」),把變長提示詞放在 messages 裡,而不是每次請求改 schema 形狀。這和直連 Claude API 上結構化輸出要穩定字首、方便提示快取的思路一致,只是 Bedrock 側快取的是語法而不是 OpenAI 式的 KV 字首。

常見問題 FAQ

InvokeModel 上的 output_config 和直連 Claude API 一樣嗎?

欄位名同為 output_config.format 和 json_schema,但 Bedrock 走 InvokeModel 原生體,且要 anthropic_version。直連 API 在 2026 年已把舊 output_format 遷到 output_config.format。兩邊都要 additionalProperties false,錯誤碼與拒答形態仍按各自閘道器返回。

為什麼每個 object 都必須 additionalProperties false?

這是 Bedrock 結構化輸出的硬性要求。設為 true 或省略時,schema 校驗階段就會拒絕請求,不會進入約束生成。目的是讓輸出物件閉包在已知欄位集內,避免模型偷偷加鍵。

stop_reason 是 max_tokens 時還能信任 JSON 嗎?

不能。公告與部落格都寫明 token 用盡時輸出可能不完整,不能當作合規抽取。應提高 max_tokens 或縮短 schema 與提示,然後重試。

只改欄位 description 會觸發重新編譯嗎?

AWS 檔案寫明:僅改名稱或 description 通常保留已快取語法;改 JSON 結構(欄位增刪、required、enum 集合)會失效快取並重新編譯。

json_schema 輸出和 strict 工具有什麼分工?

前者約束最終給使用者或下游系統的 text JSON;後者約束 tool_use 的 input 物件。Agent 裡可能先 strict 調工具,再在最後一步用 json_schema 彙總報告,兩套 schema 應分開版本管理。

有了結構化輸出就可以刪掉所有 JSON.parse 嗎?

不行。你仍要解析 InvokeModel 外層 body、從 content 取出 text,再 parse 內層字串。拒答與截斷路徑下 parse 仍會失敗。結構化輸出消除的是「模型自由文字不符合 schema」這一類錯誤,不是解析棧上的全部異常。

總結

10 月 20 日的變化,是把 Claude 在 Bedrock 上的 JSON 合約變成一等公民。runtime 用 output_config.format,mantle 用 strict 工具;物件閉包靠 additionalProperties: false;上線前用真實工單或合約測 stop_reason 三分支。

留檔時記下 modelId、schema 版本號、stop_reason 以及解析後的物件雜湊,方便和《Sonnet 5.5 工具與 schema》對照直連 API 的差異。