New API 部署与接入指南

本篇包含New API的安装部署与配置指引以及一个采用标准 OpenAI 协议访问 New API 的 Python 调用示例程序。1. 项目简介1.1 到底什么是 New API简单来说New API 就是大模型时代的“统一 API 网关 / 路由器”类似于 Web 开发中的 Nginx或支付领域的“聚合支付”。在没有 New API 时不同厂商的模型OpenAI、Claude、DeepSeek、阿里通义、智谱清言、腾讯混元、本地 Ollama 等都有各自不同的接口格式、密钥体系、计费规则和调用限制。如果你的业务需要对接多个模型你的代码就必须针对每个厂商写一套适配逻辑极其繁琐。而有了 New API 之后你只需对接 New API 这一个统一入口标准的 OpenAI 协议New API 在后台负责帮你转发、调度并抹平所有底层大模型的差异。┌─── OpenAI (GPT-4o) ├─── Anthropic (Claude 3.5) 业务应用 / 客户端 │ (Python / Dify / NextChat) ───│─── DeepSeek (官方 / 硅基流动) [统一走 OpenAI 接口协议] │ http://.../v1 ├─── 阿里百炼 / 智谱清言 / 火山引擎 └─── 本地模型 (Ollama / vLLM) 【New API 统一管理与路由】 (负载均衡 · 故障转移 · 额度分发 · 审计)1.2 它具体能做什么核心功能统一接口标准格式转换将全球各种各样的大模型即使本身不是 OpenAI 格式例如 Claude、Gemini、百度千帆等全部在网关层无感转为 OpenAI 标准格式输出。客户端一行代码都不用改。多渠道聚合与负载均衡同一个模型例如deepseek-chat你可以同时配置多个上游渠道或多个 API Key。支持按权重轮询Round-Robin分发流量有效避免单一 Key 被限速Rate Limit。高可用容灾与自动故障转移Failover当主渠道因上游欠费、宕机、超时或报错如 429、500时系统自动无感重试并切换到备用渠道保障线上业务永不中断。用户与令牌权限管控多租户分发可以为不同团队、不同系统或个人创建独立的 API 访问令牌Token。支持针对每个 Token 设置调用额度上限、限制允许访问的模型白名单、过期时间及调用频率QPS/RPM。模型别名重定向Mapping可以将请求的模型名进行动态映射。例如用户客户端请求的是gpt-4后台可以直接无感映射转给成本更低的deepseek-chat或claude-3-5-sonnet业务端完全无感知。详尽的调用审计与统计看板记录每一次调用的Token 消耗明细、输入输出消耗、耗时、模型名称、调用者 IP 及日志方便成本核算与异常溯源。1.3 用了它有什么好处核心价值优势维度传统直接调用各个厂商 API引入 New API 后的优势接入成本每引入一个新模型都要修改代码学习新 SDK零迁移成本只要客户端支持 OpenAI 协议修改base_url和api_key即可直接换模型稳定可靠性单一供应商接口抖动、限流时业务直接报错中断高可用容灾多 Key 轮询与故障自动降级切换极大提高 SLA成本控制无法精细化掌握各团队/应用的 Token 消耗多维额度管控给各部门分配不同额度 Token超额自动熔断杜绝账单失控密钥安全性真实的第三方官方 API Key 暴露在各个业务端安全隔离真实密钥只保存在自建的 New API 数据库中业务方只拿内部 Token灵活性想更换性价比更高的模型需要重新发版后台一键映射通过模型重命名规则动态更换底层供应商无需重启或发布业务代码1.4 项目信息与开源协议开源协议完全开源采用 AGPL-3.0 许可证该协议具有强传染性商业化衍生改造分发时需注意源码公开合规要求。技术栈后端基于Go 语言Gin GORM构建轻量且高性能前端基于React构建现代易用的后台管理控制台。官方仓库QuantumNous/new-api基于知名开源项目 One API 深度二次开发2. 安装部署方式方式一Docker 部署推荐官方推荐在 Linux / 服务器环境下使用docker-compose快速部署具体配置可参考 官方文档。# 克隆项目 git clone https://github.com/QuantumNous/new-api.git cd new-api # 编辑 docker-compose.yml 配置 nano docker-compose.yml # 启动服务 docker compose up -d docker-compose up -d方式二原生 Windows .exe 绿色运行免安装在 Windows 环境下可直接下载单文件可执行程序免安装运行第 1 步下载程序访问 QuantumNous/new-api Releases 页面下载最新的 Windows 版本可执行文件例如new-api-v1.0.0-rc.30.exe。建议下载后可将其重命名为new-api.exe便于后续维护与脚本编写。第 2 步创建工作目录在任意磁盘分区例如D:\new-api\下新建一个文件夹将下载好的new-api.exe放入该目录。第 3 步指定端口并启动在程序所在目录打开 PowerShell执行以下命令默认监听端口为 3000$env:PORT3000;.\new-api.exe长期后台运行提示若希望开机自启并在后台静默运行可以使用 Windows 服务注册工具如 NSSM将其注册为 Windows 系统服务。第 4 步访问系统并初始化打开浏览器访问http://localhost:3000首次访问时系统会引导您进入设置向导设置超级管理员账号与密码。比如admin/admin123.登录后台后点击「令牌」Tokens生成访问密钥以sk-开头供客户端应用接入调用。第 5 步配置渠道以 DeepSeek 为例点击左侧管理员菜单栏的「渠道」Channels。点击右上角「 创建渠道」按钮。在弹出的配置页面中填写参数类型选择DeepSeek若无该选项可选择OpenAI。渠道名称自定义名称例如deepseek。API 地址默认留空即可使用内置官方地址若走第三方中转可自定义填写。API 密钥填入申请到的 DeepSeek 官方密钥。模型列表填入需要使用的模型名称例如deepseek-chat、deepseek-reasoner或deepseek-v4-flash等支持同时添加多个。模型映射可选高级功能将请求模型名称映射到实际提供商模型名称JSON 格式。若上游模型名与对外暴露名称不一致时使用如{deepseek-chat: deepseek-ai/DeepSeek-V3}。密钥添加技巧添加模式选择“批量添加每行一个密钥”可填入同平台的多个 API Key 实现自动分流亦可创建多个独立渠道分别绑定不同平台的 Key。保存后可在渠道列表右侧点击「测试」验证渠道连通性。3. 应用程序接入Python 示例New API 完全兼容OpenAI 标准协议任何支持自定义base_url的 OpenAI SDK 或客户端应用均可无缝接入。配置说明配置项说明示例Base URLNew API 提供的 OpenAI 兼容网关地址末尾需带/v1本地http://localhost:3000/v1远程http://你的服务器IP:3000/v1API Key在 New API 的「令牌」管理中创建的 Tokensk-xxxxxxxxxxxxxxxxxxxxModel在 New API 渠道中配置的模型名称deepseek-v4-flash/deepseek-chat快速运行示例1. 安装依赖pip install-r requirements.txt2. 配置环境变量修改项目根目录下的.env文件# New API 地址末尾带 /v1 OPENAI_BASE_URLhttp://localhost:3000/v1 # New API 中生成的令牌 (以 sk- 开头) OPENAI_API_KEYsk-your-token-key # 使用的模型名称 OPENAI_MODELdeepseek-v4-flash3. 执行测试python main.pyPython 核心代码 (main.py)importosimportsysfromdotenvimportload_dotenvfromopenaiimportOpenAI,OpenAIError# 适配 Windows 控制台输出编码ifsys.stdout.encodingandsys.stdout.encoding.lower()!utf-8:try:sys.stdout.reconfigure(encodingutf-8)sys.stderr.reconfigure(encodingutf-8)exceptException:passload_dotenv()defmain():base_urlos.getenv(OPENAI_BASE_URL)api_keyos.getenv(OPENAI_API_KEY)modelos.getenv(OPENAI_MODEL,deepseek-v4-flash)ifnotbase_urlornotapi_key:print(【错误】请先在 .env 文件中设置 OPENAI_BASE_URL 和 OPENAI_API_KEY)sys.exit(1)# 初始化 OpenAI 客户端clientOpenAI(base_urlbase_url,api_keyapi_key,)try:responseclient.chat.completions.create(modelmodel,messages[{role:system,content:你是一个乐于助人的 AI 助手。},{role:user,content:你好请用一句话介绍你自己并确认连接成功。},],temperature0.7,)print(【模型回复】:)print(response.choices[0].message.content)ifresponse.usage:print(f\n[Token 统计] 输入:{response.usage.prompt_tokens}| 输出:{response.usage.completion_tokens}| 总计:{response.usage.total_tokens})exceptOpenAIErrorase:print(f【请求失败】调用 NewAPI 发生异常:{e})if__name____main__:main()4. 常见问题排查 (FAQ)4.1 请求报错与异常处理Q1请求报错503 - system disk overloaded (current: 96%, threshold: 95%)现象描述调用 API 时直接返回 HTTP 503错误提示code: system_disk_overloaded。根本原因这是 New API 内置的系统级磁盘过载保护机制。当宿主机系统盘Windows 环境下默认检测 C 盘的使用率达到或超过95%时系统会主动熔断并拦截所有转发请求以避免数据库写入失败或服务崩溃。️排查与解决检查 C 盘使用率在 PowerShell 中执行Get-PSDrive C查看 C 盘已用空间。快速清理释放空间通常仅需释放 2~3 GB 即可降回 95% 以下按Win R输入%temp%清空用户临时缓存文件。清空系统桌面「回收站」。按Win R输入cleanmgr运行 Windows 自带磁盘清理工具清理临时文件与系统更新缓存。恢复C 盘使用率降到 95% 以下后无需重启 New API 即可自动恢复请求转发。Q2请求报错401 - Invalid token / 额度不足 / 用户已被封禁现象描述客户端发起请求返回 HTTP 401 认证失败。根本原因.env中的OPENAI_API_KEY填写错误或仍保留了示例中的占位符sk-your-token-key。填写的是下游模型如 DeepSeek的官方密钥而非New API 系统内生成的访问令牌Token。该令牌绑定的用户在 New API 内设定的调用额度已耗尽。️排查与解决登录 New API 控制台进入「令牌」页面。检查使用的 Token 是否为有效状态额度是否充足。点击「编辑」确认“模型范围”已勾选了当前调用的模型或设置为“全部模型”。Q3请求报错404 / 500 - 无可用渠道 (No available channel)现象描述调用时提示找不到模型或没有可用渠道提供服务。根本原因请求传入的模型名称model与 New API 渠道中配置的模型名不一致。对应的渠道已被系统临时禁用由于多次超时、连续报错或已被手动停用。️排查与解决进入「渠道」列表检查对应的渠道开关是否处于“已启用”状态。点击该渠道右侧的「测试」按钮查看上游接口是否可正常连通。检查渠道编辑页中的「模型列表」确认已包含客户端所请求的模型名如deepseek-chat。4.2 渠道调度与高可用机制Q4如何配置“多渠道负载均衡与故障转移”在 New API 中实现多 Key 轮询与多服务商容灾备份主要有两种配置方式方式一单渠道内挂载多 Key同服务商分流适用在同一家平台申请了多个 Key用来分摊并发和限频。操作编辑该渠道在「API 密钥」输入框中换行填入多个 Key一行一个系统会自动加权轮询调用。方式二创建多个独立渠道但配置相同模型名跨服务商容灾与负载均衡适用同时接入多个供应商例如官方 DeepSeek 硅基流动 火山引擎。操作分别创建对应各厂商的独立渠道并将「模型名称」都填写为相同的名字如deepseek-chat通过设置优先级与权重进行调度。Q5New API 内部是如何进行路由与故障调度的当客户端请求某个具体模型例如modeldeepseek-chat时底层调度流转机制如下客户端发起请求 ─── 命中模型池 (所有包含 deepseek-chat 的可用渠道) │ ├── ① 筛选出【最高优先级】的可用渠道 │ ├── ② 同一优先级内按【权重比例】加权轮询分发 │ └── ③ 遇故障 (429/500/超时) ── 自动无感重试并切换下一渠道 (Failover)加权轮询相同优先级的渠道New API 会根据设定的权重比例如 10 : 5 即 2 : 1分发流量。️自动故障转移Failover请求过程中若主渠道返回网络异常、500 错误或被上游 429 限速New API 会在本次请求内自动透明重试并故障降级转移到同池内的其它可用渠道客户端业务无感知报错。自动熔断与探活连续异常超阈值的渠道会被暂时熔断挂起后台周期性发起健康探测一旦恢复立即自动重回服务池。Q6各厂商模型名称不一致时如何通过「模型映射」实现负载均衡与故障转移问题背景不同平台对同一款模型的命名往往不同。例如DeepSeek 官方deepseek-chat硅基流动 (SiliconFlow)deepseek-ai/DeepSeek-V3阿里云百炼deepseek-v3火山引擎 ARKep-20250203-xxxxxx(接入点 Endpoint ID)本地 Ollamadeepseek-r1:32b如果直接按原名添加渠道客户端就无法将它们汇入同一个模型池做负载均衡和互备容灾。️核心解法使用渠道高级设置中的「模型映射 (Model Mapping)」核心思想“对外统一叫一个名字汇入同一模型池对内转发给上游时由 New API 自动翻译为供应商实际的模型名。”JSON 配置语法{客户端请求的统一模型名:上游服务商实际真实模型名}多厂商统一聚合实战配置以客户端统一调用deepseek-chat为例渠道渠道名称模型列表对外暴露模型映射JSON 配置说明渠道 1DeepSeek 官方deepseek-chat(留空)官方原生名称即为deepseek-chat渠道 2硅基流动deepseek-chat{deepseek-chat: deepseek-ai/DeepSeek-V3}转发时自动重写为硅基流动的模型名渠道 3火山引擎deepseek-chat{deepseek-chat: ep-20250203-xxxxxx}转发时自动替换为火山引擎接入点 ID⚠️避坑与深度解析关于截图中黄色警告提示的含义黄色提示详解如截图中提示添加 gpt-3.5-turbo 到模型列表以便用户在映射将流量发送到上游之前可以使用它们。这不是要求系统中必须存在真实的 OpenAI/gpt-3.5-turbo 渠道其真实含义是你在映射规则中写了gpt-3.5-turbo: deepseek-v4-flash允许用户请求gpt-3.5-turbo但是当前渠道的「模型列表」中尚未勾选或录入gpt-3.5-turbo。底层逻辑New API 收到客户端请求时首先通过渠道的「模型列表」来筛选“谁支持此模型”。如果当前渠道的模型列表里没有声明gpt-3.5-turbo请求就会直接将其跳过根本走不到映射步骤。解决方式直接点击提示右侧的「添加缺失模型」按钮系统就会自动将对外暴露的模型名添加到当前渠道的模型列表中。跨模型/跨家族降级容灾进阶甚至可以对外提供一个统一虚拟名称如primary-chat或xxxx主渠道高优先级映射为deepseek-chat备用渠道低优先级映射为gpt-4o-mini。平时享受极低成本一旦 DeepSeek 突发大面积宕机或 429 限流New API 自动透明降级切换至 OpenAI 兜底保障核心业务永续可用至关重要的原则左边可虚拟右边必真实{xxxx:gpt-4o-mini↑ ↑ 左边右边(完全自定义)(必须是该厂商真实模型)左边Key / 请求模型名可以天马行空是任何你自定义的名字如xxxx、my-bot也可以是其他厂商的名字。唯一要求必须在当前渠道的「模型列表」中勾选或录入该名字。右边Value / 目标模型名必须是当前渠道服务商真实支持、且你的密钥有权限调用的模型名因为 New API 转发时会将右边的名字直接写入发送给上游服务商的数据体Payload中。如果右边填了该厂商没有的模型上游官方服务器会直接拒收报错如 OpenAI 报错404 Model Not Found。5. 邮件服务配置以 QQ 邮箱为例配置 SMTP 邮件服务后系统可支持新用户注册邮箱验证码、绑定邮箱、密码找回以及系统告警通知等功能。第一步配置前准备获取 QQ 邮箱授权码⚠️重要提示这是最关键的一步密码栏填的是授权码不是你的 QQ 登录密码。访问 QQ 邮箱网页版https://mail.qq.com建议切换到电脑版模式手机浏览器需勾选“请求桌面站点”。进入设置点击顶部“设置”齿轮图标 -“邮箱设置”。注意路径进入设置页后请点击顶部的“帐户”标签不是左侧或下方的“安全设置”。生成授权码向下滚动到“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”区域点击“生成授权码”。获取并保存验证后获取一串 16 位字母组合如abcdefghijklmnop复制保存只显示一次。第二步New API 后台填写配置进入 New API 后台“系统设置”-“邮箱设置”严格按照以下参数填写配置项填写内容QQ邮箱专用SMTP 服务器地址smtp.qq.comSMTP 端口465必须填 465强制 SSL 加密用户名你的完整邮箱地址如123456789qq.com密码粘贴刚才生成的 16 位授权码不是 QQ 密码发件人邮箱与用户名保持一致如123456789qq.com发件人昵称随意如New API加密方式选择SSL/TLS填写完毕后点击页面底部的“保存”按钮。第三步验证邮箱设置是否正确添加用户在管理后台添加用户设置用户名和密码。登录账户打开网页以新的用户名和密码登录。绑定邮箱验证进入设置页面绑定邮箱。如果邮箱成功收到了验证码说明 SMTP 邮件服务设置成功。