new-api 系列（三）：渠道配置——接入各类模型提供商

new-api渠道配置OpenAIAnthropicGemini模型映射教程

系列目录

  1. （一）认识 new-api——新一代 AI API 管理网关
  2. （二）安装部署——从零搭建 new-api
  3. （三）渠道配置——接入各类模型提供商（本文）
  4. （四）令牌与用户管理
  5. （五）计价模型与成本控制
  6. （六）监控、日志与告警
  7. （七）生产环境部署与安全加固
  8. （八）进阶——多实例、负载均衡与 SSO
  9. （九）接入国内支付——支付宝、微信与自动充值
  10. （十）接入国际支付——Stripe、PayPal 与海外收银
# 渠道配置 ## 渠道是什么 - 上游模型提供商的连接配置 - 包含：类型、地址、密钥、模型列表 - 一个渠道 = 一个上游账号/实例 ## 渠道类型 - OpenAI 兼容（最常用） - Anthropic 原生 - Gemini 原生 - Azure OpenAI - 自定义（Ollama / vLLM / LocalAI） ## 模型管理 - 从服务器获取模型列表 - 手动添加/删除模型 - 模型映射（别名机制） - 批量导入 ## 渠道优先级 - 权重：负载分配比例 - 优先级：主备关系 - 故障自动切换 ## 健康检查 - 定时测试连通性 - 自动禁用不健康渠道 - 自动恢复检测 - Webhook 通知

渠道的概念

在 new-api 中，渠道（Channel） 是一个上游模型提供商的连接入口。每个渠道包含：

  • 类型：决定 new-api 用什么协议与上游通信（OpenAI 兼容 / Anthropic / Gemini / Azure 等）
  • 密钥：上游提供商的 API Key，多个 Key 可换行分隔
  • 模型列表：该渠道能提供哪些模型
  • 代理地址：如果上游不是标准地址，填自定义 Base URL

一个 new-api 实例可以有多个渠道。比如：

  • 渠道 A：OpenAI 官方 API（gpt-4o, gpt-4o-mini）
  • 渠道 B：Azure OpenAI（gpt-4o-eu）
  • 渠道 C：Anthropic API（claude-sonnet-4-6, claude-opus-4-8）
  • 渠道 D：本地 Ollama（llama3:70b）

用户请求 gpt-4o 时，new-api 会自动匹配有该模型的渠道。

flowchart LR REQ["用户请求\ngpt-4o"] --> NW["new-api\n模型 → 渠道匹配"] NW --> CH1["渠道 A\nOpenAI 官方"] NW --> CH2["渠道 B\nAzure OpenAI"] CH1 -->|"API Key A"| UP1["api.openai.com"] CH2 -->|"API Key B"| UP2["azure.openai.com"]

渠道类型详解

类型一：OpenAI 兼容（最常用）

这是最通用的类型。任何提供 OpenAI 格式 API 的服务都可以用这个类型接入，包括：

  • OpenAI 官方
  • DeepSeek
  • 通义千问（DashScope）
  • 月之暗面（Moonshot）
  • 智谱（GLM）
  • Ollama / vLLM / LocalAI（本地模型）
  • CLIProxyAPI（OAuth 订阅代理）

添加步骤：

进入后台 →「渠道」→「添加渠道」，类型选择「OpenAI」：

字段 填写 示例
名称 自定义 DeepSeek-官方
代理 Base URL（留空用默认 https://api.openai.com/v1） https://api.deepseek.com/v1
密钥 API Key sk-xxxxxxxx（多个换行）
模型 勾选模型 deepseek-chat, deepseek-reasoner
flowchart LR A["添加渠道\n类型：OpenAI"] --> B["填写密钥 + 代理地址"] B --> C["从服务器获取模型"] C --> D["勾选需要的模型"] D --> E["测试 → 保存"]

常见提供商的代理地址：

提供商 代理（Base URL）
OpenAI 官方 留空或 https://api.openai.com/v1
DeepSeek https://api.deepseek.com/v1
通义千问 https://dashscope.aliyuncs.com/compatible-mode/v1
月之暗面 https://api.moonshot.cn/v1
智谱 GLM https://open.bigmodel.cn/api/paas/v4
Ollama 本地 http://localhost:11434/v1
CLIProxyAPI http://localhost:8317/v1

