> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 供應商、路由組與本地閘道器

> 把模型供應商設定一次，在多個 Agent 之間共享，並用路由組和本地閘道器管理故障轉移。

Vibex 把模型接入拆成四層。先分清它們，配置時就不會迷路：

| 層 | 回答的問題 | 在哪裡 |
| - | - | - |
| **Agent** | 誰來做？ | 配置中心 → Agent |
| **模型供應商設定** | 這個 Agent 用哪個供應商、哪套憑據、哪些模型？ | 配置中心 → Agent → 所選 Agent 的詳情 |
| **共享供應商（Provider）** | 一套地址、Key 和模型，能被哪些 Agent 和路由組使用？ | 配置中心 → 供應商 |
| **路由組與本地閘道器** | 多個供應商或模型之間如何排序、失敗轉移和轉換協議？ | 配置中心 → 供應商 → 閘道器 / 路由組 |

一個 Agent 仍然可以只用一套自己的模型供應商設定，不碰共享供應商。共享供應商和路由組是給“同一套 Key 要服務多個 Agent”和“需要故障轉移”的場景用的。

## 配置中心 → 供應商

**供應商**頁把每個共享 Provider 只列一次，並顯示哪些 Agent 正在使用它。頂部有兩個側欄標籤：

* **供應商**：共享的地址、憑據、模型和 Key。
* **路由組**：把多個 Provider 或模型組合成一個 Agent 可請求的名字。

**閘道器**是供應商頁頂部固定的一行，不是獨立分區。它顯示監聽狀態、地址、可用 Key、路由組和請求量；點進去管理 Key、路由和超時。

### 新建供應商

點 **新建供應商**，可以：

1. 從內建預設開始。預設覆蓋 Anthropic、OpenAI、Google Gemini、DeepSeek、Moonshot Kimi、Zhipu GLM、OpenRouter 等常見廠商，以及官方、中轉、本機三類來源。
2. 選擇 **自定義**，手動填寫名稱、API 地址和模型。
3. 從已有 CLI 配置匯入：Codex、Claude 或 CC Switch。匯入前會顯示將要讀取的檔案和將要建立的 Provider，不會靜默覆蓋。

新建流程會先問來源，再問欄位。預設會預填協議、地址、Key 提示和常用模型；你可以改，也可以從 `models.dev` 目錄補充圖示和模型資訊。

### 供應商設定

| 分組 | 欄位 |
| - | - |
| **基本資訊** | 名稱、型別（官方 / 中轉 / 本機）、圖示、官網、備註。 |
| **連線** | API 地址、模型列表地址、認證地址、代理、請求頭、models.dev ID、自籤 TLS。 |
| **模型** | 啟用的模型、預設模型、模型介面協議、推理檔位、上下文視窗、最大輸出 Token。 |
| **行為** | 認證頭、是否只通過路由組使用、請求體欄位。 |

* **API 地址**是 Agent 或閘道器真正請求的地址。部分 Agent 會鎖定這一項。
* **請求頭**支援字面值和內建 `session_id` 變數；`session_id` 會在每次會話啟動時填入，適合需要穩定會話頭的供應商。
* **請求體欄位**以行編輯，不要求你手寫 JSON；未知欄位不會悄悄覆蓋已有配置。
* **只通過路由組使用**會讓這個 Provider 不出現在普通模型選擇器裡，只能作為路由組成員。

### 模型

每個 Provider 有自己的模型列表：

* **拉取模型**從供應商的模型列表地址讀取，不寫入配置。
* 勾選模型即啟用；取消勾選會保留已宣告的能力，重新勾選即可恢復。
* 每個模型可以單獨宣告 **介面協議**（繼承、OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini、Mistral 等）、**推理檔位**、**上下文視窗** 和 **最大輸出 Token**。
* **預設模型**是這個 Provider 在沒有指定模型時使用的模型。
* 模型 id 可以手動新增；預設的模型列表可能過期，但不會被網路靜默改寫。

