Cloudflare AI Gatewayの導入で最初に押さえること

はじめに

Cloudflare AI Gatewayを触ろうとすると、最初に少し迷います。

名前だけ見ると「LLM APIの入口をCloudflareにするもの」だと分かります。ただ、実際に使い始めようとすると、Workers AIから使うのか、OpenAI互換APIのURLを差し替えるのか、Cloudflare側で何を作る必要があるのかが見えにくいです。

前回の記事では、AI Gatewayを挟むとLLMのリクエストとレスポンスをどこまで記録できるかを検証しました。

ただ、その記事は「すでにAI Gatewayを使う前提」で話を始めていたので、初めて読む人には少し不親切でした。

この記事では、まずAI Gatewayの導入部分だけを切り出します。Workers AIを使った最小構成でAI Gatewayにリクエストを通し、Cloudflareのダッシュボードでログを見るところまでを整理します。

AI Gatewayは何をするものか

AI Gatewayは、LLMプロバイダへのリクエストの手前に置く入口です。

アプリケーションから直接OpenAI、Anthropic、Workers AIなどへ投げる代わりに、AI Gatewayを経由します。すると、Cloudflare側でリクエスト数、モデル、ステータス、レイテンシ、トークン数、コスト、エラーなどを観測しやすくなります。

ざっくり書くと、次のような位置づけです。

Application
  ↓
Cloudflare AI Gateway
  ↓
LLM provider

AI Gatewayは、アプリ内部の処理全体をtraceとして記録する道具ではありません。RAGでどの文書を検索したか、Agentがどのツールを呼んだか、ユーザー評価がどうだったかまで見たい場合は、LangfuseのようなLLMOpsツールが必要になります。

一方で、「どのLLM呼び出しが、どのモデルに、何回、どれくらいのコストで、どのくらい遅延しているか」をまず見る入口としては使いやすいです。

最初はWorkers AIから試す

AI GatewayはOpenAI互換APIのURL差し替えでも使えますが、最初の理解にはWorkers AIから試す方が分かりやすいです。

理由は、Cloudflare Workers、Workers AI、AI GatewayをCloudflareの中だけで完結して確認できるからです。OpenAIのAPIキーや外部プロバイダの設定をいったん脇に置き、AI Gatewayを通す感覚だけを確認できます。

今回の最小構成は次のとおりです。

Browser
  ↓
Cloudflare Worker
  ↓
Workers AI binding
  ↓
AI Gateway
  ↓
Workers AI model

この記事では、アプリとして凝ったものは作りません。ブラウザでWorkerのURLを開くと、Workers AIのLLMが1回応答するだけの小さな構成にします。

前提

必要なものは次の3つです。

• Cloudflareアカウント
• Node.js
• Wrangler

WranglerはCloudflare Workersをローカル開発、デプロイするためのCLIです。手元に入っていなければ、プロジェクト作成時に一緒にセットアップされます。

Cloudflareの公式手順では、npm create cloudflare@latest を使ってWorkerプロジェクトを作ります。

npm create cloudflare@latest -- hello-ai

質問されたら、まずは次のように選べば十分です。

What would you like to start with?: Hello World example
Which template would you like to use?: Worker only
Which language do you want to use?: TypeScript
Do you want to deploy your application?: No

作成されたディレクトリへ移動します。

cd hello-ai

Workers AI bindingを追加する

WorkerからWorkers AIを呼ぶには、Wrangler設定にAI bindingを追加します。

wrangler.toml を使っている場合は、次を追加します。

[ai]
binding = "AI"

wrangler.jsonc を使っている場合は、次のような設定になります。

{
  "ai": {
    "binding": "AI"
  }
}

この設定を入れると、Workerのコードから env.AI としてWorkers AIを呼べるようになります。

AI Gateway経由でLLMを呼ぶ

次に、Workerの処理を書き換えます。

src/index.ts を次のようにします。

export interface Env {
  AI: Ai;
}

export default {
  async fetch(_request, env): Promise<Response> {
    const response = await env.AI.run(
      "@cf/meta/llama-3.1-8b-instruct-fast",
      {
        prompt:
          "Cloudflare AI GatewayをLLMアプリの運用で使うメリットを3つ、短く説明してください。",
      },
      {
        gateway: {
          id: "default",
          skipCache: true,
        },
      },
    );

    return Response.json(response);
  },
} satisfies ExportedHandler<Env>;

