← Cloudflare AI Gateway / ai-gateway / usage / providers

Google Vertex AI

Google Vertex AI ↗ позволяет разработчикам легко создавать и развертывать корпоративные генеративные ИИ-приложения.

Ниже приведено краткое руководство по настройке учетной записи Google Cloud:

Аккаунт Google Cloud Platform (GCP)
- Зарегистрируйтесь для получения аккаунт GCP ↗. Новые пользователи могут получить право на кредиты (действительны в течение 90 дней).
Включите Vertex AI API
- Перейдите в Включите Vertex AI API ↗ и активируйте API для своего проекта.
Подайте заявку на доступ к нужным моделям.

Конечная точка

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

Предварительные требования

Для запросов к Google Vertex AI вам потребуется:

AI Gateway account tag
AI Gateway gateway name
Учётные данные 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 SDK ↗ со сложной настройкой, но AI Gateway упрощает эту задачу, предлагая несколько вариантов.

Сравнение методов аутентификации

Метод	`cf-aig-authorization` заголовок	`Authorization` заголовок	Обработка регионов
BYOK (рекомендуется)	`Bearer {CF_AIG_TOKEN}`	Не требуется	Выберите в раскрывающемся списке панели управления
JSON сервисного аккаунта в заголовке	`Bearer {CF_AIG_TOKEN}`	JSON в кодировке Base64 с `region` ключ	Подключите `region` ключ в JSON
Прямой токен доступа	`Bearer {CF_AIG_TOKEN}`	`Bearer {gcloud_access_token}`	Указывается в пути URL

Вариант 1: BYOK (рекомендуется)

Рекомендуемый подход состоит в том, чтобы хранить учётные данные сервисного аккаунта Google с помощью Bring Your Own Keys (BYOK) функцию. Она защищает ваши учетные данные и не позволяет им попасть в код приложения.

Создайте ключ сервисного аккаунта ↗ в Google Cloud Console. Убедитесь, что у сервисного аккаунта есть необходимые разрешения для конечных точек и моделей Vertex AI, которые вы планируете использовать.
В панели управления Cloudflare перейдите в AI > AI Gateway > ваш шлюз > Ключи провайдера.
Выберите Добавить API-ключ и выберите Google Vertex AI в качестве провайдера.
Вставьте свой Service Account JSON и выберите регион из раскрывающегося списка. AI Gateway автоматически применяет выбранный регион к сохранённым учётным данным, поэтому вам не нужно вручную добавлять region поле в JSON.
Выберите Save.

После настройки BYOK вам нужно включить только cf-aig-authorization заголовок в своих запросах. AI Gateway автоматически выполняет аутентификацию Vertex AI.

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: Service Account JSON в заголовке

Вы можете передать JSON сервисного аккаунта Google напрямую в Authorization заголовок в каждом запросе, передавая в нём версию JSON, закодированную в base64. Этот вариант удобен для тестирования или когда BYOK использовать нельзя.

Создайте ключ сервисного аккаунта ↗ в Google Cloud Console. Убедитесь, что у сервисного аккаунта есть необходимые разрешения для конечных точек и моделей Vertex AI, которые вы планируете использовать.

AI Gateway использует JSON-файл сервисного аккаунта для генерации краткосрочных токенов доступа, которые кэшируются и используются для последующих запросов, а также автоматически обновляются по истечении срока действия.

Пример структуры JSON для service account

{
	"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": "[email protected]",
	"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 SDK и создаёте краткосрочный токен доступа (например, с помощью gcloud auth print-access-token), вы можете напрямую передать это как Bearer-токен в 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 "Authorization: Bearer ya29.c.b0Aaekm1K..." \
    -H 'Content-Type: application/json' \
    -d '{
        "contents": [
          {
            "role": "user",
            "parts": [
              {
                "text": "Tell me more about Cloudflare"
              }
            ]
          }
        ]
      }'

Использование Unified Chat Completions API

AI Gateway предоставляет Unified API который работает во всех провайдерах. Для Google Vertex AI можно использовать стандартный формат chat completions. Обратите внимание, что поле 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.

cURL с BYOK

После настройки 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"
              }
            ]
          }
        ]
      }'

cURL с Service Account JSON

Если вы не используете 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

Если вы получаете CREDENTIALS_MISSING или UNAUTHENTICATED ошибку от Google, проверьте следующие особенности, характерные для Vertex AI:

Проверьте свой регион: Используйте конкретный региональный эндпойнт (например, us-central1) в вашем URL, а не global. global конечная точка имеет ограниченную поддержку моделей.
Проверьте конфигурацию BYOK: Если вы используете BYOK, убедитесь в панели управления, что:
- Service Account JSON успешно сохранен
- В раскрывающемся списке был выбран регион
Проверьте разрешения сервисного аккаунта: убедитесь, что у вашего сервисного аккаунта есть Vertex AI User роль или эквивалентные разрешения в Google Cloud.
Проверьте региональный ключ (только для не-BYOK): при прямой передаче JSON сервисного аккаунта в Authorization заголовок, убедитесь, что JSON включает region ключ.