Google Vertex AI

Google Vertex AI ↗ を使うと、エンタープライズ向けの生成 AI 体験を簡単に構築・デプロイできます。

Google Cloud アカウントの設定手順は次のとおりです。

Google Cloud Platform (GCP) アカウント
- GCP アカウント ↗ に登録します。新規ユーザーはクレジット（90 日間有効）の対象になる場合があります。
Vertex AI API を有効にする
- Enable Vertex AI API ↗ を開き、プロジェクトで API を有効にします。
利用したいモデルへのアクセスを申請します。

エンドポイント

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai

前提条件

Google Vertex AI へリクエストするときは、次が必要です。

AI Gateway のアカウントタグ
AI Gateway のゲートウェイ名
Google Vertex AI の認証情報（サービスアカウント JSON またはアクセストークン）
Google Vertex AI のプロジェクト名
Google Vertex AI のリージョン（例: us-central1）
Google Vertex AI のモデル

URL の構成

新しいベース URL は、上記の値を使って次の構成になります。https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}

続けて、呼び出したいエンドポイントを付けます。例: /publishers/google/models/{model}:{generative_ai_rest_resource}

最終的な URL は次のようになります。https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent

Vertex AI で認証する

通常、Vertex AI の認証には Google Cloud SDKs ↗ で短期認証情報を生成する必要があり、設定が複雑です。AI Gateway では、複数の方法でこの手順を簡略化します。

認証方法の比較

方法	`cf-aig-authorization` ヘッダー	`Authorization` ヘッダー	リージョンの扱い
BYOK（推奨）	`Bearer {CF_AIG_TOKEN}`	不要	ダッシュボードのドロップダウンで選択
ヘッダー内のサービスアカウント JSON	`Bearer {CF_AIG_TOKEN}`	`region` キー付きの Base64 エンコード JSON	JSON に `region` キーを含める
直接アクセストークン	`Bearer {CF_AIG_TOKEN}`	`Bearer {gcloud_access_token}`	URL パスに含める

オプション 1: BYOK（推奨）

推奨する方法は、AI Gateway の Bring Your Own Keys (BYOK) で Google サービスアカウントの認証情報を保存することです。認証情報を安全に保ち、アプリケーションコードから切り離せます。

Google Cloud Console でサービスアカウントキーを作成 ↗ します。使う Vertex AI エンドポイントとモデルに必要な権限を、サービスアカウントに付与してください。
Cloudflare ダッシュボードで AI > AI Gateway > 対象のゲートウェイ > Provider Keys を開きます。
Add API Key を選択し、プロバイダーに Google Vertex AI を選びます。
サービスアカウント JSON を貼り付け、ドロップダウンからリージョンを選びます。AI Gateway は選択したリージョンを保存済み認証情報に自動適用するため、JSON に region フィールドを手動で追加する必要はありません。
Save を選択します。

BYOK を設定すると、リクエストに含めるのは cf-aig-authorization ヘッダーだけです。Vertex AI の認証は AI Gateway が自動で処理します。

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent" \
    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{
        "contents": [
          {
            "role": "user",
            "parts": [
              {
                "text": "Tell me more about Cloudflare"
              }
            ]
          }
        ]
      }'

オプション 2: ヘッダー内のサービスアカウント JSON

各リクエストの Authorization ヘッダーに、Google サービスアカウント JSON を Base64 エンコードして渡せます。テスト時や、BYOK を使えない場合に便利です。

Google Cloud Console でサービスアカウントキーを作成 ↗ します。使う Vertex AI エンドポイントとモデルに必要な権限を、サービスアカウントに付与してください。

AI Gateway はサービスアカウント JSON から短期アクセストークンを生成し、キャッシュして連続リクエストに使い、期限切れ時は自動で更新します。

サービスアカウント JSON の構造例

{
	"type": "service_account",
	"project_id": "your-project-id",
	"private_key_id": "your-private-key-id",
	"private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
	"client_email": "your-service-account@your-project.iam.gserviceaccount.com",
	"client_id": "your-client-id",
	"auth_uri": "https://accounts.google.com/o/oauth2/auth",
	"token_uri": "https://oauth2.googleapis.com/token",
	"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
	"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-service-account%40your-project.iam.gserviceaccount.com",
	"region": "us-central1"
}

オプション 3: 直接アクセストークン

