Google Vertex AI 上游

本指南将说明如何将 AISIX AI 网关路由到 Google Vertex AI。调用方可以通过网关的 OpenAI 兼容 API 访问托管在 Vertex 上的 Gemini 和合作伙伴模型。

该配置适用于希望使用 AISIX 认证、模型允许列表、限流和用量核算的 Vertex 托管模型。AISIX 通过 GCP OAuth2 bearer token 向 Vertex 认证，并可以基于服务账号密钥签发该 token。

准备工作

请先准备以下内容：

一个 Admin API 位于 :3001、代理 API 位于 :3000 的网关。
网关 config.yaml 中的 Admin Key。
目标 GCP 项目中已启用 Vertex AI API。
Vertex 区域，例如 us-central1，以及一个可调用目标模型的服务账号。
GCP 项目 ID、Vertex 模型 ID、面向调用方的别名，以及可选代理或私有端点主机。

配置 Vertex 上游

创建 Vertex 服务提供方密钥、模型别名和调用方 API Key。服务提供方密钥存储 GCP 项目、区域和凭证模式；模型选择 Vertex 发布方模型 ID。

创建 Vertex 服务提供方密钥

使用 GCP 凭证设置创建 Vertex 服务提供方密钥：

export AISIX_ADMIN_KEY="admin-local-only-change-me"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "vertex-prod",
    "provider": "google-vertex",
    "adapter": "vertex",
    "secret": "{\"project\":\"my-gcp-project\",\"region\":\"us-central1\",\"service_account_json\":{\"type\":\"service_account\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\nYOUR_SERVICE_ACCOUNT_PRIVATE_KEY\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"vertex-sa@my-gcp-project.iam.gserviceaccount.com\",\"token_uri\":\"https://oauth2.googleapis.com/token\"}}"
  }'

服务提供方密钥 secret 的处理方式遵循服务提供方凭证中说明的凭证处理行为。

❶ provider 用于标记上游。

❷ adapter 选择 Vertex。

❸ secret 是包含 project、region 和且仅一个凭证模式的 JSON 字符串。示例在 secret 中使用嵌套对象 service_account_json。除非覆盖 api_base，区域会决定 <region>-aiplatform.googleapis.com 主机。

除非你已经自行管理短期 GCP access token，否则建议使用 service_account_json。如果使用 access_token，需要自行负责刷新。

保存返回的服务提供方密钥 ID，后续创建模型资源时使用。

创建模型

将面向调用方的别名映射到 Vertex 模型 ID：

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gemini-prod",
    "provider": "google-vertex",
    "model_name": "gemini-2.5-flash",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

❶ provider 使用与服务提供方密钥相同的标签。

❷ model_name 是 Vertex 发布方模型 ID。

❸ provider_key_id 将模型关联到 Vertex 凭证。

其它受支持示例包括 Vertex 上的 Claude，以及 Llama、Mistral、AI21 等 OpenAI 兼容合作伙伴模型。

AISIX 会根据 model_name 选择 Vertex 路由：

模型 ID 族	AISIX 发送到 Vertex 的方式
Gemini 模型，例如 `gemini-*`	使用 Google Gemini 发布方路由。
Claude 模型，例如 `claude-*`	使用 Anthropic 发布方路由，并携带 Anthropic Messages body。
OpenAI 兼容 MaaS 模型，例如 Llama、DeepSeek、Qwen、GPT-OSS、MiniMax、Moonshot 或 Z.ai	使用 Vertex 的 OpenAI 兼容 chat completions 路由。
Mistral 和 AI21 模型	使用合作伙伴发布方路由，并携带 OpenAI 兼容 body。

创建调用方 API Key

选择应用发送给 AISIX 的明文调用方 API Key，然后为 Admin 资源计算哈希：

export AISIX_API_KEY="sk-vertex-caller"

CALLER_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

创建可访问 Vertex 模型别名的 API Key 资源：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${CALLER_KEY_HASH}"'",
    "allowed_models": ["gemini-prod"]
  }'

❶ allowed_models 必须与已创建的模型别名匹配。

验证上游

通过 AISIX 代理发送 chat completions 请求。示例使用 Gemini，它要求至少包含一轮 user 或 assistant 对话。

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-prod",
    "messages": [
      {"role": "user", "content": "Say hello from Vertex."}
    ]
  }'

网关会返回带有面向调用方别名的 OpenAI 兼容响应：

{
  "object": "chat.completion",
  "model": "gemini-prod",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello from Vertex!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 4,
    "total_tokens": 8
  }
}

请在 Vertex 日志、指标、配额用量或服务提供方侧请求记录中检查测试请求。如果 AISIX 返回 token 签发或上游认证错误，请检查服务账号密钥、区域、Vertex API 启用状态、IAM 角色和模型访问权限。

行为与限制

发布方选择基于前缀。如果 model_name 不匹配受支持前缀，网关会在发送服务提供方请求前拒绝请求，并返回不支持发布方的配置错误。

示例使用 Gemini，因为它是主要的 Google 发布方路径。对于合作伙伴模型，请在向调用方暴露别名前，在 Vertex 项目中验证精确模型 ID、配额和区域可用性。

服务提供方密钥的请求和响应覆盖项可以应用在 Vertex 路由上，但最直接的用途仍在 OpenAI 兼容路由中。Gemini 原生 contents 格式并不匹配所有 OpenAI 风格覆盖目标。

下一步

你已经将 Google Vertex AI 配置为上游服务提供方协议族。对于其它 Vertex 托管模型，可以按相同模式替换项目、区域、凭证、模型 ID 和面向调用方的别名。

准备工作​

配置 Vertex 上游​

创建 Vertex 服务提供方密钥​

创建模型​

创建调用方 API Key​

验证上游​

行为与限制​

下一步​