GDC 氣隙隔離的 AI Gateway 參考架構

問題說明

在氣隙環境中執行大型語言模型的機構，會快速累積模型端點：在 Google Distributed Cloud (GDC) 氣隙環境中提供的每個開放權重模型 (請參閱 GDC 氣隙環境中的開放權重模型)，都會公開自己的 Kubernetes Service、自己的位址、自己的憑證和自己的作業生命週期。應用程式和代理程式開發人員最終會陷入架構孤島，為每個模型硬式編碼一個端點，並在每次模型疊代時重新編寫整合項目。這種分散式架構會產生技術債，並減緩多步驟代理工作負載的部署速度，而這些工作負載對任務至關重要。

標準網路層也「無法辨識 AI」：傳統負載平衡器會將推論流量視為一般 HTTP，無法讀取要求的 model 欄位、優先處理對延遲時間敏感的工作負載、以權杖而非要求為單位計算，或將要求導向已持有相關 KV 快取的模型伺服器副本。在高成本的氣隙 GPU 叢集中，這會導致硬體使用率不足，投資報酬率不佳。Gemini on GDC 提供代管的尖端模型，但如果客戶將這些模型與自行代管的開放權重模型結合使用，就需要推論層，以提供類似雲端的靈活度，同時確保資料主權：任何要求、提示或模型權重都不得離開 GDC 邊界。

解決方案提案

本文說明 GDC 氣隙環境中，自我管理的 AI 閘道參考架構：安全集中的推論層，可為應用程式提供適用於所有模型和路徑的單一 OpenAI 相容端點，並將每項要求轉送至正確的後端。參考實作項目是以 Kubernetes Gateway API 為基礎建構而成：Envoy Gateway 是 Gateway API 實作項目 (控制層和 Envoy 代理程式資料層)，而 Envoy Agent Router (舊稱 Envoy AI Gateway) 則透過 AI 專屬要求處理功能加以擴充，包括從要求主體擷取模型、要求和回應翻譯、上游驗證、權杖會計，以及權杖式速率限制 (選用)。Gateway API 推論擴充功能會新增可感知模型伺服器的端點選取項目 (InferencePool 和端點挑選器)，以便有效運用 GPU 容量。所有構件都會在 GDC 機構的 Harbor 登錄檔中暫存，且整個堆疊會在標準叢集中執行，不需任何外部連線。

涵蓋內容：這項架構涵蓋在標準叢集中部署 Envoy Gateway 和 Envoy Agent Router、Gateway API 資源 (GatewayClass、Gateway) 和 Envoy Agent Router 資源 (AIGatewayRoute、AIServiceBackend、BackendSecurityPolicy、GatewayConfig)，這些資源會公開與 OpenAI 相容的統一端點、根據 model 欄位進行主體式路由、Gateway API 推論擴充功能 (InferencePool、InferenceObjective、Endpoint Picker) 以進行模型感知負載平衡、使用 Redis 進行選用權杖式速率限制、在閘道終止 TLS、網路政策 (NetworkPolicy/ProjectNetworkPolicy) 和 Harbor 中的氣隙式構件管理。閘道後方的模型服務後端 (Ollama、vLLM) 會透過隨附指南集「在 GDC 氣隙環境中提供開放權重模型」部署。

不包含的內容：這項架構不涵蓋受管理的 AI 閘道產品、模型本身的部署和調整 (配套指南集)、模型微調、非大型語言模型的生成式 AI 模式、代理程式到工具的流量 (MCPRoute) 或商業支援的閘道發布。GDC 上的 Gemini 是代管的產品功能，不在佈建範圍內。本指南集版本會使用自行代管的開放權重模型驗證閘道。

目標對象：這份文件的主要目標對象包括平台管理員，負責在標準叢集中部署及運作閘道，以及在與外界隔絕的環境中設計 AI 平台的技術架構師。使用統一端點的應用程式開發人員是次要目標對象，瞭解要求如何轉送對他們有益。

架構

