バッチ処理は、大量のリクエストを効率的に処理するための強力なアプローチです。リクエストを1つずつ即時に処理する代わりに、バッチ処理では複数のリクエストをまとめて非同期処理のために送信できます。このパターンは以下の場合に特に有用です：

• 大量のデータを処理する必要がある場合
• 即時のレスポンスが不要な場合
• コスト効率を最適化したい場合
• 大規模な評価や分析を実行する場合

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日間利用可能です。それ以降もバッチの表示は可能ですが、結果のダウンロードはできなくなります。
• バッチはWorkspaceごとにスコープされます。APIキーが属するWorkspace内で作成されたすべてのバッチとその結果を表示できます。
• レート制限は、Batches APIのHTTPリクエストと、処理待ちのバッチ内のリクエスト数の両方に適用されます。Message Batches APIのレート制限を参照してください。また、現在の需要とリクエスト量に基づいて処理速度が遅くなる場合があります。その場合、24時間後に期限切れとなるリクエストが増える可能性があります。
• 高スループットと並行処理のため、バッチはWorkspaceの設定された支出制限をわずかに超える可能性があります。

​

サポートされているモデル

Message Batches 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)

​

バッチ処理可能な内容

Messages APIで可能なリクエストはすべてバッチに含めることができます。これには以下が含まれます：

• Vision
• ツールの使用
• システムメッセージ
• 複数ターンの会話
• すべてのベータ機能

バッチ内の各リクエストは独立して処理されるため、1つのバッチ内で異なるタイプのリクエストを混在させることができます。

​

価格設定

Batches APIは大幅なコスト削減を提供します。すべての使用料は標準APIの価格の50%で課金されます。

​

Message Batches APIの使用方法

​

バッチの準備と作成

Message Batchは、Messageを作成するリクエストのリストで構成されています。個々のリクエストの形式は以下で構成されます：

• Messagesリクエストを識別するための一意のcustom_id
• 標準のMessages APIパラメータを含むparamsオブジェクト

このリストをrequestsパラメータに渡してバッチを作成できます：

この例では、2つの別々のリクエストが非同期処理のためにバッチ処理されています。各リクエストには一意のcustom_idがあり、Messages 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
}

​

バッチの追跡

Message Batchのprocessing_statusフィールドは、バッチの処理段階を示します。最初はin_progressで始まり、バッチ内のすべてのリクエストの処理が完了し、結果が準備できるとendedに更新されます。Consoleを訪れるか、取得エンドポイントを使用してバッチの状態を監視できます：

処理が終了したことを知るために、このエンドポイントをポーリングすることができます。

​

バッチ結果の取得

バッチ処理が終了すると、バッチ内の各Messagesリクエストに結果が設定されます。結果のタイプは4つあります：

バッチのrequest_countsで、これら4つの状態に達したリクエストの数の概要を確認できます。

バッチの結果は、ConsoleとMessage Batchのresults_urlの両方でダウンロードできます。結果のサイズが大きくなる可能性があるため、すべてを一度にダウンロードするのではなく、結果をストリーミングすることをお勧めします。

結果は.jsonl形式で、各行がMessage Batch内の単一のリクエストの結果を表す有効な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は標準のエラー形式に設定されます。

​

Message Batchesでのプロンプトキャッシュの使用

Message Batches APIはプロンプトキャッシュをサポートしており、バッチリクエストのコストと処理時間を潜在的に削減できます。プロンプトキャッシュとMessage Batchesの価格割引は重ね合わせることができ、両機能を一緒に使用するとさらなるコスト削減が可能です。ただし、バッチリクエストは非同期かつ並行して処理されるため、キャッシュヒットはベストエフォートで提供されます。ユーザーは通常、トラフィックパターンに応じて30%から98%のキャッシュヒット率を経験します。

バッチリクエストでキャッシュヒットの可能性を最大化するには：

1. バッチ内のすべてのMessageリクエストに同一のcache_controlブロックを含める
2. キャッシュエントリが5分の有効期限を過ぎて期限切れにならないよう、安定したリクエストストリームを維持する
3. できるだけ多くのキャッシュされたコンテンツを共有できるようにリクエストを構造化する

バッチでプロンプトキャッシュを実装する例：

この例では、バッチ内の両方のリクエストに同一のシステムメッセージとキャッシュ制御でマークされたPride and Prejudiceの全文が含まれており、キャッシュヒットの可能性を高めています。

​

効果的なバッチ処理のベストプラクティス

Batches APIを最大限活用するには：

• バッチ処理のステータスを定期的に監視し、失敗したリクエストに対して適切な再試行ロジックを実装する。
• 順序が保証されないため、結果とリクエストを簡単にマッチングできるよう、意味のあるcustom_id値を使用する。
• より良い管理のため、非常に大きなデータセットを複数のバッチに分割することを検討する。
• 検証エラーを避けるため、Messages APIで単一のリクエスト形式を試験的に実行する。

​

一般的な問題のトラブルシューティング

予期しない動作が発生した場合：

• バッチリクエストの総サイズが256 MBを超えていないことを確認する。リクエストサイズが大きすぎる場合、413 request_too_largeエラーが発生する可能性があります。
• バッチ内のすべてのリクエストでサポートされているモデルを使用していることを確認する。
• バッチ内の各リクエストに一意のcustom_idがあることを確認する。
• バッチのcreated_at時刻（処理のended_at時刻ではない）から29日未満であることを確認する。29日を超えると、結果は表示できなくなります。
• バッチがキャンセルされていないことを確認する。

バッチ内の1つのリクエストの失敗は、他のリクエストの処理に影響を与えないことに注意してください。

​

バッチのストレージとプライバシー

• Workspaceの分離: バッチは作成されたWorkspace内で分離されています。そのWorkspaceに関連付けられたAPIキー、またはConsoleでWorkspaceのバッチを表示する権限を持つユーザーのみがアクセスできます。

• 結果の利用可能性: バッチ結果は、バッチ作成後29日間利用可能で、取得と処理のための十分な時間が確保されています。

​

FAQ

import anthropic

client = anthropic.Anthropic()

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