✨

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

に公開
AI
JavaScript
TypeScript
Cloudflare
agents
tech

警告
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 公式ドキュメントに記載されている「動作しない」コード例

以下の画像は、Cloudflare 公式ドキュメントに記載されているコード例です。

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

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

// このコードはCloudflareのドキュメントに記載されていますが、
// `@google/generative-ai`（旧）での書き方であり、
// `@google/genai`（新）では動作しません。

// Cloudflareのドキュメントには旧パッケージをimportしている
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(apiKey);
const model = genAI.getGenerativeModel(
  { model: "gemini-2.5-flash" },
  {
    // この baseUrl の指定方法は現在サポートされていません
    baseUrl: `https://gateway.ai.cloudflare.com/v1/...`,
  }
);

await model.generateContent(["What is Cloudflare?"]);

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

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

// このコードも、現在のSDK仕様ではbaseUrlを指定できません。
const genAI = new GoogleGenerativeAI(apiKey, {
  // このオプションは存在しないため、無視されます
  baseUrl: `https://gateway.ai.cloudflare.com/v1/...`,
});

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

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

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

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

正しい実装コード

import { GoogleGenAI } from "@google/genai";

// Gemini API クライアントを初期化
const genAI = new GoogleGenAI({
  apiKey: c.env.GEMINI_API_KEY,
});

// ★★★ 最重要ポイント ★★★
// AIコンテンツを生成する際に、config.httpOptions.baseUrl で
// Cloudflare genAI Gatewayのエンドポイントを指定する
const response = await genAI.models.generateContent({
  model: model,
  contents: prompt,
  config: {
    httpOptions: {
      baseUrl: `https://gateway.ai.cloudflare.com/v1/${c.env.CLOUDFLARE_ACCOUNT_ID}/${c.env.CLOUDFLARE_AI_GATEWAY_NAME}/google-ai-studio`,
    },
  },
});

ポイントの解説

  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を指定する方法は、古い情報である可能性が高い。

特に AI の技術は日々進化していて、新しいパッケージのリリース直後は、ドキュメントが古い情報のままになっていることがよくあります。この記事で紹介したように、Cloudflare の公式ドキュメントでさえ、廃止されたパッケージを前提とした古い情報を提供していました。

開発者として最も重要なのは、ドキュメントを参考にしつつも、実際にコードを動かして検証することです。エラーが出た時は、ドキュメントが間違っている可能性も常に頭に入れておきましょう。

この記事が、同じ問題に直面している開発者の時間を節約できれば、嬉しいです。

GitHubで編集を提案

Discussion