解決方案完全在 GDC 氣隙式機構的標準叢集中執行。在服務層中，Kubernetes Gateway API 會將設定模型標準化；AI 閘道控制層 (Envoy 閘道控制器和 Envoy 代理程式路由器控制器) 會讀取 Gateway API 和 Envoy 代理程式路由器資源，並設定資料層：Envoy 代理程式 Deployment 是要求進入點 (透過 LoadBalancer 類型的 Service 公開)，而 Envoy 代理程式路由器外部處理器會在代理程式 Pod 中以 Sidecar 形式執行，並執行 AI 專屬邏輯。在應用程式層，客戶工作負載 (應用程式和代理程式) 會將 AI 要求傳送至 Proxy (1)，Proxy 會將要求交給外部處理器，後者會擷取模型名稱、翻譯要求並記錄權杖用量 (2)，Proxy 會將平衡的流量轉送至所選模型的推論 Pod (3)，模型則會在基礎架構層的 GPU 節點上執行 (4)。提供模型後端會附加至閘道，做為 AIServiceBackend (任何與 OpenAI 相容的 Service) 或 InferencePool，後者的端點挑選器會根據要求選取最佳副本。容器映像檔和 Helm 資訊套件會從 Harbor 擷取。

GDC 實體隔離方案的 AI Gateway 參考架構。

解決方案元件

這項解決方案使用下列元件：

解決方案元件 責任 資料流程 介面
Kubernetes Gateway API 標準、以角色為導向的資源模型，適用於進入和路由：GatewayClass (平台擁有)、Gateway (接聽程式、TLS) 和路由資源 (應用程式團隊擁有)。Ingress API 的後繼版本，不含廠商專屬註解。 僅限宣告式設定；控制器會監控資源，且不會傳輸任何要求流量。 Kubernetes API (gateway.networking.k8s.io/v1)；CRD 是從 Envoy Gateway CRD 圖表安裝。
Envoy Gateway 控制器 (控制層) 實作 Gateway API：為每個 Gateway 提供一個 Envoy Proxy Deployment 和 LoadBalancer Service，將路徑和政策 (BackendTrafficPolicy、SecurityPolicy、EnvoyExtensionPolicy、Backend、EnvoyProxy) 轉換為 xDS 設定，在設定時執行全域速率限制服務，並透過擴充功能管理員呼叫 Envoy Agent Router 擴充功能伺服器，以便將 InferencePool 後端新增至翻譯。 監控 Kubernetes API，並將 xDS 設定推送至 Proxy，不會有要求流量。 Kubernetes API (監控)、xDS gRPC (適用於 Proxy)、gRPC (適用於擴充功能伺服器，通訊埠 1063)。
Envoy 代理程式路由器控制器 (控制層) 將 aigateway.envoyproxy.io/v1beta1 資源、AIGatewayRoute (擷取模型名稱的路由規則)、AIServiceBackend (具有 API 架構的後端)、BackendSecurityPolicy (上游憑證) 和 GatewayConfig (每個 Gateway 的外部處理器設定) 協調至 Envoy Gateway 資源，將外部處理器 Sidecar 插入 Envoy Proxy Pod，並提供 Envoy Gateway 使用的擴充功能伺服器。 僅限設定。 Kubernetes API、gRPC 擴充功能伺服器 (通訊埠 1063)、用於加入邊車容器的變異准入 Webhook。
Envoy Proxy (資料層) 要求進入點：終止 TLS、比對監聽器和路徑、在後端端點之間進行負載平衡、強制執行速率限制和逾時、重試並回復至替代後端，以及發出存取記錄和指標。 在 LoadBalancer VIP (80/443) 上接收用戶端要求，針對每項 AI 要求諮詢外部處理器，將要求轉送至所選後端端點 (Endpoint Picker 選擇的 Service 或 Pod)，並將回應串流回用戶端。 對用戶端使用 HTTP/HTTPS (相容於 OpenAI 的 API)、對 Sidecar 和端點選擇器使用 ext_proc gRPC、對後端使用 HTTP，以及對速率限制服務使用 gRPC。
Envoy 代理程式路由器外部處理器 (ExtProc) 剖析與 OpenAI 相容的要求主體、將 model 欄位擷取至路由標頭 x-ai-eg-model、套用模型名稱覆寫、在用戶端 API 架構和後端 API 架構之間轉換要求和回應酬載、插入 BackendSecurityPolicy 定義的上游憑證，以及從回應中擷取權杖用量 (輸入、輸出、總計)，並將其做為動態中繼資料，用於頻率限制和指標。 Envoy Proxy 中的邊車容器 Pod：處理要求和回應主體，包括串流回應。 Envoy ext_proc gRPC；Prometheus 指標端點。
Gateway API 推論擴充功能 (InferencePool + 端點選擇器) InferencePool (inference.networking.k8s.io/v1) 會將一個模型伺服器部署 (標籤選取器、目標通訊埠，例如 8000) 的 Pod 分組，並參照其端點挑選器 (EPP)。InferenceObjective (v1alpha2) 會為每個模型或目標指派優先順序。EPP 會擷取模型伺服器指標 (要求佇列深度、KV 快取使用率、載入的 LoRA 轉換器)，並為每個要求選取端點。 Proxy 會使用要求標頭呼叫 EPP (ext_proc，連接埠 9002)；EPP 會回覆要使用的端點；Proxy 會將要求轉送至該 Pod。 Kubernetes API (CRD)、gRPC ext_proc (9002)、Prometheus 擷取模型伺服器。
Redis (選用) Envoy 速率限制服務的後端儲存空間：所有 Proxy 副本的共用計數器，適用於以要求為準和以權杖為準的限制。只有在設定全域速率限制時才需要。 頻率限制服務會讀取並遞增每個受限要求的連接埠 6379 計數器。 Redis 通訊協定 (6379)。部署在叢集中的 Redis 8.10，或現有的 Redis 執行個體。
模型服務後端 (Ollama / vLLM) 在閘道後方提供開放權重模型；部署時請使用「在 GDC 實體隔離方案上部署開放權重模型」隨附指南。以 AIServiceBackend (任何與 OpenAI 相容的 Service，例如 Ollama) 或 InferencePool (模型伺服器，例如 vLLM，會公開端點選擇器評估的指標) 的形式附加。 接收來自 Proxy 的已路由要求，在 GPU 節點上執行推論 (或在 CPU 上執行小型模型的功能評估)，並傳回與 OpenAI 相容的回覆。 相容於 OpenAI 的 REST API：通訊埠 8000 上的 vLLM、通訊埠 11434 上的 Ollama；端點挑選器的 Prometheus 指標 (vLLM)。
Harbor 儲存解決方案的容器映像檔 (Envoy Proxy、Envoy Gateway、Envoy Agent Router 控制器和外部處理器、速率限制服務、端點選擇器、Redis) 和 Helm 圖表 (OCI 構件)。 從可存取網際網路的工作站，使用 seed_registry.sh (crane) 將構件從公開登錄檔複製到 Harbor；叢集會透過映像檔提取密鑰和機器人帳戶提取映像檔，並使用 helm template 從 Harbor 算繪圖表。 OCI 發布 API、Harbor UI 和機器人帳戶。
標準叢集和 GPU 節點 主機所有閘道元件 (CPU 節點就足夠)，以及推論 Pods (GPU 節點，其中包含從節點探索到的加速器資源)。提供 LoadBalancer VIP、模型權重的永久儲存空間，以及網路政策強制執行功能。 基礎平台；要求會透過 Gateway 的 LoadBalancer VIP 進入，並留在叢集網路內。 Kubernetes API、GDC 網路 API (networking.gdc.goog/v1 ProjectNetworkPolicy)、GDC 控制台和 gdcloud (適用於平台管理員)。