类型二：Anthropic 原生

如果你的上游是 Anthropic 官方 API（非 OpenAI 兼容格式），选这个类型。new-api 会自动做协议转换，让下游以 OpenAI 格式调用 Claude 模型。

字段 填写
类型 Anthropic
密钥 Anthropic API Key（sk-ant- 开头）
模型 claude-sonnet-4-6、claude-opus-4-8 等

注意：如果你接入的是已经做过 OpenAI 兼容转换的服务（如 CLIProxyAPI），应该用 OpenAI 类型而不是 Anthropic 类型。

类型三：自定义（Ollama / vLLM / LocalAI）

本地部署的模型服务，选「自定义」类型。它的行为和 OpenAI 兼容类似，但可以更灵活地适配小众 API 格式。

类型四：Azure OpenAI

Azure 的 OpenAI 服务需要额外填写资源名称和 API 版本：

字段 填写
类型 Azure
代理 https://{resource-name}.openai.azure.com
API 版本 2024-06-01（按 Azure 实际版本填）
密钥 Azure API Key

模型管理

从服务器自动获取

添加渠道后，点「从服务器获取模型」按钮，new-api 会调用上游的 /v1/models 接口自动拉取模型列表。拉回来后勾选你需要的，不提供的不要勾——减少用户的选择复杂度。

手动添加模型

如果上游没有 /v1/models 接口，或你想限制可用的模型子集，可以手动输入模型名，每行一个：

gpt-4o
gpt-4o-mini
gpt-4-turbo

模型映射（别名机制）

模型映射让你给模型起别名，或把不同渠道的同功能模型统一命名。

场景一：统一名称

你有两个渠道都提供 GPT-4o，但一个叫 gpt-4o，一个叫 gpt-4o-2024-08-06。在映射中统一：

gpt-4o:gpt-4o
gpt-4o:gpt-4o-2024-08-06

格式：对外名称:渠道内实际名称。用户请求 gpt-4o 时，两个渠道都能匹配。

场景二：短别名

给冗长的模型名起个好记的别名：

sonnet:claude-sonnet-4-6
opus:claude-opus-4-8
haiku:claude-haiku-4-5-20251001
flash:gemini-3.5-flash

场景三：多对一映射

不同渠道提供名称不同但功能相同的模型，统一映射到同一个对外名称：

渠道 A（OpenAI）：

fast-model:gpt-4o-mini

渠道 B（DeepSeek）：

fast-model:deepseek-chat

用户请求 fast-model 时，new-api 在两个渠道中根据权重选择。

模型映射的高级用法：来源名与实际模型

如果你想让用户看到的模型名和渠道内实际模型名不同，在渠道的「模型映射」区域填写：

用户看到的名称:渠道实际模型名

例如将 Anthropic 渠道的模型暴露为简化名：

claude-sonnet:claude-sonnet-4-6-20250514
claude-opus:claude-opus-4-8-20250601
claude-haiku:claude-haiku-4-5-20251001

多 Key 轮询

一个渠道可以填多个 API Key（每行一个），new-api 会在多个 Key 之间轮询。这对于有多个 OpenAI 账号、希望分摊额度的场景很有用。

sk-key-account-1
sk-key-account-2
sk-key-account-3

注意：同一渠道的多 Key 轮询是简单的 round-robin，不感知每个 Key 的剩余额度。如果需要更智能的配额管理，建议每个 Key 单独建一个渠道，然后通过权重控制分发。

渠道优先级与权重

当多个渠道都提供同一个模型时，new-api 根据「优先级」和「权重」决定请求走哪个渠道。

优先级模式

  • 优先级高的渠道优先使用。优先级相同的渠道之间按权重分配。
  • 如果高优先级渠道故障（连续失败），自动 fallback 到下一优先级。

权重模式

同一优先级内的多个渠道，按权重比例分配流量：

渠道 A：权重 70 → 70% 流量
渠道 B：权重 30 → 30% 流量

配置建议

