--- title: "Cloudflare AI Gatewayの導入で最初に押さえること" description: "Cloudflare AI GatewayをWorkers AIから使い始めるための最小手順と、OpenAI互換APIへ進む前に理解しておきたい役割、設定、確認ポイントを整理する。" lang: "ja" canonical: "https://llm-lab.dev/posts/cloudflare-ai-gateway-introduction/" source: "https://llm-lab.dev/posts/cloudflare-ai-gateway-introduction.md" publishedAt: "2026-05-15" updatedAt: "2026-05-15" category: "Cloudflare" tags: - "cloudflare" - "ai-gateway" - "workers-ai" - "agentops" --- # Cloudflare AI Gatewayの導入で最初に押さえること > [!NOTE] > この記事で確認したこと > > 今回は、Cloudflare AI Gatewayの導入手順を最小構成に絞り、Workers AIのリクエストをAI Gateway経由にしてDashboardのログで確認する流れを整理しました。 > > 分かったことは、最初はWorkers AIから試すと、Worker、モデル呼び出し、AI GatewayをCloudflare内で完結して確認しやすいという点です。OpenAI互換APIへ進む前に、AI bindingの追加、`gateway` 指定、ログ確認、どの環境とpayloadを記録するかをチェックしておくと扱いやすくなります。 # 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側でリクエスト数、モデル、ステータス、レイテンシ、トークン数、コスト、エラーなどを観測しやすくなります。 ざっくり書くと、次のような位置づけです。 ```text Application ↓ Cloudflare AI Gateway ↓ LLM provider ``` AI Gatewayは、アプリ内部の処理全体をtraceとして記録する道具ではありません。RAGでどの文書を検索したか、Agentがどのツールを呼んだか、ユーザー評価がどうだったかまで見たい場合は、LangfuseのようなAgentOpsツールが必要になります。 一方で、「どのLLM呼び出しが、どのモデルに、何回、どれくらいのコストで、どのくらい遅延しているか」をまず見る入口としては使いやすいです。 ## 最初はWorkers AIから試す AI GatewayはOpenAI互換APIのURL差し替えでも使えますが、最初の理解にはWorkers AIから試す方が分かりやすいです。 理由は、Cloudflare Workers、Workers AI、AI GatewayをCloudflareの中だけで完結して確認できるからです。OpenAIのAPIキーや外部プロバイダの設定をいったん脇に置き、AI Gatewayを通す感覚だけを確認できます。 今回の最小構成は次のとおりです。 ```text 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プロジェクトを作ります。 ```bash npm create cloudflare@latest -- hello-ai ``` 質問されたら、まずは次のように選べば十分です。 ```text 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 ``` 作成されたディレクトリへ移動します。 ```bash cd hello-ai ``` ## Workers AI bindingを追加する WorkerからWorkers AIを呼ぶには、Wrangler設定にAI bindingを追加します。 `wrangler.toml` を使っている場合は、次を追加します。 ```toml [ai] binding = "AI" ``` `wrangler.jsonc` を使っている場合は、次のような設定になります。 ```jsonc { "ai": { "binding": "AI" } } ``` この設定を入れると、Workerのコードから `env.AI` としてWorkers AIを呼べるようになります。 ## AI Gateway経由でLLMを呼ぶ 次に、Workerの処理を書き換えます。 `src/index.ts` を次のようにします。 ```ts export interface Env { AI: Ai; } export default { async fetch(_request, env): Promise { 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.AI.run` の第3引数に `gateway` を指定しているところです。 ```ts { gateway: { id: "default", skipCache: true, }, } ``` `id: "default"` を指定すると、Cloudflare側でデフォルトのAI Gatewayが使われます。まだGatewayを手動作成していない場合でも、認証済みリクエストを投げることでデフォルトGatewayが作られます。 本番運用で名前を明示したい場合は、CloudflareダッシュボードでGatewayを作成し、そのGateway IDを指定します。 ## ローカルで動かす ローカルではWranglerを使います。 ```bash npx wrangler dev ``` 初回はCloudflareへのログインを求められることがあります。ログイン後、Wranglerが表示するローカルURLを開きます。 多くの場合は次のようなURLです。 ```text http://localhost:8787 ``` ブラウザで開いて、LLMの応答がJSONで返れば、WorkerからWorkers AIを呼べています。 注意点として、Workers AIはローカル開発中でもCloudflareアカウント上のAI実行を使います。手元だけで完全に閉じたモック実行ではありません。利用量や課金の扱いは確認しておいた方がよいです。 ## ダッシュボードでログを見る リクエストを数回流したら、CloudflareのダッシュボードでAI Gatewayを開きます。 見たいのは、次の項目です。 ```text gateway provider model status duration request count tokens cost logs ``` 最初に確認すべきなのは、「今のリクエストがAI Gatewayを通っているか」です。 Workerのレスポンスが返っていても、AI Gatewayのログに何も出ていないなら、`gateway` 設定が効いていない可能性があります。`id` の指定、bindingの設定、Cloudflareアカウントの向き先を確認します。 ## デプロイする ローカルで動いたら、Workerをデプロイします。 ```bash npx wrangler deploy ``` デプロイ後は、次のようなURLでWorkerにアクセスできます。 ```text https://hello-ai..workers.dev ``` このURLを開いて同じように応答が返れば、Cloudflare上にデプロイされたWorkerからWorkers AIを呼べています。あわせて、AI Gateway側にも本番リクエストとしてログが残るか確認します。 ## OpenAI互換APIで使う場合 Workers AIでAI Gatewayの感覚をつかんだら、次はOpenAI互換APIのURL差し替えに進めます。 OpenAIへ直接投げる場合、通常は次のようなエンドポイントを使います。 ```text https://api.openai.com/v1/chat/completions ``` AI Gatewayを挟む場合は、CloudflareのGateway URLに差し替えます。 ```text https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions ``` Authorizationヘッダーには、基本的にOpenAIのAPIキーを渡します。 ```http Authorization: Bearer ``` つまり、アプリ側から見ると「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のリクエストとレスポンスをどこまで記録できるか試す](/posts/cloudflare-ai-gateway-llm-request-response-logging/) 導入手順だけだと、「通った」で終わってしまいます。運用で本当に見たいのは、プロンプト、レスポンス、トークン数、コスト、レイテンシ、エラーがどこまで追えるかです。 次の記事では、OpenAI互換APIをAI Gateway経由で呼び、正常系とエラー系のログを確認します。