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，且不含尾部斜杠
# 本地私有化部署快速入门使用 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：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 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 端点。text.format 会转换为聊天的 response_format，并按 Gemini 上的结构化输出传达给模型。其他没有 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 计数映射到规范化响应，而不只是它们的总和。思考 Token（thoughtsTokenCount）按 Vertex 的计费口径计入 completion_tokens，并在 completion_tokens_details.reasoning_tokens 中单独标明。上下文缓存命中（cachedContentTokenCount）仍是 prompt_tokens 的子集，在 prompt_tokens_details.cached_tokens 中报告。

以上是 Chat Completions 的字段名。同样的数值到达 Responses 调用方时叫 output_tokens_details.reasoning_tokens 和 input_tokens_details.cached_tokens；Anthropic Messages 调用方看到的缓存命中是 cache_read_input_tokens，且没有单独的 reasoning 计数器——该协议本身没有这一概念。

Gemini 上的结构化输出

携带 JSON schema 的 response_format——直接发送到 /v1/chat/completions，或由 Responses 的 text.format、Anthropic Messages 的 output_config.format 转换而来——会变成 generationConfig.responseMimeType: "application/json"，外加 schema 本身，写入该模型这一代读取 schema 的那个字段：

• Gemini 2 及更新的版本：generationConfig.responseJsonSchema，标准 JSON Schema，按调用方书写的原样转发。
• Gemini 1.x：generationConfig.responseSchema，即较早的 OpenAPI 风格方言。类型名会转为大写（OBJECT、STRING）；该方言没有对应成员的字段会被移除，其中包括 additionalProperties，因为 Gemini 会按名称拒绝它们；同时会补上显式的 propertyOrdering，让模型输出的成员顺序固定下来，而不是未定义。exclusiveMinimum、exclusiveMaximum、multipleOf 和 uniqueItems 会改写进属性的 description 而不是被悄悄丢弃，oneOf 改写为 anyOf，内部 $ref 会被内联展开，因为该方言没有 $ref。minimum、maxLength、pattern 等数值和字符串边界属于该方言，予以保留。

AISIX 从模型名读取代次，并兼容 models/<id> 写法。无法读出代次的模型名（例如 gemini-exp-1206）回退到 responseSchema，这是每一代都接受的字段。

{"type": "json_object"} 只设置 MIME 类型；{"type": "text"} 不发送任何内容。这条路径上没有工具兜底，也没有提示词注入——Gemini 转换不发送任何工具，因而没有可强制的对象，无法约束解码的模型会像原来一样作答。两种方言中的 required 都是调用方自己的表述，AISIX 从不改写。

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。
• 模型别名：为别名配置路由、重试行为或成本元数据。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。