大量の要約やembeddingを1件ずつ同期実行すると、利用者待ち時間、rate limit、再試行が一つの経路に集中します。Cloudflare Workers AIのAsynchronous Batch APIは、複数リクエストをまとめて受付し、後で結果を回収する仕組みです[1]。本番では「速いAPI」として置き換えるのではなく、即時応答が不要で、遅れても完了させたい仕事専用の状態機械として設計します。
同期とbatchを業務要件で分ける
対話、入力補助、画面上の判定は同期経路に残します。夜間の文書要約、検索索引のembedding、過去ログの分類など、人がその場で待たない処理をbatch候補にします。Batch APIは容量不足時に即時エラーへ倒す代わりにキューへ受け付け、queuedなどの状態とrequest_idを返します[1]。
この性質から、HTTP 200を業務完了と扱ってはいけません。受付完了、処理中、完了、一部失敗、期限超過、破棄を分けます。画面や上流システムには「受付済み」と「結果利用可能」を別イベントで返します。完了時刻を約束する業務では、許容遅延と代替経路を先に定義します。
1件ごとの外部IDで結果を照合する
REST APIでは各requestにexternal_referenceを付け、結果側で対応付けできます[2]。内部のrequest_idだけへ依存せず、業務レコードID、処理版、モデル版を組み合わせた冪等キーを作ります。ただし個人情報や原文をIDへ埋め込みません。
同じbatchを再送すると二重処理になる可能性があります。投入前にmanifestを保存し、受付ID、投入件数、各外部ID、モデル、入力ハッシュ、作成者、保持期限を記録します。再実行時は「未完了だけ」「全件を新しい版で再計算」「結果を破棄」のどれかを明示します。結果の順序だけで入力へ結び付けないことも重要です。
10MB上限より小さく分割する
Cloudflareの公式文書はbatch全体のpayloadを10MB未満とする注意を示しています[1]。上限ぎりぎりへ詰めず、件数、入力サイズ、モデルの最大入力、回収時間、再実行単位でchunkを決めます。1件の巨大文書が全体を止めないよう、投入前に検証して別キューへ分けます。
分割単位は運用にも影響します。小さすぎると管理対象が増え、大きすぎると一部失敗時の再実行が重くなります。日付だけでまとめず、顧客、機密区分、削除期限、モデルをまたがない単位にします。モデルカタログでbatch対応モデルを確認し、未対応モデルを同じ経路へ流さないようにします[3]。
pollerと結果保存を独立させる
状態確認を利用者リクエストのたびに行うと、無駄なpollと画面待ちが増えます。定期pollerが状態を確認し、完了時に結果を回収して、業務DBやR2など所定の保存先へ書きます。poll間隔には上限とjitterを付け、永続的なqueuedを警告します。
Queuesはメッセージの配送と再試行を担い[4]、Workflowsは複数stepの状態と再開を担います[5]。Batch API自体の受付状態と混同せず、役割を分けます。たとえば「文書収集→batch投入→完了待ち→結果検証→索引更新」をWorkflowで表し、投入要求の平準化をQueueで行います。
完了後に品質と欠損を検査する
完了は全結果が利用可能という意味ではありません。入力件数と結果件数、外部IDの重複、エラー型、空出力、モデル版、処理時間を照合します。embeddingなら次元と非数値を、要約なら空白・上限超過・入力参照を検査します。AI Gatewayや独自ログでtoken、遅延、errorを監視しても、内容品質は別の評価セットで確認します[6]。
関連するCloudflare QueuesのAIジョブ、Workflowsの耐障害化、429制御も参照してください。
Cloudflare Workers AIの非同期基盤設計を相談する
運用runbookへ残す項目
runbookには、投入停止条件、最大chunk、poll間隔、完了待ち期限、結果保存先、再実行単位、手動復旧者を明記します。batchが長時間queuedのとき、同じ内容を無制限に再送しません。受付済みmanifestを確認し、重複投入を避けた上で、待機、取消、別経路のどれを選ぶか判断します。
モデル更新時は、同じ入力セットを少量で再評価し、出力形式、件数、empty result、embedding次元など機械検査できる契約を先に確認します。本番データを使った大規模batchを最初の互換試験にしないことが、安全な切替につながります。
適用限界
Batch APIは即時応答、厳密な完了時刻、業務トランザクションの原子性を保証するものではありません。対応モデル、上限、料金、保持仕様は更新されるため、本番前に公式文書と契約条件を再確認します。
一次情報と確認範囲
確認日：2026年9月18日。製品仕様・制度は更新されるため、導入時はリンク先の最新版を再確認してください。海外の制度・職業規範は日本へ直接適用せず、相違点と限界を本文に明記しています。