2025/10/165分ID: google-genai-with-cloudflare-ai-gatewayAI


【重要】Cloudflare AI GatewayとGeminiパッケージ「@google/genai」を繋ぐ正しい方法

警告
Google の NPM パッケージ @google/generative-ai は廃止されました。
新しい @google/genai を使用する必要があります。

今回は、この重要な変更点を踏まえつつ、Cloudflare AI Gateway と Google の最新 Gemini API パッケージ (@google/genai) を連携させる本当に正しい方法を解説します。

Cloudflare の公式ドキュメントは、廃止された古いパッケージ (@google/generative-ai) を前提に書かれているため、その情報をもとに最新の@google/genaiを導入しようとすると、確実に詰まります。

この記事では、Web 上の情報だけではたどり着きにくい、実際の動作するコードを元にした最新の実装方法を共有します。

問題点：Cloudflare ドキュメントが「廃止されたパッケージ」を案内している

開発者が混乱する最大の原因は、Cloudflare AI Gateway の公式ドキュメントが、すでに廃止され、使うべきではない @google/generative-ai パッケージを基準に解説していることです。

NPM で @google/generative-ai を見ると、以下のような警告が表示されます。

> This package is now deprecated. Please use @google/genai instead.

この警告に従い @google/genai を使うと、ドキュメントに記載されている方法は機能しません。

Cloudflare 公式ドキュメントに記載されている「動作しない」コード例

以下に、ドキュメントで紹介されているものの、廃止されたパッケージの古い仕様であるため、現在の@google/genaiでは動作しない実装パターンを示します。

ドキュメント記載のパターン：getGenerativeModelの第二引数で指定

javascript

この方法を試すと、リクエストは Cloudflare AI Gateway を経由せず、Google のデフォルトエンドポイントに直接送信されてしまいます。

パターン 2：コンストラクタで指定

javascript

これらの方法を試すと、リクエストは Cloudflare AI Gateway を経由せず、Google のデフォルトエンドポイントに直接送信されてしまいます。

解決策：generateContentメソッドのconfigで指定する

結論から言うと、最新の@google/genaiパッケージで Cloudflare AI Gateway のエンドポイントを指定する正しい方法は、generateContentメソッドの引数内でconfigオブジェクトを渡すことです。

以下が、実際に動作する Hono を使った Cloudflare Worker のコードです。

正しい実装コード

typescript

ポイントの解説

  1. クライアントの初期化はシンプルに: new GoogleGenAI()のコンストラクタでは、API キーのみを渡します。baseUrlはここでは指定しません。
  2. generateContentでconfigを渡す: 実際に API リクエストが発生するai.models.generateContentメソッドの引数オブジェクトにconfigプロパティを追加します。
  3. httpOptions.baseUrl: configの中にhttpOptionsオブジェクトをネストし、その中にbaseUrlとして Cloudflare AI Gateway のエンドポイント URL を指定します。
  4. 結果の取得: レスポンスから生成されたテキストを取得する際は、response.textプロパティにアクセスします。（最新の SDK ではresponse.text()メソッドの場合もありますが、この実装ではプロパティです）

この方法により、リクエストごとに動的にエンドポイントを切り替えるといった、より柔軟な対応も可能になります。

まとめ

公式ドキュメントが更新されていない状況では、実際にコードを動かして試行錯誤するしかありません。今回ご紹介した方法は、まさにその試行錯誤の末に見つかった、確実な解決策です。

  • @google/genaiで Cloudflare AI Gateway を使う場合、generateContentメソッドのconfig.httpOptions.baseUrlで指定する。
  • コンストラクタやgetGenerativeModelでbaseUrlを指定する方法は、古い情報である可能性が高い。

ドキュメントを鵜呑みにせず、実際のコードと向き合うことの重要性を再認識させられますね。
この記事が、同じ問題に直面している開発者の時間を節約できれば、これ以上嬉しいことはありません。