Google Vertex AI

Google Vertex AI 是 Google Cloud 面向 Gemini 和合作伙伴模型的托管平台。AISIX 为应用提供统一的兼容 OpenAI API，以调用这些由 Vertex 托管的模型。

此配置适用于需要使用 AISIX 认证、模型允许列表、速率限制和用量核算的 Vertex 托管模型。AISIX 使用 GCP OAuth2 Bearer Token 向 Vertex 认证，并可从服务账号密钥签发该 Token。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 已在目标 GCP 项目中启用 Vertex AI API。
• 目标模型支持的 Vertex 位置，以及可调用该模型的服务账号。当前 Gemini 示例使用 global。
• GCP 项目 ID 和 Vertex 模型 ID。
• curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不带斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

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

创建 Vertex 服务提供方密钥

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

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "vertex-prod",
    "provider": "google-vertex",
    "api_base": "https://aiplatform.googleapis.com",
    "config": {
      "project": "my-gcp-project",
      "region": "global",
      "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"
      }
    },
    "allowed_environments": ["'"$ENV_ID"'"]
  }' | jq -r '.provider_key.id')

❶ provider 选择 Google Vertex 目录条目，该条目通过 Vertex 协议适配器路由流量。

❷ AISIX Cloud 要求为此平台服务提供方设置 api_base。对于 global 位置，请使用 https://aiplatform.googleapis.com；https://global-aiplatform.googleapis.com 并非全局端点。对于区域位置，请使用与 config.region 匹配的 https://<region>-aiplatform.googleapis.com。代理或私有端点可以替代任一 Origin。

❸ config 是结构化凭证，包含 project、region，且必须恰好包含一种凭证模式。示例使用嵌套对象形式的 service_account_json。通过 config 提供凭证时，请省略 api_key；此服务提供方会拒绝非空的 api_key。

除非你已经自行管理短期 GCP 访问 Token，否则请使用 service_account_json。AISIX 会签名 JWT、签发并缓存 OAuth Token，并在到期前刷新。如果使用 access_token，你需要负责刷新它。当前适配器不会发现应用默认凭证、元数据服务器凭证或工作负载身份联合凭证。

服务提供方密钥中的机密信息遵循服务提供方密钥中介绍的凭证处理行为。

该命令保存返回的服务提供方密钥 ID，以供模型资源使用。allowed_environments 允许该环境引用此密钥。

创建模型

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

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gemini-prod",
    "model_name": "gemini-3.6-flash",
    "provider_key_id": "'"$PROVIDER_KEY_ID"'"
  }' | jq -r '.model.id')

❶ model_name 是 Vertex 发布方模型 ID。当前示例 Gemini 3.6 Flash 已在 global 正式发布。Google 说明该模型会忽略自定义 temperature、top-P 和 top-K 值，因此通过 AISIX 调用时请省略 temperature 和 top_p。请求还必须以用户消息结尾。Google 会拒绝最后一轮角色为 model 的 GenerateContent 请求，而 AISIX 会将最后一条 OpenAI assistant 消息映射为该角色。

❷ provider_key_id 将模型关联到上一步保存的 Vertex 凭证。

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

AISIX 根据 model_name 选择 Vertex 路由：

模型 ID 系列	AISIX 如何将其发送到 Vertex
Gemini 模型，例如 gemini-*	使用 Google Gemini 发布方路由。
Claude 模型，例如 claude-*	使用 Anthropic 发布方路由，并采用 Anthropic Messages 请求体。
兼容 OpenAI 的 MaaS 模型，例如 Llama、DeepSeek、Qwen、GPT-OSS、MiniMax、Moonshot 或 Z.ai	使用 Vertex 兼容 OpenAI 的 chat-completions 路由。
Mistral 和 AI21 模型	使用合作伙伴发布方路由，并采用兼容 OpenAI 的请求体。

创建调用方 API Key

创建可访问 Vertex 支持的模型别名的 API Key 资源。服务器会生成密钥，并仅返回一次明文：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "vertex-caller",
    "allowed_models": ["'"$MODEL_ID"'"]
  }' | jq -r '.plaintext')

allowed_models 通过 ID 引用模型，因此调用方只能使用 Vertex 支持的别名。请安全存储明文密钥；读取端点不会再次返回它。

使用开源 AISIX 网关配置

对于开源网关，请设置 adapter: vertex，并将项目、区域和凭证模式放入服务提供方密钥的 api_key 值中。以下示例从环境变量读取结构化凭证：

export VERTEX_CREDENTIAL='{"project":"my-gcp-project","region":"global","service_account_json":{"type":"service_account","private_key":"YOUR_PRIVATE_KEY","client_email":"vertex-sa@my-gcp-project.iam.gserviceaccount.com","token_uri":"https://oauth2.googleapis.com/token"}}'

