Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
結構化輸出會限制 Claude 的回應遵循特定的結構描述（schema），確保輸出有效且可解析，以供下游處理使用。結構化輸出提供兩個互補的功能：
output_config.format）：以特定的 JSON 格式取得 Claude 的回應strict: true）：保證對工具名稱和輸入進行結構描述驗證您可以獨立使用這些功能，也可以在同一個請求中一起使用。
如果沒有結構化輸出，Claude 可能會產生格式錯誤的 JSON 回應或無效的工具輸入，導致您的應用程式出錯。即使經過仔細的提示設計，您仍可能遇到：
結構化輸出透過受限解碼（constrained decoding）保證回應符合結構描述：
JSON.parse() 錯誤JSON 輸出控制 Claude 的回應格式，確保 Claude 回傳符合您結構描述的有效 JSON。在以下情況下使用 JSON 輸出：
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
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(next(block.text for block in response.content if block.type == "text"))回應格式： 在回應的文字內容區塊中，包含符合您結構描述的有效 JSON
{
"name": "John Smith",
"email": "[email protected]",
"plan_interest": "Enterprise",
"demo_requested": true
}定義您的 JSON 結構描述
建立一個 JSON 結構描述，描述您希望 Claude 遵循的結構。該結構描述使用標準的 JSON Schema 格式，但有一些限制（請參閱 JSON Schema 限制）。
新增 output_config.format 參數
在您的 API 請求中包含 output_config.format 參數，並設定 type: "json_schema" 以及您的結構描述定義。
解析回應
Claude 的回應是符合您結構描述的有效 JSON，會在回應的文字內容區塊中回傳。
SDK 提供了輔助工具，讓您更容易使用 JSON 輸出，包括結構描述轉換、自動驗證，以及與熱門結構描述函式庫的整合。
您可以使用您所用語言中熟悉的結構描述定義工具，而不必撰寫原始的 JSON 結構描述：
client.messages.parse() 使用 Pydantic 模型zodOutputFormat() 使用 Zod 結構描述，或搭配 jsonSchemaOutputFormat() 使用具類型的 JSON Schema 字面值outputConfig(Class<T>) 使用純 Java 類別並自動衍生結構描述output_config: {format: Model} 使用 Anthropic::BaseModel 類別outputConfig: ['format' => MyClass::class] 使用實作 StructuredOutputModel 的類別Create<T>() 多載搭配純 C# 類別，自動衍生結構描述output_config 使用原始 JSON 結構描述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-5",
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 頁面以取得完整詳細資訊。
client.messages.parse()（建議使用）
parse() 方法會自動轉換您的 Pydantic 模型、驗證回應，並回傳 parsed_output 屬性。
from pydantic import BaseModel
class ContactInfo(BaseModel):
name: str
email: str
plan_interest: str
response = client.messages.parse(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Extract contact info: John Smith, [email protected], interested in the Pro plan",
}
],
output_format=ContactInfo,
)
# 直接存取已解析的輸出
contact = response.parsed_output
print(contact.name, contact.email)transform_schema() 輔助函式
適用於您需要在傳送前手動轉換結構描述，或想要修改 Pydantic 產生的結構描述的情況。與會自動轉換所提供結構描述的 client.messages.parse() 不同，此函式會提供轉換後的結構描述，讓您可以進一步自訂。
from anthropic import transform_schema
from pydantic import TypeAdapter
# 先將 Pydantic 模型轉換為 JSON schema，再進行轉換
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# 視需要修改 schema
schema["properties"]["custom_field"] = {"type": "string"}
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "..."}],
output_config={
"format": {"type": "json_schema", "schema": schema},
},
)Python、TypeScript、Ruby 和 PHP SDK 會自動轉換包含不支援功能的結構描述。當結構描述是從原生類型衍生時（C# 中的 Create<T>()；Go 測試版 API 上的結構體反射或 BetaJSONSchemaOutputFormat()），C# 和 Go SDK 也會套用相同的轉換。轉換步驟如下：
minimum、maximum、minLength、maxLength）additionalProperties: false這表示 Claude 會收到簡化的結構描述，但您的程式碼仍會透過驗證強制執行所有限制。
範例： 帶有 minimum: 100 的 Pydantic 欄位在傳送的結構描述中會變成普通整數，但 SDK 會將描述更新為「必須至少為 100」，並根據原始限制驗證回應。
如需透過文法限制取樣（grammar-constrained sampling）在工具輸入上強制執行 JSON Schema 合規性，請參閱嚴格工具使用。
JSON 輸出和嚴格工具使用解決不同的問題，並可協同運作：
結合使用時，Claude 可以使用保證有效的參數呼叫工具，並且回傳結構化的 JSON 回應。這對於需要可靠工具呼叫和結構化最終輸出的代理式工作流程非常有用。
response = client.messages.create(
model="claude-opus-5",
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)結構化輸出使用受限取樣搭配編譯後的文法產物。這會帶來一些需要注意的效能特性：
name 或 description 欄位不會使快取失效使用結構化輸出時，Claude 會自動收到一個額外的系統提示，說明預期的輸出格式。這表示：
output_config.format 參數會使該對話串的任何提示快取失效結構化輸出支援標準 JSON Schema，但有一些限制。JSON 輸出和嚴格工具使用都共用這些限制。
使用結構化輸出時，物件中的屬性會維持您結構描述中定義的順序，但有一個重要的注意事項：必要屬性會先出現，接著才是選用屬性。
例如，給定以下結構描述：
{
"type": "object",
"properties": {
"notes": { "type": "string" },
"name": { "type": "string" },
"email": { "type": "string" },
"age": { "type": "integer" }
},
"required": ["name", "email"],
"additionalProperties": false
}輸出的屬性排序如下：
name（必要，依結構描述順序）email（必要，依結構描述順序）notes（選用，依結構描述順序）age（選用，依結構描述順序）這表示輸出可能如下所示：
{
"name": "John Smith",
"email": "[email protected]",
"notes": "Interested in enterprise plan",
"age": 35
}如果輸出中的屬性順序對您的應用程式很重要，請將所有屬性標記為必要，或在解析邏輯中考量此重新排序。
雖然結構化輸出在大多數情況下保證符合結構描述，但在某些情況下輸出可能不符合您的結構描述：
拒絕（stop_reason: "refusal"）
即使在使用結構化輸出時，Claude 仍會維持其安全性和有用性的特性。如果 Claude 因安全原因拒絕請求：
stop_reason 為 "refusal"達到 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 的請求：
| 限制 | 值 | 說明 |
|---|---|---|
| 每個請求的嚴格工具數 | 20 | 設定 strict: true 的工具數量上限。非嚴格工具不計入此限制。 |
| 選用參數 | 24 | 所有嚴格工具結構描述和 JSON 輸出結構描述中的選用參數總數。每個未列在 required 中的參數都會計入此限制。 |
| 使用聯合類型的參數 | 16 | 所有嚴格結構描述中使用 anyOf 或類型陣列（例如 "type": ["string", "null"]）的參數總數。這些特別耗費資源，因為它們會造成指數級的編譯成本。 |
除了上表中的明確限制外，編譯後的文法大小還有額外的內部限制。這些限制的存在是因為結構描述的複雜度無法簡化為單一維度：選用參數、聯合類型、巢狀物件和工具數量等功能會相互影響，可能使編譯後的文法不成比例地變大。
當超出這些限制時，您會收到 400 錯誤，訊息為「Schema is too complex for compilation」（結構描述過於複雜，無法編譯）。這些錯誤表示您的結構描述的綜合複雜度超出了可有效編譯的範圍，即使上表中的每個個別限制都已滿足。作為最後的保護措施，API 還強制執行 180 秒的編譯逾時。通過所有明確檢查但產生非常大的編譯文法的結構描述可能會觸發此逾時。
如果您遇到複雜度限制，請依序嘗試以下策略：
僅將關鍵工具標記為嚴格。 如果您有許多工具，請將嚴格模式保留給結構描述違規會造成實際問題的工具，並對較簡單的工具依賴 Claude 的自然遵循能力。
減少選用參數。 盡可能將參數設為 required。每個選用參數大約會使文法狀態空間的一部分加倍。如果某個參數總是有合理的預設值，請考慮將其設為必要，並讓 Claude 明確提供該預設值。
簡化巢狀結構。 帶有選用欄位的深層巢狀物件會加劇複雜度。盡可能扁平化結構。
拆分為多個請求。 如果您有許多嚴格工具，請考慮將它們拆分到不同的請求或子代理中。
如果有效的結構描述持續出現問題，請附上您的結構描述定義聯絡支援團隊。
使用結構化輸出時，提示和回應會以 ZDR 方式處理。然而，JSON 結構描述本身會為了最佳化目的而暫時快取，自最後一次使用起最多保留 24 小時。除了 API 回應之外，不會保留任何提示或回應資料。
結構化輸出符合 HIPAA 資格，但 JSON 結構描述定義中不得包含 PHI。API 會將 JSON 結構描述編譯成文法，這些文法與訊息內容分開快取，且這些快取的結構描述不會獲得與提示和回應相同的 PHI 保護。請勿在結構描述屬性名稱、enum 值、const 值或 pattern 正規表示式中包含 PHI。PHI 應僅出現在訊息內容（提示和回應）中，在那裡它受到 HIPAA 保護措施的保護。
如需所有功能的 ZDR 和 HIPAA 資格資訊，請參閱 API 與資料保留。
相容於：
output_config.format）和嚴格工具使用（strict: true）不相容於：
output_config.format 的同時啟用引用，會回傳 400 錯誤。讓 Claude 在回答有關所提供文件的問題時引用其來源。
透過文法限制取樣，在 Claude 的工具輸入上強制執行 JSON Schema 合規性。
將 Claude 連接到外部工具和 API。了解工具在何處執行以及代理式迴圈如何運作。
了解 Anthropic 針對模型和功能的定價結構。
| Supported models |
|
|---|---|
| Supported platforms |
Was this page helpful?