在 AI 閘道中管理渠道

「渠道（Channel）」是 AI 閘道中一個供應商接入點的設定——它儲存了某家供應商的位址、真實 API Key、可用模型以及計價與額度等資訊。閘道正是依據這些渠道，把應用程式送來的請求路由到對應供應商。本文介紹如何新增、設定、測試和管理渠道。

前提條件

• 已安裝並執行 ServBay，且已登入 ServBay 帳號（新增渠道前需要登入）。
• 已備妥目標供應商的真實 API Key（本地供應商如 Ollama / LM Studio 可不填）。
• 若尚未了解 AI 閘道的整體架構，建議先閱讀 AI 閘道介紹。

新增渠道

進入 AI 閘道 → 渠道（Channels） 頁面，點擊 新增（Add） 開啟精靈。精靈分為三個步驟。

第一步：選擇供應商

供應商依類別分組顯示，點擊卡片即可選擇：

• 主流（Mainstream）：OpenAI、Anthropic、Google Gemini、Azure OpenAI、AWS Bedrock、OpenRouter。
• 中國（China）：DeepSeek、通義千問、智譜 GLM、Kimi、豆包·火山、文心一言、混元、MiniMax、零一萬物、階躍星辰。
• 本地（Local）：Ollama、LM Studio。
• 自訂（Custom）：OpenAI Compatible、Custom。

選擇供應商後，閘道會自動填入該供應商的預設 Base URL。

雙區域切換

通義千問、智譜 GLM、Kimi、豆包·火山、混元、MiniMax、階躍星辰等中國供應商同時提供國內與全球兩套端點。選擇這類供應商時，精靈會出現「區域」選擇器（🇨🇳 國內 / 🌐 全球），切換後 Base URL 會自動更新為對應區域位址。

第二步：填寫設定

• 渠道名稱（必填） — 用於在列表中辨識該渠道，可自訂。
• Base URL（必填） — 供應商 API 位址。多數供應商已自動填好；Azure OpenAI 與 Custom 需要你手動填寫。
• API Key（選填） — 供應商的真實金鑰。若留空，只能測試端點是否可達，無法驗證金鑰有效性；本地供應商（Ollama / LM Studio）通常無需填寫。
• 模型 — 有兩種方式，二選一：
  • 自動探索：點擊探索後，閘道呼叫供應商的模型列表介面拉取可用模型，你以標籤（chip）方式多選。
  • 手動填寫：直接輸入模型名稱。Azure 渠道需填入**部署名稱（Deployment name）**而非模型名稱。
• 優先順序 / 權重 — 當多個渠道可服務同一模型時，閘道據此決定路由與負載分配。

Azure OpenAI 注意

Azure 渠道的「模型」欄位應填寫你在 Azure 入口網站中建立的部署名稱（Deployment name），而不是底層模型名稱。Base URL 也需填寫你的 Azure 資源端點。

第三步：確認並提交

核對設定摘要後提交。提交成功後，新渠道會出現在渠道列表中，並顯示即時健康狀態。

能力探測與路由策略

新增渠道後，閘道會對該渠道進行能力探測（capability probing）——這是 AI 閘道最核心的智慧路由機制。探測的結果決定了 Claude Code 等工具能否直接使用、還是需要建立模型對應，以及如何選擇目標模型。

探測的兩個關鍵指標

閘道對每個渠道探測兩個核心事實（均為三態：true / false / 未探明）：

探測項	含義	true	false	未探明
認得 Claude 模型名稱（accepts_claude_names）	渠道是否原生辨識 claude-opus-* / claude-sonnet-* / claude-haiku-* 這些模型名稱	直連即可，不需對應	不認得，必須建立對應，把 claude-* 名稱轉譯成上游真實模型名稱	探測沒執行或失敗，不能下結論
依等級區分（tier_aware）	上游是否自行依 opus / sonnet / haiku 等級回傳不同的模型	上游已分等級，交給上游處理即可	不分等級（對所有等級回傳同一個模型），需要閘道建立對應	探測不出或未曾探測