特點與功能

這項參考架構提供下列核心功能：

  • 與 OpenAI 相容的統一端點：應用程式會為閘道後方服務的每個模型呼叫一個位址 (/v1/chat/completions、/v1/models 等)。
    • 元件： Gateway、AIGatewayRoute、Envoy Proxy、外部處理器。
    • 職責：公開穩定的虛擬 IP、終止 TLS、接受與 OpenAI 相容的要求格式，並視需要將其轉換為後端結構定義。
    • 介面：HTTPS REST (JSON，包括用於串流的伺服器傳送事件)。
  • 以主體為依據的路由 (模型感知)：閘道會讀取要求主體的 model 欄位，並將要求轉送至相符的後端，不需任何用戶端端點邏輯。
    • 元件：外部處理器、AIGatewayRoute 規則比對 (x-ai-eg-model、AIServiceBackend、InferencePool)。
    • 職責：擷取模型名稱、比對路徑規則、重新命名模型 (modelNameOverride)、依權重分配流量，以及依優先順序回溯至替代後端。
    • 介面：Kubernetes API (aigateway.envoyproxy.io/v1beta1)。
  • 模型伺服器感知的負載平衡：系統會將 InferencePool 的要求傳送至佇列最短且 KV 快取最實用的副本，而非以循環方式傳送。
    • 元件：Gateway API 推論擴充功能 (InferencePool、InferenceObjective、端點挑選器)。
    • 職責：擷取模型伺服器指標、評估端點 (佇列深度、KV 快取使用率、前置字元快取親和性、LoRA 配接器)，並在負載下遵守各目標的優先順序。
    • 介面：Kubernetes API (inference.networking.k8s.io/v1、inference.networking.x-k8s.io/v1alpha2)、ext_proc gRPC (9002)。
  • 上游驗證和安全政策：閘道會注入需要憑證的後端，且絕不會將憑證發布至應用程式。
    • 元件： BackendSecurityPolicy、Envoy Gateway SecurityPolicy、TLS 監聽器。
    • 職責：將 API 金鑰注入後端、在 Gateway 終止用戶端 TLS、視需要強制執行用戶端驗證和授權政策。
    • 介面：政策參照的 Kubernetes Secret。
  • 以權杖為準的頻率限制 (選用)：用量是以權杖為單位計算，而不只是要求。
    • 元件：外部處理器 (llmRequestCosts)、Envoy Gateway BackendTrafficPolicy (全域速率限制)、速率限制服務、Redis。
    • 職責：從每個回應中擷取輸入、輸出和總詞元數，將這些詞元數附加為要求費用，並在所有 Proxy 副本中，強制執行每個消費者或每個模型的預算。
    • 介面：Kubernetes API、Redis (6379)。
  • 流量管理：標準 Gateway API 功能適用於 AI 流量。
    • 元件： Gateway、HTTPRoute、AIGatewayRoute、 BackendTrafficPolicy。
    • 職責：根據主機、路徑和標頭進行比對、適合長時間生成的逾時、重試、加權流量分配，以及後端之間的優先順序型備援。
    • 介面：Kubernetes API。
  • 可觀測性：所有模型都提供要求、延遲時間和權杖指標。
    • 元件：Envoy 代理程式存取記錄和統計資料、外部處理器指標 (權杖用量、要求時間長度、第一個權杖的時間)、端點選擇器指標。
    • 責任：公開 Prometheus 格式的指標和結構化存取記錄，供 GDC 可觀測性堆疊或客戶管理的 Prometheus 抓取。
    • 介面：Prometheus 指標端點、標準輸出記錄。
  • 氣隙構件管理：所有映像檔和圖表都會在安裝前暫存在 Harbor 中。
    • 元件：Harbor、seed_registry.sh、機器人帳戶、映像檔提取密鑰、EnvoyProxy 資源 (Proxy 映像檔和提取密鑰)。
    • 職責：從連線的工作站植入映像檔和 OCI Helm 資訊套件、固定版本，以及使用 helm template 離線算繪資訊套件。
    • 介面：OCI Distribution API、Kubernetes API。

