結構化輸出

結構化輸出限制 Claude 的回應遵循特定的架構，確保有效、可解析的輸出以供下游處理。結構化輸出提供兩個互補的功能：

• JSON 輸出 (output_config.format)：以特定的 JSON 格式獲得 Claude 的回應
• 嚴格工具使用 (strict: true)：保證工具名稱和輸入的架構驗證

您可以在同一請求中獨立使用這些功能或一起使用。

為什麼使用結構化輸出

沒有結構化輸出，Claude 可能會生成格式不正確的 JSON 回應或無效的工具輸入，導致應用程式中斷。即使進行仔細的提示，您也可能遇到：

• 來自無效 JSON 語法的解析錯誤
• 缺少必需的欄位
• 不一致的資料類型
• 需要錯誤處理和重試的架構違規

結構化輸出通過受限解碼保證架構相容的回應：

• 始終有效：不再有 JSON.parse() 錯誤
• 類型安全：保證欄位類型和必需欄位
• 可靠：無需重試架構違規

JSON 輸出

JSON 輸出控制 Claude 的回應格式，確保 Claude 返回與您的架構相匹配的有效 JSON。當您需要以下情況時，請使用 JSON 輸出：

• 控制 Claude 的回應格式
• 從圖像或文本中提取資料
• 生成結構化報告
• 格式化 API 回應

快速開始

回應格式： 在 response.content[0].text 中與您的架構相匹配的有效 JSON

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

運作方式

在 SDK 中使用 JSON 輸出

SDK 提供了幫助程式，使得使用 JSON 輸出變得更加容易，包括架構轉換、自動驗證和與流行架構庫的整合。

使用原生架構定義

與其編寫原始 JSON 架構，不如在您的語言中使用熟悉的架構定義工具：

• Python：使用 client.messages.parse() 的 Pydantic 模型
• TypeScript：使用 zodOutputFormat() 的 Zod 架構或使用 jsonSchemaOutputFormat() 的類型化 JSON Schema 字面量
• Java：通過 outputConfig(Class<T>) 進行自動架構推導的純 Java 類別
• Ruby：使用 output_config: {format: Model} 的 Anthropic::BaseModel 類別
• PHP：實現 StructuredOutputModel 的類別，使用 outputConfig: ['format' => MyClass::class]
• CLI、C#、Go：通過 output_config 傳遞的原始 JSON 架構

SDK 特定方法

每個 SDK 都提供了幫助程式，使得使用結構化輸出變得更加容易。有關完整詳細資訊，請參閱個別 SDK 頁面。

SDK 轉換如何工作

Python、TypeScript、Ruby 和 PHP SDK 自動轉換具有不支持功能的架構：

1. 移除不支持的約束（例如 minimum、maximum、minLength、maxLength）
2. 更新描述與約束信息（例如「必須至少 100」），當約束不直接支持結構化輸出時
3. 將 additionalProperties: false 添加到所有物件
4. 篩選字符串格式到支持的列表
5. 驗證回應針對您的原始架構（包含所有約束）

這意味著 Claude 接收簡化的架構，但您的代碼仍然通過驗證強制所有約束。

範例： 具有 minimum: 100 的 Pydantic 欄位在發送的架構中變成普通整數，但 SDK 將描述更新為「必須至少 100」，並針對原始約束驗證回應。

常見用例

嚴格工具使用

若要在工具輸入上使用文法約束採樣來強制執行 JSON Schema 合規性，請參閱嚴格工具使用。

同時使用兩項功能

JSON 輸出和嚴格工具使用解決不同的問題並可以協同運作：

• JSON 輸出控制 Claude 的回應格式（Claude 說什麼）
• 嚴格工具使用驗證工具參數（Claude 如何呼叫您的函數）

結合使用時，Claude 可以使用保證有效的參數呼叫工具，並返回結構化的 JSON 回應。這對於需要可靠工具呼叫和結構化最終輸出的代理工作流程很有用。

重要考量事項

文法編譯和快取

結構化輸出使用具有編譯文法工件的受限採樣。這引入了一些需要注意的效能特性：

• **首次請求延遲：**第一次使用特定架構時，文法編譯期間會有額外延遲
• **自動快取：**編譯的文法會快取 24 小時（從上次使用起），使後續請求快得多
• **快取失效：**如果您變更以下內容，快取將失效：
  • JSON 架構結構
  • 請求中的工具集（使用結構化輸出和工具使用時）
  • 僅變更 name 或 description 欄位不會使快取失效

提示修改和代幣成本

使用結構化輸出時，Claude 會自動收到一個額外的系統提示，說明預期的輸出格式。這意味著：

• 您的輸入代幣計數略高
• 注入的提示會像任何其他系統提示一樣消耗代幣
• 變更 output_config.format 參數將使該對話執行緒的任何提示快取失效

