要約、文字起こし、埋め込み生成、レポート作成のようなAI処理をHTTPリクエスト内で完了させようとすると、providerの遅延やrate limitがそのまま利用者の待ち時間と失敗になります。処理をCloudflare Queuesへ渡せば、受付と実行を分けられます。ただし、キューを挟むだけで信頼性が完成するわけではありません。
設計の要点は、同じメッセージが複数回届いても結果を壊さず、失敗を見失わないことです。
受付時にjob IDを確定する
APIは入力を検証し、job IDを発行して受付状態を保存してからQueueへ送ります。メッセージには大きな本文や秘密情報を詰めず、job ID、tenant ID、処理種別、入力オブジェクトの参照、schema versionを入れます。
利用者には同期結果ではなく、202 Accepted相当の受付と状態確認先を返します。送信成功と処理完了を同じイベントにしないことが重要です。
at-least-onceを前提に冪等化する
Cloudflare Queuesは既定でat-least-once deliveryです。信頼性を優先する一方、まれに同じメッセージが複数回配信され得ます。請求、メール送信、外部API更新、レポート確定のような副作用は、重複実行すると事故になります。
対策は、job IDを冪等キーにし、処理開始前に状態を比較することです。
completedなら再実行せずackするrunningでleaseが有効なら重複処理を避ける- 外部APIにも同じidempotency keyを渡す
- 結果保存はjob IDを一意キーにして上書き条件を限定する
「consumerが一度しか動かない」という前提を置かないことが、非同期化の第一条件です。
再試行を失敗種別で分ける
timeout、HTTP 429、一時的なprovider障害は再試行候補です。一方、入力形式不正、権限不足、存在しないmodelは同じ処理を繰り返しても直りません。
Cloudflareの公式ドキュメントでは既定の再試行回数は3回で、delaySecondsを使った遅延や、attemptsに応じたbackoffを構成できます。再試行は追加readとして課金されるため、回数を大きくするだけではなく、エラー分類と待ち時間を決めます。
バッチ処理では、個別ackをしないと一件の失敗でバッチ全体が再配信される場合があります。成功したメッセージを明示的にackし、失敗したものだけをretryする構成を検討します。
DLQを「墓場」にしない
Dead Letter Queueは、consumerがmax_retriesへ達したメッセージの退避先です。DLQを設定しなければ、retry上限後にメッセージは削除されます。DLQを作っても監視しなければ、処理漏れを別の場所へ移しただけです。
DLQには専用consumerか監視を付け、次を記録します。
- 最終error classとattempts
- 元queue、job ID、schema version
- 手動再実行の可否と理由
- 再実行者、日時、新しいjob IDとの関係
公式ドキュメントでは、active consumerのないDLQ上のメッセージは4日で削除されるとされています。調査期限をそれより短くし、長期保管が必要なら別の監査ストアへ必要最小限を移します。
最小の状態機械
状態はaccepted → running → succeededを基本にし、retryingとfailedを追加します。providerへのrequest ID、model、開始・終了時刻、token量、error classを残しますが、プロンプト本文を無期限にログへ保存しません。
監視ではqueue backlog、oldest message age、成功率、retry率、DLQ件数、処理時間、job当たり費用を見ます。APIの成功率だけを見ても、後段の滞留は発見できません。
海外の一次情報と適用限界
Cloudflareの公式仕様ではQueuesはat-least-once配信であり、まれな重複を前提にconsumer側を冪等化する必要があります。再試行回数を超えたメッセージはDLQへ送れますが、DLQを置くだけでは復旧しません。失敗理由、元job ID、再実行条件を記録し、運用者が安全に戻せる手順まで含める必要があります。なお、QueuesとWorkflowsは代替関係ではなく、単純な非同期配信と状態を持つ長時間処理で使い分けます。
AI基盤の非同期処理を設計したい方へ
TechWorkerでは、Cloudflare Workers、Queues、R2、AI providerを組み合わせ、受付、処理、再試行、監査、削除までを本番運用の単位で設計します。まず一つのAIジョブで失敗モードを洗い出し、必要最小限の状態と監視から始めます。
デプロイ設定の注意点はCloudflare Workersの本番運用で踏んだ罠5つ、監査と削除は情シス審査を通すために実装したことも参照してください。
一次情報と確認範囲
確認日：2026年9月3日。製品仕様・制度は更新されるため、導入時はリンク先の最新版を再確認してください。海外の制度・職業規範は日本へ直接適用せず、相違点と限界を本文に明記しています。