API 网关：通过AI网关接入Vertex AI

1. 准备 GCP Service Account

在开始配置之前，您需要在 Google Cloud Console 中创建 Service Account 并下载 JSON 密钥文件。

1. 登录 Google Cloud Console。

2. 在左侧导航栏，选择 IAM 和管理 > 服务账号。

3. 单击 创建服务账号，填写服务账号名称和描述。

4. 为服务账号分配 Vertex AI User 角色（或更高权限）。

5. 单击 KEY，选择创建，下载密钥JSON文件。

说明 密钥文件包含敏感信息，请妥善保管。JSON 文件格式示例如下：

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "your-sa@your-project.iam.gserviceaccount.com",
  "token_uri": "https://oauth2.googleapis.com/token"
}

对于 GCP Service Account 的管理，详见Google官方文档。

2. 创建 AI 服务

1. 登录 AI 网关控制台。

2. 在左侧导航栏，选择 实例，并在顶部菜单栏选择地域。

3. 在 实例 页面，单击目标 实例 ID。

4. 在左侧导航栏，单击 服务，并单击 服务 页签。

5. 单击 创建服务，在 创建服务 面板，参考如下信息配置 AI 服务：

OpenAI 协议兼容方式说明：

重要提示：

• 如果 JSON 密钥格式不正确或缺少必要字段，系统会显示相应的错误提示。

• vertexProjectId 为只读字段，前端会自动解析 JSON 密钥中的 project_id。

• 使用「Vertex AI 原生兼容端点」模式时，请求体中的 model 参数需要添加 Provider 前缀 google/。例如：原本使用 gemini-3-flash-preview 需要改为 google/gemini-3-flash-preview。

关于「Vertex AI 原生兼容端点」模式支持的参数及模型，详见Google官方文档。

3. 创建 Model API

1. 登录 AI 网关控制台。

2. 在左侧导航栏，选择 实例，并在顶部菜单栏选择地域。

3. 在 实例 页面，单击目标 实例 ID。

4. 在左侧导航栏，单击 Model API，然后单击 创建 Model API。

5. 在 创建 Model API 面板中，配置基本信息如下：

   • 域名：建议配置自定义域名（使用默认环境域名存在限流）。

   • Base Path：API 的基本路径，如 /gemini。

   • 模型类型：选择 文本生成。

   • 协议：选择 OpenAI 兼容。

   • 路由配置：需要勾选 /v1/chat/completions 路由。

   • AI 请求观测：开启。

   • 服务模型：单模型服务。

   • 服务列表：

     • 服务名称：选择上一步中配置的 Vertex AI 服务。

     • 模型名称：选择透传，或指定具体模型如 gemini-2.0-flash。

6. 单击 确定 完成创建。

4. 调试 Model API

1. 单击目标 Model API 操作 列下的 调试 按钮进行测试。

2. 在 调试 控制面板中，模型名称 输入 Gemini 系列模型（如 gemini-3-flash-preview），在右侧 模型返回 页签下与大模型进行对话。

重要 在模型返回页签下，使用的是 /v1/chat/completions 对话接口，如需使用其他接口，您可选择 CURL 命令 或 原始输出 的方式通过 curl、SDK 调试。

CURL 调用示例：

curl -X POST "http://your-gateway-domain/gemini/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "stream": false
  }'

1. 获取 Vertex AI Express Mode API Key

获取API-KEY的方式请参考文档 Vertex AI in express mode。

说明 Express Mode API Key 可能有使用限制，详情请参考 Google 官方文档。

2. 创建 AI 服务

1. 登录 AI 网关控制台。

2. 在左侧导航栏，选择 实例，并在顶部菜单栏选择地域。

3. 在 实例 页面，单击目标 实例 ID。

4. 在左侧导航栏，单击 服务，并单击 服务 页签。

5. 单击 创建服务，在 创建服务 面板，参考如下信息配置 AI 服务：

说明 Express Mode 配置方式与其他大模型供应商（如 OpenAI、Claude）类似，只需填写 API Key 即可。

3. 创建 Model API

1. 在左侧导航栏，单击 Model API，然后单击 创建 Model API。