> [!NOTE]
>
> 推理檔位和上下文視窗是**宣告資料**，不會從模型 id 猜測。宣告錯誤會讓 Agent 收到它不支援的選項；不確定時留空，讓 Agent 使用自己的目錄。

### Key

一個 Provider 可以儲存多把 Key：

* 預設掩碼顯示，點眼睛圖示可以臨時檢視。
* **優先** Key 會先被閘道器使用；失敗後按冷卻策略切換。
* 每把 Key 可以單獨設定模型範圍、代理和 token 上限。
* **測試**會真實請求一次供應商介面；**批次新增**一次寫入多把 Key。
* Key 失效、冷卻中或額度不足時，列表會顯示狀態，而不是隻報一個籠統的錯誤。

> [!WARNING]
>
> 測試連線、拉取模型和真實會話都會訪問供應商網路並可能產生費用。確認地址、Key 和模型後再執行。

## 路由組

路由組把多個成員組合成一個 Agent 可請求的模型名。成員可以是：

* 整個 Provider（供應商組），對外提供成員目錄的交集。
* 一個 `(Provider, 模型)` 對（模型組），對外提供一個穩定的模型名。

開啟 **供應商 → 路由組 → 新建路由組**：

1. 填寫 **名稱** 和 **對外模型名**。對外模型名不能包含 `/`。
2. 從下方模型面板新增成員，每個成員選擇 Provider 和模型。
3. 調整 **嘗試順序**；閘道器從上往下嘗試。
4. 選擇 **策略**（見下表）。
5. 按需設定 **固定對話成員**、**失敗時自動切換**、**耐心等待**、**首 Token 超時**、**上下文 Token** 和 **Token 上限**。
6. 在 **Agent** 區域點選允許使用該路由組的 Agent。
7. 用 **試執行** 檢視某個請求會落到哪個成員，不會真的傳送請求。
8. 儲存。

### 策略

| 策略 | 如何選擇成員 |
| - | - |
| **按順序** | 按配置順序嘗試。 |
| **輪詢** | 每個請求前進一個成員。 |
| **最少使用** | 選擇本地觀測到 token 用量最少的成員。 |
| **智慧** | 先排除冷卻中的成員，再按 p50 延遲、進行中請求數和用量排序。 |
| **最低延遲** | 按 p50，再按 p95。 |
| **加權** | 按權重交錯輪轉，而不是連續發完一個成員。 |
| **手動** | 只使用你指定的成員，不自動回退。 |

權重在 1–100 之間；切換策略時權重會保留。

### 限制與可見性

* **固定對話成員**：同一對話儘量留在同一個成員上，保住供應商的提示快取。
* **失敗時自動切換**：當前成員失敗時直接換下一個；關閉則先詢問。
* **首 Token 超時**：流式請求在收到第一個位元組前等待多久；超時會嘗試下一個成員。
* **耐心等待**：成員冷卻時最多等多久再放棄。
* **上下文 Token**：留空時使用最小成員的視窗。
* **Token 上限**：按本地觀測的 token 計數，可設每天、每週或每月。
* **不在選擇器中顯示**：名字仍可呼叫，但不出現在模型選擇器裡。
* **作為兜底組合**：隱藏的組合，供其他路由組回退使用。

路由組只擁有路由策略，不擁有 Key。刪除一個 Provider 會讓引用它的成員顯示為缺失，但不會靜默刪除整個路由組。

## 本地閘道器

閘道器是一個只監聽 `127.0.0.1` 的 HTTP 端點。使用路由組的 Agent 會指向它，而不是直接指向廠商。它負責：

* 在成員之間排序、冷卻、重試和故障轉移。
* 在 OpenAI Chat、OpenAI Responses、Anthropic Messages 和 Gemini 之間轉換請求與流式響應。
* 按對話保持 Key 和成員選擇，儘量不丟提示快取。
* 記錄只含 token、延遲、狀態和路由決策的請求臺賬；不儲存提示詞、響應正文或 Key。

閘道器頁有四個標籤：

