API Gateway：通過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)

方式二：使用 Base 64 編碼圖片

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)

方式二：使用 Base 64 編碼視頻

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 Gateway。

• 確認目的地區域的網路連通性。