2. 在 创建 Model API 面板中，配置基本信息如下：

   • 域名：建议配置自定义域名（使用默认环境域名存在限流）。

   • Base Path：API 的基本路径，如 /gemini。

   • 模型类型：选择 文本生成。

   • 协议：选择 OpenAI 兼容。

   • 路由配置：需要勾选 /v1/chat/completions 路由。

   • AI 请求观测：开启。

   • 服务模型：单模型服务。

   • 服务列表：

     • 服务名称：选择上一步中配置的 Vertex AI Express 服务。

     • 模型名称：选择透传。

3. 单击 确定 完成创建。

4. 调试 Model API

1. 单击目标 Model API 操作 列下的 调试 按钮进行测试。

2. 在 调试 控制面板中，选择 Gemini 模型进行对话测试。

适用场景

• 使用 Imagen 4 等图片生成模型

• 使用 Veo 3 等视频生成模型

• 使用通过 Vertex AI Model Garden 托管的第三方模型

• 需要直接调用 Vertex AI 原生 REST API 的场景

1. 创建 AI 服务

创建 AI 服务的步骤与场景一或场景二类似，关键差异如下：

1. 登录 AI 网关控制台。

2. 在左侧导航栏，选择 实例，并在顶部菜单栏选择地域。

3. 在 实例 页面，单击目标 实例 ID。

4. 在左侧导航栏，单击 服务，并单击 服务 页签。

5. 单击 创建服务，在 创建服务 面板，参考如下信息配置 AI 服务：

重要提示：

• 模型协议必须选择「原生协议」，表示使用 Vertex AI 原生 REST API 格式。

• 选择「原生协议」后，将不会显示「OpenAI 协议兼容方式」选项，因为此模式不进行协议转换。

2. 创建 Model API

1. 在左侧导航栏，单击 Model API，然后单击 创建 Model API。

2. 在 创建 Model API 面板中，配置基本信息如下：

   • 域名：建议配置自定义域名（使用默认环境域名存在限流）。

   • Base Path：API 的基本路径，如 /vertex-api。

   • 使用场景：根据您的需求选择（此处仅是控制台的分类辅助，混用也不会有问题）：

     • 文本生成：适用于 Llama 等文本模型

     • 图片生成：适用于 Imagen 4 等图片生成模型

     • 视频生成：适用于 Veo 3 等视频生成模型

   • 协议：选择 VertexAI。

   • 路由配置：选择 VertexAI 协议后，网关会自动配置以下两条内置路由：

     路由路径	用途
     /{api-version}/publishers/{publisher}/models/{model}:{action}	Express Mode 使用的路径格式
     /{api-version}/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:{action}	Service Account 模式使用的路径格式

   • 服务模型：单模型服务。

   • 服务列表：

     • 服务名称：选择上一步中创建的 AI 服务（如 vertex-rest-api）。

     • 模型名称：选择透传。

3. 单击 确定 完成创建。

3. 调用示例

配置完成后，您可以使用 Vertex AI 原生 REST API 格式进行调用。

使用 Imagen 4 生成图片（Express Mode）：

curl -X POST "https://your-gateway-domain/vertex-api/v1/publishers/google/models/imagen-4.0-generate-preview-06-06:predict" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "instances": [
      {
        "prompt": "一只可爱的橘猫在阳光下打盹"
      }
    ],
    "parameters": {
      "sampleCount": 1,
      "aspectRatio": "1:1"
    }
  }'

使用 Veo 3 生成视频（Express Mode）：

curl -X POST "https://your-gateway-domain/vertex-api/v1/publishers/google/models/veo-3.0-generate-preview:predictLongRunning" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "instances": [
      {
        "prompt": "一只橘猫在草地上奔跑的慢动作视频"
      }
    ],
    "parameters": {
      "aspectRatio": "16:9",
      "durationSeconds": 8
    }
  }'

支持的模型

说明 具体支持的模型列表请参考 Google官方文档。

1. 创建 DNS 服务

由于 SDK 自行完成鉴权，您需要创建一个 DNS 类型的服务直接指向 Vertex AI 后端。

1. 登录 AI 网关控制台。

2. 在左侧导航栏，选择 实例，并在顶部菜单栏选择地域。

3. 在 实例 页面，单击目标 实例 ID。

