Claude Platform Docs
  • Messages
  • Managed Agents
  • 管理

Search...
⌘K
第一步
Claude 簡介快速入門
使用 Claude 進行建構
功能概覽使用 Messages API停止原因與備援拒絕與備援備援額度
模型能力
擴展思考自適應思考Effort任務預算(測試版)快速模式(研究預覽)結構化輸出引用串流 Messages批次處理搜尋結果串流拒絕多語言支援嵌入
工具
概覽工具使用的運作方式教學:建構使用工具的代理定義工具處理工具呼叫平行工具使用Tool Runner (SDK)嚴格工具使用工具使用與提示快取伺服器工具疑難排解網頁搜尋工具網頁擷取工具程式碼執行工具顧問工具記憶工具Bash 工具電腦使用工具文字編輯器工具
工具基礎架構
工具參考管理工具上下文工具組合工具搜尋程式化工具呼叫細粒度工具串流
上下文管理
上下文視窗壓縮上下文編輯提示快取對話中系統訊息建構協調模式快取診斷(測試版)Token 計數
處理檔案
Files APIPDF 支援圖片與視覺
技能
概覽快速入門最佳實務企業技能API 中的技能
MCP
遠端 MCP 伺服器MCP 連接器
雲端平台上的 Claude
Amazon BedrockAmazon Bedrock(舊版)AWS 上的 Claude PlatformMicrosoft FoundryVertex AI

Log in
批次處理
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Claude Platform Docs

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Claude on AWS
  • Claude on Google Cloud

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
Messages/模型能力

批次處理

Was this page helpful?

  • Message Batches API 的運作方式
  • 批次限制
  • 支援的模型
  • 可批次處理的內容
  • 定價
  • 如何使用 Message Batches API
  • 準備並建立您的批次
  • 追蹤您的批次
  • 列出所有 Message Batches
  • 擷取批次結果
  • 取消 Message Batch
  • 在 Message Batches 中使用提示快取
  • 伺服器工具與代理迴圈
  • 擴展輸出(測試版)
  • 有效批次處理的最佳實務
  • 常見問題疑難排解
  • 批次儲存與隱私
  • 資料保留
  • 常見問題
  • 後續步驟

批次處理是一種高效處理大量請求的強大方法。批次處理不是一次處理一個請求並立即回應,而是允許您將多個請求一起提交以進行非同步處理。這種模式在以下情況特別有用:

  • 您需要處理大量資料
  • 不需要立即回應
  • 您希望優化成本效益
  • 您正在執行大規模評估或分析

Message Batches API 是 Anthropic 對此模式的首次實作。



此功能不符合零資料保留(Zero Data Retention,ZDR)的資格。資料將依據該功能的標準保留政策進行保留。

Message Batches API

Message Batches API 是一種強大且具成本效益的方式,可非同步處理大量 Messages 請求。這種方法非常適合不需要立即回應的任務,大多數批次在 1 小時內完成,同時降低 50% 的成本並提高吞吐量。

除了本指南外,您還可以直接探索 API 參考文件。

Message Batches API 的運作方式

當您向 Message Batches API 發送請求時:

  1. 系統會使用提供的 Messages 請求建立一個新的 Message Batch。
  2. 然後批次會進行非同步處理,每個請求都會獨立處理。
  3. 您可以輪詢批次的狀態,並在所有請求處理結束後擷取結果。

這對於不需要立即結果的大量操作特別有用,例如:

  • 大規模評估:高效處理數千個測試案例。
  • 內容審核:非同步分析大量使用者生成的內容。
  • 資料分析:為大型資料集生成洞察或摘要。
  • 大量內容生成:為各種用途建立大量文字(例如產品描述、文章摘要)。

