logo

New API 大模型网关部署与使用指南

作者:狼烟四起2026.11.17 03:21浏览量:1

简介:本文面向需要统一接入多家大模型的开发者和团队,讲解 New API 的核心能力、Docker 部署、千帆渠道配置、OpenAI 兼容调用,以及生产环境的安全与成本治理。读完后,你可以独立搭建一套可用的模型网关,并避免部署和升级中的常见风险。

一、New API 是什么

New API 是基于 One API 发展而来的开源 AI 大模型网关与资产管理系统。它位于业务应用和多家模型服务商之间。业务系统只需要对接 New API 提供的 OpenAI 兼容接口,网关再根据渠道配置、模型映射和权限规则,把请求转发到实际的上游模型。

团队引入这类网关,通常是为了解决以下五类问题:

  1. 多模型接入复杂:不同厂商的 API 协议、鉴权方式和返回结构各不相同。
  2. 模型迁移成本高:业务代码直接绑定某一家模型时,切换供应商需要大量改造。
  3. 成本与配额难管理:多个团队共用模型时,需要按应用、用户或模型统计 Token 并限流。
  4. 稳定性要求高:单一上游服务异常时,需要路由切换、重试和限流保护。
  5. 安全合规要求提升:企业需要密钥管理、权限控制、调用审计和私有化部署能力。

New API 以 Go 语言和 Gin 框架编写,整体是一个模块化的单体服务。它支持 Docker 部署,兼容 SQLite、MySQL、PostgreSQL 等数据库。个人用户可以使用轻量配置快速起步。企业场景则需要通过多实例部署、共享数据库和负载均衡来提高可用性。项目的开源协议以仓库根目录的 LICENSE 文件为准,选型和二次开发前请先阅读该文件。

二、核心能力:统一入口、路由分发与协议适配

New API 的能力可以归纳为四个方面:统一入口、协议适配、路由与高可用、运营治理。

1. OpenAI 兼容接口

New API 对外提供 OpenAI 兼容接口。原本使用 OpenAI SDK 或 HTTP 请求调用模型的应用,只需修改 Base URL 和令牌,就能接入网关。客户端仍然请求 /v1/chat/completions,实际转发到哪个上游模型由网关决定。

这种方式适合以下场景:

  • 从 OpenAI API 迁移到国内模型服务;
  • 同时接入多家厂商,但业务层只维护一套调用代码;
  • 为不同团队提供统一的模型调用入口;
  • 在测试、预发布和生产环境之间切换模型。

2. 渠道映射与模型别名

渠道是 New API 管理上游服务的基本单位。每个渠道包含上游地址、密钥和可用模型列表。模型映射的作用是把客户端请求的模型名转换为上游的真实模型名。例如,映射关系为 yi-large 指向 yi-large-1.5t 时,业务请求 yi-large 会被转发到 yi-large-1.5t。

模型别名的价值在于解耦。上游模型版本升级时,业务代码无需修改,只需在网关后台调整映射即可完成切换。映射的具体填写格式以控制台页面提示为准。

3. 负载均衡与高可用

同一个模型配置多个渠道时,网关可以按权重、优先级或可用性进行分发。生产环境建议至少具备以下能力:

  • 多渠道冗余:同一模型配置多个上游服务;
  • 失败重试:对超时、限流和临时错误做有限次数的重试;
  • 健康检查:定期探测渠道可用性;
  • 限流保护:避免异常流量拖垮上游服务;
  • 监控告警:观测调用量、错误率、延迟和 Token 消耗。

官方文档或宣传中的可用性数字需要结合自身环境验证。上线前应结合真实流量模型做压测,不能只依赖单一指标。

三、Docker 部署

New API 通常使用 Docker Compose 同时启动应用和数据库。下面的配置是示意模板,镜像版本和密钥都需要替换为实际值。镜像名以官方仓库的 README 为准,常见名称为 calciumion/new-api。

  1. services:
  2. new-api:
  3. image: calciumion/new-api:<官方发布的固定版本号>
  4. container_name: new-api
  5. restart: always
  6. ports:
  7. - "3000:3000"
  8. environment:
  9. - SQL_DSN=postgresql://newapi:${POSTGRES_PASSWORD}@postgres:5432/newapi
  10. - SESSION_SECRET=${SESSION_SECRET}
  11. - TZ=Asia/Shanghai
  12. depends_on:
  13. - postgres
  14. postgres:
  15. image: postgres:16
  16. container_name: new-api-postgres
  17. restart: always
  18. environment:
  19. - POSTGRES_USER=newapi
  20. - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
  21. - POSTGRES_DB=newapi
  22. volumes:
  23. - pgdata:/var/lib/postgresql/data
  24. volumes:
  25. pgdata:

密码和密钥不要写进 Compose 文件,应放在同目录的 .env 文件中,并把 .env 加入 .gitignore。启动命令如下:

  1. docker compose up -d
  2. docker compose logs -f new-api

启动后,通过 http://服务器IP:3000 访问管理界面。首次进入时,先初始化管理员账号并修改默认密码。

正式对外使用前,还需要完成以下配置:

  • 反向代理与 TLS:使用 Nginx 或 Caddy 提供 HTTPS,不要把 3000 端口直接暴露到公网;
  • 访问控制:管理后台限制可访问的 IP 段,并启用强密码;
  • 数据备份:定期导出数据库,例如执行 docker exec new-api-postgres pg_dump -U newapi newapi > backup.sql;
  • 运维接入:把容器日志和监控指标接入统一的日志与告警平台。

企业环境中,应使用共享数据库,将多个 New API 实例放在负载均衡器之后,并对数据库做备份和高可用配置。

四、接入百度智能云千帆