4. 在左侧导航栏，单击 服务，并单击 服务 页签。

5. 单击 创建服务，在 创建服务 面板，参考如下信息配置 DNS 服务：

说明

• 使用全局端点 aiplatform.googleapis.com:443 适用于 Express Mode。

• 使用区域端点 {location}-aiplatform.googleapis.com:443 适用于 Service Account 模式，需根据您的 GCP 项目所在区域填写。

2. 创建 Model API

1. 在左侧导航栏，单击 Model API，然后单击 创建 Model API。

2. 在 创建 Model API 面板中，配置基本信息如下：

   • 域名：建议配置自定义域名（使用默认环境域名存在限流）。

   • Base Path：API 的基本路径（可选），如 /vertex。

   • 模型类型：选择 文本生成 或 图片生成。

   • 协议：选择 VertexAI。

   • 路由配置：选择 VertexAI 协议后，网关会自动配置以下两条内置路由：

     | 路由路径 | 用途 |

     |------------------------------------------------------------------------------------------------|---------|

     | /{api-version}/publishers/{publisher}/models/{model}:{action} | Express Mode 使用的路径格式 |

     | /{api-version}/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:{action} | Service Account 模式使用的路径格式 |

   • 服务模型：单模型服务。

   • 服务列表：

     • 服务名称：选择上一步中创建的 DNS 服务（如 vertex-dns）。

     • 模型名称：选择透传。

3. 单击 确定 完成创建。

3. 配置 GenAI SDK

在您的 Python 代码中，将 GenAI SDK 的 base_url 指向 AI 网关地址：

from google import genai

# 配置 API Key（Express Mode）或使用默认凭证（Service Account）
API_KEY = "your-api-key"

# 网关地址 = 域名 + Base Path（如果配置了的话）
# 示例：如果域名为 your-gateway-domain.com，Base Path 为 /vertex
base_url = "https://your-gateway-domain.com/vertex"

# 创建客户端，将请求代理到 AI 网关
client = genai.Client(
    vertexai=True,  # 目前仅支持 vertexai=True
    api_key=API_KEY,
    http_options={
        'base_url': base_url,
    },
)

# 调用模型
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="你好，请介绍一下你自己",
)

print(response.text)

配置说明：

使用 Service Account 模式：

如果使用 Service Account 进行认证，可以通过环境变量配置凭证：

# 设置 Service Account 密钥文件路径
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

from google import genai

# Service Account 模式下无需设置 api_key
base_url = "https://your-gateway-domain.com/vertex"

client = genai.Client(
    vertexai=True,
    http_options={
        'base_url': base_url,
    },
)

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="你好，请介绍一下你自己",
)

print(response.text)

4. 验证接入效果

配置完成后，您可以在 AI 网关控制台查看请求的观测数据：

1. 在左侧导航栏，单击 观测分析 > 日志中心。

2. 查看通过 GenAI SDK 发起的请求记录，包括：

   • 请求路径

   • 响应状态码

   • 响应时间

   • Token 用量（如果响应中包含）

说明 由于鉴权在客户端完成，网关无法进行鉴权配置代理。如需完整的AI网关使用体验，建议使用场景一、场景二或场景三的接入方式。

配置要点

• AI 服务：选择 Vertex AI 作为大模型供应商，GCP Service Account 或 Express Mode 均可

• Model API：使用场景选择 文本生成，协议选择 OpenAI 兼容，路由需要勾选 /v1/chat/completions

图片理解

方式一：使用图片 URL

from openai import OpenAI

client = OpenAI(
    base_url="http(s)://{your-domain}/{model-api-base-path}/v1"
)

completion = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这道题怎么解答？"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://img.alicdn.com/imgextra/i1/O1CN01gDEY8M1W114Hi3XcN_!!6000000002727-0-tps-1024-406.jpg"
                    },
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)

方式二：使用 Base64 编码图片

import base64
from openai import OpenAI

client = OpenAI(
    base_url="http(s)://{your-domain}/{model-api-base-path}/v1"
)

# 将本地图片编码为 Base64
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

# 指定图片路径
image_path = "<your-image-path>"
base64_image = encode_image(image_path)

completion = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这张图片里有什么？"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{base64_image}",
                    },
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)