批次限制

  • 一個 Message Batch 限制為 100,000 個 Message 請求或 256 MB 大小,以先達到者為準。
  • 系統會盡快處理每個批次,大多數批次在 1 小時內完成。當所有訊息完成或 24 小時後(以先到者為準),您可以存取批次結果。如果處理未在 24 小時內完成,批次將過期。
  • 批次結果在建立後 29 天內可供下載。之後,您仍可檢視批次,但其結果將不再可供下載。
  • 批次的範圍限定於 Workspace。您可以檢視在您的 API 金鑰所屬 Workspace 中建立的所有批次(及其結果)。
  • 速率限制適用於 Batches API 的 HTTP 請求以及批次中等待處理的請求數量。請參閱 Message Batches API 速率限制。此外,處理速度可能會根據當前需求和您的請求量而減慢。在這種情況下,您可能會看到更多請求在 24 小時後過期。
  • 由於高吞吐量和並行處理,批次可能會略微超過您 Workspace 設定的支出限制。
  • 每個批次請求的 max_tokens 必須至少為 1。批次內不支援 max_tokens: 0(快取預熱),因為在批次處理期間寫入的臨時快取項目可能會在後續請求執行之前過期。

支援的模型

所有現行模型都支援 Message Batches API。

可批次處理的內容

幾乎任何您可以向 Messages API 發出的請求都可以包含在批次中。這包括:

  • 視覺
  • 工具使用,包括所有伺服器工具(網頁搜尋、網頁擷取、程式碼執行、MCP 連接器、advisor 和工具搜尋)
  • 系統訊息
  • 多輪對話
  • 擴展思考
  • 大多數測試版功能

由於批次中的每個請求都是獨立處理的,您可以在單一批次中混合不同類型的請求。

少數 Messages API 參數在批次請求中不受支援。包含以下任何參數都會傳回驗證錯誤:

參數原因
stream: true批次結果以單一檔案形式傳回,而非串流。
speed(快速模式)快速模式調整同步延遲,這不適用於非同步批次處理。
store / previous_thread_event_id(Threads)Threads 是有狀態的;批次請求則不是。
cache_hint / context_hint這些路由提示僅適用於同步請求排程。
max_tokens: 0請參閱批次限制。
research_preview_2026_02: "active"研究預覽模式在批次路徑上不可用。


由於批次處理可能需要超過 5 分鐘,在處理具有共享上下文的批次時,請考慮搭配提示快取使用 1 小時快取持續時間,以獲得更好的快取命中率。

定價

Batches API 提供顯著的成本節省。所有使用量均按標準 API 價格的 50% 收費。

模型批次輸入批次輸出
Claude Fable 5$5 / MTok$25 / MTok
Claude Mythos 5(限量供應)$5 / MTok$25 / MTok
Claude Opus 4.8$2.50 / MTok$12.50 / MTok
Claude Opus 4.7$2.50 / MTok$12.50 / MTok
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(已停用,Vertex AI 除外)$7.50 / MTok$37.50 / MTok

如何使用 Message Batches API

準備並建立您的批次

Message Batch 由建立 Message 的請求清單組成。單一請求的結構包含:

  • 用於識別 Messages 請求的唯一 custom_id。必須為 1 到 64 個字元,且只能包含英數字元、連字號和底線(符合 ^[a-zA-Z0-9_-]{1,64}$)。
  • 包含標準 Messages API 參數的 params 物件

您可以透過將此清單傳入 requests 參數來建立批次:

在此範例中,兩個獨立的請求被批次處理在一起以進行非同步處理。每個請求都有唯一的 custom_id,並包含您用於 Messages API 呼叫的標準參數。



使用 Messages API 測試您的批次請求

每個訊息請求的 params 物件驗證是非同步執行的,驗證錯誤會在整個批次處理結束時傳回。您可以先使用 Messages API 驗證您的請求結構,以確保您正確建構輸入。

首次建立批次時,回應的處理狀態將為 in_progress。

