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 的标准端点没有静态 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
VERTEX_PROJECT_ID 和 VERTEX_REGION 会覆盖 config.yaml 中的 vertex.project_id / vertex.region 值。用它们进行按 shell 的临时覆盖;持久设置则保留在 config.yaml 中。
认证工作原理
- Kopi Agent 按以下顺序解析凭据:
VERTEX_CREDENTIALS_PATH→GOOGLE_APPLICATION_CREDENTIALS→ ADC。 - 它生成一个 OAuth2 access token(
cloud-platformscope)并进行缓存,在 token 距离过期不足 5 分钟时刷新。 - 该 token 会被交给一个指向 Vertex 端点的标准 OpenAI client:
区域位置(location)则改用
https://aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{region}/endpoints/openapi{region}-aiplatform.googleapis.com主机。 - 如果会话运行时间超过 token 生命周期,且某个请求返回
401,Kopi Agent 会重新生成 token 并自动重试。在长时间运行的网关上,如果 ADC 的 refresh token 本身已过期,Kopi Agent 会在配置了 service-account JSON 的情况下回退使用它。
可用模型
Vertex 要求模型 ID 带有 google/ vendor 前缀。kopi model 选择器提供:
| 模型 | ID |
|---|---|
| Gemini 3.1 Pro Preview | google/gemini-3.1-pro-preview |
| Gemini 3 Pro Preview | google/gemini-3-pro-preview |
| Gemini 3 Flash Preview | google/gemini-3-flash-preview |
| Gemini 3.1 Flash Lite Preview | google/gemini-3.1-flash-lite-preview |
| Gemini 2.5 Pro | google/gemini-2.5-pro |
| Gemini 2.5 Flash | google/gemini-2.5-flash |
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。
相关内容
- Google Gemini (AI Studio) —— 无需 GCP 的静态 API key 方式使用 Gemini
- AWS Bedrock —— 另一个原生云服务提供商集成
- AI Providers
- Configuration