架構原則

  • 標準優先：閘道是透過 Kubernetes Gateway API 及其推論擴充功能設定，並向應用程式傳送與 OpenAI 相容的 API，因此應用程式、路徑和後端在閘道實作項目之間保持可攜性。
  • 安全至上：所有元件和資料都位於 GDC 氣隙邊界內。TLS 會在 Gateway 終止，閘道會注入後端憑證，並透過 NetworkPolicy 和 ProjectNetworkPolicy 物件限制網路存取權。
  • 資料主權：提示、回覆、模型權重和使用資料絕不會離開客戶的 GDC 機構；運作時不需要外部連線。
  • 關注點分離：以角色為導向的 Gateway API 可讓平台管理員擁有 GatewayClass、Gateway、TLS 和網路政策，而應用程式團隊則可在自己的命名空間中擁有 AIGatewayRoute、AIServiceBackend 和 InferencePool 資源。
  • 控制和資料平面分離：控制器只會轉譯設定；要求路徑包含 Envoy 代理程式、其外部處理器 Sidecar 和端點選擇器，如果控制器重新啟動，這些項目會繼續提供流量。
  • 開放且彈性：架構全面採用開放原始碼軟體 (Envoy Gateway、Envoy Agent Router、Gateway API Inference Extension、Ollama、vLLM)，且替代實作項目可提供相同的 Gateway API 資源。
  • 擴充性和效能：資料平面可透過新增 Proxy 副本進行水平擴充，並透過調整 CPU 和記憶體進行垂直擴充；模型伺服器感知負載平衡可讓 GPU 保持飽和，不會造成個別副本過載。
  • 簡化使用者體驗：每個模型都只有一個端點、一種 API 格式和一組憑證，可縮短從模型部署到使用的路徑。
  • 復原能力：Kubernetes 健康狀態檢查和複製、Envoy 重試，以及後端之間的優先順序式備援，可在個別模型副本失敗時，確保端點可用。

