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

• 需要處理大量數據
• 不需要即時回應
• 想要優化成本效益
• 正在進行大規模評估或分析

訊息批次 API 是我們首次實現這種模式。

​

訊息批次 API

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

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

​

訊息批次 API 的運作方式

當您向訊息批次 API 發送請求時：

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

這對於不需要即時結果的大量操作特別有用，例如：

• 大規模評估：高效處理數千個測試案例。
• 內容審核：非同步分析大量用戶生成的內容。
• 數據分析：為大型數據集生成見解或摘要。
• 批量內容生成：為各種目的創建大量文本（例如，產品描述、文章摘要）。

​

批次限制

• 一個訊息批次限制為100,000個訊息請求或256 MB大小，以先達到的為準。
• 我們會盡快處理每個批次，大多數批次在1小時內完成。當所有訊息完成處理或24小時後（以先到者為準），您就可以存取批次結果。如果批次在24小時內未完成處理，將會過期。
• 批次結果在創建後29天內可用。之後，您仍可以查看批次，但其結果將不再可供下載。
• 批次的範圍限定在工作區內。您可以查看在您的 API 金鑰所屬工作區內創建的所有批次及其結果。
• 速率限制適用於批次 API HTTP 請求和等待處理的批次內請求數量。請參閱訊息批次 API 速率限制。此外，我們可能會根據當前需求和您的請求量來降低處理速度。在這種情況下，您可能會看到更多請求在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 發送的請求都可以包含在批次中。這包括：

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

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

​

定價

批次 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 支援提示快取，允許您可能減少批次請求的成本和處理時間。提示快取和訊息批次的價格折扣可以疊加，當兩個功能一起使用時提供更大的成本節省。然而，由於批次請求是非同步和並行處理的，快取命中是以最佳努力為基礎提供的。用戶通常經歷30%到98%的快取命中率，具體取決於其流量模式。

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

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

實現提示快取的批次示例：

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

​

有效批次處理的最佳實踐

要充分利用批次 API：

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

​

常見問題故障排除

如果遇到意外行為：

• 驗證總批次請求大小不超過256 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"],
    ...
)