支持的图片格式：image/png, image/jpeg, image/webp, image/heic, image/heif

不同模型的支持能力详见Google官方文档。

视频理解

说明：由于 OpenAI 的接口规范仅定义了 image_url 类型，但这不妨碍我们传入视频内容。AI 网关会自动完成兼容性转换，将视频内容正确传递给 Vertex AI。

方式一：使用视频 URL

from openai import OpenAI

client = OpenAI(
    base_url="http(s)://{your-domain}/{model-api-base-path}/v1"
)

completion = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "简要描述视频内容"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241115/cqqkru/1.mp4"
                    },
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)

方式二：使用 Base64 编码视频

import base64
from openai import OpenAI

client = OpenAI(
    base_url="http(s)://{your-domain}/{model-api-base-path}/v1"
)

# 将本地视频编码为 Base64
def encode_video(video_path):
    with open(video_path, "rb") as video_file:
        return base64.b64encode(video_file.read()).decode("utf-8")

# 指定视频路径
video_path = "example.mp4"
base64_video = encode_video(video_path)

completion = client.chat.completions.create(
    model="gemini-3-flash-preview",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "简要描述视频内容"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:video/mp4;base64,{base64_video}",
                    },
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)

支持的视频格式：video/x-flv, video/quicktime, video/mpeg, video/mpegs, video/mpg, video/mp4, video/webm, video/wmv, video/3gpp

不同模型的支持能力详见Google官方文档。

代码说明

配置要点

与场景一或场景二类似，但有以下关键差异：

重要提示：在 GCP Service Account 模式下进行图片生成/编辑/变体时，OpenAI 协议兼容方式必须选择「AI 网关转换」。这是因为 Vertex AI 原生兼容端点目前仅支持文本对话接口（Chat Completions），而 AI 网关的协议转换支持图片相关接口的转换。

接口支持矩阵

图片生成（/v1/images/generations）

配置完成后，您可以使用 OpenAI Python SDK 调用图片生成接口：

from openai import OpenAI
from PIL import Image
from io import BytesIO
import base64

# 创建客户端，指向 AI 网关地址
client = OpenAI(
    base_url="http(s)://{your-domain}/{model-api-base-path}/v1"
)

# 调用图片生成接口
response = client.images.generate(
    model="gemini-3-pro-image-preview",  # Gemini Nano Banana Pro 模型
    prompt="一只可爱的橘猫在阳光下打盹",
    size="1024x1024",
    n=1
)

# 获取生成的图片（base64 编码）
image_data = response.data[0].b64_json
if image_data:
    # 解码并保存图片到本地
    image = Image.open(BytesIO(base64.b64decode(image_data)))
    image.save("output_folder/example-image-cat.png")
    print("图片已保存到 output_folder/example-image-cat.png")

代码说明：

尺寸参数映射：

由于 OpenAI 接口使用分辨率（如 1024x1024）而 Vertex AI 使用宽高比（aspectRatio）+ 分辨率等级（imageSize）的方式，AI 网关会自动进行参数转换。

Vertex AI 支持的宽高比：1:1、3:2、2:3、3:4、4:3、4:5、5:4、9:16、16:9、21:9

Vertex AI 支持的分辨率等级：1k、2k、4k

CURL 调用示例：

curl -X POST "https://your-gateway-domain/gemini-image/v1/images/generations" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "一只可爱的橘猫在阳光下打盹",
    "size": "1024x1024",
    "n": 1
  }'

图片编辑（/v1/images/edits）

配置完成后，您可以使用 OpenAI Python SDK 通过 multipart 方式上传原图并执行编辑：

from openai import OpenAI
from PIL import Image
from io import BytesIO
import base64

client = OpenAI(
    base_url="http(s)://{your-domain}/{model-api-base-path}/v1",
    api_key="YOUR_API_KEY"
)

# 使用文件上传方式调用 Edit 接口（OpenAI SDK 推荐方式）
with open("assets/image-cat.png", "rb") as image_file:
    response = client.images.edit(
        model="gemini-3-pro-image-preview",
        prompt="将猫的品种修改为布偶猫，保持原图姿势",
        image=image_file,
        size="1024x1024",
        n=1
    )

