批次處理是一種高效處理大量請求的強大方法。批次處理不是逐一處理請求並立即回應,而是允許您將多個請求一起提交進行非同步處理。這種模式在以下情況特別有用:
Message Batches API 是我們對此模式的首個實作。
This feature is not covered by Zero Data Retention (ZDR) arrangements. Data is retained according to the feature's standard retention policy.
Message Batches API 是一種強大且具成本效益的方式,可非同步處理大量 Messages 請求。這種方法非常適合不需要即時回應的任務,大多數批次在不到 1 小時內完成處理,同時降低 50% 的成本並提高吞吐量。
除了本指南外,您還可以直接探索 API 參考文件。
當您向 Message Batches API 發送請求時:
Was this page helpful?
這對於不需要即時結果的批量操作特別有用,例如:
所有活躍模型都支援 Message Batches API。
任何您可以向 Messages API 發出的請求都可以包含在批次中。這包括:
由於批次中的每個請求都是獨立處理的,您可以在單一批次中混合不同類型的請求。
由於批次處理可能需要超過 5 分鐘,請考慮在處理具有共享上下文的批次時,使用提示快取的 1 小時快取持續時間以獲得更好的快取命中率。
Batches API 提供顯著的成本節省。所有使用量按標準 API 價格的 50% 收費。
| Model | Batch input | Batch output |
|---|---|---|
| Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.1 | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 3.7 (deprecated) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 (deprecated) | $7.50 / MTok | $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Message Batch 由一個建立 Message 的請求列表組成。單個請求的結構包含:
custom_idparams 物件您可以將此列表傳入 requests 參數來建立批次:
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hi again, friend"}
]
}
}
]
}'在此範例中,兩個獨立的請求被批次在一起進行非同步處理。每個請求都有一個唯一的 custom_id,並包含您在 Messages API 呼叫中使用的標準參數。
使用 Messages API 測試您的批次請求
每個訊息請求的 params 物件驗證是非同步執行的,驗證錯誤會在整個批次處理結束時返回。您可以先使用 Messages API 驗證您的請求格式,以確保您正確建構了輸入。
當批次首次建立時,回應的處理狀態將為 in_progress。
{
"id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
"type": "message_batch",
"processing_status": "in_progress",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": null,
"results_url": null
}Message Batch 的 processing_status 欄位表示批次所處的處理階段。它從 in_progress 開始,然後在批次中所有請求處理完成且結果準備就緒後更新為 ended。您可以透過造訪控制台或使用擷取端點來監控批次的狀態。
要輪詢 Message Batch,您需要其 id,該 ID 在建立批次時的回應中提供,或透過列出批次取得。您可以實作一個輪詢迴圈,定期檢查批次狀態直到處理結束:
import anthropic
import time
client = anthropic.Anthropic()
message_batch = None
while True:
message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
if message_batch.processing_status == "ended":
break
print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
time.sleep(60)
print(message_batch)您可以使用列表端點列出工作區中的所有 Message Batches。API 支援分頁,會根據需要自動擷取額外的頁面:
import anthropic
client = anthropic.Anthropic()
# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)批次處理結束後,批次中的每個 Messages 請求都會有一個結果。有 4 種結果類型:
| 結果類型 | 描述 |
|---|---|
succeeded | 請求成功。包含訊息結果。 |
errored | 請求遇到錯誤且未建立訊息。可能的錯誤包括無效請求和內部伺服器錯誤。這些請求不會向您收費。 |
canceled | 使用者在此請求發送到模型之前取消了批次。這些請求不會向您收費。 |
expired | 批次在此請求發送到模型之前達到了 24 小時的過期時間。這些請求不會向您收費。 |
您可以透過批次的 request_counts 查看結果概覽,其中顯示有多少請求達到了這四種狀態中的每一種。
批次的結果可在 Message Batch 的 results_url 屬性中下載,如果組織權限允許,也可在控制台中查看。由於結果可能非常大,建議串流傳輸結果而不是一次全部下載。
#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
| grep -o '"results_url":[[:space:]]*"[^"]*"' \
| cut -d'"' -f4 \
| while read -r url; do
curl -s "$url" \
--header "anthropic-version: 2023-06-01" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
| sed 's/}{/}\n{/g' \
| while IFS= read -r line
do
result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
case "$result_type" in
"succeeded")
echo "Success! $custom_id"
;;
"errored")
if [ "$error_type" = "invalid_request" ]; then
# Request body must be fixed before re-sending request
echo "Validation error: $custom_id"
else
# Request can be retried directly
echo "Server error: $custom_id"
fi
;;
"expired")
echo "Expired: $line"
;;
esac
done
done
結果將以 .jsonl 格式呈現,其中每一行都是一個有效的 JSON 物件,代表 Message Batch 中單個請求的結果。對於每個串流傳輸的結果,您可以根據其 custom_id 和結果類型執行不同的操作。以下是一組範例結果:
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-6","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}如果您的結果包含錯誤,其 result.error 將設定為我們的標準錯誤格式。
批次結果可能與輸入順序不符
批次結果可以以任何順序返回,可能與建立批次時的請求順序不符。在上面的範例中,第二個批次請求的結果在第一個之前返回。為了正確地將結果與其對應的請求配對,請始終使用 custom_id 欄位。
您可以使用取消端點取消正在處理中的 Message Batch。取消後,批次的 processing_status 會立即變為 canceling。您可以使用上述相同的輪詢技術等待取消完成。已取消的批次最終狀態為 ended,可能包含在取消前已處理的請求的部分結果。
import anthropic
client = anthropic.Anthropic()
message_batch = client.messages.batches.cancel(
MESSAGE_BATCH_ID,
)
print(message_batch)回應將顯示批次處於 canceling 狀態:
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message_batch",
"processing_status": "canceling",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
"results_url": null
}Message Batches API 支援提示快取,讓您可以潛在地降低批次請求的成本和處理時間。提示快取和 Message Batches 的價格折扣可以疊加,當兩個功能同時使用時可以提供更大的成本節省。然而,由於批次請求是非同步且並行處理的,快取命中是以盡力而為的方式提供的。使用者通常會體驗到 30% 到 98% 的快取命中率,具體取決於其流量模式。
為了最大化批次請求中快取命中的可能性:
cache_control 區塊在批次中實作提示快取的範例:
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Write a summary of Pride and Prejudice."}
]
}
}
]
}'在此範例中,批次中的兩個請求都包含相同的系統訊息和標記了 cache_control 的《傲慢與偏見》全文,以增加快取命中的可能性。
為了充分利用 Batches API:
custom_id 值來輕鬆將結果與請求配對,因為順序不保證。如果遇到意外行為:
request_too_large 錯誤。custom_id。created_at(非處理 ended_at)時間起不超過 29 天。如果超過 29 天,結果將不再可查看。請注意,批次中一個請求的失敗不會影響其他請求的處理。
工作區隔離:批次在其建立的工作區內是隔離的。只有與該工作區關聯的 API 金鑰,或有權限在主控台中查看工作區批次的使用者才能存取。
結果可用性:批次結果在批次建立後 29 天內可用,提供充足的時間進行檢索和處理。