proxycast/docs/content/03.providers/10.vertex-ai.md

title, description, navigation

title	description	navigation
Vertex AI	Google Cloud Vertex AI Provider 配置	icon i-heroicons-cloud

Vertex AI Provider

::alert{type="info"} 本页属于进阶连接配置。若你已能正常创作，可先跳过。 ::

使用 API Key 访问 Google Cloud Vertex AI 服务，支持模型别名映射。

概述

Vertex AI Provider 允许你：

• 使用 API Key 访问 Vertex AI 兼容端点
• 配置模型别名映射
• 多账号负载均衡
• 为每个 Key 单独配置代理

支持的模型

• Gemini 2.0 系列
• Gemini 1.5 系列
• 其他 Vertex AI 支持的模型

配置

基础配置

credential_pool:
  vertex_api_keys:
    - id: "vertex-main"
      api_key: "vk-123..."
      base_url: "https://example.com/api"
      disabled: false

完整配置

credential_pool:
  vertex_api_keys:
    - id: "vertex-main"
      api_key: "vk-123..."
      base_url: "https://example.com/api"
      proxy_url: "socks5://proxy:1080"
      models:
        - name: "gemini-2.0-flash"
          alias: "vertex-flash"
        - name: "gemini-1.5-pro"
          alias: "vertex-pro"
      disabled: false

配置项说明

配置项	类型	必填	说明
id	string	✅	凭证唯一标识
api_key	string	✅	Vertex AI API Key
base_url	string	❌	Vertex AI 端点 URL
proxy_url	string	❌	单独的代理 URL
models	array	❌	模型别名映射列表
disabled	boolean	❌	是否禁用此凭证

模型别名

工作原理

模型别名允许你使用自定义名称访问上游模型：

1. 客户端请求别名（如 vertex-flash）
2. Lime 将别名解析为上游模型名（如 gemini-2.0-flash）
3. 使用上游模型名发送请求
4. 响应中保留客户端请求的别名

配置示例

models:
  - name: "gemini-2.0-flash"      # 上游模型名
    alias: "vertex-flash"          # 客户端使用的别名
  - name: "gemini-1.5-pro"
    alias: "vertex-pro"
  - name: "gemini-2.0-flash-lite"
    alias: "vertex-lite"

使用场景

1. 简化模型名称：使用简短易记的别名
2. 版本管理：通过别名切换模型版本
3. 兼容性：保持客户端代码不变，后端切换模型

API Key 认证

Vertex AI Provider 使用 x-goog-api-key 头进行认证：

x-goog-api-key: your-api-key

Lime 会自动将配置的 API Key 添加到请求头中。

负载均衡

配置多个凭证

credential_pool:
  vertex_api_keys:
    - id: "vertex-1"
      api_key: "vk-123..."
      base_url: "https://endpoint1.example.com/api"
    - id: "vertex-2"
      api_key: "vk-456..."
      base_url: "https://endpoint2.example.com/api"

工作原理

1. 使用 Round-Robin 在凭证之间分配请求
2. 如果某个凭证失败，自动尝试下一个
3. 配额超限时自动切换到其他凭证

使用示例

使用上游模型名

curl http://127.0.0.1:8999/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

使用模型别名

curl http://127.0.0.1:8999/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vertex-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

路由配置

将 Vertex 模型路由到 Vertex AI Provider：

routing:
  rules:
    - pattern: "vertex-*"
      provider: "vertex"
      priority: 1

与 Gemini API Key 的区别

特性	Vertex AI	Gemini API Key
认证方式	x-goog-api-key	API Key
模型别名	✅	❌
模型排除	❌	✅
自定义 Base URL	✅	✅
适用场景	Vertex 兼容端点	官方 Gemini API

故障排除

API Key 无效

1. 确认 Key 格式正确
2. 检查 Key 是否已被撤销
3. 确认 Base URL 正确

模型不可用

1. 检查模型名称或别名是否正确
2. 确认端点支持该模型
3. 检查别名映射配置

连接失败

1. 检查 Base URL 是否可访问
2. 确认代理配置正确
3. 检查网络连接