image_data = response.data[0].b64_json
if image_data:
    image = Image.open(BytesIO(base64.b64decode(image_data)))
    image.save("output_folder/edited-image-cat.png")
    print("图片编辑完成，已保存到 output_folder/edited-image-cat.png")

# 1) 将本地图片转为 Base64（去掉换行）
BASE64_IMAGE=$(base64 < assets/image-cat.png | tr -d '\n')

# 2) 通过 image_url(data URL) 调用 edits 接口
curl -X POST "https://your-gateway-domain/{model-api-base-path}/v1/images/edits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "{
    \"model\": \"gemini-3-pro-image-preview\",
    \"prompt\": \"将猫的品种修改为布偶猫，保持原图姿势\",
    \"image_url\": {
      \"url\": \"data:image/png;base64,${BASE64_IMAGE}\"
    },
    \"size\": \"1024x1024\",
    \"n\": 1
  }"

图片变体（/v1/images/variations）

配置完成后，您可以使用 OpenAI Python SDK 通过 multipart 方式生成图片变体：

from openai import OpenAI
from PIL import Image
from io import BytesIO
import base64

client = OpenAI(
    base_url="http(s)://{your-domain}/{model-api-base-path}/v1",
    api_key="YOUR_API_KEY"
)

with open("assets/image-cat.png", "rb") as image_file:
    response = client.images.create_variation(
        model="gemini-3-pro-image-preview",
        image=image_file,
        size="1792x1024",
        n=1
    )

image_data = response.data[0].b64_json
if image_data:
    image = Image.open(BytesIO(base64.b64decode(image_data)))
    image.save("output_folder/variation-image-cat.png")
    print("图片变体生成完成，已保存到 output_folder/variation-image-cat.png")

如果您希望在 Variation 场景中使用 image_url（URL 或 data URL）而不是文件上传，也可以直接使用 HTTP JSON 请求：

# 1) 将本地图片转为 Base64（去掉换行）
BASE64_IMAGE=$(base64 < assets/image-cat.png | tr -d '\n')

# 2) 通过 image_url(data URL) 调用 variations 接口
curl -X POST "https://your-gateway-domain/{model-api-base-path}/v1/images/variations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "{
    \"model\": \"gemini-3-pro-image-preview\",
    \"image_url\": {
      \"url\": \"data:image/png;base64,${BASE64_IMAGE}\"
    },
    \"size\": \"1792x1024\",
    \"n\": 1
  }"

支持的图片生成模型

说明 具体支持的图片生成模型列表请参考 Google官方文档。

多供应商高可用配置

为了实现更高的可用性，您可以配置 Vertex AI 与其他供应商形成 Fallback 关系：

1. 创建多个 AI 服务（如 Vertex AI + 阿里云百炼）。

2. 创建 Model API 时，选择 多模型服务（按模型名称）。

3. 配置路由规则：

   • 服务名称：vertex-ai，模型名称匹配规则：gemini*

   • 服务名称：bailian，模型名称匹配规则：qwen*

4. 开启 Fallback，选择备用服务。

安全配置建议

1. 凭证管理：建议通过引用凭据方式将 Service Account Key 或 API Key 存储在阿里云 KMS 中，避免凭证泄露风险。

2. 访问控制：配置 IP 白名单或其他访问控制策略，限制 API 访问来源。

3. 限流保护：设置合理的限流规则，避免意外的高额费用。

401/403 鉴权失败

• 检查 Service Account JSON 密钥的完整性，确保包含 private_key、client_email、token_uri 等必要字段。

• 确认 Service Account 具有 Vertex AI User 或更高权限。

• 对于 Express Mode，确认 API Key 有效且未过期。

404 模型不存在

• 确认使用的模型名称正确，如 gemini-3-flash-preview、gemini-3-pro-preview 等。

• 检查所选区域是否支持该模型。

JSON 解析失败

• 确保粘贴的是完整的 Service Account JSON 内容，不要遗漏开头的 { 或结尾的 }。

• 检查 JSON 格式是否正确，可使用在线 JSON 验证工具进行验证。

请求超时

• 检查 VPC 是否正确配置公网 NAT 网关。

• 确认目标区域的网络连通性。