訊息批次處理 (beta)

訊息批次處理 API 是一種強大且具成本效益的方式,可以非同步處理大量的訊息請求。這種方法非常適合不需要即時回應的任務,可以降低 50% 的成本同時提高處理量。

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

​

訊息批次處理 API 的運作方式

當您向訊息批次處理 API 發送請求時:

1. 系統會使用提供的訊息請求建立一個新的訊息批次。
2. 批次會以非同步方式處理,每個請求都獨立處理。
3. 您可以查詢批次的狀態,並在所有請求處理完成後取得結果。

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

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

​

批次限制

• 一個訊息批次限制為 10,000 個訊息請求或 32 MB 大小,以先達到的為準。
• 批次最多需要 24 小時來生成回應,但處理可能會提前結束。在整個批次處理結束之前,您無法取得批次結果。如果批次在 24 小時內未完成處理,將會過期。
• 批次結果在建立後 29 天內可用。之後,您仍可以查看批次,但其結果將無法下載。
• 批次的範圍限於工作區。您可以查看在您的 API 金鑰所屬工作區內建立的所有批次及其結果。
• 速率限制適用於批次處理 API 的 HTTP 請求,而不是批次中的請求數量。此外,我們可能會根據當前需求和您的請求量來降低處理速度。在這種情況下,您可能會看到更多請求在 24 小時後過期。
• 由於高吞吐量和並行處理,批次可能會略微超過您工作區配置的支出限制。

​

支援的模型

訊息批次處理 API 目前支援:

• Claude 3.5 Sonnet (claude-3-5-sonnet-20240620 和 claude-3-5-sonnet-20241022)
• Claude 3.5 Haiku (claude-3-5-haiku-20241022)
• Claude 3 Haiku (claude-3-haiku-20240307)
• Claude 3 Opus (claude-3-opus-20240229)

​

可以批次處理的內容

任何您可以向訊息 API 發送的請求都可以包含在批次中。這包括:

• 視覺
• 工具使用
• 系統訊息
• 多輪對話
• 任何 beta 功能

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

​

定價

批次處理 API 提供顯著的成本節省。所有使用費用均為標準 API 價格的 50%。

​

如何使用訊息批次處理 API

​

準備並建立您的批次

訊息批次由一系列建立訊息的請求組成。每個請求包含:

• 用於識別訊息請求的唯一 custom_id
• 包含標準訊息 API參數的 params 物件

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

在此範例中,兩個獨立的請求被批次處理以進行非同步處理。每個請求都有一個唯一的 custom_id 並包含您用於訊息 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
}

​

追蹤您的批次

訊息批次的 processing_status 欄位表示批次處理的階段。它最初為 in_progress,然後在批次中所有請求完成處理且結果準備就緒時更新為 ended。您可以透過訪問控制台或使用檢索端點來監控批次狀態:

您可以輪詢此端點以知道處理何時結束。

​

取得批次結果

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

您可以在批次的 request_counts 中看到結果概覽,顯示有多少請求達到這四種狀態。

批次結果可以在控制台和訊息批次的 results_url 下載。由於結果可能很大,建議串流結果而不是一次下載全部。

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

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","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-3-5-sonnet-20241022","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 將設置為我們標準的錯誤格式。

​

有效批次處理的最佳實踐

要充分利用批次處理 API:

• 定期監控批次處理狀態並為失敗的請求實施適當的重試邏輯。
• 使用有意義的 custom_id 值以輕鬆匹配結果與請求,因為順序不受保證。
• 考慮將非常大的資料集分成多個批次以便更好地管理。
• 使用訊息 API 測試單個請求格式以避免驗證錯誤。

​

常見問題疑難排解

如果遇到意外行為:

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

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

​

批次儲存和隱私

• 工作區隔離: 批次在其建立的工作區內隔離。只有與該工作區相關聯的 API 金鑰,或具有在控制台中查看工作區批次權限的使用者才能存取。

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

​

常見問題

import anthropic

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas: ["max-tokens-3-5-sonnet-2024-07-15"],
    ...
)