Was this page helpful?
批次處理是一種高效處理大量請求的強大方法。與逐一處理請求並立即回應不同,批次處理允許您將多個請求一起提交以進行非同步處理。此模式在以下情況特別有用:
Message Batches API 是 Anthropic 對此模式的首個實作。
This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.
Message Batches API 是一種強大且具成本效益的方式,可非同步處理大量 Messages 請求。此方法非常適合不需要立即回應的任務,大多數批次在不到 1 小時內完成,同時可降低 50% 的成本並提高吞吐量。
除了本指南外,您還可以直接探索 API 參考。
當您向 Message Batches API 發送請求時:
這對於不需要立即結果的批量操作特別有用,例如:
所有現行模型均支援 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 |
Message Batch 由建立 Message 的請求清單組成。個別請求的結構包含:
custom_idparams 物件您可以透過將此清單傳入 requests 參數來建立批次:
在此範例中,兩個獨立的請求被批次在一起進行非同步處理。每個請求都有唯一的 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 在建立批次時的回應中提供,或透過列出批次取得。您可以實作一個輪詢迴圈,定期檢查批次狀態,直到處理結束:
您可以使用列表端點列出工作區中的所有 Message Batch。API 支援分頁,根據需要自動擷取額外頁面:
批次處理結束後,批次中的每個 Messages 請求都將有一個結果。共有 4 種結果類型:
| 結果類型 | 描述 |
|---|---|
succeeded | 請求成功。包含訊息結果。 |
errored | 請求遇到錯誤,訊息未建立。可能的錯誤包括無效請求和內部伺服器錯誤。這些請求不會向您收費。 |
canceled | 使用者在此請求發送到模型之前取消了批次。這些請求不會向您收費。 |
expired | 批次在此請求發送到模型之前達到 24 小時到期時間。這些請求不會向您收費。 |
您將在批次的 request_counts 中看到結果概覽,其中顯示有多少請求達到這四種狀態中的每一種。
批次的結果可在 Message Batch 的 results_url 屬性下載,如果組織權限允許,也可在主控台中下載。由於結果可能非常大,建議串流結果而不是一次性下載所有內容。
結果將採用 .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,可能包含取消前已處理的請求的部分結果。
回應將顯示批次處於 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 區塊在批次中實作提示快取的範例:
在此範例中,批次中的兩個請求都包含相同的系統訊息以及標有 cache_control 的《傲慢與偏見》全文,以提高快取命中的可能性。
為了充分利用 Batches API:
custom_id 值,以便輕鬆將結果與請求匹配,因為順序不保證。如果遇到意外行為:
request_too_large 錯誤。custom_id。created_at(而非處理 ended_at)時間起不超過 29 天。如果超過 29 天,結果將不再可查看。請注意,批次中一個請求的失敗不會影響其他請求的處理。
工作區隔離:批次在其建立的工作區內隔離。它們只能由與該工作區關聯的 API 金鑰存取,或由在 Console 中具有查看工作區批次權限的使用者存取。
結果可用性:批次結果在批次建立後 29 天內可用,提供充足的時間進行擷取和處理。
批次處理在批次建立後最多儲存請求和回應資料 29 天。您可以在處理完成後隨時使用 DELETE /v1/messages/batches/{batch_id} 端點刪除訊息批次。非同步處理需要在伺服器端儲存輸入和輸出,直到批次完成並擷取結果。
有關所有功能的 ZDR 資格,請參閱 API 和資料保留。
| $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 |
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"}
]
}
}
]
}'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)import anthropic
client = anthropic.Anthropic()
# 根據需要自動擷取更多頁面。
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)#!/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
import anthropic
client = anthropic.Anthropic()
message_batch = client.messages.batches.cancel(
MESSAGE_BATCH_ID,
)
print(message_batch)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."}
]
}
}
]
}'