| 標籤 | 內容 |
| - | - |
| **概覽** | 狀態、地址、可用 Key、路由組、請求量、成功率、p50/p95、輸入/輸出/快取 token、故障轉移、進行中請求、請求最多的供應商和模型。 |
| **Key** | 每個上游 Provider 的 Key、優先 Key、啟用/停用、替換、批次新增、token 上限和冷卻狀態。 |
| **路由** | 即時路由圖、請求記錄、篩選、分頁、重放一次請求的路徑。 |
| **設定** | Token 上限、協議轉換、錯誤率/延遲告警、連線/請求/流空閒超時、各類冷卻時間。 |

### 閘道器狀態

| 狀態 | 含義 |
| - | - |
| **執行中** | 埠已繫結，至少一個路由組可服務。 |
| **降級** | 埠仍在監聽，但某些路由組在連續失敗後暫時退讓；其他路由組繼續服務。 |
| **不可用** | 埠繫結失敗或服務已停止；直接 Provider 不受影響。 |
| **已停用** | 你關閉了閘道器；所有路由組暫時不可用，但配置保留。 |

關閉閘道器不會刪除 Provider、路由組或 Key；重新開啟後會重新繫結埠並恢復路由組。

### 請求臺賬與重放

**路由**標籤記錄最近的請求：時間、請求的模型、命中的路由組、實際成員、狀態、延遲、token 和錯誤。可以按時間範圍、狀態和路由組篩選，也可以開啟一次請求檢視它的路由路徑。

**重放**只重建當時的候選順序和決策，不會再次向上遊傳送請求。即時路由圖只顯示閘道器當前處理的請求；直接 Provider 不經過閘道器，所以不會出現在圖裡。

## 在會話中使用

傳送訊息前，在輸入框頂部選擇：

* **Agent**：誰來做。
* **供應商設定**：這個 Agent 用哪套配置。
* **模型**：具體的模型或路由組對外模型名。
* **思考深度**：由 Agent 和模型宣告決定。

如果 Agent 繫結的是路由組，請求會經過本地閘道器；如果繫結的是直接 Provider，請求不經過閘道器。切換隻影響後續執行，已有時間線保留原來的執行身份。

## 安全與限制

* 閘道器只繫結迴環地址，不監聽區域網或公網；需要遠端使用時，讓執行階段跑在遠端機器上，通過 SSH 隧道或 Remote v2 訪問。
* 閘道器不儲存提示詞、響應正文、Key 或賬號密碼；臺賬只記錄 token 和路由後設資料。
* 路由組不擁有 Key，刪除 Provider 不會刪除 Key 本身。
* 沒有成本、餘額、預算或配額管理；token 上限是本地觀測計數，不是供應商賬單。
* 路由組只能在桌面端或 TUI 的管理頁編輯，行動端只讀。
* 協議轉換覆蓋文本、圖片、工具呼叫和流式響應；供應商特有的非標準欄位可能被丟棄，遇到問題時先用 **測試** 和請求臺賬確認。

## 故障排查

| 現象 | 處理 |
| - | - |
| 模型選擇器裡看不到共享 Provider | 檢查它是否勾選了 **只通過路由組使用**，以及當前 Agent 是否綁定了它。 |
| 路由組顯示“沒有可用 Key” | 到閘道器 → Key 檢查成員 Provider 的 Key 是否啟用、是否在冷卻。 |
| 閘道器顯示“不可用” | 檢查埠是否被佔用；關閉閘道器再開啟會重新繫結。直接 Provider 仍可使用。 |
| 請求總是落到同一個成員 | 檢查策略是否為 **手動** 或 **按順序**，以及是否開啟了 **固定對話成員**。 |
| 首 Token 很慢 | 調整首 Token 超時和耐心等待；檢視請求臺賬裡的 p50/p95。 |
| 協議錯誤或工具呼叫失敗 | 確認模型的介面協議宣告正確；必要時在 Provider 設定裡改為繼承或指定協議。 |
| 刪除 Provider 後路由組報錯 | 路由組成員引用了已刪除的 Provider；編輯路由組，移除或替換該成員。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.