メッセージバッチ(ベータ版)
メッセージバッチAPIは、大量のメッセージリクエストを非同期で処理する強力で費用対効果の高い方法です。このアプローチは即時の応答を必要としないタスクに適しており、コストを50%削減しながらスループットを向上させます。
メッセージバッチAPIはベータ版です
バッチAPIがパブリックベータ版として利用可能になったことをお知らせできることを嬉しく思います!この機能にアクセスするには、APIリクエストにanthropic-beta: message-batches-2024-09-24
ヘッダーを含めるか、SDKコールでclient.beta.messages.batches
を使用する必要があります。
今後数週間にわたってこのオープンベータ版の改善を続けていきますので、皆様のフィードバックをお待ちしています。このフォームからアイデアや提案をお寄せください。
このガイドに加えて、API リファレンスを直接確認することもできます。
メッセージバッチAPIの仕組み
メッセージバッチAPIにリクエストを送信すると:
- システムは提供されたメッセージリクエストで新しいメッセージバッチを作成します。
- バッチは非同期で処理され、各リクエストは独立して処理されます。
- バッチのステータスを確認し、すべてのリクエストの処理が終了したら結果を取得できます。
これは特に、即時の結果を必要としない以下のような一括操作に有用です:
- 大規模な評価:数千のテストケースを効率的に処理
- コンテンツモデレーション:大量のユーザー生成コンテンツを非同期で分析
- データ分析:大規模データセットの洞察や要約を生成
- 一括コンテンツ生成:様々な目的(製品説明、記事の要約など)のための大量のテキストを作成
バッチの制限
- メッセージバッチは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に送信できるリクエストはすべてバッチに含めることができます。これには以下が含まれます:
- Vision
- ツールの使用
- システムメッセージ
- マルチターン会話
- すべてのベータ機能
バッチ内の各リクエストは独立して処理されるため、1つのバッチ内で異なるタイプのリクエストを組み合わせることができます。
価格設定
バッチAPIは大幅なコスト削減を提供します。すべての使用料は標準APIの価格の50%で課金されます。
モデル | バッチ入力 | バッチ出力 |
---|---|---|
Claude 3.5 Sonnet | $1.50 / MTok | $7.50 / MTok |
Claude 3 Opus | $7.50 / MTok | $37.50 / MTok |
Claude 3 Haiku | $0.125 / MTok | $0.625 / MTok |
メッセージバッチAPIの使用方法
バッチの準備と作成
メッセージバッチはメッセージを作成するためのリクエストのリストで構成されています。個々のリクエストの形式は以下で構成されます:
- メッセージリクエストを識別するための一意の
custom_id
- 標準のメッセージAPIパラメータを含む
params
オブジェクト
このリストをrequests
パラメータに渡してバッチを作成できます:
この例では、2つの別々のリクエストが非同期処理のためにバッチ処理されています。各リクエストには一意のcustom_id
があり、メッセージAPIで使用する標準のパラメータが含まれています。
バッチリクエストをメッセージAPIでテストする
各メッセージリクエストのparams
オブジェクトの検証は非同期で実行され、検証エラーはバッチ全体の処理が終了したときに返されます。メッセージAPIで最初にリクエストの形式を確認することで、入力が正しく構築されていることを確認できます。
バッチが最初に作成されると、レスポンスの処理ステータスはin_progress
になります。
バッチの追跡
メッセージバッチのprocessing_status
フィールドは、バッチの処理段階を示します。最初はin_progress
で始まり、バッチ内のすべてのリクエストの処理が完了し、結果が準備できるとended
に更新されます。コンソールを訪れるか、取得エンドポイントを使用してバッチの状態を監視できます:
処理が終了したことを知るために、このエンドポイントをポーリングできます。
バッチ結果の取得
バッチ処理が終了すると、バッチ内の各メッセージリクエストに結果が得られます。結果には4つのタイプがあります:
結果タイプ | 説明 |
---|---|
succeeded | リクエストが成功。メッセージ結果を含みます。 |
errored | リクエストでエラーが発生し、メッセージは作成されませんでした。無効なリクエストや内部サーバーエラーなどが考えられます。これらのリクエストには課金されません。 |
canceled | このリクエストがモデルに送信される前にユーザーがバッチをキャンセルしました。これらのリクエストには課金されません。 |
expired | このリクエストがモデルに送信される前にバッチが24時間の期限に達しました。これらのリクエストには課金されません。 |
バッチのrequest_counts
で結果の概要を確認できます。これは、これら4つの状態のそれぞれに何件のリクエストが達したかを示します。
バッチの結果は、コンソールとメッセージバッチのresults_url
の両方でダウンロードできます。結果のサイズが大きくなる可能性があるため、すべてを一度にダウンロードするのではなく、結果をストリーミングすることをお勧めします。
結果は.jsonl
形式で、各行がメッセージバッチ内の単一のリクエストの結果を表す有効なJSONオブジェクトになります。ストリーミングされた各結果に対して、そのcustom_id
と結果タイプに応じて異なる処理を行うことができます。以下は結果の例です:
結果にエラーがある場合、そのresult.error
は標準のエラー形式に設定されます。
バッチ結果は入力順序と一致しない場合があります
バッチ結果は任意の順序で返される可能性があり、バッチ作成時のリクエストの順序と一致しない場合があります。上記の例では、2番目のバッチリクエストの結果が1番目より先に返されています。結果を対応するリクエストと正しくマッチングするには、常にcustom_id
フィールドを使用してください。
効果的なバッチ処理のベストプラクティス
バッチAPIを最大限活用するために:
- バッチ処理のステータスを定期的に監視し、失敗したリクエストに対して適切な再試行ロジックを実装する。
- 順序が保証されないため、結果とリクエストを簡単にマッチングできるよう、意味のある
custom_id
値を使用する。 - より良い管理のために、非常に大きなデータセットを複数のバッチに分割することを検討する。
- 検証エラーを避けるため、メッセージAPIで単一のリクエスト形式を事前テストする。
一般的な問題のトラブルシューティング
予期しない動作が発生した場合:
- バッチリクエストの総サイズが32 MBを超えていないことを確認してください。リクエストサイズが大きすぎる場合、413
request_too_large
エラーが発生する可能性があります。 - バッチ内のすべてのリクエストでサポートされているモデルを使用していることを確認してください。
- バッチ内の各リクエストに一意の
custom_id
があることを確認してください。 - バッチの
created_at
時刻(処理のended_at
時刻ではない)から29日未満であることを確認してください。29日を超えると、結果は表示できなくなります。 - バッチがキャンセルされていないことを確認してください。
バッチ内の1つのリクエストの失敗は、他のリクエストの処理に影響を与えないことに注意してください。
バッチのストレージとプライバシー
-
ワークスペースの分離:バッチは作成されたワークスペース内で分離されています。そのワークスペースに関連付けられたAPIキー、またはコンソールでワークスペースのバッチを表示する権限を持つユーザーのみがアクセスできます。
-
結果の利用可能性:バッチ結果は、バッチ作成後29日間利用可能で、取得と処理のための十分な時間が確保されています。
よくある質問
Was this page helpful?