如何統一管理 OpenAI、Claude、Gemini API？LLM Gateway 最佳實踐

你遇到的症狀通常是：同一個功能要維護三套 SDK、三種錯誤格式，還要在應用程式裡直接放置多組 API Key。

最快的解法，是在業務應用與模型供應商之間建立穩定的內部 LLM Gateway 契約，統一模型別名、鑑權、逾時、重試、預算與日誌；但不要為了介面一致，抹平 OpenAI、Claude、Gemini 在工具呼叫、串流格式、錯誤語義和資料政策上的差異。

這篇文章適合三類讀者：

• 維護多模型應用的後端工程師；
• 負責企業模型接入、金鑰治理與用量控管的平台團隊；
• 準備部署高可用 LLM Gateway 的 DevOps 與架構負責人。

先盤點能力，不要急著包成同一個 API

在寫 Gateway 程式碼之前，先把目前應用真正使用的能力列出來。至少要分開記錄文字生成、結構化輸出、工具呼叫、圖片或其他多模態輸入，以及串流回應。

原因是三家 API 的互動模型並不相同。OpenAI Responses API 以事件串流傳遞回應狀態、工具呼叫與使用量；Gemini API 的串流回應則以 SSE 傳送 GenerateContentResponse；Claude 的工具流程會以 tool_use 等內容區塊表達模型意圖。若 Gateway 只保留一個簡化後的 content 欄位，工具參數、部分事件或模型狀態很容易在轉換時遺失。可先對照 OpenAI Responses API 串流事件文件、Gemini API 串流文件 與 Claude 工具使用文件。(platform.openai.com)

接入盤點時，建議為每個模型建立一份差異表：

同時記錄帳號所屬組織、部署區域、可用端點、資料處理政策，以及每家服務對逾時、限流和內容拒絕的定義。這些資訊不能由 Gateway 自己猜測，也不能只看 SDK 的共同欄位。

第一步：定義不隨供應商改名的內部契約

多個大模型 API 要使用統一介面，核心不是把三家請求格式硬翻成同一份 JSON，而是先設計一個不容易變動的內部資料模型。

請求可以包含以下欄位：

{
  "model_alias": "balanced",
  "messages": [],
  "tools": [],
  "response_schema": null,
  "stream": true,
  "tenant_id": "tenant_placeholder",
  "trace_id": "trace_placeholder",
  "extensions": {}
}

其中 model_alias 只代表你的業務意圖，不直接暴露供應商模型名稱。extensions 則用來承載特定供應商才支援的參數，例如特殊工具選擇、推理設定或多模態選項。這比把不認識的欄位靜默刪除安全，因為刪除後的請求可能仍然成功，但輸出品質已經悄悄改變。

回應契約也要區分：

• output_text：可直接顯示的文字；
• tool_calls：工具名稱、參數、呼叫 ID 與執行狀態；
• usage：輸入、輸出及快取等用量欄位；
• finish_reason：完成、拒絕、逾時或工具中止；
• provider_error：只供內部排查，不直接暴露給終端使用者。

OpenAI 的回應物件已提供輸入、輸出與總用量欄位；Gemini 錯誤回應則可能同時包含 HTTP code、狀態字串與 details。這表示 Gateway 可以做統一觀測，但不能假設每家服務的欄位含義完全相同。(platform.openai.com)

第二步：把 API Key、租戶與權限放在 Gateway 內側

LLM Gateway 應該成為唯一持有供應商密鑰的伺服器邊界。業務應用只使用內部憑據，前端、行動程式與瀏覽器都不應直接接觸 OpenAI、Claude 或 Gemini 的供應商金鑰。

API Key 管理可以按以下層次實施：

1. 供應商金鑰只存在伺服器環境變數或專用密鑰管理服務；
2. 每個環境使用不同憑據，開發、測試與正式環境不可共用；
3. 按租戶、專案或使用者建立內部權限；
4. 管理 API 與推理 API 分離，輪換金鑰的權限不可等同於送出模型請求；
5. 日誌中遮蔽 Authorization、x-goog-api-key 和任何自訂密鑰欄位；
6. 建立撤銷、輪換與失效後的回退流程。

OpenAI 官方文件明確要求 API Key 以伺服器端安全方式保存，並透過 Bearer 驗證傳送；Gemini 的入門文件則展示以 x-goog-api-key 傳遞金鑰。這些身份標頭不應直接漏到你的業務層或用戶端。(platform.openai.com)

你也要預先決定資料邊界：哪些欄位可以進入供應商 API，哪些欄位必須在 Gateway 脫敏，提示詞與回應是否允許寫入除錯日誌，以及租戶之間是否禁止共用快取。統一鑑權不代表統一資料政策。

多模型路由失敗後，什麼情況才適合自動切換？

自動切換不是「任何錯誤都換下一家」。你要先區分可重試錯誤、不可重試錯誤，以及重新送出可能造成副作用的請求。

建議先採用確定性路由：

• balanced 固定指向經過驗證的主要模型；
• low_latency 指向延遲優先的模型；
• tool_agent 只指向已通過工具呼叫測試的模型；
• vision 不回退到不支援圖片輸入的模型；
• restricted_data 只選符合資料政策與區域要求的端點。

只有在你已經掌握實際流量後，才加入負載均衡、租戶策略或成本策略。否則一開始就做動態路由，發生品質下降時很難判斷是提示詞、模型版本還是路由規則造成。

錯誤格式可以轉換成內部類型，例如：

• AUTH_FAILURE：金鑰、帳號或權限錯誤，不應盲目重試；
• INVALID_REQUEST：參數或內容不相容，應修正請求；
• RATE_LIMITED：受到限流，依供應商提示等待；
• UPSTREAM_UNAVAILABLE：供應商暫時不可用，可評估回退；
• TIMEOUT：逾時，需根據請求是否具備冪等性處理。

