結構化輸出
從代理工作流程中取得經過驗證的 JSON 結果
「Structured outputs」(結構化輸出)會限制 Claude 的回應遵循特定的結構描述,確保輸出有效且可解析,以供下游處理使用。結構化輸出提供兩項互補的功能:
- JSON 輸出(
output_config.format):以特定 JSON 格式取得 Claude 的回應,例如從圖片或文字中擷取資料、產生結構化報告,或格式化 API 回應。本頁介紹 JSON 輸出。 - 嚴格工具使用(
strict: true):保證對工具名稱和輸入進行結構描述驗證。請參閱嚴格工具使用。
您可以單獨使用這些功能,也可以在同一個請求中一起使用。
為什麼要使用結構化輸出
若不使用結構化輸出,Claude 可能會產生格式錯誤的 JSON 回應或無效的工具輸入,進而導致您的應用程式發生錯誤。即使經過仔細的提示設計,您仍可能遇到:
- 因無效的 JSON 語法而產生的解析錯誤
- 缺少必要欄位
- 資料型別不一致
- 違反結構描述,需要錯誤處理與重試
結構化輸出透過「constrained decoding」(受限解碼)保證回應符合結構描述:
- 永遠有效: 不再出現 JSON 解析錯誤
- 型別安全: 保證欄位型別與必要欄位
- 可靠: 不需因違反結構描述而重試
運作方式
定義您的結構描述
以 JSON 結構描述或您所用語言中的型別來描述您想要的結構。結構描述遵循 JSON Schema,但有一些限制。
在 output_config.format 中傳送
請求會在
output_config.format中攜帶結構描述,並設定type: "json_schema"。SDK 輔助工具會為您進行此設定。讀取回應
Claude 會在回應的文字內容區塊中傳回符合您結構描述的有效 JSON。SDK 輔助工具會將其解析為您的型別。
使用方式
from pydantic import BaseModel
class ContactInfo(BaseModel):
name: str
email: str
plan_interest: str
demo_requested: bool
client = Anthropic()
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": (
"Extract the key information from this email: "
"John Smith (john@example.com) is interested in our Enterprise plan "
"and wants to schedule a demo for next Tuesday at 2pm."
),
}
],
output_format=ContactInfo,
)
print(response.parsed_output)將 Pydantic 模型作為 output_format 傳遞給建議使用的方法 client.messages.parse()。SDK 會轉換該模型的結構描述,將其作為 output_config.format 傳送,驗證回應,並在 parsed_output 中傳回解析後的模型。
上述範例的輸出為:
name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True如果您知道欄位的鍵,請使用巢狀 Pydantic 模型,而非 dict。SDK 會將 dict 欄位作為 properties 為空的物件傳送,因此 Claude 只能為其傳回 {}。如果您事先不知道有哪些鍵,請參閱具有任意鍵的物件。
SDK 轉換的運作方式
大多數 SDK 輔助工具會轉換使用了不支援功能的結構描述。轉換步驟如下:
- 移除不支援的限制條件(例如
minimum、maximum、minLength、maxLength) - 更新描述,將每個不支援的限制條件新增至欄位的描述中(例如
{minimum: 100}) - 新增
additionalProperties: false至所有物件 - 篩選字串格式,僅保留支援的清單
- 驗證回應,若輔助工具會驗證回應,則依據您原始的結構描述及其所有限制條件進行驗證
Claude 收到的是簡化後的結構描述,但會驗證回應的輔助工具仍會在您的程式碼中強制執行每一項限制條件。
範例: 具有 minimum: 100 的欄位在傳送的結構描述中會變成一般整數,而 SDK 會將 {minimum: 100} 新增至該欄位的描述中。會驗證回應的輔助工具仍會依據 minimum: 100 檢查回應。
使用原始 JSON 結構描述
若要使用來自檔案、OpenAPI 規格,或在執行階段建立的 JSON 結構描述,請將其傳遞至 output_config.format。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": (
"Extract the key information from this email: "
"John Smith (john@example.com) 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,
},
}
},
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)上述範例的輸出為:
{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}若要將API 不支援的限制條件移至欄位描述中,請在傳送之前將結構描述傳入 anthropic 套件中的 transform_schema(),並視需要編輯結果。transform_schema() 也接受 Pydantic 模型。與 client.messages.parse() 不同,它會傳回轉換後的結構描述,而不是將其傳送出去。
常見使用情境
從非結構化文字中擷取結構化資料:
from pydantic import BaseModel
class LineItem(BaseModel):
description: str
quantity: float
unit_price: float
class Invoice(BaseModel):
invoice_number: str
date: str
total_amount: float
line_items: list[LineItem]
customer_name: str
client = anthropic.Anthropic()
invoice_text = """
Invoice #12345
Date: 2024-01-15
Customer: Acme Corp
2 widgets at $150.00 each
1 setup fee at $200.00
Total: $500.00
"""
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=4096,
output_format=Invoice,
messages=[
{"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
],
)
print(response.parsed_output)以結構化類別對內容進行分類:
from pydantic import BaseModel
client = Anthropic()
class Classification(BaseModel):
category: str
confidence: float
tags: list[str]
sentiment: str
feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
output_format=Classification,
messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)
print(response.parsed_output)產生可直接用於 API 的回應:
from pydantic import BaseModel
client = Anthropic()
class Payload(BaseModel):
message: str
class APIError(BaseModel):
code: str
detail: str
class Metadata(BaseModel):
request_id: str
class APIResponse(BaseModel):
status: str
data: Payload
errors: list[APIError] | None = None
metadata: Metadata
response = client.messages.parse(
model="claude-opus-5-5",
max_tokens=1024,
output_format=APIResponse,
messages=[
{
"role": "user",
"content": "Write an API response: request req_2abc3def has an invalid email.",
}
],
)
print(response.parsed_output)嚴格工具使用
若要透過語法受限取樣對工具輸入強制執行 JSON Schema 合規性,請參閱嚴格工具使用。
同時使用兩項功能
JSON 輸出與嚴格工具使用解決不同的問題,並且可以搭配使用:
- JSON 輸出控制 Claude 的回應格式(Claude 說了什麼)。
- 嚴格工具使用驗證工具參數(Claude 如何呼叫您的函式)。
結合使用時,Claude 可以使用保證有效的參數呼叫工具,並且傳回結構化的 JSON 回應。這對於同時需要可靠工具呼叫與結構化最終輸出的代理工作流程非常有用。
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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)重要注意事項
語法編譯與快取
結構化輸出使用搭配已編譯語法產物的受限取樣。這會帶來一些需要留意的效能特性:
- 首次請求延遲: 第一次使用特定結構描述時,會因語法編譯而產生額外的「latency」(延遲)。
- 自動快取: 已編譯的語法會自最後一次使用起快取 24 小時,使後續請求快上許多。
- 快取失效: 如果您變更 JSON 結構描述的結構,或在同時使用結構化輸出與工具使用時變更請求中的工具組合,快取就會失效。僅變更
name或description欄位不會使快取失效。
提示修改與 token 成本
使用結構化輸出時,Claude 會自動收到一段額外的系統提示,說明預期的輸出格式。這表示:
- 您的輸入 token 數會略為增加。
- 注入的提示與其他系統提示一樣會消耗您的 token。
- 變更
output_config.format參數會使該對話串的任何提示快取失效。
JSON Schema 限制
結構化輸出支援標準 JSON Schema,但有一些限制。JSON 輸出與嚴格工具使用都適用這些限制。
- 所有基本型別:object、array、string、integer、number、boolean、null
enum和const(僅限字串、數字、布林值或 null),並有一項大小寫注意事項anyOf和allOf,但「不支援」中列出的用法除外$ref、$defs和definitions- 所有支援型別的
default屬性 required和additionalProperties(物件必須設定為false)- 字串格式:
date-time、time、date、duration、email、hostname、uri、ipv4、ipv6、uuid - 陣列
minItems(僅支援 0 和 1)
- 遞迴結構描述
oneOf(請改用anyOf)not- 在同一個結構描述物件中,將
anyOf與type或properties等關鍵字並用(title和description等註解則沒有問題) - 搭配相互衝突之結構描述的
allOf(例如,type值不同) - 搭配兩個以上結構描述,且其中一個直接包含
$ref、anyOf或allOf的allOf - 列舉中的複雜型別
- 外部
$ref(例如'$ref': 'http://...') - 數值限制條件(例如
minimum、maximum、multipleOf) - 字串限制條件(
minLength、maxLength) - 除了 0 或 1 的
minItems之外的陣列限制條件 - 設定為
false以外任何值的additionalProperties(請參閱具有任意鍵的物件)
如果您使用了不支援的功能,將收到附有詳細資訊的 400 錯誤。
支援的 regex 功能:
- 完整比對(
^...$)與部分比對 - 量詞:
*、+、?、簡單的{n,m}情況 - 字元類別:
[]、.、\d、\w、\s - 群組:
(...)
不支援:
- 群組的反向參照(例如
\1、\2) - 前瞻/後顧斷言(例如
(?=...)、(?!...)) - 字詞邊界:
\b、\B - 範圍很大的複雜
{n,m}量詞
簡單的 regex 模式運作良好。複雜的模式可能會導致 400 錯誤。
具有任意鍵的物件
請列出物件的每個鍵,可以列在 properties 中,或作為您傳遞給 SDK 的類別或結構描述的欄位。由於 additionalProperties 必須為 false,Claude 只能傳回您列出的鍵。
API 會接受 properties 為空或缺少 properties 的物件,但 Claude 只能為其傳回 {}。map、dictionary 或 record 型別不會列出任何鍵,因此 Python 和 TypeScript SDK 會將其作為 properties 為空的物件傳送。Java 和 Ruby SDK 則會引發錯誤。
如果您事先不知道有哪些鍵,請改用陣列。為每個項目提供 key 和 value,如以下結構描述所示:
{
"type": "array",
"items": {
"type": "object",
"properties": {
"key": { "type": "string" },
"value": { "type": "string" }
},
"required": ["key", "value"],
"additionalProperties": false
}
}屬性順序
使用結構化輸出時,物件中的屬性會維持您在結構描述中定義的順序,但有一個重要的例外:必要屬性會先出現,接著才是選用屬性。
例如,給定以下結構描述:
{
"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": "john@example.com",
"notes": "Interested in enterprise plan",
"age": 35
}如果輸出中的屬性順序對您的應用程式很重要,請將所有屬性標記為必要,或在您的解析邏輯中考量此重新排序。
無效輸出
雖然結構化輸出在大多數情況下都能保證符合結構描述,但仍有一些情況下輸出可能不符合您的結構描述:
拒絕(stop_reason: "refusal")
即使使用結構化輸出,Claude 仍會維持其安全性與有用性。如果 Claude 基於安全理由拒絕請求:
- 回應會包含
stop_reason: "refusal"。 - 您會收到 200 狀態碼。
- 您將為所產生的 token 付費。
- 輸出可能不符合您的結構描述,因為拒絕訊息的優先順序高於結構描述限制條件。
要求提供模型思考過程或逐步推理的屬性,可能會導致 reasoning_extraction 拒絕。請改為要求簡短的說明。請參閱將推理保留在思考區塊中。
達到 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"])的參數總數。這些參數的成本特別高,因為它們會造成指數級的編譯成本。 |
其他內部限制
除了上表中的明確限制外,已編譯語法的大小還有其他內部限制。這些限制之所以存在,是因為結構描述的複雜度無法簡化為單一維度:選用參數、聯集型別、巢狀物件和工具數量等功能會以各種方式相互作用,可能使已編譯的語法變得不成比例地龐大。
超過這些限制時,您會收到附有訊息「Schema is too complex for compilation.」的 400 錯誤。這些錯誤表示您的結構描述的綜合複雜度超出了能有效編譯的範圍,即使上表中的每項個別限制都已滿足。作為最後的防線,API 也強制執行 180 秒的編譯逾時。通過所有明確檢查但產生非常龐大的已編譯語法的結構描述,可能會觸及此逾時。
降低結構描述複雜度的秘訣
如果您遇到複雜度限制,請依序嘗試以下策略:
-
僅將關鍵工具標記為嚴格。 如果您有許多工具,請將嚴格工具使用保留給違反結構描述會造成實際問題的工具,而對於較簡單的工具則依賴 Claude 本身的遵循能力。
-
減少選用參數。 盡可能將參數設為
required。每個選用參數大約會使語法狀態空間的一部分加倍。如果某個參數總是有合理的預設值,請考慮將其設為必要,並讓 Claude 明確提供該預設值。 -
簡化巢狀結構。 具有選用欄位的深層巢狀物件會使複雜度加劇。請盡可能將結構扁平化。
-
拆分為多個請求。 如果您有許多嚴格工具,請考慮將它們拆分到不同的請求或子代理中。
若有效的結構描述持續發生問題,請附上您的結構描述定義並聯絡支援團隊。
從 beta 版遷移
output_format 參數已移至 output_config.format,且不再需要 beta 標頭。output_format 參數已被棄用。若仍要使用,請新增 structured-outputs-2025-11-13 beta 標頭。若未新增,API 會傳回 400 錯誤。
在 Python SDK(v1.0 及更新版本)中,以 output_format={...} 傳遞的結構描述字典會引發 TypeError。請改用 output_config。以 output_format=Model 傳遞給 parse() 或 stream() 的 Pydantic 模型無需任何變更,也不需要 beta 標頭即可運作,因為 SDK 會將其作為 output_config 傳送。如需更新後的 API 形式,請參閱使用原始 JSON 結構描述。
功能相容性
可搭配使用:
- 批次處理: 以 50% 的折扣大規模處理結構化輸出
- Token 計數: 無需編譯即可計算 token
- 串流: 像一般回應一樣串流結構化輸出
- 合併使用: 在同一個請求中同時使用 JSON 輸出(
output_config.format)與嚴格工具使用(strict: true)
不相容:
- 引用: 引用需要將引用區塊與文字交錯排列,這與嚴格的 JSON 結構描述限制條件相衝突。如果在使用
output_config.format時啟用引用,API 會傳回 400 錯誤。若要擷取結構化資料並為每個值附上引用,請參閱取得附帶引用的結構化資料。 - 訊息預填: 預填與 JSON 輸出不相容。
可用性
Claude API
- API
- Messages API
- Managed Agents 不支援
- 模型
- 所有模型
Amazon Bedrock
- API
- Messages API
- 模型
- 所有模型
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- 模型
- 所有模型
Claude Platform on AWS
- API
- Messages API
- Managed Agents 不支援
- 模型
- 所有模型
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents 不支援
- 模型
- 所有模型
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- 模型
- 所有模型
Microsoft Foundry
- API
- Messages API
- 模型
- 所有模型
資料處理
資料處理概覽使用結構化輸出時,提示與回應會以 ZDR 方式處理。不過,JSON 結構描述本身會基於最佳化目的,自最後一次使用起暫時快取最多 24 小時。API 回應傳回後,不會保留任何提示或回應資料。
結構化輸出符合 HIPAA 資格,但JSON 結構描述定義中不得包含 PHI。API 會將 JSON 結構描述編譯為與訊息內容分開快取的語法,而這些快取的結構描述並不享有與提示和回應相同的 PHI 保護。請勿在結構描述屬性名稱、enum 值、const 值或 pattern 規則運算式中包含 PHI。PHI 應僅出現在訊息內容(提示與回應)中,在那裡它會受到 HIPAA 保護措施的保障。
後續步驟
讓 Claude 在回答關於所提供文件的問題時引用其來源。
透過語法受限取樣,對 Claude 的工具輸入強制執行 JSON Schema 合規性。
將 Claude 連接到外部工具和 API。了解工具在何處執行,以及代理迴圈如何運作。
了解 Anthropic 針對模型與功能的定價結構。
這個頁面有幫助嗎?