渠道 A（OpenAI 官方）：优先级 1，权重 100
渠道 B（Azure OpenAI）：优先级 2，权重 100（备份）
渠道 C（DeepSeek）：     优先级 1，权重 50
渠道 D（通义千问）：     优先级 1，权重 50
flowchart LR REQ["请求 gpt-4o"] --> CHECK{"优先级 1\n渠道健康?"} CHECK -- A 健康 --> A["渠道 A（主）\n权重 100"] CHECK -- A 故障 --> B["渠道 B（备）\n优先级 2"] A --> UP["上游"] B --> UP

渠道健康检查

new-api 可以定时向渠道发送测试请求，自动检测渠道是否正常。

开启健康检查

在渠道列表页，找到渠道，开启「自动禁用」开关。

配置项 建议值 说明
检测间隔 300 秒（5 分钟） 过于频繁会增加上游开销
连续失败次数 3 次 避免偶发网络波动误判
自动恢复 开启 渠道恢复后自动重新启用

健康检查的工作流程

flowchart LR T["定时器触发\n每 5 分钟"] --> CH["向渠道发测试请求"] CH --> R{成功?} R -- 是 --> OK["标记健康\n继续使用"] R -- 否 --> F{连续失败 ≥ 3?} F -- 否 --> RETRY["等待下次检测"] F -- 是 --> BAN["自动禁用渠道\n触发 Webhook 通知"] BAN --> RECOV["定时尝试恢复"] RECOV --> R

Webhook 通知

在「设置 → 通用设置」中配置 Webhook URL，渠道状态变化时会收到通知：

{
  "type": "channel_disabled",
  "channel_name": "OpenAI-官方",
  "reason": "连续 3 次健康检查失败",
  "timestamp": 1749135600
}

支持的 Webhook 平台：钉钉、飞书、企业微信、Slack、Discord、自定义 HTTP。

渠道测试

添加渠道后，一定先点「测试」按钮确认连通性。测试会向渠道发送一个最小请求（hi 消息），验证：

  • API 地址是否可达
  • API Key 是否有效
  • 返回格式是否被 new-api 正确解析

测试通过后保存。如果测试失败，检查：

  1. 网络连通性（curl 代理地址试试）
  2. API Key 是否正确
  3. 代理地址末尾是否有 /v1
  4. 有没有配置 HTTPS 代理（国内服务器访问 OpenAI 可能需要）

多渠道实战示例

假设你有以下资源：

  • 1 个 OpenAI API Key（有 gpt-4o, gpt-4o-mini）
  • 1 个 Anthropic API Key（有 claude-sonnet-4-6, claude-opus-4-8）
  • 1 个 DeepSeek API Key（有 deepseek-chat, deepseek-reasoner）
  • 1 台跑 Ollama 的本地服务器（有 llama3:70b）

你的渠道配置：

渠道名 类型 模型 优先级
OpenAI-官方 OpenAI gpt-4o, gpt-4o-mini 1
Anthropic-官方 Anthropic claude-sonnet-4-6, claude-opus-4-8 1
DeepSeek-官方 OpenAI deepseek-chat, deepseek-reasoner 1
Ollama-本地 OpenAI llama3:70b 2

用户通过同一个 sk- 令牌，可以请求这四个渠道上的所有模型。new-api 自动路由，用户无需关心模型来自哪个提供商。

系列导航

系列导航

实操清单

  • 添加 OpenAI 兼容渠道（CLIProxyAPI，type 1，已激活）
  • 添加第二个不同类型渠道（deepseek，type 43，已激活）
  • 两个渠道状态均为 active（status=1），已通过连通测试
  • 用「从服务器获取」拉取各渠道的实际模型列表，确认模型覆盖完整
  • 配置模型映射（别名），将上游模型名统一为用户友好的名称
  • 如有多个上游账号，为同一渠道配置多 Key 轮询
  • 为两个渠道设置优先级（priority）和权重（weight）策略（当前均为默认值 0）
  • 开启每个渠道的健康检查（自动禁用故障渠道 + 自动恢复）
  • 配置 Webhook 通知（可选，渠道故障时推送钉钉/飞书/企业微信）