模型路徑總覽

API Gateway 的模型路徑是受管理的流量管理層，可接受與 OpenAI 相容的提示要求、在傳輸期間轉碼，並將要求傳送至特定 Vertex AI 模型。模型路徑可做為用戶端 Proxy (例如 LiteLLM) 的受管理替代方案，提供集中式基礎架構，管理 AI 代理的生命週期。

模型路徑會將路徑邏輯移至網路邊緣，並與 Vertex AI Model Garden 整合，以進行相同主機的最佳化。這個架構可免除代管、擴充及維護非受管理 Proxy 伺服器的需求，進而降低營運費用和基礎架構成本。

範圍和使用者歷程

模型路由支援下列核心使用者歷程：

  • 模型選取：AI 開發人員在 Vertex AI Model Garden 中使用模型即服務 (MaaS) 的開放式模型。包括 Gemini、Anthropic Claude 或 OpenAI GPT 系列模型。
  • 規格撰寫：AI 開發人員在 OpenAPI 3.x 規格中建立或更新模型路由器設定，以參照已部署的模型。
  • 閘道部署：AI 開發人員使用撰寫的 OpenAPI 規格，部署 API 設定和 API Gateway 執行個體。
  • 提示路徑：用戶端應用程式會將與 OpenAI 相容的提示要求傳送至閘道，閘道會根據 JSON 酬載中指定的模型名稱，轉送要求並翻譯酬載。

API Gateway 後續版本預計支援更多使用者歷程。

模型路徑的好處

在 API Gateway 中實作模型路徑具有下列優點：

  • 集中式管理：將 AI 流量管理作業整合至單一受管理閘道，取代分散的用戶端轉送設定。
  • 降低營運負擔：免除部署獨立 Proxy 伺服器相關的基礎架構成本和維護負擔。
  • 邊緣最佳化效能：檢查提示並在網路邊緣路徑傳輸流量，直接整合 Vertex AI Model Garden 端點。
  • 標準化用戶端介面：讓用戶端應用程式與相容於 OpenAI 的統一 REST 介面互動，同時將要求動態調度至各種基礎模型。

角色和應用情境

模型路徑可滿足下列角色需求：

  • 平台工程師：提供代管基礎架構解決方案，取代企業 AI 部署作業的用戶端路由邏輯。
  • AI 開發人員：公開標準化 API 端點，根據要求酬載參數，在不同基礎模型 (例如 Gemini Pro、Gemini Flash 或 Anthropic Claude) 之間動態路由傳送要求。
  • 控管管理員：強制執行集中式存取政策 (例如驗證和配額)，並監控整個機構的整體 AI 流量。

支援應用實例

在公開搶先版期間，模型路徑支援完全根據 OpenAI 相容用戶端要求 JSON 酬載中指定的模型標記或名稱 (例如 "model": "gemini-3.5-flash-lite") 進行路徑設定。

架構和要求流程

模型路由會在 API Gateway 資料層中做為代管路由層運作。當用戶端應用程式將與 OpenAI 相容的提示要求傳送至閘道時，會發生下列事件：

  1. 要求攔截：閘道會攔截傳入的 POST 要求 (例如 POST /chat/completions)。
  2. 檢查酬載：模型路由器會檢查傳入 JSON 酬載中的 model 屬性 (例如 {"model": "claude-opus-4-7", "messages": [...]})。
  3. 規則評估：路由器會根據 OpenAPI 規格中定義的轉送規則，比對 model 字串。如果沒有符合的規則，路由器會選取設定的預設模型。
  4. 轉送期間轉碼：閘道會將相容於 OpenAI 的要求轉碼為目標 Vertex AI 預測結構定義。
  5. 後端調度：閘道會將轉碼要求調度至指定的 Vertex AI Model Garden 端點，並將模型回應傳回給用戶端。

效能和限制

導入模型路徑之前，請先詳閱下列技術限制：

  • 主機限制：模型路徑僅支援將路徑導向 Vertex AI Model Garden 上預先部署的 MaaS 模型，其中單一路徑參照的所有模型共用相同的主機名稱 (例如全域端點 aiplatform.googleapis.com 或單一區域端點，如 us-central1-aiplatform.googleapis.com)。
  • 規格需求：模型路徑需要 OpenAPI 3.x 規格，以及對應的 API Gateway OpenAPI 3.x 擴充功能。不支援 OpenAPI 2.0 (Swagger) 規格。
  • 閘道更新：您無法更新未啟用模型路徑的現有閘道，也無法更新已啟用模型路徑的閘道來停用或移除模型路徑。如要切換路由模式，必須建立並部署新的 API 設定和閘道執行個體。
  • 混合設定：OpenAPI 規格不得同時包含模型轉送和非模型轉送作業。規格中的所有作業都必須使用模型轉送或標準閘道轉送。
  • VPC Service Controls：模型路由閘道不支援 VPC Service Controls。啟用模型路徑的 API Gateway 執行個體無法使用 VPC Service Controls perimeter。
  • 串流和不支援的通訊協定：模型路徑支援回應串流 (伺服器傳送的事件)，但不支援要求端串流、gRPC、WebSockets 或 Gemini Live。
  • 支援的模態：在公開預先發布期間，模型路徑會假設文字提示要求格式為與 OpenAI 相容的 JSON 酬載，並完全根據酬載中的 model 標記或名稱來決定路徑。
  • 必要酬載欄位：傳入的 JSON 要求酬載必須包含 model 屬性。在公開測試期間，如果用戶端要求酬載中缺少 model 欄位，閘道會錯誤地處理要求，而不是拒絕要求並傳回錯誤。請務必確保用戶端要求在 JSON 酬載中指定 model 欄位。
  • 執行階段限制：標準閘道主機基礎架構服務限制和行為適用於模型路徑端點：
    • 逾時時間上限：閘道會強制執行 3,600 秒 (1 小時) 的要求逾時時間上限，適用於長時間執行的串流要求。
    • 冷啟動延遲：如果閘道執行個體在閒置期間縮減為零，初始要求可能會發生冷啟動延遲，進而影響對延遲時間敏感的 AI 推論路徑。
    • 保留的網址路徑：您無法使用保留的網址路徑，例如 /eventlog、以 /_ah/ 開頭的路徑，或以 z 結尾的特定路徑 (為避免衝突，請勿使用以 z 結尾的路徑名稱)。
    • 網址字元解碼：閘道會在處理要求前，自動解碼要求網址中的特定編碼字元 (例如，%41 會解碼為 A)。

後續步驟