在 AI 网关中管理渠道

「渠道（Channel）」是 AI 网关中一个供应商接入点的配置——它保存了某家供应商的地址、真实 API Key、可用模型以及计价与额度等信息。网关正是依据这些渠道，把应用发来的请求路由到对应供应商。本文介绍如何添加、配置、测试和管理渠道。

前提条件

• 已安装并运行 ServBay，且已登录 ServBay 账号（添加渠道前需要登录）。
• 已准备好目标供应商的真实 API Key（本地供应商如 Ollama / LM Studio 可不填）。
• 如未了解 AI 网关整体架构，建议先阅读 AI 网关介绍。

添加渠道

进入 AI 网关 → 渠道（Channels） 页，点击 添加（Add） 打开向导。向导分为三步。

第一步：选择供应商

供应商按类别分组展示，点击卡片即可选择：

• 主流（Mainstream）：OpenAI、Anthropic、Google Gemini、Azure OpenAI、AWS Bedrock、OpenRouter。
• 中国（China）：DeepSeek、通义千问、智谱 GLM、Kimi、豆包·火山、文心一言、混元、MiniMax、零一万物、阶跃星辰。
• 本地（Local）：Ollama、LM Studio。
• 自定义（Custom）：OpenAI Compatible、Custom。

选择供应商后，网关会自动填入该供应商的默认 Base URL。

双区域切换

通义千问、智谱 GLM、Kimi、豆包·火山、混元、MiniMax、阶跃星辰等中国供应商同时提供国内与全球两套端点。选择这类供应商时，向导会出现「区域」选择器（🇨🇳 国内 / 🌐 全球），切换后 Base URL 会自动更新为对应区域地址。

第二步：填写配置

• 渠道名称（必填） — 用于在列表中识别该渠道，可自定义。
• Base URL（必填） — 供应商 API 地址。多数供应商已自动填好；Azure OpenAI 与 Custom 需要你手动填写。
• API Key（可选） — 供应商的真实密钥。若留空，只能测试端点是否可达，无法验证密钥有效性；本地供应商（Ollama / LM Studio）通常无需填写。
• 模型 — 有两种方式，二选一：
  • 自动发现：点击发现后，网关调用供应商的模型列表接口拉取可用模型，你以标签（chip）方式多选。
  • 手动填写：直接输入模型名。Azure 渠道需填入**部署名（Deployment name）**而非模型名。
• 优先级 / 权重 — 当多个渠道可服务同一模型时，网关据此决定路由与负载分配。

Azure OpenAI 注意

Azure 渠道的「模型」字段应填写你在 Azure 门户中创建的部署名（Deployment name），而不是底层模型名。Base URL 也需填写你的 Azure 资源端点。

第三步：确认并提交

核对配置摘要后提交。提交成功后，新渠道会出现在渠道列表中，并显示实时健康状态。

能力探测与路由策略

添加渠道后，网关会对该渠道进行能力探测（capability probing）——这是 AI 网关最核心的智能路由机制。探测的结果决定了 Claude Code 等工具能否直接使用、还是需要建模型映射、以及如何选择目标模型。

探测的两个关键指标

网关对每个渠道探测两个核心事实（均为三态：true / false / 未探明）：

探测项	含义	true	false	未探明
认 Claude 模型名（accepts_claude_names）	渠道是否原生识别 claude-opus-* / claude-sonnet-* / claude-haiku-* 这些模型名	直连即可，不需映射	不认，必须建映射把 claude-* 名翻译成上游真实模型名	探测没跑或失败，不能下结论
按档位区分（tier_aware）	上游是否自己按 opus / sonnet / haiku 档位返回不同的模型	上游已分档，交给上游处理即可	不分档（对所有档位返回同一个模型），需要网关建映射	探不出或没探过

为什么要探测而不是猜

不同供应商的行为差异很大。OpenAI 原生不认 claude-* 模型名；某些中转供应商通过转发识别；而编码套餐类供应商（如 Claude Pro/Max 订阅）可能只认订阅绑定的特定模型名。网关不靠渠道类型猜测，而是实际探测后再决定路由策略。

路由判定：五种状态

当你在 AI Gateway → 接入管理 → 客户端页对 Claude Code 做「一键接管」时，网关会聚合所有候选渠道的探测结果，得出一个路由判定：

候选渠道状态	判定	含义
没有可用候选渠道（无渠道 / 全不健康 / 虚拟密钥作用域内无渠道）	无候选渠道	你需要先添加或修复渠道
任一候选渠道的探测值为未探明	未检测	需要先跑一次探测，不能在未验证的前提下建映射
全部候选渠道都认 claude 模型名	直连	不建映射，请求原样转发
全部候选渠道都不认 claude 模型名	必须映射	网关建三档映射，把 claude-* 翻译成上游真实模型名
候选中既有认的也有不认的	混合	需要人工决定（认的直接走，不认的走映射）

模型映射：把 claude-* 翻译成上游真实模型

当判定为「必须映射」时，网关会为 Claude Code 建立三条模型映射规则，分别覆盖三个档位：

Claude Code 发出的模型名	映射规则（通配符）	映射到
claude-opus-*	匹配所有 opus 档请求	候选渠道中的旗舰模型
claude-sonnet-*	匹配所有 sonnet 档请求	候选渠道中的旗舰模型或标准模型
claude-haiku-*	匹配所有 haiku 档请求	候选渠道中的轻量模型

目标模型的选择规则（按优先级回退）：