注意事項

  • 擴充性和效能：
    • 閘道元件是僅限 CPU 的工作負載；Gateway 的 Envoy Proxy Deployment 會透過增加副本數量 (EnvoyProxy 資源) 進行水平擴充，並透過提高 CPU 和記憶體要求進行垂直擴充。外部處理器檢查主體時，CPU 費用會與要求和回應大小成正比；串流回應則會以遞增方式處理。
    • 模型伺服器感知負載平衡僅適用於以 InferencePool 形式附加的後端；以 AIServiceBackend 形式附加的後端會由 Proxy 在 Service 的端點之間進行負載平衡。
    • 閘道不會增加 GPU 容量：處理量和延遲時間受模型伺服器限制。使用隨附的指南集 (vLLM 適用於高處理量、Ollama 適用於易用性，以及僅限 CPU 的評估)，調整模型部署大小。
    • 與一般 HTTP API 相比，長時間生成內容需要較長的請求和閒置逾時時間，請在路徑和政策中設定這些時間，而非在用戶端中設定。
  • 資源管理：
    • 所有閘道元件都會在 CPU 節點上執行，不需要加速器；下表提供功能部署的指標大小。參考實作會設定確切的要求和限制；實際值取決於要求比率和酬載大小。
    • 下方的連接埠表格列出網路政策必須允許的所有連接埠。
    • GPU 規劃屬於模型部署作業：系統會從節點探索加速器資源名稱，如配套指南集所述。

閘道元件的指標大小 (僅限 CPU)

元件 備用資源 CPU (要求) 記憶體 (要求) 附註
Envoy Gateway 控制器 1 100 公尺至 500 公尺 256MiB 至 1GiB 控制層；不在要求路徑中
Envoy Agent Router 控制器 1 100 公尺至 500 公尺 256Mi 至 512Mi 控制層和擴充功能伺服器
Envoy Proxy Pod (Proxy + 外部處理器 Sidecar) 每 Gateway 1 到 2 次 500m–2 512Mi–2Gi 根據要求比率和酬載大小調整規模
端點挑選器 每 InferencePool 1 個 100 公尺至 500 公尺 256Mi 至 512Mi 擷取模型伺服器指標
速率限制服務 (選用) 1 100 公尺至 500 公尺 256Mi 至 512Mi 僅限全域速率限制
Redis (選用) 1 100 公尺至 500 公尺 256MiB 至 1GiB 僅限全域速率限制

網路通訊埠

通訊埠 元件 目的
80 / 443 Envoy Proxy (Gateway 監聽器) LoadBalancer VIP 上的 HTTP / HTTPS 進入點
1063 Envoy Agent Router 控制器 (擴充功能伺服器) 來自 Envoy Gateway 擴充功能管理工具的 gRPC 呼叫
9002 端點挑選器 Envoy Proxy 的 ext_proc gRPC 呼叫
6379 Redis 頻率限制計數器
8000 vLLM 與 OpenAI 相容的 API 和模型伺服器指標
11434 Ollama Ollama 和模型伺服器的 OpenAI 相容 API
  • 可用性和穩定性：
    • Proxy 和外部處理器會在同一個 Pod 中執行；LoadBalancer 後方的多個副本會遮蓋個別 Pod 失敗，且控制器可以重新啟動，不會中斷流量。Service
    • AIGatewayRoute 規則可以列出多個後端，並設定優先順序，這樣一來，當後端不正常時，閘道就會改用其他副本集或模型伺服器。
    • 端點挑選器是每個集區的 Deployment；如果無法使用，對該 InferencePool 的要求就會失敗，直到恢復運作為止。使用資源要求和就緒探查執行，並像監控資料平面元件一樣監控。
    • Redis 只會保留速率限制計數器；Redis 服務中斷會影響速率限制，但不會影響路由。
  • 作業複雜度：
    • Envoy Gateway、Envoy Agent Router 和 Gateway API Inference Extension 之間的版本對齊：將這三者一併升級至經過測試的組合 (Envoy Gateway 1.8.4、Envoy Agent Router 1.1.0、Gateway API Inference Extension 1.5.0)。
    • 與外部網路隔離的生命週期：每次升級時，所有映像檔和圖表都會重新植入 Harbor；EnvoyProxy 資源和圖表值會釘選登錄檔和提取密鑰。
    • 兩個設定層級：平台擁有的 GatewayClass / Gateway/EnvoyProxy 和團隊擁有的 AIGatewayRoute / AIServiceBackend/InferencePool；導入新模型時，需要新增路由規則和後端，而不是新的閘道。
    • 監控：要求比率、延遲時間 (包括第一個詞元的時間)、每個模型和每個消費者的詞元用量、端點選擇器評分，以及模型伺服器的 GPU 使用率。
    • InferenceObjective 仍為 Alpha 版 API (v1alpha2)，因此在 Inference Extension 的各個版本之間，架構可能會有所變更。
  • 安全性和法規遵循：
    • 整個解決方案都在 GDC 的安全防護範圍內運作，與外界完全隔絕。
    • 網路政策為必要條件：命名空間 NetworkPolicy 允許從 Proxy 到模型伺服器連接埠 (8000、11434) 和端點挑選器 (9002) 的流量，且 ProjectNetworkPolicy 允許用戶端流量到 LoadBalancer VIP (如果消費者位於專案外部)。
    • TLS 會在 Gateway 終止，憑證則儲存在 Kubernetes Secret 中；用戶端只會看到閘道端點。
    • 上游憑證 (例如模型伺服器所需的 API 金鑰) 會儲存在 Secret 中，並由閘道參照 BackendSecurityPolicy 插入，因此應用程式絕不會持有後端憑證。
    • 以權杖為準的速率限制會根據消費者或模型，限制耗用昂貴的 GPU 容量。
    • Harbor 機器人帳戶和 Kubernetes 映像檔提取密鑰可確保容器映像檔的存取安全；以角色為導向的 Gateway API RBAC 可區分平台和應用程式職責。