すでに Google Cloud SDKs を使い、短期アクセストークンを生成している場合（例: gcloud auth print-access-token）、そのトークンをリクエストの Authorization ヘッダーに Bearer トークンとして渡せます。

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent" \
    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
    -H "Authorization: Bearer ya29.c.b0Aaekm1K..." \
    -H 'Content-Type: application/json' \
    -d '{
        "contents": [
          {
            "role": "user",
            "parts": [
              {
                "text": "Tell me more about Cloudflare"
              }
            ]
          }
        ]
      }'

統合 Chat Completions API を使う

AI Gateway は、プロバイダー横断で使える Unified API を提供します。Google Vertex AI では、標準のチャット補完フォーマットを使えます。model フィールドにはプロバイダープレフィックスが含まれるため、モデル文字列は google-vertex-ai/google/gemini-2.5-pro のようになります。

エンドポイント

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

BYOK を使った例

BYOK を設定すると、含めるのは cf-aig-authorization ヘッダーだけです。

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions" \
    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{
        "model": "google-vertex-ai/google/gemini-2.5-pro",
        "messages": [
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }'

OpenAI SDK を使った例

BYOK を使わない場合は、Base64 エンコードしたサービスアカウント JSON（region キーを含む）を API キーとして渡します。

import OpenAI from "openai";

// Service account JSON must include "region" key when not using BYOK
const serviceAccountJson = JSON.stringify({
	type: "service_account",
	project_id: "your-project-id",
	// ... other fields from your downloaded JSON
	region: "us-central1", // Required: add this to your service account JSON
});

const client = new OpenAI({
	apiKey: Buffer.from(serviceAccountJson).toString("base64"),
	baseURL:
		"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat",
	defaultHeaders: {
		"cf-aig-authorization": `Bearer {cf_aig_token}`,
	},
});

const response = await client.chat.completions.create({
	model: "google-vertex-ai/google/gemini-2.5-pro",
	messages: [
		{
			role: "user",
			content: "What is Cloudflare?",
		},
	],
});

console.log(response.choices[0].message.content);

cURL を使った例

# First, base64-encode your service account JSON (must include "region" key)
SERVICE_ACCOUNT_BASE64=$(base64 < service-account.json | tr -d '\n')

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions" \
    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
    -H "Authorization: Bearer $SERVICE_ACCOUNT_BASE64" \
    -H 'Content-Type: application/json' \
    -d '{
        "model": "google-vertex-ai/google/gemini-2.5-pro",
        "messages": [
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }'

プロバイダー固有のエンドポイントを使う

Vertex AI API の全体にアクセスするには、プロバイダー固有のエンドポイントも使えます。

BYOK を使った cURL

BYOK を設定すると、必要なのは cf-aig-authorization ヘッダーだけです。

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent" \
    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{
        "contents": [
          {
            "role": "user",
            "parts": [
              {
                "text": "Tell me more about Cloudflare"
              }
            ]
          }
        ]
      }'

サービスアカウント JSON を使った cURL

BYOK を使わない場合は、Base64 エンコードしたサービスアカウント JSON（region キーを含む）を Authorization ヘッダーで渡します。

# First, base64-encode your service account JSON (must include "region" key) as a single line
SERVICE_ACCOUNT_BASE64=$(base64 < service-account.json | tr -d '\n')

curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-2.5-flash:generateContent" \
    -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
    -H "Authorization: Bearer $SERVICE_ACCOUNT_BASE64" \
    -H 'Content-Type: application/json' \
    -d '{
        "contents": [
          {
            "role": "user",
            "parts": [
              {
                "text": "Tell me more about Cloudflare"
              }
            ]
          }
        ]
      }'

トラブルシューティング

AI Gateway 全般のトラブルシューティングは、トラブルシューティングを参照してください。

401 Unauthenticated エラー

Google から CREDENTIALS_MISSING または UNAUTHENTICATED エラーが返った場合は、次の Vertex AI 固有の点を確認してください。

リージョンを確認する: URL では global ではなく、us-central1 などの特定のリージョンエンドポイントを使います。global エンドポイントは対応モデルが限られています。
BYOK の設定を確認する: BYOK を使っている場合は、ダッシュボードで次を確認します。
- サービスアカウント JSON が正しく保存されていること
- ドロップダウンからリージョンが選択されていること
サービスアカウントの権限を確認する: サービスアカウントに、Google Cloud の Vertex AI User ロールまたは同等の権限があることを確認します。
region キーを確認する（BYOK 以外）: サービスアカウント JSON を Authorization ヘッダーに直接渡す場合は、JSON に region キーが含まれていることを確認します。