為什麼要探測而不是猜

不同供應商的行為差異很大。OpenAI 原生不認得 claude-* 模型名稱；某些中轉供應商透過轉發辨識；而編碼套餐類供應商（如 Claude Pro/Max 訂閱）可能只認得訂閱綁定的特定模型名稱。閘道不靠渠道類型猜測，而是實際探測後再決定路由策略。

路由判定：五種狀態

當你在 AI Gateway → 接入管理 → 用戶端頁面對 Claude Code 執行「一鍵接管」時，閘道會彙總所有候選渠道的探測結果，得出一個路由判定：

候選渠道狀態	判定	含義
沒有可用的候選渠道（無渠道 / 全部不健康 / 虛擬金鑰作用範圍內無渠道）	無候選渠道	你需要先新增或修復渠道
任一候選渠道的探測值為未探明	未檢測	需要先執行一次探測，不能在未驗證的前提下建立對應
全部候選渠道都認得 claude 模型名稱	直連	不建立對應，請求原樣轉發
全部候選渠道都不認得 claude 模型名稱	必須對應	閘道建立三個等級的對應，把 claude-* 轉譯成上游真實模型名稱
候選中既有認得的也有不認得的	混合	需要人工決定（認得的直接走，不認得的走對應）

模型對應：把 claude-* 轉譯成上游真實模型

當判定為「必須對應」時，閘道會為 Claude Code 建立三條模型對應規則，分別涵蓋三個等級：

Claude Code 發出的模型名稱	對應規則（萬用字元）	對應至
claude-opus-*	比對所有 opus 等級請求	候選渠道中的旗艦模型
claude-sonnet-*	比對所有 sonnet 等級請求	候選渠道中的旗艦模型或標準模型
claude-haiku-*	比對所有 haiku 等級請求	候選渠道中的輕量模型

目標模型的選擇規則（依優先順序回退）：

1. 家族預設：如果候選模型中出現已知家族關鍵字（如 glm），直接取該家族的旗艦款（如 glm-5.2）作為 opus/sonnet 等級目標，取該家族的輕量款（如 glm-4.7-flash）作為 haiku 等級目標。
2. 關鍵字比對：沒有家族預設時，opus/sonnet 取候選清單的第一個模型；haiku 取候選中比對到輕量關鍵字（flash / mini / lite / air / small / turbo / haiku）的第一個模型。
3. 備援：仍未命中時，三個等級都取候選清單的第一個模型。

haiku 等級設定錯誤的代價最高

Claude Code 的 haiku 等級呼叫量最大（每次對話的輕量呼叫都用它）。如果誤把旗艦模型填進 haiku 等級，帳單可能暴增數倍。閘道的關鍵字比對表涵蓋了 7 種輕量後綴（flash / mini / lite / air / small / turbo / haiku），確保不會把重型模型填進 haiku 等級。

對應寫入的機制

接管確認後，閘道透過 /admin/model-mappings API 寫入對應記錄。每筆對應記錄包含：

• 來源協定（source_protocol）：anthropic（Claude Code 發出的請求是 Anthropic 格式）
• 來源模型比對（source_model_pattern）：萬用字元，如 claude-opus-*
• 目標協定（target_protocol）：openai（統一轉成 OpenAI 格式傳送給上游）
• 目標模型（target_model）：探測選出的具體模型名稱

寫入是冪等的——重複接管不會產生重複對應；寫入前會先拉取現有對應清單進行比對。

執行時路由規則：failover 與降級

除了接管階段寫入的靜態對應，閘道還支援執行時路由規則（routing rules），在請求經過閘道時動態決策：

規則欄位	作用
觸發條件（condition_type）	何時觸發降級，如渠道額度耗盡（quota_exhausted）
成本閾值（cost_threshold_usd）	選填：當該渠道累計成本超過閾值時觸發
動作（action_type）	觸發後要做什麼，如切換到指定的備用渠道（switch_to）
目標渠道（target_channel_id）	降級後要使用的備用渠道
目標模型（target_model）	選填：降級到備用渠道時同時切換模型

