LlamaCloud 支持 Google Vertex AI，经由 Google Cloud Platform 为企业级地访问 Google 的 AI 模型。与直连 Gemini API 相比，Vertex AI 提供私有端点、更强的安全性以及与 GCP 的深度集成等进阶能力。

前置条件

• 一个有效的 Google Cloud Platform 账号

• 已启用 Vertex AI API 的 Google Cloud project

• 具备相应 IAM 权限的服务账号

• 所支持模型的访问权限与配额：

  • Gemini 3.1 Pro
  • Gemini 3.0 Flash
  • Gemini 2.5 Flash
  • Gemini 2.5 Pro
  • Gemini 2.5 Flash Lite
  • Gemini 2.0 Flash
  • Gemini 2.0 Flash Lite

环境变量

Google Vertex AI 集成使用下列环境变量：

• GOOGLE_VERTEX_AI_ENABLED —— 设为 “true” 以启用 Google Vertex AI（必需）
• GOOGLE_VERTEX_AI_PROJECT_ID —— Google Cloud project ID（必需）
• GOOGLE_VERTEX_AI_LOCATION —— Google Cloud 位置／地域（可选，默认 us-central1）
• GOOGLE_VERTEX_AI_CREDENTIALS_JSON —— 服务账号凭据的 JSON 字符串（必需）
• GOOGLE_VERTEX_AI_BASE_URL —— 覆盖 Vertex AI 端点（可选；默认为 https://{location}-aiplatform.googleapis.com）

配置

按下面这些步骤配置 Google Vertex AI 集成：

第 1 步：准备 Google Cloud project

1. 新建或沿用一个 Google Cloud project

2. 启用 Vertex AI API：

   终端窗口

   gcloud services enable aiplatform.googleapis.com

3. 确认该项目已开通计费

第 2 步：创建服务账号

创建一个具备所需 IAM 权限的服务账号：

必需的 IAM 权限

你的服务账号需要下列权限：

• aiplatform.endpoints.predict
• aiplatform.endpoints.explain
• ml.models.predict（用于遗留版本的模型）

方案一：使用预定义角色

终端窗口

gcloud iam service-accounts create llamacloud-vertex \
    --description="Service account for LlamaCloud Vertex AI" \
    --display-name="LlamaCloud Vertex AI"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:llamacloud-vertex@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

方案二：自定义角色

创建一个只含最小权限的自定义角色：

{
  "title": "LlamaCloud Vertex AI User",
  "description": "Custom role for LlamaCloud Vertex AI access",
  "stage": "GA",
  "includedPermissions": [
    "aiplatform.endpoints.predict",
    "aiplatform.endpoints.explain",
    "ml.models.predict"
  ]
}

第 3 步：生成服务账号密钥

为该服务账号生成一个 JSON 密钥：

终端窗口

gcloud iam service-accounts keys create llamacloud-vertex-key.json \
    --iam-account=llamacloud-vertex@PROJECT_ID.iam.gserviceaccount.com

第 4 步：创建 Kubernetes Secret

用你的 Vertex AI 凭据创建一个 secret：

apiVersion: v1
kind: Secret
metadata:
  name: vertex-ai-credentials
type: Opaque
stringData:
  GOOGLE_VERTEX_AI_ENABLED: "true"
  GOOGLE_VERTEX_AI_PROJECT_ID: "your-project-id"
  GOOGLE_VERTEX_AI_LOCATION: "us-central1"
  GOOGLE_VERTEX_AI_CREDENTIALS_JSON: |
    {
      "type": "service_account",
      "project_id": "your-project-id",
      "private_key_id": "key-id",
      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "client_email": "llamacloud-vertex@your-project-id.iam.gserviceaccount.com",
      "client_id": "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/llamacloud-vertex%40your-project-id.iam.gserviceaccount.com"
    }

应用这个 secret：

终端窗口

kubectl apply -f vertex-ai-secret.yaml

第 5 步：配置 Helm values

在你的 Helm 配置里引用这个 secret：

# External Secret (recommended)
config:
  llms:
    googleVertexAi:
      secret: "vertex-ai-credentials"
      baseUrl: "https://us-central1-aiplatform.googleapis.com"  # Optional — override endpoint

# or direct configuration (not recommended for production)
config:
  llms:
    googleVertexAi:
      projectId: "your-project-id"
      location: "us-central1"
      credentialsJson: |
        {
          "type": "service_account",
          ...
        }
      baseUrl: "https://us-central1-aiplatform.googleapis.com"  # Optional — override endpoint

可选的 baseUrl / GOOGLE_VERTEX_AI_BASE_URL 覆盖，会把 Vertex AI 流量改走代理或网关（例如自托管的 LLM 网关），而不是 Google Cloud 的地域端点。留着不设，则使用由 location 推导出的默认地域端点。

验证

配置完成后，请这样验证你的 Google Vertex AI 集成：

1. 在管理界面核对：在 LlamaCloud 管理界面查看可用的 Google 模型

2. 测试功能：上传一份文档，确认 Vertex AI 模型确在工作

故障排查

常见问题

服务账号权限

Error: Permission denied

解决办法：

• 确认你的服务账号具备所需的 IAM 权限
• 确保已授予 aiplatform.endpoints.predict 权限
• 检查该服务账号处于启用状态、未被禁用

project 配置

Error: Project not found or Vertex AI API not enabled

解决办法：

• 确保你的 Google Cloud project 已启用 Vertex AI API
• 核对配置里的 project ID 正确无误
• 确认该项目已开通计费

凭据问题

Error: Could not load credentials

解决办法：

• 确认服务账号 JSON 格式正确
• 确保凭据 JSON 里所有必填字段都在
• 检查私钥在 secret 里被正确转义
• 确认该服务账号密钥没有被删除或过期

地域限制

Error: Model not available in region

解决办法：

• 查看模型在你指定地域是否可用
• 换一个地域试试（例如 us-central1、us-east1）
• 某些模型并非在所有地域都可用

排查步骤

1. 测试 Vertex AI 认证：

   终端窗口

   gcloud auth activate-service-account --key-file=vertex-key.json
   gcloud ai models list --region=us-central1

2. 确认 secret 已挂载：

   终端窗口

   kubectl get secret vertex-ai-credentials -o yaml
   kubectl describe pod <pod-name> | grep -A 20 Environment

3. 检查网络连通性：确保你的集群能够访问 aiplatform.googleapis.com

4. 测试一次 API 调用：

   终端窗口

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-pro:predict" \
     -d '{"instances": [{"content": "Hello"}]}'