管理员指南
渠道管理
渠道是平台对接 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。路由失败排查可参考 分组管理 与 模型管理。