在声明式资源文件中使用导出的凭证：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: vertex-prod
    provider: google-vertex
    adapter: vertex
    api_key: ${VERTEX_CREDENTIAL}
    api_base: https://aiplatform.googleapis.com

models:
  - display_name: gemini-prod
    provider: google-vertex
    model_name: gemini-3.6-flash
    provider_key: vertex-prod

api_keys:
  - display_name: vertex-caller
    key_env: VERTEX_CALLER_KEY
    allowed_models:
      - gemini-prod

凭证必须包含 project、region，以及 access_token 或 service_account_json 中的恰好一个。对于其他 Vertex 发布方，请使用上文介绍的相同 model_name 值。

对于区域 OSS 配置，可以省略 api_base，AISIX 会推导 https://<region>-aiplatform.googleapis.com。当 region: global 时请显式设置它，因为正确的 Origin 是 https://aiplatform.googleapis.com；使用代理或私有端点时也应显式设置。

导出调用方密钥：

export VERTEX_CALLER_KEY="YOUR_CALLER_API_KEY"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两个命令中使用 -e 传入它引用的每个环境变量。资源加载后，为通用验证请求设置 AISIX_API_KEY：

export AISIX_API_KEY="$VERTEX_CALLER_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 chat-completions 请求。示例使用 Gemini，它要求至少包含一条用户或助手消息。

curl -sS -X POST "$AISIX_PROXY/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 角色和模型访问权限。

端点和内容支持

Vertex AI 提供的能力多于当前 AISIX vertex 适配器能够转换的范围。网关行为同时取决于调用方路由和 model_name 所选择的发布方系列。

路由	使用 google-vertex 服务提供方密钥时的行为
/v1/chat/completions	支持，包括流式传输。当前 Gemini 发布方转换仅支持文本；合作伙伴发布方的行为取决于其协议。
/v1/embeddings	支持 Google 发布方的文本嵌入模型，例如 gemini-embedding-001。AISIX 将文本输入发送到 publishers/google/models/<model>:predict；不支持合作伙伴和多模态嵌入格式。使用 gemini-embedding-001 时，每个请求只发送一个输入字符串。AISIX 会将输入数组作为一个上游请求转发，但该模型只接受一个输入，包含多项的数组可能被拒绝。
/v1/responses	通过基于 Chat 的 Responses 桥接支持，并非原生 Vertex Responses 端点。没有 Chat 等价项的字段会被忽略。
/v1/messages	通过转换为 Chat 支持。因为配置的服务提供方是 google-vertex，即使使用 Vertex 托管的 Claude 模型，也无法使用 /v1/messages/count_tokens。
/v1/completions	Vertex 适配器不支持。
/v1/images/generations、/v1/audio/*、/v1/videos 和 /v1/rerank	Vertex 适配器或这些路由的服务提供方规则不支持，即使 Vertex 另有原生媒体服务。
/v1/files、/v1/batches 和 /v1/fine_tuning/jobs	不支持，因为 AISIX 作业接口不接受 vertex 适配器。
/passthrough/google-vertex/*	不能作为调用原生 Vertex API 的变通方案。透传会绕过适配器，因此既不会从服务账号 JSON 签发 OAuth Token，也不会从结构化凭证提取访问 Token。

对于 Gemini 发布方模型，AISIX 当前会序列化文本部分、系统指令和基本生成设置。它不会序列化图片、音频或视频部分、函数声明和工具结果、Gemini 特定的思考控制或思维签名。工具消息会被简化为用户文本，非文本响应部分不会返回。

不要将当前 Vertex 适配器用于 Gemini 函数调用循环。Gemini 3 要求应用在工具使用期间重放思维签名，但此适配器既不返回也不接受这些签名。通过 Responses 或 Messages 桥接访问 Gemini 时同样存在此限制。

AISIX 会将 Vertex 汇总 Token 总数映射到规范化响应，但不会单独公开 Vertex 的详细思考 Token 或缓存内容 Token 计数。需要这些明细时，请使用 Vertex 账单和监控。

Vertex 发布方路由

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

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

一个服务提供方密钥只对应一个项目和位置。如果合作伙伴模型仅在其他位置可用，请创建另一个服务提供方密钥；更改 model_name 不会改变 Vertex 资源路径使用的位置。

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

后续步骤

现在，你已将 AISIX 连接到 Google Vertex AI，并验证了模型别名。接下来可阅读以下指南：

• Gemini（Google AI Studio）：使用 AI Studio API Key 而不是 Google Cloud 项目来配置 Gemini。
• 模型别名：为别名配置路由、重试行为或成本元数据。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。