Gemini 官方錯誤文件列出 400、403、429、503 等常見狀態；其中 429 可能代表請求量、Token 或支出限制，503 則可能表示服務暫時無法提供容量。這些狀態不能全部套用同一個重試延遲。(ai.google.dev)

串流請求尤其要小心：如果上游已經送出部分文字，你再自動切換到另一個模型，使用者可能收到重複內容或兩段互相矛盾的回應。因此，串流開始後通常應停止透明回退，改由應用層顯示中止狀態，或重新建立一個明確標記為重試的請求。

提醒： 重試前先判斷冪等性。讀取型摘要通常比較容易安全重試；會觸發付款、寫入資料庫、發送通知或執行外部工具的請求，必須使用請求 ID、去重記錄和明確的執行狀態，不能只依賴 HTTP 逾時判斷失敗。

第三步：把預算、限流與可觀測性接到同一條追蹤鏈

AI Gateway 上線後，單看 HTTP 200 並不足以判斷系統是否健康。你至少要記錄：

• 租戶、專案、環境與使用者範圍；
• 內部模型別名、實際供應商與模型版本；
• trace_id、供應商請求 ID、狀態與中止原因；
• 首個 Token 延遲、完整回應延遲與逾時；
• 輸入、輸出及快取用量；
• 工具呼叫次數、失敗原因與回傳大小；
• 回退前後的模型和最終結果。

提示詞與回應不必預設完整保存。你可以只保留雜湊、長度、敏感資料標籤與抽樣片段，並對電子郵件、電話、存取權杖、帳戶識別資料和原始程式碼進行脫敏。

預算控制最好分成三層：

1. 告警層：接近租戶或專案預算時通知負責人；
2. 限制層：超過每日或每小時上限後拒絕非必要請求；
3. 保護層：異常流量、重試暴增或單一租戶突發用量時暫停路由。

限流也不應只看請求數。對模型 API 而言，請求數、輸入 Token、輸出 Token 和並行連線都可能是不同限制。若只設一個每分鐘請求數，長提示詞或串流連線仍可能把上游壓垮。

第四步：用固定測試集完成企業 AI Gateway 上線驗收

企業 AI Gateway 上線前要檢查什麼？不要只測一個「請模型回答問題」的成功案例，而要建立固定測試集，讓每次更換模型、路由或供應商後都能重跑。

建議按以下條件分支決策：

• 若應用只需要文字回應，且沒有外部副作用：先使用確定性路由，測試錯誤轉換、用量記錄和逾時。
• 若應用需要工具呼叫：只有在工具名稱、參數、呼叫 ID、工具結果回傳與多輪流程都通過後，才把該模型加入 tool_agent 路由。
• 若應用需要串流：分別驗證正常結束、上游中途斷線、空文字事件、部分回應後逾時，以及用戶端取消連線。
• 若應用處理敏感資料：先驗證脫敏、日誌保留、區域限制和租戶隔離；任一項不合格，就回退到不接收該類資料的路由。
• 若回退後品質不達標：不要只保留技術上可用的備援模型，應改成明確錯誤或人工接手。
• 若供應商回傳限流或服務不可用：驗證退避、最大重試次數、斷路器和告警是否同時生效。

測試結果要保存請求摘要、模型別名、實際路由、錯誤類型、延遲、用量與人工判定。這樣你才能分辨「請求成功」和「業務結果可接受」之間的差距。

如果你還在整理部署環境、權限與服務交付條件，可以先參考 ZavCloud 幫助中心 的相關說明；需要在隔離環境測試多模型端點時，也可把 Mac 雲端租用方案 納入測試週期規劃。

第五步：用模型別名和灰度策略處理長期變更

供應商會新增模型、調整 API 版本、改變限制，甚至淘汰舊端點。業務程式若直接寫死供應商模型名稱，後續每次升級都會變成全站修改。

較穩定的做法是：

• 由平台團隊維護模型別名到實際模型的映射；
• 新模型先以小比例租戶或內部流量灰度；
• 對文字、工具、結構化輸出和串流分別比較結果；
• 保留上一個可用映射，直到新模型完成驗收；
• 在路由設定中加入生效日期、負責人與回退版本；
• 定期移除已停用端點、失效金鑰和不再使用的日誌欄位。

每次供應商推出新 API 或廢棄端點，都應重新對照官方文件，特別是請求格式、串流事件、工具呼叫、錯誤回應、身份驗證與資料政策。Google 文件目前已提醒部分舊版 Generate Content API 使用者改看新的 Interactions API；這類文件變更正是不能只依賴「相容 SDK」的原因。(ai.google.dev)

如果你目前是把三組 SDK 直接嵌入業務程式，常見缺點是金鑰散落、錯誤格式分裂、預算無法按租戶追蹤，以及供應商升級會直接影響產品發版；自建一台長期在線的伺服器雖然控制力較高，但還要自行處理環境維護、網路連線、權限和故障演練。若你的目標是短期驗證 LLM Gateway、進行多模型相容性測試，或需要一個可快速交付的 Mac 算力環境，租用 ZavCloud 的 Mac 方案通常比臨時採購硬體更容易按測試週期調整；若是長期穩定重負載、需要固定實體介面或已有成熟機房，則應先比較自購 Mac 與既有伺服器的總持有成本，再決定是否適合租用。

完成供應商盤點後，你可以按測試週期與服務持續時間選擇臨時驗證環境或長期在線的 Mac 算力，並逐項核對金鑰隔離、模型路由、串流、限流、預算、日誌和故障回退，避免 Gateway 在「看起來統一」之後，反而把最重要的模型差異藏起來。