設計決策

這項參考架構已做出下列重要設計決策：

決策 1：AI 閘道實作：Envoy 上的開放原始碼 Envoy 代理路由器，以及替代發布版本

背景資訊 重要決策 理由
AI 閘道是主要架構選項，另有可行的替代方案，包括自行管理的開放原始碼選項，以及商業支援的產品：(a) Envoy Gateway 上的 Envoy Agent Router (開放原始碼)；(b) kgateway 和 agentgateway (開放原始碼 Gateway API 實作項目，可處理 LLM 供應商流量、MCP 工具和代理與代理之間的通訊，並可選擇是否使用 solo.io 的供應商支援服務)；(c) Solo Enterprise for agentgateway，做為商業支援的進階選項。 參考實作項目會使用 Envoy Gateway 上的開放原始碼 Envoy 代理路由器。這些替代方案仍是相同 Gateway API 資源的有效選擇；建議在需要專屬供應商支援的正式版環境中，使用商業支援的發行版本。 開源優勢：輕量化且符合標準、高效能 L7 路由，無授權費，非常適合在採用付費方案前評估解決方案；Envoy 代理程式路由器是本指南集驗證的選項。開放原始碼的缺點：解決方案團隊和社群會盡力提供支援，但可能無法滿足核心生產環境的需求。進階優勢：閘道生命週期的企業支援協議，以及通常具備的進階代理功能。進階版缺點：需要付費授權或支援協議，以及額外的供應商關係。

決策 2：使用 Kubernetes Gateway API 和推論擴充功能，還是 Ingress 或專屬的 Gateway API

背景資訊 重要決策 理由
您可以透過舊版 Ingress API、閘道專屬設定格式或 Kubernetes Gateway API 公開推論端點。模型感知負載平衡還需要方法來描述模型伺服器集區及其優先順序。 這項解決方案會以 Envoy Gateway 實作的 Kubernetes Gateway API (GatewayClass、Gateway、路徑) 為標準，並以 Gateway API Inference Extension (InferencePool、InferenceObjective、端點挑選器) 進行模型感知路徑。 Gateway API 是 Kubernetes 標準，可取代 Ingress，以角色為導向 (平台與應用程式團隊)，且可跨實作項目移植。Inference Extension 是模型伺服器感知型轉送 (佇列深度、KV 快取、優先順序) 的社群標準，Envoy Agent Router 預設支援這項標準；替代的閘道發布項目會實作相同的 API，因此 Decision 1 仍可還原。

決策 3：在相容於 OpenAI 的要求中，以 model 欄位為依據，將要求轉送至統一端點

背景資訊 重要決策 理由
應用程式可透過每個模型 (以主機或路徑為準) 的一個端點、用戶端設定的自訂標頭，或每個與 OpenAI 相容的要求已攜帶的 model 欄位，來處理模型。 閘道會公開一個與 OpenAI 相容的端點，並在 model 欄位中轉送：外部處理器會將其擷取至 x-ai-eg-model 標頭，而 AIGatewayRoute 規則會與該標頭相符。 現有的 OpenAI 相容用戶端和 SDK 運作方式不變，只要變更一個字串即可切換模型；端點、憑證和模型位置可以變更，不必修改應用程式；相同的規則可將模型名稱對應至多個後端，用於流量分割、備援或模型名稱覆寫。

