管理員指南
渠道管理
渠道是平台對接 AI 服務商的核心設定單元
每個渠道對應一家上游服務商的 API Key 與接入參數。管理員登入後,在左側邊欄「管理員區域 → 渠道管理」進入,或直接造訪 `/console/channel`。列表支援依 ID、名稱、Key、API 位址與模型關鍵字搜尋;Web 控制台頁面與參考設計一致,正在對接中。
| ID | 名稱 | 分組 | 類型 | 狀態 | 響應時間 | 優先級 | 操作 | |
|---|---|---|---|---|---|---|---|---|
| ☐ | 1 | OpenAI 預設 | default | OpenAI | 已啟用 | 128 ms | 10 | 測試 · 禁用 · 編輯 · ··· |
| ☐ | 2 | Azure 備用 | prod | Azure | 已禁用 | — | 5 | 測試 · 啟用 · 編輯 · ··· |
渠道列表示意:標籤 Tab、篩選列、列內測試與啟停
添加渠道
基本設定
點擊「添加渠道」開啟表單,填寫接入上游所需的基本資訊:
| 欄位 | 說明 |
|---|---|
name · 渠道名稱 | 建議依服務商 + 用途命名,如「OpenAI 正式」 |
type · 渠道類型 | 決定請求轉接器與預設 Base URL |
key · API Key | 上游金鑰;支援單 Key 或多 Key(見多 Key 模式) |
base_url · Base URL | 自訂代理或相容閘道位址,留空則使用類型預設值 |
group · 分組 | 預設 default;與令牌分組、ability 表比對 |
priority · 優先級 | 同模型多渠道路由時的優先順序 |
weight · 權重 | 負載平衡權重,搭配輪詢模式使用 |
tag · 標籤 | 批次啟用/禁用、批次編輯時的分組標籤 |
選擇模型
- 勾選此渠道可轉發的模型,或點擊「從上游拉取」呼叫
POST /api/channel/fetch_models - 指定渠道拉取:
GET /api/channel/fetch_models/{id} - 已選模型寫入
models欄位;與「模型管理」能力表共同決定路由
進階設定
| 欄位 | 說明 |
|---|---|
model_mapping · 模型映射 | JSON:將平台模型名稱映射為上游模型名稱 |
status_code_mapping · 狀態碼映射 | 將上游 HTTP 狀態碼映射為統一錯誤 |
test_model · 測試模型 | 連線測試時使用的模型 ID |
auto_ban · 自動禁用 | 連續失敗時自動禁用渠道 |
header_override · 請求標頭覆寫 | 新增或取代轉發到上游的 HTTP 標頭 |
remark · 備註 | 僅管理員可見的說明文字 |
提交儲存
- 新增:
POST /api/channel/ - 更新:
PUT /api/channel/ - 複製既有渠道:
POST /api/channel/{id}/copy - 儲存成功後返回列表;Root 可透過
POST /api/channel/{id}/key檢視完整金鑰
渠道測試
單一渠道測試
點擊列內「測試」,或呼叫 POST /api/channel/{id}/test。系統使用渠道設定的 test_model 發起探測,成功則更新 response_time 與 test_time。
批次測試
工具列「測試所有渠道」對應 GET /api/channel/test,依序檢測全部已啟用渠道。也可呼叫 GET /api/channel/update_balance 批次重新整理餘額。
批次操作
選擇渠道
勾選列表左側核取方塊;可依頂部 tag Tab 篩選同一標籤下的渠道,或使用搜尋框依 ID、名稱、Key、Base URL、模型關鍵字篩選(GET /api/channels?keyword=)。
執行批次操作
| 操作 | 介面 | 說明 |
|---|---|---|
| 批次刪除 | POST /api/channel/batch | 刪除所選渠道(無法復原) |
| 依標籤啟用 | POST /api/channel/tag/enabled | 啟用同一 tag 下全部渠道 |
| 依標籤禁用 | POST /api/channel/tag/disabled | 禁用同一 tag 下全部渠道 |
| 批次設定標籤 | POST /api/channel/batch/tag | 為所選渠道統一設定 tag |
| 刪除已禁用 | DELETE /api/channel/disabled | 清除全部已禁用渠道 |
多 Key 模式
設定多 Key
在渠道編輯表單開啟「多 Key」,每行填寫一個上游金鑰;或透過 POST /api/channel/multi_key/manage 批次維護。適用於同一服務商多帳號輪詢以提高配額上限。
選擇輪詢模式
| 模式 | 說明 |
|---|---|
random · 隨機 | 每次請求隨機選取一個可用 Key |
round_robin · 輪詢 | 依序循環使用各 Key |
priority · 優先級 | 優先使用高優先級 Key,失敗時降級 |
儲存設定
儲存後閘道在轉發請求時依所選模式調度多個 Key;單一 Key 連續失敗時可搭配 auto_ban 自動禁用該 Key 或整條渠道。
參數覆寫系統
簡單覆寫模式
在 param_override 中填寫 JSON 物件,鍵為點分路徑(如 temperature、max_tokens),值為要寫入請求主體的內容。適合固定改寫少量參數。
進階操作模式
使用 operations 陣列定義複雜參數操作,支援條件判斷、陣列操作、字串串接與正規化;可與 header_override 搭配處理特殊上游格式。
基本結構
{
"operations": [
{
"path": "temperature",
"mode": "set",
"value": 0.8,
"conditions": [...],
"logic": "AND"
}
]
}| 欄位 | 說明 |
|---|---|
mode | 必填,操作類型 |
path | 適用於 set / delete / append / prepend / trim_* / ensure_* / trim_space / to_lower / to_upper / replace / regex_replace |
value | 常見於 set / append / prepend / trim_prefix / trim_suffix / ensure_prefix / ensure_suffix |
from / to | 適用於 move / copy / replace / regex_replace |
keep_origin | set 時已有值則略過;append / prepend 合併物件時使用 |
conditions | 條件陣列,滿足時才執行該操作 |
logic | AND(全部滿足)或 OR(任一滿足,預設) |
操作模式 (mode)
- set - 設定值:設定指定路徑的值;`keep_origin: true` 時若已有值則略過
- delete - 刪除欄位:從請求主體中移除指定路徑的欄位
- move - 移動欄位:將 `from` 路徑的值移動到 `to` 路徑
- append - 附加內容:附加到字串末尾、陣列末尾或合併物件屬性
{ "path": "messages.0.content", "mode": "append", "value": "\n\n請用繁體中文回答。" } - prepend - 前置內容:插入到字串開頭、陣列開頭或合併物件屬性
- copy - 複製欄位:將 `from` 的值複製到 `to`,不刪除來源欄位
- trim_prefix - 去除前綴:去除字串指定前綴,不符合則不變
- trim_suffix - 去除後綴:去除字串指定後綴,不符合則不變
- ensure_prefix - 確保前綴:確保字串以指定前綴開頭
- ensure_suffix - 確保後綴:確保字串以指定後綴結尾
- trim_space - 去除首尾空白:對字串執行 TrimSpace
- to_lower - 轉小寫:將字串欄位轉為小寫
- to_upper - 轉大寫:將字串欄位轉為大寫
- replace - 字串取代:子字串取代;`from` 必填,`to` 選填
- regex_replace - 正規表示式取代:以 Go regexp 語法進行正規表示式比對取代
{ "path": "model", "mode": "regex_replace", "from": "^gpt-", "to": "openai/gpt-" }
條件判斷
透過 conditions 陣列設定操作執行條件,僅當條件滿足時才執行對應操作。
條件結構
{
"conditions": [
{
"path": "model",
"mode": "contains",
"value": "gpt-4",
"invert": false,
"pass_missing_key": false
}
],
"logic": "AND"
}條件比對模式
full:完全比對(預設)prefix:前綴比對suffix:後綴比對contains:包含比對gt / gte / lt / lte:數值比較,僅用於數字類型
數值比較只能用於數字類型;字串操作(prefix、suffix、contains)會將值轉為字串比較。
條件參數說明
invert:true 時將比對結果反轉pass_missing_key:路徑不存在時:true 視為通過,false 視為不通過(預設)
邏輯關係 (logic)
AND:所有條件都必須滿足OR:任一條件滿足即可(預設)
路徑語法
使用 JSON 路徑存取巢狀欄位:
| 路徑 | 說明 |
|---|---|
temperature | 根層級欄位 |
messages.0.content | 陣列第一個元素的 content |
messages.-1.content | 陣列最後一個元素的 content |
metadata.user.name | 巢狀物件欄位 |
內建變數(無需存在於請求主體中,可直接用於條件判斷):
| 變數 | 說明 |
|---|---|
model / upstream_model | 重新導向後的目標模型,用於條件比對 |
original_model | 重新導向前使用者請求的模型 |
實用範例
1. 動態調整模型參數
依訊息內容關鍵字設定不同 temperature
{
"operations": [
{
"path": "temperature",
"mode": "set",
"value": 0.3,
"conditions": [{ "path": "messages.0.content", "mode": "contains", "value": "程式碼" }]
},
{
"path": "temperature",
"mode": "set",
"value": 0.9,
"conditions": [{ "path": "messages.0.content", "mode": "contains", "value": "創意" }]
}
]
}2. 新增系統提示
在 messages 陣列開頭 prepend 系統訊息
{
"operations": [
{
"path": "messages",
"mode": "prepend",
"value": [{ "role": "system", "content": "你是一個專業的 AI 助理,請始終保持禮貌和專業。" }]
}
]
}3. 依模型類型調整參數
依 model 前綴設定不同 max_tokens
{
"operations": [
{
"path": "max_tokens",
"mode": "set",
"value": 4000,
"conditions": [{ "path": "model", "mode": "prefix", "value": "gpt-4" }]
},
{
"path": "max_tokens",
"mode": "set",
"value": 2000,
"conditions": [{ "path": "model", "mode": "prefix", "value": "gpt-3.5" }]
}
]
}4. 多條件組合(AND 邏輯)
同時滿足多個條件時才執行操作
{
"operations": [
{
"path": "stream",
"mode": "set",
"value": false,
"conditions": [
{ "path": "model", "mode": "contains", "value": "claude" },
{ "path": "messages.0.content", "mode": "contains", "value": "長文" }
],
"logic": "AND"
}
]
}5. 數值比較條件
依數值大小進行條件判斷
{
"operations": [
{
"path": "temperature",
"mode": "set",
"value": 0.1,
"conditions": [
{ "path": "max_tokens", "mode": "gt", "value": 1000 }
]
}
]
}6. 反向條件
使用 invert 實現反向邏輯
{
"operations": [
{
"path": "stream",
"mode": "set",
"value": true,
"conditions": [
{
"path": "model",
"mode": "contains",
"value": "gpt-3.5",
"invert": true
}
]
}
]
}7. 處理缺少的欄位
使用 pass_missing_key 處理可能不存在的欄位
{
"operations": [
{
"path": "temperature",
"mode": "set",
"value": 0.7,
"conditions": [
{
"path": "custom_field",
"mode": "full",
"value": "special",
"pass_missing_key": true
}
]
}
]
}8. 字串串接範例
在使用者訊息後附加引導語
{
"operations": [
{
"path": "messages.-1.content",
"mode": "append",
"value": "\n\n請詳細解釋你的思考過程。"
}
]
}注意事項
- 操作依 operations 陣列順序依次執行,前面的操作會影響後續操作
- 參數覆寫僅用於合法的上游介面相容、企業網路相容與請求正規化
- 數值比較條件只能用於數字類型;字串操作為字串比較
列表欄位說明
| 欄 | 欄位 | 說明 |
|---|---|---|
| ID | id | 渠道唯一識別碼 |
| 名稱 | name | 便於識別的渠道名稱 |
| 分組 | group | 與令牌分組、能力表連動 |
| 類型 | type | OpenAI、Azure、Anthropic 等接入類型 |
| 狀態 | status | 已啟用 / 已禁用;可快速切換 |
| 響應時間 | response_time | 最近一次連線測試耗時(ms) |
| 已用/剩餘 | used_quota / balance | 渠道端額度或餘額概覽 |
| 優先級 | priority | 同分組內調度優先級,數值越大越優先 |
管理員邊欄入口可在 個人設定 → 邊欄模組中開啟 sidebar_modules.admin.channel。路由失敗排查可參考 分組管理 與 模型管理。