Loading...
    • 開發者指南
    • API 參考
    • MCP
    • 資源
    • 發行說明
    Search...
    ⌘K
    開始使用
    Claude 簡介快速開始
    模型與定價
    模型概覽選擇模型Claude 4.5 新功能遷移至 Claude 4.5模型棄用定價
    使用 Claude 構建
    功能概覽使用 Messages API上下文窗口提示詞最佳實踐
    功能
    提示詞快取上下文編輯擴展思考努力串流消息批次處理引用多語言支援Token 計數嵌入視覺PDF 支援Files API搜尋結果結構化輸出Google Sheets 附加元件
    工具
    概覽如何實現工具使用Token 高效工具使用細粒度工具串流Bash 工具代碼執行工具程式化工具調用計算機使用工具文字編輯器工具Web 獲取工具Web 搜尋工具記憶體工具工具搜尋工具
    Agent 技能
    概覽快速開始最佳實踐使用 API 的技能
    Agent SDK
    概覽TypeScript SDKPython SDK遷移指南
    指南
    串流輸入處理權限會話管理SDK 中的結構化輸出託管 Agent SDK修改系統提示詞SDK 中的 MCP自訂工具SDK 中的子 AgentSDK 中的斜線命令SDK 中的 Agent 技能追蹤成本和使用情況待辦事項清單SDK 中的外掛程式
    API 中的 MCP
    MCP 連接器遠端 MCP 伺服器
    第三方平台上的 Claude
    Amazon BedrockMicrosoft FoundryVertex AI
    提示詞工程
    概覽提示詞生成器使用提示詞範本提示詞改進器清晰直接使用範例(多次提示)讓 Claude 思考(CoT)使用 XML 標籤給 Claude 一個角色(系統提示詞)預填 Claude 的回應鏈接複雜提示詞長上下文提示擴展思考提示
    測試與評估
    定義成功標準開發測試案例使用評估工具降低延遲
    加強防護欄
    減少幻覺增加輸出一致性緩解越獄串流拒絕減少提示詞洩露保持 Claude 的角色
    管理和監控
    Admin API 概覽使用和成本 APIClaude Code Analytics API
    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
    • Catalog
    • 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
    • Catalog
    • 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
    • 在 Message Batches 中使用提示快取

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

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

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


    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 天內可用。之後,您仍可檢視批次,但其結果將不再可供下載。
    • 批次的範圍限定在工作區內。您可以檢視在您的 API 金鑰所屬工作區內建立的所有批次及其結果。
    • 速率限制適用於 Batches API HTTP 請求和批次內等待處理的請求數量。請參閱 Message Batches API 速率限制。此外,我們可能會根據當前需求和您的請求量放慢處理速度。在這種情況下,您可能會看到更多請求在 24 小時後過期。
    • 由於高吞吐量和並行處理,批次可能會略微超過您工作區配置的支出限制。

    支援的模型

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

    可以批次處理的內容

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

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

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

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


    定價

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

    ModelBatch inputBatch output
    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.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 ()

    如何使用 Message Batches API

    準備並建立您的批次

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

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

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

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

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

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

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

    JSON
    {
      "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。您可以透過造訪控制台或使用檢索端點來監控批次的狀態:

    您可以輪詢此端點以了解處理何時結束。

    檢索批次結果

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

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

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

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

    結果將採用 .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-sonnet-4-5-20250929","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-sonnet-4-5-20250929","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 Batches 中使用提示快取

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

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

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

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

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

    有效批次處理的最佳實務

    要充分利用 Batches API:

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

    常見問題疑難排解

    如果遇到意外行為:

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

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


    批次儲存和隱私

    • 工作區隔離:批次在建立它們的工作區內被隔離。它們只能由與該工作區關聯的 API 金鑰或在控制台中有權限檢視工作區批次的使用者存取。

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


    常見問題

    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-sonnet-4-5",
                    "max_tokens": 1024,
                    "messages": [
                        {"role": "user", "content": "Hello, world"}
                    ]
                }
            },
            {
                "custom_id": "my-second-request",
                "params": {
                    "model": "claude-sonnet-4-5",
                    "max_tokens": 1024,
                    "messages": [
                        {"role": "user", "content": "Hi again, friend"}
                    ]
                }
            }
        ]
    }'
    curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'
    #!/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
    
    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-sonnet-4-5",
                    "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-sonnet-4-5",
                    "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."}
                    ]
                }
            }
        ]
    }'