JSON 架構限制

結構化輸出支援標準 JSON 架構，但有一些限制。JSON 輸出和嚴格工具使用都共享這些限制。

屬性排序

使用結構化輸出時，物件中的屬性會保持從您的架構定義的順序，但有一個重要的注意事項：必需屬性首先出現，然後是可選屬性。

例如，給定此架構：

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

輸出將按以下順序排列屬性：

1. name（必需，按架構順序）
2. email（必需，按架構順序）
3. notes（可選，按架構順序）
4. age（可選，按架構順序）

這意味著輸出可能看起來像：

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

如果輸出中的屬性順序對您的應用程式很重要，請將所有屬性標記為必需，或在您的解析邏輯中考慮此重新排序。

無效輸出

雖然結構化輸出在大多數情況下保證架構合規性，但在某些情況下輸出可能不符合您的架構：

拒絕（stop_reason: "refusal"）

Claude 即使在使用結構化輸出時也會保持其安全性和有用性屬性。如果 Claude 因安全原因拒絕請求：

• 回應具有 stop_reason: "refusal"
• 您將收到 200 狀態碼
• 您將被計費生成的代幣
• 輸出可能不符合您的架構，因為拒絕訊息優先於架構約束

達到代幣限制（stop_reason: "max_tokens"）

如果因達到 max_tokens 限制而截斷回應：

• 回應具有 stop_reason: "max_tokens"
• 輸出可能不完整且不符合您的架構
• 使用更高的 max_tokens 值重試以獲得完整的結構化輸出

架構複雜性限制

結構化輸出的工作原理是將您的 JSON 架構編譯成限制 Claude 輸出的文法。更複雜的架構會產生更大的文法，編譯時間更長。為了防止過度編譯時間，API 強制執行多個複雜性限制。

明確限制

以下限制適用於所有具有 output_config.format 或 strict: true 的請求：

其他內部限制

除了上述明確限制外，編譯文法大小還有其他內部限制。這些限制存在是因為架構複雜性不會簡化為單一維度：可選參數、聯合類型、嵌套物件和工具數量等功能以相互作用的方式相互作用，可能使編譯文法不成比例地大。

超過這些限制時，您將收到 400 錯誤，訊息為「架構對於編譯來說太複雜」。這些錯誤意味著您的架構的組合複雜性超過了可以有效編譯的範圍，即使每個上述個別限制都滿足。作為最後的防止措施，API 還強制執行編譯超時 180 秒。通過所有明確檢查但產生非常大編譯文法的架構可能會達到此超時。

減少架構複雜性的提示

如果您達到複雜性限制，請按順序嘗試這些策略：

1. **僅將關鍵工具標記為嚴格。**如果您有許多工具，請將其保留給架構違規會造成真實問題的工具，並依賴 Claude 對更簡單工具的自然遵守。

2. **減少可選參數。**盡可能使參數 required。每個可選參數大約會使文法狀態空間的一部分加倍。如果參數始終有合理的預設值，請考慮使其成為必需的，並讓 Claude 明確提供該預設值。

3. **簡化嵌套結構。**具有可選欄位的深層嵌套物件會加重複雜性。盡可能平坦化結構。

4. **分割成多個請求。**如果您有許多嚴格工具，請考慮將它們分割到單獨的請求或子代理中。

如有有效架構的持續問題，請聯絡支援並提供您的架構定義。

資料保留

使用結構化輸出時，提示和回應會使用 ZDR 進行處理。但是，JSON 架構本身會暫時快取長達 24 小時（自上次使用起）以用於最佳化目的。API 回應之外不會保留任何提示或回應資料。

結構化輸出符合 HIPAA 資格，但PHI 不得包含在 JSON 架構定義中。API 將 JSON 架構編譯成單獨快取的文法，與訊息內容分開，這些快取架構不會獲得與提示和回應相同的 PHI 保護。不要在架構屬性名稱、enum 值、const 值或 pattern 正規表達式中包含 PHI。PHI 應僅出現在訊息內容（提示和回應）中，其中受 HIPAA 保障保護。

有關所有功能的 ZDR 和 HIPAA 資格，請參閱 API 和資料保留。

功能相容性

適用於：

• 批次處理：以 50% 折扣大規模處理結構化輸出
• 代幣計數：計數代幣而無需編譯
• 串流：像普通回應一樣串流結構化輸出
• 組合使用：在同一請求中同時使用 JSON 輸出（output_config.format）和嚴格工具使用（strict: true）

不相容於：

• 引用：引用需要將引用區塊與文字交錯，這與嚴格 JSON 架構約束衝突。如果啟用引用且使用 output_config.format，則返回 400 錯誤。
• 訊息預填充：與 JSON 輸出不相容