決策 4：將構件以氣隙隔離方式植入 Harbor，還是視需求提取

背景資訊 重要決策 理由
上游安裝作業會視需要從公開登錄檔和 Helm 資訊套件提取容器映像檔做為 OCI 構件，這在無網路連線的環境中是不可能的。 所有容器映像檔 (Envoy Proxy、Envoy Gateway、Envoy Agent Router 控制器和外部處理器、速率限制服務、端點選擇器、Redis) 和 Envoy Gateway 與 Envoy Agent Router Helm 圖表都會植入含有 seed_registry.sh (crane) 的 Harbor 專案，圖表會透過 Harbor 以 helm template 離線算繪，而 EnvoyProxy 資源和圖表值會釘選 Harbor 登錄檔和提取密鑰。 每個版本都有一個可重複執行的稽核播種步驟；叢集永遠不需要外部連線；版本固定可明確升級及還原。

決策 5：使用 Redis 進行選用的權杖式速率限制，而非僅限於要求式限制

背景資訊 重要決策 理由
GPU 容量是依權杖而非要求消耗；要求數量上限無法保護共用模型，避免幾個非常大的提示或長時間生成內容。Envoy Gateway 中的全域速率限制需要共用的計數器儲存空間。 以權杖為準的速率限制是架構的選用功能：外部處理器會記錄每個要求的輸入、輸出和權杖總數 (llmRequestCosts)，BackendTrafficPolicy 會強制執行預算，而 Redis 執行個體 (在叢集或現有執行個體中部署的 Redis 8.10) 會儲存計數器。沒有頻率限制的部署作業不需要 Redis。 用量會以反映費用的單位計算，所有 Proxy 副本都會強制執行預算，且只有需要配額的客戶才需支付依附元件費用。

決策 6：拓撲：標準叢集的專屬命名空間中的閘道控制和資料層，應用程式命名空間中的模型

背景資訊 重要決策 理由
閘道可在專屬叢集、每個應用程式命名空間中執行，或在模型旁邊的每個標準叢集中執行一次。在 GDC 氣隙環境中，開放權重模型會部署在標準叢集 (隨附指南集)。 Envoy Gateway 和 Envoy Agent Router 控制層，以及 Envoy Proxy 資料層，會在主機模型的標準叢集專屬命名空間中執行；AIGatewayRoute、AIServiceBackend、InferencePool 和模型部署作業則位於應用程式命名空間，並在各個命名空間中參照。 要求會留在叢集網路中，介於 Proxy 和模型 Pod 之間 (延遲時間最短，沒有額外的負載平衡器)，平台管理員擁有閘道命名空間，應用程式團隊則擁有自己的路徑和模型，端點選擇器可以直接擷取模型伺服器。轉送至中央伺服器閘道的專案專屬用戶端閘道，仍是多專案耗用量的這個拓撲延伸項目。

假設和限制

  • GDC air-gapped 1.16.2-hf1 以上環境適用於執行 Kubernetes v1.32.13-gke.400 以上版本的標準叢集。
  • 模型服務後端有足夠的硬體資源 (尤其是 GPU)，閘道元件本身則在 CPU 節點上執行。實際模型需要 GPU；Ollama 上的小型模型只能在 CPU 上執行，用於功能評估。
  • Harbor 執行個體已設定完畢並可存取，且工作站可連上網際網路，並連線至 GDC 環境 (Harbor 和 Kubernetes API)，可供植入映像檔和圖表。
  • 使用者具備必要權限：專案角色 Harbor 執行個體檢視者和標準叢集管理員，以及叢集範圍安裝 (CRD、GatewayClass、命名空間) 的標準叢集 StandardClusterRoleBindingcluster-admin 角色，請參閱參考實作。
  • 提供模型的後端會公開與 OpenAI 相容的 API；以 InferencePool 形式附加的後端也會公開與 vLLM 相容的指標，而端點選擇器會依據這些指標運作。
  • 限制：解決方案團隊會盡力支援開放原始碼元件 (Envoy Gateway、Envoy Agent Router、Gateway API Inference Extension)；如需專屬供應商支援服務，請使用商業支援發行版本 (決策 1)。
  • 限制： InferenceObjective 是 Alpha 版 API (inference.networking.x-k8s.io/v1alpha2)，在 Inference Extension 的各個版本之間可能會有所變更。
  • 限制：專案外部的消費者需要 Gateway 的 LoadBalancer VIP 和 ProjectNetworkPolicy；專案內部叢集中的用戶端或 kubectl port-forward 則可直接連線至閘道 Service。
  • 限制：這項解決方案的目前版本不支援 GDC 上的 Gemini、模型微調、非 LLM 的生成式 AI 模型，以及多節點模型服務。

