Loading...
    • 建構
    • 管理
    • 模型與定價
    • 客戶端 SDK
    • API 參考
    Search...
    ⌘K
    第一步
    Claude 簡介快速入門
    使用 Claude 建構
    功能概覽使用 Messages API處理停止原因
    模型功能
    延伸思考自適應思考效能快速模式(測試版:研究預覽)結構化輸出引用來源串流訊息批次處理搜尋結果串流拒絕多語言支援嵌入向量
    工具
    概覽工具使用方式網路搜尋工具網路擷取工具程式碼執行工具記憶體工具Bash 工具電腦使用工具文字編輯器工具
    工具基礎架構
    工具搜尋程式化工具呼叫細粒度工具串流
    上下文管理
    上下文視窗壓縮上下文編輯提示快取Token 計數
    處理檔案
    Files APIPDF 支援圖像與視覺
    技能
    概覽快速入門最佳實踐企業版技能API 中的技能
    MCP
    遠端 MCP 伺服器MCP 連接器
    提示工程
    概覽提示最佳實踐Console 提示工具
    測試與評估
    定義成功標準並建立評估在 Console 中使用評估工具降低延遲
    強化防護欄
    減少幻覺提高輸出一致性防範越獄減少提示洩漏
    資源
    詞彙表
    版本說明
    Claude Platform
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

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

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    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
    模型功能

    批次處理

    使用 Message Batches API 高效地非同步處理大量請求

    批次處理是一種強大的方法,可以有效地處理大量請求。與其逐個處理請求並立即獲得回應,批次處理允許您將多個請求一起提交以進行非同步處理。此模式特別適用於以下情況:

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

    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

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

    您可以 直接探索 API 參考,以及閱讀本指南。

    Message Batches API 如何運作

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

    1. 系統使用提供的 Messages 請求創建新的 Message Batch。
    2. 然後批次被非同步處理,每個請求獨立處理。

    Was this page helpful?

    • Message Batches API 如何運作
    • 如何使用 Message Batches API
    • 列出所有 Message Batches
    • 取消 Message Batch
    • 在 Message Batches 中使用提示詞快取
  1. 您可以輪詢批次的狀態,並在所有請求處理完成後檢索結果。
  2. 這對於不需要立即結果的批量操作特別有用,例如:

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

    批次限制

    • Message Batch 限制為 100,000 個 Message 請求或 256 MB 大小,以先達到的為準。
    • 系統盡可能快地處理每個批次,大多數批次在 1 小時內完成。您可以在所有消息完成或 24 小時後(以先發生者為準)訪問批次結果。如果處理在 24 小時內未完成,批次將過期。
    • 批次結果在創建後 29 天內可用。之後,您仍然可以查看 Batch,但其結果將不再可供下載。
    • 批次的範圍限於 Workspace。您可以查看在您的 API 密鑰所屬 Workspace 內創建的所有批次(及其結果)。
    • 速率限制適用於 Batches API HTTP 請求和批次內等待處理的請求數量。請參閱 Message Batches API 速率限制。此外,根據當前需求和您的請求量,處理可能會減速。在這種情況下,您可能會看到更多請求在 24 小時後過期。
    • 由於高吞吐量和並發處理,批次可能會略微超過您的 Workspace 配置的 支出限制。

    支持的模型

    所有 活躍模型 都支持 Message Batches API。

    可以批處理的內容

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

    • Vision
    • 工具使用
    • 系統消息
    • 多輪對話
    • 任何測試版功能

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

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


    定價

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

    ModelBatch inputBatch 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 Batches API

    準備並創建您的批次

    Message Batch 由創建 Message 的請求列表組成。單個請求的形狀包括:

    • 用於識別 Messages 請求的唯一 custom_id
    • 包含標準 Messages API 參數的 params 對象

    您可以通過將此列表傳遞到 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 的處理狀態。

    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 在創建批次時的響應中提供,或通過列出批次獲得。您可以實現一個輪詢循環,定期檢查批次狀態,直到處理結束:

    #!/bin/sh
    # ...
    until [[ $(curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
              --header "x-api-key: $ANTHROPIC_API_KEY" \
              --header "anthropic-version: 2023-06-01" \
              | grep -o '"processing_status":[[:space:]]*"[^"]*"' \
              | cut -d'"' -f4) == "ended" ]]; do
        echo "Batch $MESSAGE_BATCH_ID is still processing..."
    # ...
        sleep 60
    done
    
    echo "Batch $MESSAGE_BATCH_ID has finished processing"

    列出所有 Message Batches

    您可以使用 列表端點 列出 Workspace 中的所有 Message Batches。該 API 支持分頁,根據需要自動獲取其他頁面:

    #!/bin/sh
    
    if ! command -v jq &> /dev/null; then
        echo "Error: This script requires jq. Please install it first."
        exit 1
    fi
    
    BASE_URL="https://api.anthropic.com/v1/messages/batches"
    
    has_more=true
    after_id=""
    
    while [ "$has_more" = true ]; do
        # Construct URL with after_id if it exists
        if [ -n "$after_id" ]; then
            url="${BASE_URL}?limit=20&after_id=${after_id}"
        else
            url="$BASE_URL?limit=20"
        fi
    
        response=$(curl -s "$url" \
                  --header "x-api-key: $ANTHROPIC_API_KEY" \
                  --header "anthropic-version: 2023-06-01")
    
        # Extract values using jq
        has_more=$(echo "$response" | jq -r '.has_more')
        after_id=$(echo "$response" | jq -r '.last_id')
    
        # Process and print each entry in the data array
        echo "$response" | jq -c '.data[]' | while read -r entry; do
            echo "$entry" | jq '.'
        done
    done

    檢索批次結果

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

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

    您將看到批次結果的概覽,其中包含批次的 request_counts,顯示有多少請求達到這四種狀態中的每一種。

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

    #!/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_error" ]; 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 和結果類型執行不同的操作。以下是一組結果範例:

    .jsonl file
    {"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

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

    #!/bin/sh
    # ...
    curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
        --header "x-api-key: $ANTHROPIC_API_KEY" \
        --header "anthropic-version: 2023-06-01"

    回應將顯示批次處於 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. 結構化您的請求以共享盡可能多的快取內容

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

    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 的完整傲慢與偏見文本,以增加快取命中的可能性。

    擴展輸出(測試版)

    output-300k-2026-03-24 測試版標頭將 max_tokens 上限提高到 300,000,用於使用 Claude Opus 4.6 或 Claude Sonnet 4.6 的批次請求。包含該標頭以在單次轉換中生成遠長於標準限制(根據模型為 64k 到 128k)的輸出。

    擴展輸出僅在 Message Batches API 上可用,不在同步 Messages API 上可用。它在 Claude API 上受支援,在 Amazon Bedrock、Vertex AI 或 Microsoft Foundry 上不可用。

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

    單次 300k 令牌生成可能需要超過一小時才能完成,因此請根據 24 小時處理窗口計劃您的批次提交。標準批次定價(標準 API 價格的 50%)適用。

    curl https://api.anthropic.com/v1/messages/batches \
         --header "x-api-key: $ANTHROPIC_API_KEY" \
         --header "anthropic-version: 2023-06-01" \
         --header "anthropic-beta: output-300k-2026-03-24" \
         --header "content-type: application/json" \
         --data \
    '{
        "requests": [
            {
                "custom_id": "long-form-request",
                "params": {
                    "model": "claude-opus-4-6",
                    "max_tokens": 300000,
                    "messages": [
                        {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
                    ]
                }
            }
        ]
    }'

    有效批次處理的最佳實踐

    為了充分利用 Batches API:

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

    常見問題故障排除

    如果遇到意外行為:

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

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


    批次儲存和隱私

    • 工作區隔離:批次在建立它們的工作區內隔離。它們只能由與該工作區相關聯的 API 金鑰或有權限在 Console 中查看工作區批次的使用者存取。

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


    資料保留

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

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

    常見問題