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 account tag
- AI Gateway gateway 名称
- Google Vertex AI 凭证（服务账户 JSON 或访问令牌）
- Google Vertex AI 项目名称
- Google Vertex AI 区域（例如
us-central1） - Google Vertex AI 模型
你的新基础 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 进行身份验证通常需要通过 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 路径中 |
推荐的方式是使用 AI Gateway 的 Bring Your Own Keys (BYOK) 功能存储你的 Google 服务账户凭证。这样可以将凭证妥善保管，避免写入应用代码。
- 在 Google Cloud Console 中 创建服务账户密钥 ↗。确保该服务账户对你计划使用的 Vertex AI 端点和模型拥有所需权限。
- 在 Cloudflare 仪表板中，转到 AI > AI Gateway > 你的 gateway > Provider Keys（提供商密钥）。
- 选择 Add API Key（添加 API 密钥），并将提供商选为 Google Vertex AI。
- 粘贴你的服务账户 JSON，并从下拉菜单中选择区域。AI Gateway 会自动将所选区域应用到已存储的凭证，因此你无需手动在 JSON 中添加
region字段。 - 选择 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"
}
]
}
]
}'你可以在每次请求的 Authorization 标头中直接传递 Google 服务账户 JSON 的 Base64 编码版本。此选项适用于测试或无法使用 BYOK 的场景。
在 Google Cloud Console 中 创建服务账户密钥 ↗。确保该服务账户对你计划使用的 Vertex AI 端点和模型拥有所需权限。
AI Gateway 使用你的服务账户 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": "[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"
}如果你已经在使用 Google Cloud SDKs 并生成短期访问令牌（例如使用 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"
}
]
}
]
}'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 后，你只需包含 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?"
}
]
}'如果未使用 BYOK，请将包含 region 键的 Base64 编码服务账户 JSON 作为 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);# 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 后，你只需要 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"
}
]
}
]
}'如果未使用 BYOK，请在 Authorization 标头中传递包含 region 键的 Base64 编码服务账户 JSON：
# 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 的一般故障排除，请参阅 故障排除。
如果你收到来自 Google 的 CREDENTIALS_MISSING 或 UNAUTHENTICATED 错误，请检查以下 Vertex AI 特定问题：
-
检查你的区域：在 URL 中使用具体的区域端点（例如
us-central1），而不是global。global端点的模型支持有限。 -
验证 BYOK 配置：如果使用 BYOK，请在仪表板中确认：
- 你的服务账户 JSON 已正确保存
- 已从下拉菜单中选择区域
-
检查服务账户权限：确保你的服务账户在 Google Cloud 中具有
Vertex AI User角色或等效权限。 -
验证 region 键（仅限非 BYOK）：如果在
Authorization标头中直接传递服务账户 JSON，请确保 JSON 包含region键。