QuantumNous/new-api · 上手攻略
- 仓库：QuantumNous/new-api
- 链接：https://github.com/QuantumNous/new-api
- 分类：llm-infra
- 作者：Jay
- 更新：2026-07-06
这是什么
new-api 是一个统一 AI 模型网关，核心功能是把来自不同供应商的 LLM（OpenAI、Claude、Gemini、DeepSeek 等）聚合到一个入口，通过格式转换（Format Bridge）让它们互相兼容，并以统一 API 暴露给下游应用。
简单类比：AI 领域的 Nginx + 多路复用代理，支持渠道加权随机调度、自动失败重试、Token 级权限控制、用量统计和计费管理。底层基于 One API（MIT）开发，使用 Go 语言编写。
官方定位：个人 LLM API 管理 + 企业多渠道聚合网关。
解决什么问题
痛点场景： - 多供应商管理混乱：同时在用 OpenAI、Claude、Gemini、DeepSeek，每家 API 格式不同，下游应用要写多套适配 - 成本不透明：团队多人共用账号，无法追踪谁用了多少 - Key 暴露风险：API Key 直接写在代码里 - 模型切换麻烦：想从 GPT-4 切到 Claude，需要改代码 - 私有化部署需求：企业内网不能用外部 API，需要本地模型网关
new-api 的解法：所有模型统一暴露为 OpenAI兼容/Claude兼容/Gemini兼容格式，应用层只对接一个端点。
快速安装
Docker 方式（推荐，最快）
# SQLite 版本（开箱即用，数据存在本地）
docker run --name new-api -d --restart always \
-p 3000:3000 \
-e TZ=Asia/Shanghai \
-v $(pwd)/data:/data \
calciumion/new-api:latest
# MySQL 版本
docker run --name new-api -d --restart always \
-p 3000:3000 \
-e SQL_DSN="root:yourpassword@tcp(localhost:3306)/newapi" \
-e TZ=Asia/Shanghai \
-v $(pwd)/data:/data \
calciumion/new-api:latest
启动后访问 http://localhost:3000，默认管理员账号密码在首次启动时显示（通常为 root / 123456，请立即修改）。
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
宝塔面板（一键安装）
- 安装宝塔面板 ≥ 9.2.0
- 在应用商店搜索 "New-API"
- 一键部署
核心配置与使用
配置上游渠道（Channel）
- 登录管理后台 → 渠道 → 添加渠道
- 选择模型类型（OpenAI / Claude / Gemini 等）
- 填入上游 API Key 和 Base URL
- 设置权重（用于加权随机调度）
支持的模型类型：
| 类型 | 说明 |
|---|---|
| OpenAI 兼容 | OpenAI 全系列、Azure OpenAI |
| Claude Messages | Anthropic Claude 全系列 |
| Google Gemini | Gemini 全系列 |
| OpenAI Responses | 最新 OpenAI Responses API |
| OpenAI Realtime | 实时语音/视频 API（含 Azure） |
| Rerank | Cohere、Jina Rerank |
| Midjourney-Proxy | 图像生成 |
| Suno API | 音乐生成 |
| 自定义上游 | 支持配置任意合法 API 端点 |
格式转换配置
在渠道编辑的 Channel Extra Settings 中可开启：
- thinking_to_content: true —— 将 Claude/Gemini 的思维链内容（reasoning_content）以 <thinking> 标签追加到回复末尾
推理强度（Reasoning Effort）配置
通过模型名称后缀控制（无需额外配置）：
OpenAI o3-mini-high → 高推理强度
OpenAI o3-mini-medium → 中推理强度
OpenAI o3-mini-low → 低推理强度
Claude: claude-3-7-sonnet-20250219-thinking → 开启思维模式
Gemini: gemini-2.5-flash-thinking → 开启思维模式
Gemini: gemini-2.5-pro-thinking-128 → 128k 思维预算
创建 Token 并授权
- 令牌 → 创建令牌
- 设置该 Token 可访问的模型范围
- 设置每日/每月用量上限
- 将 Token 分发给团队成员
下游应用使用时，API Key 即为该 Token，Base URL 指向你的 new-api 部署地址。
智能路由
- 加权随机：多渠道配置权重后，自动按比例分配请求
- 失败自动重试：在"系统设置 → 操作设置 → 失败重试次数"中配置
- 用户级别限流：可为不同 Token 设置独立的 QPS 上限
典型使用场景
| 场景 | 价值 |
|---|---|
| 团队共享付费 API | Token 级隔离 + 用量统计，谁用了多少一目了然 |
| 私有化 LLM 部署 | 对接内网 vLLM / Ollama，统一出口 |
| 多模型 A/B 测试 | 同一 Prompt 发给多个模型，对比输出质量 |
| 成本管控 | Token 级消费限额，防止某个调用者耗尽配额 |
| 统一认证网关 | 不把 Key 暴露给应用，只暴露 Token |
| 模型聚合展示 | 一个面板管理所有渠道 |
坑与注意
- 必须设置 SESSION_SECRET：单机器部署可选；多机器共享 Redis 时必须设置
CRYPTO_SECRET，否则 Redis 中的数据无法正确解密。 - AGPL-3.0 许可：这是传染性开源协议，改动必须开源。如果你的商业产品不能接受 AGPL，可以联系
support@quantumnous.com谈商业授权。 - 计费仅做参考：缓存命中计费等高级功能是企业版能力，开源版提供基础统计，不保证金融级精度。
- 格式转换有局限：Gemini → OpenAI 兼容模式暂不支持 function calling；OpenAI ↔ OpenAI Responses 仍在开发中。
- Docker 数据持久化：务必挂载
./data:/data，否则容器重建后所有渠道配置和 Token 数据丢失。 - 不要把 new-api 直接暴露公网：管理后台有管理员账号密码，公网裸奔风险极高，建议放在 VPN 或内网后，或至少开启登录验证码。
与同类对比
| 方案 | 语言 | 格式转换 | 权限系统 | 适用场景 |
|---|---|---|---|---|
| new-api | Go | ✅ 跨格式（OpenAI↔Claude↔Gemini） | Token 级 + 渠道级 | 多供应商聚合 + 计费 |
| One API | Go | ❌ 仅 OpenAI 兼容 | Token 级 | 简单渠道管理 |
| API King | Go | ❌ | 简单 | 个人用量管理 |
| Flask + 手动路由 | Python | ❌ | DIY | 定制化极高的小团队 |
| PortKey | 云服务 | ✅ | ✅ | 不想自建，但需要观测 |
| Helicone | 云服务 | ❌ | 基础 | 纯用量观测 |
new-api 在自建网关赛道中格式转换能力最强，是 One API 的重要增强版；相比云服务 PortKey 等，优势是完全自主部署、数据不外流。
一句话推荐结论
如果你管理着多渠道 LLM API（不管是自己团队用还是企业客户用），new-api 是目前最完整的开源聚合网关方案——format bridge 让切换模型不需要改代码，Token 级权限和用量统计让 API 管理从混乱变清晰。
来源
- GitHub README：https://github.com/QuantumNous/new-api
- 官方文档：https://docs.newapi.pro/en/docs
- Docker 镜像：
calciumion/new-api:latest - 底层基于 One API (MIT)：https://github.com/songquanpeng/one-api