Output
{
  "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。您可以透過造訪 Console 或使用擷取端點來監控批次的狀態。

輪詢 Message Batch 完成狀態

要輪詢 Message Batch,您需要其 id,該 ID 在建立批次時的回應中提供,或透過列出批次取得。您可以實作一個輪詢迴圈,定期檢查批次狀態,直到處理結束:

列出所有 Message Batches

您可以使用列表端點列出您 Workspace 中的所有 Message Batches。API 支援分頁,會根據需要自動擷取額外頁面:

擷取批次結果

批次處理結束後,批次中的每個 Messages 請求都會有一個結果。共有 4 種結果類型:

結果類型描述
succeeded請求成功。包含訊息結果。
errored請求遇到錯誤,未建立訊息。可能的錯誤包括無效請求和內部伺服器錯誤。您不會為這些請求付費。
canceled使用者在此請求發送到模型之前取消了批次。您不會為這些請求付費。
expired批次在此請求發送到模型之前達到 24 小時過期時間。您不會為這些請求付費。

您將透過批次的 request_counts 看到結果概覽,其中顯示達到這四種狀態的請求數量。

批次結果可在 Message Batch 的 results_url 屬性下載,如果組織權限允許,也可在 Console 中下載。由於結果可能很大,建議串流結果而不是一次下載全部。

結果為 .jsonl 格式,其中每一行都是一個有效的 JSON 物件,代表 Message Batch 中單一請求的結果。對於每個串流結果,您可以根據其 custom_id 和結果類型執行不同的操作。以下是一組結果範例:

.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-8","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-8","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

您可以使用取消端點取消目前正在處理的 Message Batch。取消後,批次的 processing_status 將立即變為 canceling。您可以使用上述相同的輪詢技術等待取消完成。已取消的批次最終狀態為 ended,可能包含在取消前已處理的請求的部分結果。

回應將顯示批次處於 canceling 狀態:

Output
{
  "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 中使用提示快取

Message Batches API 支援提示快取,可讓您潛在地降低批次請求的成本和處理時間。提示快取和 Message Batches 的定價折扣可以疊加,當兩個功能一起使用時可提供更大的成本節省。然而,由於批次請求是非同步且並行處理的,快取命中是以盡力而為的方式提供。使用者通常會體驗到 30% 到 98% 的快取命中率,具體取決於其流量模式。

要最大化批次請求中快取命中的可能性:

  1. 在批次中的每個 Message 請求中包含相同的 cache_control 區塊
  2. 維持穩定的請求流,以防止快取項目在其 5 分鐘生命週期後過期
  3. 建構您的請求以盡可能共享快取內容

在批次中實作提示快取的範例:

在此範例中,批次中的兩個請求都包含相同的系統訊息和標記為 cache_control 的《傲慢與偏見》全文,以增加快取命中的可能性。

伺服器工具與代理迴圈

所有伺服器工具(網頁搜尋、網頁擷取、程式碼執行、MCP 連接器、advisor 和工具搜尋)都可在批次請求中使用。批次工作程序執行與同步 Messages API 相同的伺服器端代理迴圈。

由於沒有需要維持的開放連線,批次迴圈在傳回 stop_reason: "pause_turn" 之前,每輪執行的迭代次數比同步請求更多。如果批次結果傳回 pause_turn,表示該輪尚未完成;您可以透過在後續請求(批次或同步)中提交暫停的助手內容來繼續,完全按照 pause_turn 接續模式中所示的方式進行。

批次工作程序還會針對每個組織限制 web_search 的速率,以確保高度並行的批次處理不會耗盡您組織的網頁搜尋速率限制。批次會自動重試受限制的請求;您不需要自行處理此問題,但非常大的網頁搜尋批次可能需要更長時間才能完成。

擴展輸出(測試版)

output-300k-2026-03-24 測試版標頭可將使用 Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 或 Claude Sonnet 4.6 的批次請求的 max_tokens 上限提高到 300,000。包含此標頭可在單一輪次中生成遠超過標準限制(根據模型不同為 64k 到 128k)的輸出。



擴展輸出僅在 Message Batches API 上可用,不適用於同步 Messages API。它在 Claude API 和 AWS 上的 Claude Platform 上受支援,目前在 Amazon Bedrock、Vertex AI 或 Microsoft Foundry 上不可用。

擴展輸出適用於長篇生成,例如書籍長度的草稿和技術文件、詳盡的結構化資料擷取、大型程式碼生成框架以及長推理鏈。

單次 300k token 的生成可能需要超過一小時才能完成,因此請在規劃批次提交時考慮 24 小時的處理時間窗口。適用標準批次定價(標準 API 價格的 50%)。

有效批次處理的最佳實務

要充分利用 Batches API:

  • 定期監控批次處理狀態,並為失敗的請求實作適當的重試邏輯。
  • 使用有意義的 custom_id 值,以便輕鬆將結果與請求配對,因為順序無法保證。
  • 考慮將非常大的資料集分成多個批次,以便更好地管理。
  • 使用 Messages API 試執行單一請求結構,以避免驗證錯誤。

常見問題疑難排解

如果遇到非預期的行為:

  • 確認批次請求總大小不超過 256 MB。如果請求大小過大,您可能會收到 413 request_too_large 錯誤。
  • 檢查批次中的所有請求是否使用支援的模型。
  • 確保批次中的每個請求都有唯一的 custom_id。
  • 確保自批次 created_at(而非處理 ended_at)時間起未超過 29 天。如果超過 29 天,結果將不再可檢視。
  • 確認批次尚未被取消。

請注意,批次中一個請求的失敗不會影響其他請求的處理。

批次儲存與隱私

  • Workspace 隔離:批次在其建立的 Workspace 內隔離。它們只能由與該 Workspace 關聯的 API 金鑰存取,或由有權在 Console 中檢視 Workspace 批次的使用者存取。

  • 結果可用性:批次結果在批次建立後 29 天內可用,提供充足的時間進行擷取和處理。

資料保留

批次處理會在批次建立後儲存請求和回應資料長達 29 天。您可以在處理完成後隨時使用 DELETE /v1/messages/batches/{batch_id} 端點刪除訊息批次。要刪除進行中的批次,請先取消它。非同步處理需要在伺服器端儲存輸入和輸出,直到批次完成和結果擷取為止。

有關所有功能的 ZDR 資格,請參閱 API 與資料保留。

常見問題

後續步驟

搜尋結果

透過提供具有來源歸屬的搜尋結果,為 RAG 應用程式啟用自然引用。

提示快取

透過快取批次中各請求共享的提示前綴來降低成本和延遲。

Claude Sonnet 4.6$1.50 / MTok$7.50 / MTok
Claude Sonnet 4.5$1.50 / MTok$7.50 / MTok
Claude Sonnet 4(已停用,Bedrock 和 Vertex AI 除外)$1.50 / MTok$7.50 / MTok
Claude Haiku 4.5$0.50 / MTok$2.50 / MTok
Claude Haiku 3.5(已停用,Bedrock 和 Vertex AI 除外)$0.40 / MTok$2 / MTok
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)
import time

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

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)
client = anthropic.Anthropic()

# 根據需要自動擷取更多頁面。
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)
client = anthropic.Anthropic()

# 以節省記憶體的區塊方式串流結果檔案,一次處理一個
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    match result.result.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if result.result.error.error.type == "invalid_request_error":
                # 重新傳送請求前必須先修正請求主體
                print(f"Validation error {result.custom_id}")
            else:
                # 請求可直接重試
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")
client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                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.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                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.",
                    }
                ],
            ),
        ),
    ]
)
from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas=["output-300k-2026-03-24"],
    requests=[
        Request(
            custom_id="long-form-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=300_000,
                messages=[
                    {
                        "role": "user",
                        "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                    }
                ],
            ),
        ),
    ],
)

print(message_batch)