透過組合多個路由規則，你可以實現：當渠道 A 的訂閱額度耗盡時，自動切換到渠道 B 的按量付費端點；當某渠道 24 小時成本超限時，降級到更便宜的模型。

負載平衡與優先順序

當多個健康渠道可服務同一個模型時，閘道依以下策略選擇：

• 優先順序模式（預設）：只取優先順序最高的渠道；同優先順序的渠道中，閘道依內部權重分配。
• 輪詢模式（round_robin）：在所有健康候選渠道間輪流分配請求。

優先順序在渠道設定中設定（數字越大優先順序越高），虛擬金鑰的 allowed_channels 限定可選渠道範圍。

連通性測試

在渠道列表中可對單一渠道執行連通性測試。測試分為兩個維度：

• 端點可達性（reachable） — 檢查 Base URL 是否能連通（網路與位址是否正確）。
• 金鑰有效性（authenticated） — 實際呼叫供應商介面，驗證 API Key 是否有效。僅在填寫了 API Key 時才會驗證。

測試結果會顯示：往返延遲（毫秒）、狀態徽章以及錯誤訊息。

TIP

在新增精靈中，如果端點不可達，會阻止你進入下一步；如果端點可達但金鑰無效，只會顯示警告，你仍可繼續（例如你打算稍後再補上金鑰）。

進階設定

新增或編輯渠道時可展開進階設定，用於成本核算與額度控制：

• 計價倍率（Rate Multiplier） — 在供應商官方價格基礎上乘以一個倍率，方便依你的真實成本或轉售價核算，預設為 1.0。
• 計費結構 — 說明該渠道的計費方式，如按量付費（pay as you go）、訂閱（subscription）、套餐包（package）。
• 餘額 — 餘額來源可選固定值、OSS 帳單或手動維護；選擇 OSS 帳單時還可指定帳單類型。餘額與更新時間在渠道詳細資料中為唯讀顯示。
• 訂閱到期時間 — 訂閱 / 套餐包類渠道可記錄到期時間。
• 額度限制 — 可依 Token 數、請求數或金額設定上限，並選擇週期（每日 / 每週 / 每月 / 自訂）。額度用盡後該渠道會被自動排除於選路之外，是防止意外超支的安全閥。

編輯與刪除渠道

• 編輯 — 在渠道列表中開啟某個渠道即可修改名稱、Base URL、API Key、模型與進階設定。
• 刪除 — 刪除渠道後，依賴該渠道的虛擬金鑰將無法再路由到它，請謹慎操作。

健康狀態

渠道列表與 總覽頁 會即時顯示各渠道的健康狀態（正常 / 降級 / 不可用），協助你快速找出失效的供應商設定。

常見問題（FAQ）

• Q：新增渠道時提示需要登入？
  • A：AI 閘道是 ServBay 的加值功能，新增渠道 / 金鑰前需登入 ServBay 帳號，依介面引導登入即可。
• Q：提示渠道數已達上限？
  • A：可建立的渠道數與帳號方案相關，達到上限時可刪除不用的渠道或升級方案。
• Q：模型自動探索拉不到清單？
  • A：請先確認 Base URL 正確、API Key 有效（可用連通性測試的「金鑰有效性」驗證），部分供應商需要有效的金鑰才能回傳模型清單；也可改用手動填寫模型名稱。
• Q：接入本地的 Ollama / LM Studio 需要填 Key 嗎？
  • A：通常不需要。只要確認對應的本地服務已啟動並監聽預設連接埠（Ollama 11434、LM Studio 1234）即可。

總結

渠道是 AI 閘道路由請求的基礎。透過三步精靈，你可以快速接入近 20 家供應商，搭配雙區域切換、模型自動探索與兩維度連通性測試，確保設定正確，再借助計價與額度等進階設定精細管理成本。設定好渠道後，即可建立 虛擬金鑰 供應用程式與工具使用。