渠道管理

管理員指南

渠道管理

渠道是平台對接 AI 服務商的核心設定單元

每個渠道對應一家上游服務商的 API Key 與接入參數。管理員登入後,在左側邊欄「管理員區域 → 渠道管理」進入,或直接造訪 `/console/channel`。列表支援依 ID、名稱、Key、API 位址與模型關鍵字搜尋;Web 控制台頁面與參考設計一致,正在對接中。

easyapi.com/console/channel
添加渠道重新整理欄位設定全部 43
渠道 ID / 名稱 / Key / API 位址模型關鍵字選擇標籤查詢重設
ID名稱分組類型狀態響應時間優先級操作
☐1OpenAI 預設defaultOpenAI已啟用128 ms10測試 · 禁用 · 編輯 · ···
☐2Azure 備用prodAzure已禁用—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_originset 時已有值則略過;append / prepend 合併物件時使用
conditions條件陣列,滿足時才執行該操作
logicAND(全部滿足)或 OR(任一滿足,預設)

操作模式 (mode)

  1. set - 設定值:設定指定路徑的值;`keep_origin: true` 時若已有值則略過
  2. delete - 刪除欄位:從請求主體中移除指定路徑的欄位
  3. move - 移動欄位:將 `from` 路徑的值移動到 `to` 路徑
  4. append - 附加內容:附加到字串末尾、陣列末尾或合併物件屬性
    {
      "path": "messages.0.content",
      "mode": "append",
      "value": "\n\n請用繁體中文回答。"
    }
  5. prepend - 前置內容:插入到字串開頭、陣列開頭或合併物件屬性
  6. copy - 複製欄位:將 `from` 的值複製到 `to`,不刪除來源欄位
  7. trim_prefix - 去除前綴:去除字串指定前綴,不符合則不變
  8. trim_suffix - 去除後綴:去除字串指定後綴,不符合則不變
  9. ensure_prefix - 確保前綴:確保字串以指定前綴開頭
  10. ensure_suffix - 確保後綴:確保字串以指定後綴結尾
  11. trim_space - 去除首尾空白:對字串執行 TrimSpace
  12. to_lower - 轉小寫:將字串欄位轉為小寫
  13. to_upper - 轉大寫:將字串欄位轉為大寫
  14. replace - 字串取代:子字串取代;`from` 必填,`to` 選填
  15. 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 陣列順序依次執行,前面的操作會影響後續操作
  • 參數覆寫僅用於合法的上游介面相容、企業網路相容與請求正規化
  • 數值比較條件只能用於數字類型;字串操作為字串比較

列表欄位說明

欄欄位說明
IDid渠道唯一識別碼
名稱name便於識別的渠道名稱
分組group與令牌分組、能力表連動
類型typeOpenAI、Azure、Anthropic 等接入類型
狀態status已啟用 / 已禁用;可快速切換
響應時間response_time最近一次連線測試耗時(ms)
已用/剩餘used_quota / balance渠道端額度或餘額概覽
優先級priority同分組內調度優先級,數值越大越優先

管理員邊欄入口可在 個人設定 → 邊欄模組中開啟 sidebar_modules.admin.channel。路由失敗排查可參考 分組管理 與 模型管理。