結構化輸出

結構化輸出（structured outputs）會限制 Claude 的回應遵循特定的結構描述（schema），確保輸出有效且可解析，以供下游處理。結構化輸出提供兩個互補的功能：

• JSON 輸出（output_config.format）：以特定的 JSON 格式取得 Claude 的回應
• 嚴格工具使用（strict: true）：保證對工具名稱和輸入進行結構描述驗證

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



為什麼使用結構化輸出

如果沒有結構化輸出，Claude 可能會產生格式錯誤的 JSON 回應或無效的工具輸入，進而破壞您的應用程式。即使經過仔細的提示設計，您仍可能遇到：

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

結構化輸出透過受限解碼（constrained decoding）保證回應符合結構描述：

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



JSON 輸出

JSON 輸出控制 Claude 的回應格式，確保 Claude 回傳符合您結構描述的有效 JSON。在以下情況使用 JSON 輸出：

• 控制 Claude 的回應格式
• 從圖片或文字中擷取資料
• 產生結構化報告
• 格式化 API 回應



快速開始

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    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_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,
            },
        }
    },
)
print(response.content[0].text)

回應格式： 在 response.content[0].text 中符合您結構描述的有效 JSON

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



運作方式



在 SDK 中使用 JSON 輸出

SDK 提供了輔助工具，讓使用 JSON 輸出更加容易，包括結構描述轉換、自動驗證，以及與熱門結構描述函式庫的整合。



使用原生結構描述定義

您可以使用您語言中熟悉的結構描述定義工具，而不必撰寫原始 JSON 結構描述：

• Python： Pydantic 模型搭配 client.messages.parse()
• TypeScript： Zod 結構描述搭配 zodOutputFormat()，或型別化的 JSON Schema 字面值搭配 jsonSchemaOutputFormat()
• Java： 純 Java 類別，透過 outputConfig(Class<T>) 自動推導結構描述
• Ruby： Anthropic::BaseModel 類別搭配 output_config: {format: Model}
• PHP： 實作 StructuredOutputModel 的類別搭配 outputConfig: ['format' => MyClass::class]
• C#： 純 C# 類別搭配泛型 Create<T>() 多載，自動推導結構描述
• Go： 在 beta API 上自動將 Go 結構（struct）反射為 JSON 結構描述，或透過 output_config 使用原始 JSON 結構描述
• CLI： 透過 output_config 傳遞原始 JSON 結構描述

from pydantic import BaseModel
from anthropic import Anthropic


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


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=1024,
    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)



SDK 特定方法

每個 SDK 都提供輔助工具，讓使用結構化輸出更加容易。請參閱各個 SDK 頁面以取得完整詳細資訊。



SDK 轉換的運作方式

Python、TypeScript、Ruby 和 PHP SDK 會自動轉換具有不支援功能的結構描述。當結構描述是從原生類型推導時（C# 中的 Create<T>()；Go beta API 上的結構反射或 BetaJSONSchemaOutputFormat()），C# 和 Go SDK 會套用相同的轉換。轉換步驟：

1. 移除不支援的約束（例如 minimum、maximum、minLength、maxLength）
2. 更新描述以包含約束資訊（例如「必須至少為 100」），當結構化輸出不直接支援該約束時
3. 為所有物件加入 additionalProperties: false
4. 過濾字串格式，僅保留支援的清單
5. 針對您的原始結構描述驗證回應（包含所有約束）

這表示 Claude 收到的是簡化的結構描述，但您的程式碼仍會透過驗證強制執行所有約束。

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



常見使用案例



嚴格工具使用

若要透過文法約束取樣（grammar-constrained sampling）對工具輸入強制執行 JSON Schema 合規性，請參閱嚴格工具使用。



同時使用兩種功能

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

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

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

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON 輸出：結構化回應格式
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # 嚴格工具使用：保證工具參數
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)



重要考量



文法編譯與快取

結構化輸出使用帶有已編譯文法成品（grammar artifact）的受限取樣。這會帶來一些需要注意的效能特性：

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



提示修改與 token 成本

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

• 您的輸入 token 數量會略高
• 注入的提示會像任何其他系統提示一樣消耗您的 token
• 變更 output_config.format 參數會使該對話串的任何提示快取失效



JSON Schema 限制

結構化輸出支援標準 JSON Schema，但有一些限制。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 狀態碼
• 您會為產生的 token 付費
• 輸出可能不符合您的結構描述，因為拒絕訊息優先於結構描述約束

達到 token 限制（stop_reason: "max_tokens"）

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

• 回應的 stop_reason 為 "max_tokens"
• 輸出可能不完整且不符合您的結構描述
• 使用更高的 max_tokens 值重試以取得完整的結構化輸出

列舉值大小寫

結構化輸出不保證字串 enum 和 const 值的大小寫：Claude 可能回傳一個僅在大小寫上與您的結構描述不同的值，通常是空格後單字的第一個字母。例如，給定以下結構描述：

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

輸出可能包含 "Conversation Topic 3"（大寫「T」），即使該確切值不在列舉中。回應會正常完成，沒有錯誤也沒有特殊的 stop_reason。這適用於 JSON 輸出和嚴格工具使用。請以不區分大小寫的方式比較列舉值，並避免使用僅在大小寫上不同的列舉值。



結構描述複雜度限制

結構化輸出的運作方式是將您的 JSON 結構描述編譯成約束 Claude 輸出的文法。更複雜的結構描述會產生更大的文法，需要更長的編譯時間。為了防止過長的編譯時間，API 強制執行多項複雜度限制。



明確限制

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



額外的內部限制

除了上表中的明確限制外，對已編譯文法的大小還有額外的內部限制。這些限制之所以存在，是因為結構描述的複雜度無法簡化為單一維度：選用參數、聯合類型、巢狀物件和工具數量等功能會以可能使已編譯文法不成比例地變大的方式相互影響。

當超過這些限制時，您會收到帶有「Schema is too complex for compilation」訊息的 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% 折扣大規模處理結構化輸出
• Token 計數： 在不編譯的情況下計算 token
• 串流： 像一般回應一樣串流結構化輸出
• 組合使用： 在同一個請求中同時使用 JSON 輸出（output_config.format）和嚴格工具使用（strict: true）

不相容：

• 引用： 引用需要將引用區塊與文字交錯，這與嚴格的 JSON 結構描述約束衝突。如果在啟用引用的情況下使用 output_config.format，會回傳 400 錯誤。
• 訊息預填（Message Prefilling）： 與 JSON 輸出不相容



後續步驟