如果你还在选型阶段,可以先参考百度智能云词元所,了解模型能力、价格与接入方式,再决定 New API 中使用哪些上游渠道和模型组合。

百度智能云千帆大模型平台提供模型调用、应用开发和模型精调等服务。在 New API 中接入千帆时,需要在控制台创建 API Key,并在网关中新建对应类型的渠道。渠道类型名称会随版本变化,请以所用版本的控制台列表为准。

渠道关键配置如下:

配置项 说明 注意事项
渠道类型 与上游协议匹配的类型,例如百度文心千帆相关类型或 OpenAI 兼容类型 以控制台可选项为准
Base URL 上游服务的接口地址 以服务商文档为准,不要混用
API Key 上游服务的密钥 只保存在网关后台,不写入代码
模型列表 允许该渠道转发的模型名称 只添加实际需要的模型
模型映射 客户端模型名与上游模型名的对应关系 业务侧使用别名,便于后续替换
权重与优先级 多渠道时的分发策略 主备可用优先级,灰度可用权重

配置完成后,按以下顺序操作:

  1. 在千帆控制台创建 API Key;
  2. 在 New API 中新建渠道,填写上表中的配置项;
  3. 点击测试,确认渠道连通;
  4. 创建令牌,设置可用模型和额度上限;
  5. 把令牌分发给业务应用使用。

如果业务需要长上下文能力,可以评估 ERNIE-4.0-Turbo-128K 等模型。具体模型名称和可用性以千帆控制台的模型列表为准。

五、协议适配与调用示例

New API 接收客户端的 OpenAI 格式请求,识别目标模型,再把请求转发到对应渠道,并完成必要的协议转换。业务侧只关心 model 和 messages 等字段。

使用 curl 调用的示例如下:

  1. curl http://localhost:3000/v1/chat/completions \
  2. -H "Authorization: Bearer sk-your-token" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "model": "ernie-4.0-turbo-128k",
  6. "messages": [
  7. {
  8. "role": "user",
  9. "content": "请用一句话解释什么是大模型网关"
  10. }
  11. ]
  12. }'

Python 开发者可以直接使用 OpenAI SDK,只需修改 base_url 和 api_key。本示例需要 openai 1.x 及以上版本,旧版 0.x 的调用方式与此不同。

  1. from openai import OpenAI
  2. client = OpenAI(
  3. api_key="sk-your-token",
  4. base_url="http://localhost:3000/v1"
  5. )
  6. response = client.chat.completions.create(
  7. model="ernie-4.0-turbo-128k",
  8. messages=[
  9. {"role": "user", "content": "请介绍 New API 的主要作用"}
  10. ]
  11. )
  12. print(response.choices[0].message.content)

如果以后需要更换供应商,只要修改网关中的渠道或模型映射。业务代码通常不需要改动。

六、企业落地:Token 管理、成本治理与安全

New API 不只是转发工具,也是企业 AI 资产的管理入口。多团队、多应用、多模型的场景尤其需要以下治理措施。

1. Token 与配额管理

不同模型的价格和性能差异较大。对高成本模型,建议采取更严格的策略:

  • 按应用分配 Token 配额;
  • 按用户或租户设置调用上限;
  • 对高成本模型启用审批或白名单;
  • 对异常调用设置告警;
  • 定期分析各业务线的 Token 消耗。

选型时,不要只比较单价。还要综合评估效果、上下文长度、并发能力、稳定性和迁移成本。

2. 安全与版本管理

支付、充值和计费功能风险较高,需要持续关注。建议执行以下措施:

  • 关注官方安全公告,确认所用版本是否已修复已知问题;
  • 检查支付、计费、充值和权限相关的配置与逻辑;
  • 对管理后台启用强认证,限制高风险接口的访问来源;
  • 定期审计 API Key、令牌和渠道配置;
  • 对异常充值、异常额度和异常调用设置监控。

升级版本时,建议按以下步骤进行:

  1. 备份数据库,并记录当前镜像的版本号;
  2. 在测试环境部署新版本,验证协议兼容性、计费和充值逻辑;
  3. 在低峰期升级生产环境,观察日志和错误率;
  4. 如果出现问题,回退到已记录的旧版本镜像,并恢复备份。

3. 运营看板与可观测性

New API 提供可视化运营看板,可以查看调用量、模型分布、错误率和资源消耗。企业环境中,建议把这些指标接入统一的日志、指标和告警平台,便于快速定位问题。

七、适用场景与最佳实践

New API 适合以下场景:

  • AI 应用统一接入层:业务系统通过同一接口调用多个模型;
  • OpenAI 迁移过渡层:逐步把调用从 OpenAI 切换到国内模型服务;
  • 多租户模型管理平台:不同团队共享模型资源,并按配额分配;
  • 模型灰度与 A/B 测试:通过渠道权重切换不同模型;
  • 私有化 AI 基础设施:在企业内网部署网关,统一管理模型资产。

实践中建议注意以下几点:

  1. 不要把所有模型放进同一个默认渠道,应按业务场景拆分渠道。
  2. 关键业务配置多渠道冗余,避免单点故障。
  3. 规范模型别名,避免业务代码绑定具体版本。
  4. 为高成本模型设置独立配额和告警。
  5. 定期审查渠道密钥、令牌和权限配置。
  6. 升级前先在测试环境验证协议兼容性和计费逻辑。
  7. 对支付、充值和管理后台相关功能保持更高的安全优先级。

New API 的价值在于通过统一接口、路由、协议适配和运营治理,把大模型服务变成可管理、可计量、可扩展的基础设施。团队可以先从模型选型和调用管理入手,再逐步完善网关的高可用、安全与成本治理体系。

发表评论

活动