跳到主要内容

Google Vertex AI

KOPI AI AGENT 通过 Vertex 的 OpenAI 兼容端点支持 Google Cloud Vertex AI 上的 Gemini 模型。与 Google AI Studio provider(使用针对 generativelanguage.googleapis.com 的静态 API key)不同,Vertex 提供企业级速率限制和 GCP 计费/额度,当你希望 Gemini 的使用量计入 Google Cloud 账户而非 AI Studio key 时,它是更合适的选择。

Vertex 使用 OAuth2 认证,而非 API key

Vertex 的标准端点没有静态 API key。每个请求都需要一个短期的 OAuth2 access token(TTL 约 1 小时),该 token 由 service-account JSON 或 Application Default Credentials(ADC)生成。Kopi Agent 会为你生成并自动刷新这些 token —— 你无需手动粘贴 token。这也是为什么将临时 token 粘贴到自定义 provider 的 api_key 字段中不起作用:它会在会话中途过期。

前提条件​

  • 一个 Google Cloud 项目,已启用 Vertex AI API 且计费处于激活状态。
  • 凭据,以下之一:
    • 带有 roles/aiplatform.user 角色的 service-account JSON 密钥文件,或
    • 通过 gcloud auth application-default login 获取的 Application Default Credentials(在 GCP VM 上运行时则通过 metadata server)。
  • google-auth —— 首次选择 Vertex 时会自动安装(懒安装),也可以使用 pip install 'kopi-ai-agent[vertex]' 显式安装。

快速开始​

# Option A — service account JSON (recommended for servers / gateways)
echo "VERTEX_CREDENTIALS_PATH=/path/to/service-account.json" >> ~/.kopi/.env

# Option B — Application Default Credentials (good for local dev)
gcloud auth application-default login

# Select Vertex as your provider
kopi model
# → Choose "More providers..." → "Google Vertex AI"
# → Enter your GCP project ID (or leave blank to use the one in your credentials)
# → Choose a region (default: global)
# → Select a Gemini model

# Start chatting
kopi chat

配置​

Vertex 按敏感度拆分其设置:

  • 凭据路径指向一个密钥,保存在 ~/.kopi/.env 中。
  • 项目 ID 和区域属于非敏感的路由设置,保存在 ~/.kopi/config.yaml 中。

~/.kopi/.env:

# One of these (checked in this order); omit both to use ADC:
VERTEX_CREDENTIALS_PATH=/path/to/service-account.json
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

~/.kopi/config.yaml:

model:
default: google/gemini-3-flash-preview
provider: vertex

vertex:
project_id: my-gcp-project # blank → use the project embedded in the credentials
region: global # "global" is required for the Gemini 3.x previews
环境变量优先于 config.yaml

VERTEX_PROJECT_ID 和 VERTEX_REGION 会覆盖 config.yaml 中的 vertex.project_id / vertex.region 值。用它们进行按 shell 的临时覆盖;持久设置则保留在 config.yaml 中。

认证工作原理​

  1. Kopi Agent 按以下顺序解析凭据:VERTEX_CREDENTIALS_PATH → GOOGLE_APPLICATION_CREDENTIALS → ADC。
  2. 它生成一个 OAuth2 access token(cloud-platform scope)并进行缓存,在 token 距离过期不足 5 分钟时刷新。
  3. 该 token 会被交给一个指向 Vertex 端点的标准 OpenAI client:
    https://aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{region}/endpoints/openapi
    区域位置(location)则改用 {region}-aiplatform.googleapis.com 主机。
  4. 如果会话运行时间超过 token 生命周期,且某个请求返回 401,Kopi Agent 会重新生成 token 并自动重试。在长时间运行的网关上,如果 ADC 的 refresh token 本身已过期,Kopi Agent 会在配置了 service-account JSON 的情况下回退使用它。

可用模型​

Vertex 要求模型 ID 带有 google/ vendor 前缀。kopi model 选择器提供:

模型ID
Gemini 3.1 Pro Previewgoogle/gemini-3.1-pro-preview
Gemini 3 Pro Previewgoogle/gemini-3-pro-preview
Gemini 3 Flash Previewgoogle/gemini-3-flash-preview
Gemini 3.1 Flash Lite Previewgoogle/gemini-3.1-flash-lite-preview
Gemini 2.5 Progoogle/gemini-2.5-pro
Gemini 2.5 Flashgoogle/gemini-2.5-flash
Gemini 3.x 的 global 区域

Gemini 3.x preview 模型通过 global 端点提供服务。区域端点(us-central1 等)可能会返回 404。除非有特定原因需要固定区域,否则请保持 region: global。

会话中途切换模型​

/model google/gemini-3-pro-preview
/model google/gemini-3-flash-preview

/model 用于在已配置的 provider 和模型之间切换;它不会收集新的凭据。请先使用 kopi model 配置 Vertex。

推理 / 思考​

Vertex 通过 OpenAI 兼容接口暴露 Gemini 的思考预算(thinking budget)。Kopi Agent 会自动将其 reasoning-effort 设置映射到 extra_body.google.thinking_config,因此 reasoning_effort 的工作方式与其他 Gemini 平台上一致。

诊断​

kopi doctor

doctor 会报告 Vertex 凭据是否可解析(service-account 路径或 ADC),以及该 provider 是否已配置。

故障排查​

"Vertex AI credentials could not be resolved"​

Kopi Agent 既未找到 service-account JSON,也没有可用的 ADC。可以在 ~/.kopi/.env 中设置 VERTEX_CREDENTIALS_PATH,或运行 gcloud auth application-default login。如果凭据中未包含你的项目,请在 config.yaml 中设置 vertex.project_id。

google-auth 未安装​

安装该扩展:pip install 'kopi-ai-agent[vertex]'。Kopi Agent 在你首次选择 Vertex provider 时也会进行懒安装。

Gemini 3.x 模型返回 404​

你很可能使用了区域端点。请在 config.yaml 的 vertex: 部分中设置 region: global(或取消设置 VERTEX_REGION)。

403 / permission denied​

该 service account(或你的 ADC 身份)需要在该项目上拥有 roles/aiplatform.user 角色,且该项目必须启用 Vertex AI API。

相关内容​