跳到主要内容
版本：3.10.x

将 AI 流量路由到 Gemini Enterprise Agent Platform

Gemini Enterprise Agent Platform 是此前文档中称为 Vertex AI 的 Google Cloud 模型平台的现用名称。它通过 Google Cloud 身份认证和区域端点提供 Gemini 及合作伙伴模型。本指南介绍如何使用 ai-proxy 插件，通过 API7 网关路由 Agent Platform 流量。已发布的服务提供方标识符仍为 vertex-ai。

前置条件​

  • 安装 Docker。

  • 安装 cURL，用于发送请求并验证服务。

  • 安装 jq，用于将服务账户 JSON 压缩为适合 Shell 使用的格式。

  • 拥有一个正在运行的 API7 网关实例。

  • 拥有一个已启用结算功能及 Agent Platform API 的 Google Cloud 项目。

  • 从控制台获取 Token，并将其保存到环境变量：

    export API_KEY=your-dashboard-token   # 请替换为你的控制台 Token

  • 将 {gateway_group_id} 替换为网关组 ID。如果正在按照快速入门操作，请使用 default。

  • 如果使用 Admin API 示例，请在 API7 网关中创建或复用一个服务。如果尚无服务，请按照创建或复用服务操作，然后将其 ID 保存到环境变量：

    export SERVICE_ID=your-service-id         # 请替换为你的服务 ID

配置 GCP 身份认证​

创建服务账户，为其授予 Agent Platform User（roles/aiplatform.user）角色，并创建 JSON 服务账户密钥。API7 网关需要使用下载的密钥，因为它不会自动发现应用默认凭证（Application Default Credentials）或 Workload Identity Federation 凭证。

将服务账户 JSON 作为压缩后的单行 JSON 字符串保存到环境变量：

export GCP_SERVICE_ACCOUNT_JSON="$(jq -c . /path/to/service-account.json)"

jq -c 参数会让 JSON 保持在一行内，避免在 Admin API 或 ADC 示例中复用变量时出现 Shell 引号问题。网关会根据服务账户凭证自动生成并缓存 OAuth 2.0 Token。

为 Agent Platform 配置 AI 代理​

创建一个启用 ai-proxy 插件的路由：

curl -k "https://localhost:7443/apisix/admin/routes/vertex-ai-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "name": "vertex-ai-route",
    "service_id": "$SERVICE_ID",
    "paths": ["/vertex-ai"],
    "plugins": {
      "ai-proxy": {
        "provider": "vertex-ai",
        "override": {
          "endpoint": "https://aiplatform.googleapis.com/v1beta1/projects/<GCP_PROJECT_ID>/locations/global/endpoints/openapi/chat/completions"
        },
        "auth": {
          "gcp": {
            "service_account_json": "$GCP_SERVICE_ACCOUNT_JSON"
          }
        },
        "options": {
          "model": "google/gemini-3.5-flash"
        }
      }
    }
  }
EOF

❶ 将服务提供方设置为 vertex-ai，并使用文档指定的全局 Chat Completions URL 覆盖其端点。将 <GCP_PROJECT_ID> 替换为你的项目 ID。

❷ 提供 GCP 服务账户 JSON。网关会自动生成并缓存 OAuth 2.0 Token。

❸ 设置一个在全局端点上支持 Chat Completions 的 Agent Platform 模型。示例使用 google/gemini-3.5-flash，该模型在 global 区域支持默认的 Standard PayGo 消费模式。

此处显式指定全局端点，是因为已发布的 vertex-ai 驱动程序会根据 provider_conf.region 推导区域主机名。

验证配置​

发送聊天补全请求：

curl "http://127.0.0.1:9080/vertex-ai" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a mathematician." },
      { "role": "user", "content": "What is 1+1?" }
    ]
  }'

你应收到类似以下内容的响应：

{
  "object": "chat.completion",
  "model": "google/gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1 + 1 = 2\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 11,
    "completion_tokens": 8,
    "total_tokens": 19
  }
}

要启用流式响应，请在请求体中设置 "stream": true。使用 proxy-buffering 插件禁用 NGINX proxy_buffering，避免服务器发送事件（SSE）被缓冲。

后续步骤​

你已将 API7 网关连接到 Gemini Enterprise Agent Platform。有关支持的模型和请求字段，请参阅 Agent Platform 模型目录和 OpenAI 兼容的 Chat Completions 文档。