1. 家族预设：如果候选模型中出现已知家族关键词（如 glm），直接取该家族的旗舰款（如 glm-5.2）作为 opus/sonnet 档目标，取该家族的轻量款（如 glm-4.7-flash）作为 haiku 档目标。
2. 关键词匹配：没有家族预设时，opus/sonnet 取候选列表的第一个模型；haiku 取候选中匹配轻量关键词（flash / mini / lite / air / small / turbo / haiku）的第一个模型。
3. 兜底：仍未命中时，三档都取候选列表的第一个模型。

haiku 档配错代价最高

Claude Code 的 haiku 档调用量最大（每次对话的轻量调用都用它）。如果误把旗舰模型填进 haiku 档，账单可能翻数倍。网关的关键词匹配表覆盖了 7 种轻量后缀（flash / mini / lite / air / small / turbo / haiku），确保不会把重模型填进 haiku 档。

映射写入的机制

接管确认后，网关通过 /admin/model-mappings API 写入映射记录。每条映射记录包含：

• 来源协议（source_protocol）：anthropic（Claude Code 发出的请求是 Anthropic 格式）
• 来源模型匹配（source_model_pattern）：通配符，如 claude-opus-*
• 目标协议（target_protocol）：openai（统一转成 OpenAI 格式发给上游）
• 目标模型（target_model）：探测选出的具体模型名

写入是幂等的——重复接管不会产生重复映射；写入前会先拉取现有映射清单做比对。

运行时路由规则：failover 与降级

除了接管阶段写入的静态映射，网关还支持运行时路由规则（routing rules），在请求经过网关时动态决策：

规则字段	作用
触发条件（condition_type）	什么时候触发降级，如渠道额度耗尽（quota_exhausted）
成本阈值（cost_threshold_usd）	可选：当该渠道累计成本超过阈值时触发
动作（action_type）	触发后做什么，如切换到指定备用渠道（switch_to）
目标渠道（target_channel_id）	降级到的备用渠道
目标模型（target_model）	可选：降级到备用渠道时同时切换模型

通过组合多个路由规则，你可以实现：当渠道 A 的订阅额度耗尽时自动切换到渠道 B 的按量付费端点；当某渠道 24 小时成本超限时降级到更便宜的模型。

负载均衡与优先级

当多个健康渠道可服务同一个模型时，网关按以下策略选择：

• 优先级模式（默认）：只取优先级最高的渠道；同优先级的渠道中网关按内部权重分配。
• 轮询模式（round_robin）：在所有健康候选渠道间轮流分配请求。

优先级在渠道配置中设置（数字越大优先级越高），虚拟密钥的 allowed_channels 限定可选渠道范围。

连通性测试

在渠道列表中可对单个渠道执行连通性测试。测试分两个维度：

• 端点可达性（reachable） — 检查 Base URL 是否能连通（网络与地址是否正确）。
• 密钥有效性（authenticated） — 实际调用供应商接口，验证 API Key 是否有效。仅在填写了 API Key 时才会验证。

测试结果会展示：往返延迟（毫秒）、状态徽标以及错误信息。

TIP

在添加向导中，如果端点不可达，会阻止你进入下一步；如果端点可达但密钥无效，只会给出警告，你仍可继续（例如你打算稍后再补密钥）。

高级配置

添加或编辑渠道时可展开高级配置，用于成本核算与额度控制：

• 计价倍率（Rate Multiplier） — 在供应商官方价格基础上乘以一个倍率，便于按你的真实成本或转售价核算，默认 1.0。
• 计费结构 — 说明该渠道的计费方式，如按量付费（pay as you go）、订阅（subscription）、套餐包（package）。
• 余额 — 余额来源可选固定值、OSS 账单或手动维护；选择 OSS 账单时还可指定账单类型。余额与更新时间在渠道详情中只读展示。
• 订阅到期时间 — 订阅 / 套餐包类渠道可记录到期时间。
• 额度限制 — 可按 Token 数、请求数或金额设定上限，并选择周期（每日 / 每周 / 每月 / 自定义）。额度用尽后该渠道会被自动排除出选路，是防止意外超支的安全阀。

编辑与删除渠道

• 编辑 — 在渠道列表中打开某渠道即可修改名称、Base URL、API Key、模型与高级配置。
• 删除 — 删除渠道后，依赖该渠道的虚拟密钥将无法再路由到它，请谨慎操作。

健康状态

渠道列表与 概览页 会实时展示各渠道的健康状态（正常 / 降级 / 不可用），帮助你快速发现失效的供应商配置。

常见问题（FAQ）

• Q：添加渠道时提示需要登录？
  • A：AI 网关是 ServBay 的增值功能，添加渠道 / 密钥前需登录 ServBay 账号，按界面引导登录即可。
• Q：提示渠道数已达上限？
  • A：可创建的渠道数与账号套餐相关，达到上限时可删除不用的渠道或升级套餐。
• Q：模型自动发现拉不到列表？
  • A：请先确认 Base URL 正确、API Key 有效（可用连通性测试的「密钥有效性」验证），部分供应商需要有效密钥才能返回模型列表；也可改用手动填写模型名。
• Q：接入本地的 Ollama / LM Studio 需要填 Key 吗？
  • A：通常不需要。确保对应本地服务已启动并监听默认端口（Ollama 11434、LM Studio 1234）即可。

总结

渠道是 AI 网关路由请求的基础。通过三步向导，你可以快速接入近 20 家供应商，配合双区域切换、模型自动发现与两维度连通性测试确保配置正确，再借助计价与额度等高级配置精细管理成本。配置好渠道后，即可创建 虚拟密钥 供应用与工具使用。

相关文章

• 路由与模型选择