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

Google Vertex AI

Google Vertex AI ↗ umožňuje vývojářům snadno vytvářet a nasazovat generativní AI řešení připravená pro podnikové nasazení.

Níže je stručný návod, jak nastavit svůj účet Google Cloud:

Účet Google Cloud Platform (GCP)
- Zaregistrujte si Účet GCP ↗. Noví uživatelé mohou mít nárok na kredity (platné 90 dní).
Povolte Vertex AI API
- Přejděte na Povolte Vertex AI API ↗ a aktivujte API pro váš projekt.
Požádejte o přístup k požadovaným modelům.

Endpoint

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

Předpoklady

Při odesílání požadavků do Google Vertex AI budete potřebovat:

Account tag AI Gateway
Název gateway AI Gateway
Přihlašovací údaje Google Vertex AI (JSON Service Accountu nebo přístupový token)
Název projektu Google Vertex AI
Region Google Vertex AI (například us-central1)
Model Google Vertex AI

Struktura URL

Vaše nová base URL bude mít podle výše uvedených údajů tuto strukturu: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}.

Poté můžete připojit koncový bod, který chcete volat, například: /publishers/google/models/{model}:{generative_ai_rest_resource}

Vaše výsledná URL adresa tak bude vypadat takto: 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

Ověřování pomocí Vertex AI

Ověřování pomocí Vertex AI obvykle vyžaduje vygenerování krátkodobých přihlašovacích údajů pomocí Google Cloud SDK ↗ se složitým nastavením, ale AI Gateway vám to díky několika možnostem usnadňuje.

Porovnání metod ověřování

Metoda	`cf-aig-authorization` hlavička	`Authorization` hlavička	Zpracování regionů
BYOK (Doporučeno)	`Bearer {CF_AIG_TOKEN}`	Není potřeba	Vyberte v rozevírací nabídce dashboardu
JSON Service Accountu v hlavičce	`Bearer {CF_AIG_TOKEN}`	JSON kódovaný v base64 s `region` klíč	Vložte `region` klíč v JSON
Přímý přístupový token	`Bearer {CF_AIG_TOKEN}`	`Bearer {gcloud_access_token}`	Zahrnuto v cestě URL

Možnost 1: BYOK (doporučeno)

Doporučeným postupem je uložit přihlašovací údaje Google service account pomocí Bring Your Own Keys (BYOK) funkci. Díky tomu zůstávají vaše přihlašovací údaje v bezpečí a mimo kód vaší aplikace.

Vytvořit klíč Service Accountu ↗ v Google Cloud Console. Ujistěte se, že má servisní účet potřebná oprávnění pro koncové body a modely Vertex AI, které plánujete používat.
V Cloudflare dashboardu přejděte na AI > AI Gateway > vaše gateway > Provider Keys.
Vyberte Přidat API klíč a vyberte Google Vertex AI jako poskytovatele.
Vložte JSON Service Accountu a vyberte svůj region z rozbalovací nabídky. AI Gateway tento vybraný region automaticky použije pro vaše uložené přihlašovací údaje, takže nemusíte ručně přidávat region pole do JSON.
Vyberte Save.

Po nakonfigurování BYOK stačí zahrnout pouze cf-aig-authorization hlavičku ve svých požadavcích. AI Gateway automaticky zajišťuje ověřování 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"
              }
            ]
          }
        ]
      }'

Možnost 2: Service Account JSON v hlavičce

JSON Service Accountu Google můžete předat přímo v Authorization hlavičku v každém požadavku spolu s verzí JSON kódovanou v base64. Tato možnost je užitečná pro testování nebo v situacích, kdy nelze použít BYOK.

Vytvořit klíč Service Accountu ↗ v Google Cloud Console. Ujistěte se, že má servisní účet potřebná oprávnění pro koncové body a modely Vertex AI, které plánujete používat.

AI Gateway pomocí JSON service accountu generuje krátkodobé přístupové tokeny, které se ukládají do mezipaměti a používají pro následující požadavky, a po vypršení platnosti se automaticky obnoví.

Příklad struktury JSON pro 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"
}

Možnost 3: Přímý přístupový token

Pokud již používáte Google Cloud SDK a generujete krátkodobý přístupový token (například pomocí gcloud auth print-access-token), můžete jej přímo předat jako Bearer token v Authorization hlavičky požadavku.

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"
              }
            ]
          }
        ]
      }'

Používání Unified Chat Completions API

AI Gateway poskytuje Unified API která funguje napříč poskytovateli. Pro Google Vertex AI můžete použít standardní formát chat completions. Mějte na paměti, že pole model obsahuje prefix poskytovatele, takže váš řetězec modelu bude vypadat například takto: google-vertex-ai/google/gemini-2.5-pro.

Endpoint

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

Příklad s BYOK

Po nakonfigurování BYOK stačí zahrnout pouze cf-aig-authorization hlavičku:

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?"
          }
        ]
      }'

Příklad s OpenAI SDK

Pokud nepoužíváte BYOK, předejte JSON Service Accountu zakódovaný v base64 (s region klíčem) jako klíč 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);

Příklad s 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?"
          }
        ]
      }'

Používání specifického koncového bodu poskytovatele

Také můžete použít koncový bod specifický pro poskytovatele a získat přístup k celému Vertex AI API.

cURL s BYOK

Po nakonfigurování BYOK potřebujete pouze cf-aig-authorization hlavičku:

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 s JSON Service Accountu

Pokud nepoužíváte BYOK, předejte JSON Service Accountu zakódovaný v base64 (s region klíčem) v hlavičce 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"
              }
            ]
          }
        ]
      }'

Řešení potíží

Obecné řešení problémů s AI Gateway najdete v Řešení potíží.

Chyby 401 Unauthenticated

Pokud obdržíte CREDENTIALS_MISSING nebo UNAUTHENTICATED chybu od Google, zkontrolujte následující problémy specifické pro Vertex AI:

Zkontrolujte svůj region: Použijte konkrétní regionální koncový bod (například us-central1) ve vaší URL, nikoli global. global koncový bod má omezenou podporu modelů.
Ověřte konfiguraci BYOK: Pokud používáte BYOK, ověřte v dashboardu, že:
- Váš JSON Service Accountu byl úspěšně uložen
- Z rozevírací nabídky byl vybrán region
Zkontrolujte oprávnění servisního účtu: Ujistěte se, že váš service account má Vertex AI User roli nebo ekvivalentní oprávnění v Google Cloud.
Ověřte klíč regionu (pouze bez BYOK): Pokud JSON Service Accountu předáváte přímo v Authorization hlavičku a ujistěte se, že JSON obsahuje region klíč.