渠道管理

管理员指南

渠道管理

渠道是平台对接 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_timetest_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 对象,键为点分路径(如 temperaturemax_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。路由失败排查可参考 分组管理模型管理