ポイントは、env.AI.run の第3引数に gateway を指定しているところです。

{
  gateway: {
    id: "default",
    skipCache: true,
  },
}

id: "default" を指定すると、Cloudflare側でデフォルトのAI Gatewayが使われます。まだGatewayを手動作成していない場合でも、認証済みリクエストを投げることでデフォルトGatewayが作られます。

本番運用で名前を明示したい場合は、CloudflareダッシュボードでGatewayを作成し、そのGateway IDを指定します。

ローカルで動かす

ローカルではWranglerを使います。

npx wrangler dev

初回はCloudflareへのログインを求められることがあります。ログイン後、Wranglerが表示するローカルURLを開きます。

多くの場合は次のようなURLです。

http://localhost:8787

ブラウザで開いて、LLMの応答がJSONで返れば、WorkerからWorkers AIを呼べています。

注意点として、Workers AIはローカル開発中でもCloudflareアカウント上のAI実行を使います。手元だけで完全に閉じたモック実行ではありません。利用量や課金の扱いは確認しておいた方がよいです。

ダッシュボードでログを見る

リクエストを数回流したら、CloudflareのダッシュボードでAI Gatewayを開きます。

見たいのは、次の項目です。

gateway
provider
model
status
duration
request count
tokens
cost
logs

最初に確認すべきなのは、「今のリクエストがAI Gatewayを通っているか」です。

Workerのレスポンスが返っていても、AI Gatewayのログに何も出ていないなら、gateway 設定が効いていない可能性があります。id の指定、bindingの設定、Cloudflareアカウントの向き先を確認します。

デプロイする

ローカルで動いたら、Workerをデプロイします。

npx wrangler deploy

デプロイ後は、次のようなURLでWorkerにアクセスできます。

https://hello-ai.<YOUR_SUBDOMAIN>.workers.dev

このURLを開いて同じように応答が返れば、Cloudflare上にデプロイされたWorkerからWorkers AIを呼べています。あわせて、AI Gateway側にも本番リクエストとしてログが残るか確認します。

OpenAI互換APIで使う場合

Workers AIでAI Gatewayの感覚をつかんだら、次はOpenAI互換APIのURL差し替えに進めます。

OpenAIへ直接投げる場合、通常は次のようなエンドポイントを使います。

https://api.openai.com/v1/chat/completions

AI Gatewayを挟む場合は、CloudflareのGateway URLに差し替えます。

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions

Authorizationヘッダーには、基本的にOpenAIのAPIキーを渡します。

Authorization: Bearer <OPENAI_API_KEY>

つまり、アプリ側から見ると「APIキーはプロバイダのものを使い、URLだけAI Gateway経由にする」形です。

この構成にすると、既存のOpenAI SDKやfetch実装を大きく変えずに、Cloudflare側でLLMリクエストの観測を始められます。

導入時に決めておくこと

AI Gatewayは便利ですが、何も考えずに有効化すると危ない部分もあります。

特に、ログにプロンプトやレスポンス本文が残る場合は注意が必要です。個人開発の検証なら問題になりにくくても、業務データ、個人情報、顧客情報、社内文書を含むプロンプトを扱うなら、ログ保存方針を先に決める必要があります。

導入時には、最低限次を決めておくとよさそうです。

• どの環境からAI Gatewayを通すか
• Gateway IDを環境ごとに分けるか
• ログに本文を残してよいか
• 誰がAI Gatewayのログを見られるか
• エラー調査時にどのログを一次情報にするか
• Langfuseなど別の観測ツールとどう役割分担するか

個人的には、まず開発環境か検証用の小さなWorkerで試し、何がログに残るかを目で見てから、実アプリに入れるのがよいと思います。

次に読む記事

ここまでで、AI Gatewayを通してLLMリクエストを流す入口は作れました。

次は、AI Gatewayに実際にどんなログが残るのかを見ます。

AI GatewayでLLMのリクエストとレスポンスをどこまで記録できるか試す

導入手順だけだと、「通った」で終わってしまいます。運用で本当に見たいのは、プロンプト、レスポンス、トークン数、コスト、レイテンシ、エラーがどこまで追えるかです。

次の記事では、OpenAI互換APIをAI Gateway経由で呼び、正常系とエラー系のログを確認します。