本文へ移動
OrangeCloud.run
GitHub のリポジトリ （新しいタブで開く）
章と記事の一覧

読む実行環境

AI Gateway

ログ・キャッシュ・制限・フォールバックをモデルの手前に

外部の LLM プロバイダや Workers AI をフロントエンドやバックエンドから直接叩く設計は、運用フェーズに入った途端に脆弱性を露呈する。上流 API の突発的な障害、同一プロンプトに対する重複リクエストによる課金の浪費、そして悪意あるユーザーによる過剰なトークン消費。これらをアプリケーションコード側の個別ロジックで受け止めるのは限界がある。

AI Gateway は、モデル呼び出しの直前に配置するリバースプロキシである。推論処理そのものは行わず、OpenAI、Anthropic、Google Gemini、Workers AI へ向かう通信を一元的に仲介し、可観測性とコスト防壁を提供する。

もたらされる 5 つの防壁

  1. リクエストのログ: 既定で、プロンプト、レスポンス、プロバイダ、モデル、トークン数、コスト、所要時間をダッシュボードに記録する。誰の呼び出しかを区別するには、カスタムメタデータ（1 リクエスト 5 件まで）に user_id などを付ける。保存できるログの量と期間には上限がある。
  2. 完全一致キャッシュ: プロバイダ、エンドポイント、モデル、認証ヘッダ、リクエスト本文がすべて一致するリクエストには、Cloudflare のキャッシュから応答を返す。キャッシュに当たった呼び出しはプロバイダへ送られないので、トークン課金が発生せず、往復の通信も省ける。既定では無効で、ゲートウェイの設定で有効にする。意味の近いプロンプトにも当てるセマンティックキャッシュは、Cloudflare が今後の追加を予定している段階で、まだ使えない。
  3. レート制限: ゲートウェイ全体に一律で、回数と間隔（固定ウィンドウまたはスライディングウィンドウ）を決めて制限する。超えたリクエストには 429 を返す。ユーザーごとに制限したい場合は、dynamic route（条件分岐や制限を組み込めるルーティング機能）の Rate Limit ノードで、metadata.user_id などをキーに指定する。
  4. 再試行とフォールバック: 失敗したリクエストを最大 5 回まで再試行できる（間隔は最大 60 秒、バックオフは constant・linear・exponential）。優先モデルがエラーやタイムアウトで失敗したときの切り替え先と順序は、dynamic route か model alias（複数のモデルを 1 つの名前で呼べるようにする機能）で自分で定義する。
  5. 支出上限: 固定またはローリングの期間内の累計費用が上限に達すると、ゲートウェイは 429 を返して遮断する。プロバイダ・モデル・メタデータ（ユーザー ID など）ごとに予算を分けられる。費用は推定値で、同時リクエストが集中すると一時的に上限を超えることがある。

導入手法

導入にあたって特別な SDK は必須ではない。既存の API クライアントや fetch 呼び出しの向く先を AI Gateway のエンドポイント URL へ差し替え、ゲートウェイの認証トークンを cf-aig-authorization ヘッダに付ける。新しく作るゲートウェイは認証が必須である。

const response = await fetch(
  `https://gateway.ai.cloudflare.com/v1/${env.CF_ACCOUNT_ID}/${env.AI_GATEWAY_NAME}/anthropic/v1/messages`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": env.ANTHROPIC_API_KEY,
      "anthropic-version": "2026-10-21",
      "cf-aig-authorization": `Bearer ${env.CF_AIG_TOKEN}`,
    },
    body: JSON.stringify({
      model: "claude-haiku-5-5",
      max_tokens: 256,
      messages: [{ role: "user", content: "Workers の特徴を要約してください。" }],
    }),
  },
);

コストを抑え込むための設計原則

  • 既定値は最小・最安のモデルに固定する: 全てのリクエストに最高性能のモデルを割り当てず、高度な推論を要する特定の機能にのみフラグで切り替える。
  • 入力テキスト長の上限バリデーション: クライアントから送られた巨大なテキストをそのままプロバイダへ流さず、Worker の手前で文字数やトークン数を打ち切る。
  • キャッシュの生存期間（TTL）を意識する: 同じリクエストが繰り返され、リアルタイム性を求めない用途には長めのキャッシュを設定し、エッジから即答させる。