使用者流程

以下是 GDC air-gapped 上 AI 閘道的完整使用者流程：首先是應用程式開發人員依賴的要求路徑，然後是平台管理員遵循的設定路徑。

1. 開發人員要求路徑

應用程式或代理程式只需要閘道端點、用戶端憑證 (如果閘道強制執行) 和模型名稱。

  • 傳送要求：應用程式會對閘道端點呼叫 POST /v1/chat/completions，並使用與 OpenAI 相容的 JSON 主體命名模型 (例如 "model": "gemma")，就像呼叫任何與 OpenAI 相容的服務一樣。
  • 進入閘道：要求會抵達 LoadBalancer 的 VIP Gateway；Envoy Proxy 會終止 TLS，並比對接聽器和路徑。
  • 處理主體：Proxy 會將要求交給 Envoy 代理程式路由器外部處理器，該處理器會剖析主體、將模型名稱擷取至 x-ai-eg-model 標頭，並在酬載與後端結構定義不同時進行翻譯。
  • 選取後端：與模型名稱相符的 AIGatewayRoute 規則會選取 AIServiceBackend (例如 Ollama Service) 或 InferencePool (例如 vLLM 副本集)；如果是 InferencePool，端點選擇器會選擇佇列最短且 KV 快取比對最佳的副本。
  • 轉送及回應：當 BackendSecurityPolicy 適用時，Proxy 會注入上游憑證、將要求轉送至所選 Pod、將回應串流回傳，並允許外部處理器記錄權杖用量，以提供指標，以及在設定時提供權杖用量限制。
  • 切換模型：如要使用其他模型，開發人員只要變更 model 字串即可，不需要新的端點、憑證或用戶端程式庫。

2. 平台管理員設定路徑

  • 將構件植入 Harbor：建立 Harbor 機器人帳戶，然後從可存取網際網路的工作站，使用 seed_registry.sh 將容器映像檔、Envoy Gateway 和 Envoy Agent Router Helm 圖表複製到 Harbor。
  • 安裝 Envoy Gateway：使用 helm template 從 Harbor 算繪 CRD 和控制器圖表，並在閘道命名空間中套用；建立 EnvoyProxy 資源，釘選 Proxy 映像檔和提取密鑰，並使用基本 GatewayClass、Gateway 和 HTTPRoute 驗證控制器。
  • 安裝 Envoy Agent Router：安裝 Envoy Agent Router CRD 和 Gateway API Inference Extension CRD，部署 Envoy Agent Router 控制器，重新設定 Envoy Gateway 以呼叫其擴充功能伺服器 (連接埠 1063)，並接受 InferencePool 後端；視需要部署 Redis 並啟用全域速率限制服務。
  • 公開閘道：建立 GatewayClass 和 Gateway，並使用 HTTP 和 HTTPS 接聽程式 (TLS 憑證 Secret)，等待 LoadBalancer VIP，然後為專案外部的消費者套用 ProjectNetworkPolicy。
  • 附加模型：使用隨附指南設定部署模型服務後端，然後為與 OpenAI 相容的 AIServiceBackend 和與 vLLM 相容的副本集建立 Service 和 InferencePool，以及命名空間 NetworkPolicy 物件。
  • 發布路徑：為每個模型名稱建立 AIGatewayRoute (以主體為準的轉送)，並視需要為上游憑證和權杖預算建立 BackendSecurityPolicy 和 BackendTrafficPolicy 物件。
  • 驗證及運作：透過 VIP (或 kubectl port-forward 後備機制) 呼叫 /v1/models 和 /v1/chat/completions，檢查 Proxy、外部處理器和端點選擇器指標，並將端點和模型名稱交給應用程式團隊。獨立擴充 Proxy 副本和模型部署作業；一併升級 Envoy Gateway、Envoy Agent Router 和 Inference Extension。

如需詳細步驟，請參閱 Envoy 代理路由器參考實作和 Envoy 代理路由器使用者指南：以主體為依據的路由。

其他資料