結構化輸出

結構化輸出會限制 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： 搭配 client.messages.parse() 使用 Pydantic 模型
• TypeScript： 搭配 zodOutputFormat() 使用 Zod 結構描述，或搭配 jsonSchemaOutputFormat() 使用類型化的 JSON Schema 字面值
• Java： 透過 outputConfig(Class<T>) 自動衍生結構描述的純 Java 類別
• Ruby： 搭配 output_config: {format: Model} 使用 Anthropic::BaseModel 類別
• PHP： 搭配 outputConfig: ['format' => MyClass::class] 使用實作 StructuredOutputModel 的類別
• C#： 搭配泛型 Create<T>() 多載使用純 C# 類別，自動衍生結構描述
• Go： 在測試版 API 上自動反射為 JSON 結構描述的 Go 結構體，或透過 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# 和 Go SDK 在結構描述是從原生類型衍生時（C# 中的 Create<T>()；Go 測試版 API 上的結構體反射或 BetaJSONSchemaOutputFormat()）會套用相同的轉換。轉換步驟如下：

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)



重要考量事項



語法編譯與快取

結構化輸出使用帶有已編譯語法產物的受限取樣。這會帶來一些需要注意的效能特性：

• 首次請求延遲： 首次使用特定結構描述時，會因語法編譯而產生額外的延遲
• 自動快取： 已編譯的語法會從最後一次使用起快取 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 值重試，以取得完整的結構化輸出



結構描述複雜度限制

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



明確限制

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



額外的內部限制

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

當超過這些限制時，您會收到 400 錯誤，訊息為「Schema is too complex for compilation」。這些錯誤表示您的結構描述的合併複雜度超過了可有效編譯的範圍，即使上表中的每個個別限制都已滿足。作為最後的保護措施，API 還強制執行 180 秒的編譯逾時。通過所有明確檢查但產生非常大的已編譯語法的結構描述可能會觸發此逾時。



降低結構描述複雜度的技巧

如果您遇到複雜度限制，請依序嘗試以下策略：

1. 僅將關鍵工具標記為嚴格。 如果您有許多工具，請將嚴格模式保留給結構描述違規會造成實際問題的工具，並依賴 Claude 對較簡單工具的自然遵循能力。

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

3. 簡化巢狀結構。 帶有選填欄位的深層巢狀物件會加劇複雜度。盡可能扁平化結構。

4. 拆分為多個請求。 如果您有許多嚴格工具，請考慮將它們拆分到不同的請求或子代理中。

如果有效的結構描述持續出現問題，請附上您的結構描述定義聯絡支援。



資料保留

使用結構化輸出時，提示和回應會以 ZDR 方式處理。然而，JSON 結構描述本身會為了最佳化目的而暫時快取，自最後一次使用起最多保留 24 小時。除了 API 回應之外，不會保留任何提示或回應資料。

結構化輸出符合 HIPAA 資格，但 JSON 結構描述定義中不得包含 PHI。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 錯誤。
• 訊息預填： 與 JSON 輸出不相容



後續步驟