結構化輸出

結構化輸出限制 Claude 的回應遵循特定的架構，確保有效、可解析的輸出以供下游處理。使用 JSON 輸出（output_format）進行結構化資料回應，或使用嚴格工具使用（strict: true）以保證工具名稱和輸入的架構驗證。

為什麼使用結構化輸出

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

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

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

• 始終有效：不再有 JSON.parse() 錯誤
• 類型安全：保證欄位類型和必需欄位
• 可靠：無需重試架構違規
• 兩種模式：JSON 用於資料提取等任務，嚴格工具用於複雜工具和代理工作流程等情況

快速開始

何時使用 JSON 輸出與嚴格工具使用

為您的使用案例選擇正確的模式：

為什麼嚴格工具使用對代理很重要

建立可靠的代理系統需要保證架構相容性。無效的工具參數會破壞您的函數和工作流程。Claude 可能會返回不相容的類型（"2" 而不是 2）或缺少欄位，導致執行時錯誤。

嚴格工具使用保證類型安全的參數：

• 函數每次都會收到正確類型的引數
• 無需驗證和重試工具呼叫
• 在規模上一致工作的生產就緒代理

例如，假設預訂系統需要 passengers: int。在沒有嚴格模式的情況下，Claude 可能會提供 passengers: "two" 或 passengers: "2"。使用 strict: true，您可以保證 passengers: 2。

結構化輸出如何工作

在 SDK 中使用 JSON 輸出

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

使用 Pydantic 和 Zod

對於 Python 和 TypeScript 開發人員，您可以使用熟悉的架構定義工具（如 Pydantic 和 Zod），而不是編寫原始 JSON 架構。

SDK 特定方法

Python：client.beta.messages.parse()（推薦）

parse() 方法自動轉換您的 Pydantic 模型、驗證回應，並返回 parsed_output 屬性。

Python：transform_schema() 幫助程式

用於在發送前手動轉換架構，或當您想修改 Pydantic 生成的架構時。與 client.beta.messages.parse() 不同，後者自動轉換提供的架構，這給您轉換後的架構，以便您可以進一步自訂它。

SDK 轉換如何工作

Python 和 TypeScript SDK 自動轉換具有不支援功能的架構：

1. 移除不支援的限制（例如 minimum、maximum、minLength、maxLength）
2. 更新描述與限制資訊（例如「必須至少 100」），當結構化輸出不直接支援該限制時
3. 將 additionalProperties: false 新增到所有物件
4. 篩選字串格式為僅支援的清單
5. 驗證回應針對您的原始架構（具有所有限制）

這意味著 Claude 會收到簡化的架構，但您的程式碼仍然通過驗證強制執行所有限制。

**範例：**具有 minimum: 100 的 Pydantic 欄位在發送的架構中變成純整數，但描述會更新為「必須至少 100」，SDK 會根據原始限制驗證回應。

常見使用案例

重要考慮事項

文法編譯和快取

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

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

提示修改和代幣成本

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

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

JSON Schema 限制

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

無效輸出

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

拒絕（stop_reason: "refusal"）

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

• 回應將具有 stop_reason: "refusal"
• 您將收到 200 狀態碼
• 您將被計費生成的代幣
• 輸出可能不符合您的架構（拒絕優先）

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

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

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

架構驗證錯誤

如果您的架構使用不支援的功能或過於複雜，您將收到 400 錯誤：

「架構中的遞迴定義過多」

• 原因：架構具有過度或循環遞迴定義
• 解決方案：簡化架構結構，減少巢狀深度

「架構過於複雜」

• 原因：架構超過複雜性限制
• 解決方案：分解為較小的架構、簡化結構或減少標記為 strict: true 的工具數量

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

功能相容性

適用於：

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

不相容於：

• 引用：引用需要將引用區塊與文字交錯，這與嚴格 JSON 架構限制衝突。如果啟用引用和 output_format，則返回 400 錯誤。
• 訊息預填：與 JSON 輸出不相容

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)