One Api：大语言模型 API 管理和分发系统

共计 6252 个字符，预计需要花费 16 分钟才能阅读完成。

什么是 One API？

One API 是一个功能强大的开源 LLM（大语言模型）接口管理和分发系统。它通过统一的 OpenAI API 格式，让用户可以轻松访问来自不同厂商的各种大语言模型。作为一个中间层解决方案，One API 充当了用户应用和多个 AI 模型提供商之间的桥梁，实现了模型的统一管理、分发和控制。

这个项目由开发者 songquanpeng 精心开发，已在 GitHub 上获得 27.7k 星标，拥有超过 138 名贡献者，是业界非常受欢迎的开源项目。该项目完全开源，采用 MIT 许可证，用户可以自由下载、修改和部署。

One Api：大语言模型 API 管理和分发系统

核心价值主张

One API 的核心价值在于其开箱即用的特性——通过标准的 OpenAI API 格式访问所有的大模型。这意味着无论底层使用的是哪个 AI 厂商的服务，用户都可以用统一的接口来调用它们，大大简化了开发流程和系统架构。

One API 支持的模型种类

One API 的一个重大亮点是对多种大语言模型的广泛支持，覆盖了几乎所有主流的 AI 服务厂商：

国际主流模型

OpenAI 系列：ChatGPT 系列模型，支持 Azure OpenAI API
Anthropic Claude：支持 AWS Claude 部署方式
Google 系列：PaLM2 和 Gemini 系列模型
其他国际服务：Mistral、Groq、Cohere、xAI 等

国内模型

字节跳动豆包大模型（火山引擎）
百度文心一言系列模型
阿里通义千问系列模型
讯飞星火认知大模型
智谱 ChatGLM 系列模型
360 智脑
腾讯混元大模型
Moonshot AI
百川大模型
MINIMAX
零一万物
阶跃星辰

其他支持

本地模型：Ollama
多个第三方服务：Cloudflare Workers AI、DeepL、together.ai、novita.ai、硅基流动 SiliconCloud 等

这种全面的模型支持意味着用户可以在一个平台上灵活切换不同的模型提供商，充分利用各家模型的优势特性。

One API 的核心优势

统一的 API 接口

最核心的优势是统一性。One API 通过标准的 OpenAI API 格式将所有不同厂商的模型进行了适配。这带来的好处是显而易见的：开发者只需要学习一套 API 接口规范，就可以与数十个不同的模型提供商进行交互，无需针对每个提供商单独开发适配层。

灵活的负载均衡

One API 支持通过负载均衡的方式访问多个渠道。这意味着当一个模型提供商出现故障或性能下降时，系统可以自动将请求转移到其他可用的渠道。这对于关键业务系统至关重要，可以显著提升系统的可靠性和稳定性。

完整的令牌管理系统

系统提供了强大的令牌（Token）管理功能，允许用户设置令牌的过期时间、配置使用额度限制、设定允许的 IP 范围，以及限制令牌可访问的模型列表，实现细粒度的权限控制。这使得 One API 适合在企业环境中使用，可以为不同的用户、团队或客户分配不同权限的令牌。

多渠道管理和分组功能

One API 允许管理员创建多个渠道（每个渠道对应一个模型提供商的 API Key），并支持用户分组和渠道分组，为不同分组设置不同的成本倍率，以及针对每个渠道设置可用的模型列表。这种灵活的分组机制使得不同的用户或业务部门可以享受到定制化的服务质量和成本配置。

流式传输支持

One API 支持 stream（流式）模式，可以实现打字机效果的实时回复流。这对于需要实时交互体验的应用（如聊天机器人）至关重要，可以大大提升用户体验。

强大的用户管理系统

系统支持多种用户登录和注册方式，包括邮箱注册和登录（支持注册白名单）、飞书授权登录、GitHub 授权登录以及微信公众号授权登录（需额外部署）。多样化的认证方式使得平台更加易用和安全。

兑换码系统

One API 提供了兑换码管理功能，支持批量生成兑换码、导出兑换码，以及使用兑换码为账户充值。这在需要向多个用户分发使用配额的场景下非常有用。

全面的数据管理和分析

系统支持查看额度明细，帮助用户了解成本分布。同时支持查看用户邀请奖励等信息，方便进行成本分析和财务审计。系统还支持以美元为单位显示额度，满足国际化业务需求。

自定义和扩展能力

One API 提供了丰富的自定义选项，包括自定义系统名称、Logo 和页脚，自定义首页和关于页面（支持 HTML & Markdown），通过 iframe 嵌入外部网页，以及主题切换功能。系统还通过访问令牌调用管理 API，实现无需二次开发的功能扩展。

企业级功能

One API 还包含多个企业级特性，如绘图接口支持、Cloudflare AI Gateway 支持、失败自动重试机制、模型映射和请求重定向、多机部署支持，以及与 Message Pusher 集成的报警通知功能。

One API 的核心功能

模型管理与渠道管理

在 One API 系统中，管理员可以在渠道页面添加各个 API 提供商的 API Key。系统会定期更新渠道的可用余额（可配置更新频率），并支持定期检查渠道的可用性。一旦发现渠道无法使用或成功率低于阈值，系统可以自动禁用该渠道，确保用户始终获得稳定的服务。github

令牌发放与权限管理

在创建好渠道后，管理员可以在令牌页面为用户生成访问令牌。用户使用这些令牌就可以像调用官方 OpenAI API 一样来调用 One API。令牌本身可以设置额度限制，令牌的使用不会直接影响账户余额，提供了额外的控制层。

负载均衡与渠道选择

默认情况下，One API 会使用负载均衡的方式在多个渠道之间分发请求。但用户也可以通过在授权令牌后面添加特定的渠道 ID 来指定使用某个特定的渠道，例如：Authorization: Bearer ONE_API_KEY-CHANNEL_ID。

精细的成本控制

系统内置了精细的成本计算和控制机制。额度的计算公式为：

补全 token 数的消耗倍率与 OpenAI 官方保持一致（GPT-3.5 为 1.33，GPT-4 为 2）。通过配置不同分组的倍率，管理员可以实现灵活的成本分配策略。github

One API 的部署方式

One API 提供了多种灵活的部署选项，适应不同用户的需求。

Docker 快速部署

最简单的部署方式是使用 Docker。对于使用 SQLite 的部署，命令为：

docker run --name one-api -d --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api

这个命令会在本地 3000 端口启动 One API，数据保存在主机的 /home/ubuntu/data/one-api 目录。系统会在首次启动时自动建表，无需手动配置数据库。

对于需要处理高并发的场景，建议使用 MySQL 数据库。添加 MySQL 配置后的命令为：

docker run --name one-api -d --restart always -p 3000:3000 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api

初始登录用户名为 root，密码为 123456。第一次登录后务必修改默认密码，以保证系统安全。

Nginx 反向代理配置

为了在生产环境中使用 One API，通常需要配置 Nginx 反向代理以支持 HTTPS 和自定义域名。

server{
   server_name openai.justsong.cn;
   location / {
          client_max_body_size 64m;
          proxy_http_version 1.1;
          proxy_pass http://localhost:3000;
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-For $remote_addr;
          proxy_cache_bypass $http_upgrade;
          proxy_set_header Accept-Encoding gzip;
          proxy_read_timeout 300s;
   }
}

之后使用 Let’s Encrypt 的 certbot 配置 HTTPS：

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx
sudo service nginx restart

宝塔面板一键部署

对于不熟悉命令行的用户，可以通过宝塔面板进行一键部署。安装宝塔面板 9.2.0 及以上版本后，在宝塔中安装 Docker 服务，随后在应用商店搜索并安装 One-API，最后配置域名等基本信息即可完成安装。这种方式大幅降低了部署难度，即使是技术水平有限的用户也可以轻松部署。

Docker Compose 部署

对于更复杂的部署场景，用户可以使用 Docker Compose 进行多容器编排：

bash

docker-compose up -d
docker-compose ps

bash

docker-compose up -d docker-compose ps

Docker Compose 配置会同时启动 One API 和 MySQL 数据库，开箱即用。

手动编译部署

对于需要进行深度定制的用户，可以从源码编译：

bash

# 克隆仓库
git clone https://github.com/songquanpeng/one-api.git

# 构建前端
cd one-api/web/default
npm install
npm run build

# 构建后端
cd ../..
go mod download
go build -ldflags "-s -w" -o one-api

# 运行
chmod u+x one-api
./one-api --port 3000 --log-dir ./logs

之后访问 http://localhost:3000/ 即可登录系统，初始账号为 root，密码为 123456。

第三方平台部署

One API 还支持在多个第三方平台上部署。Sealos 的服务器位于国外，不需要额外处理网络问题，支持高并发和动态伸缩，一键部署体验极佳。Zeabur 的服务器也在国外，自动解决网络问题，免费额度足够个人使用，但需要配置数据库连接和环境变量。Render 提供免费额度，并支持直接部署 Docker 镜像。

多机部署架构

对于大型企业应用，One API 支持多机部署，实现高可用和分布式架构。所有服务器需要使用相同的 SESSION_SECRET，必须配置 MySQL 数据库且所有服务器连接同一个数据库，从服务器设置 NODE_TYPE=slave，配置 Redis 缓存加速（可选但推荐），设置 SYNC_FREQUENCY 定期同步配置。这种架构可以实现请求的分布式处理，显著提升系统的并发处理能力。

与第三方应用的集成

One API 设计为 API 网关，可以与各种 AI 客户端和应用进行集成。

ChatGPT Next Web

ChatGPT Next Web 是一个跨平台的 ChatGPT 应用。集成方式非常简单：启动应用后，在应用中设置接口地址为 One API 的部署地址（如 https://openai.justsong.cn/），设置 API Key 为 One API 中生成的令牌即可。

ChatGPT Web

ChatGPT Web 是另一个流行的网页 ChatGPT 应用。部署时指定 One API 的地址和 API Key，以及修改端口号、基础 URL 和 API Key 即可。

QChatGPT – QQ 机器人

对于想要在 QQ 上使用 AI 的用户，可以部署 QChatGPT。根据项目文档完成基本部署后，修改 data/provider.json 文件设置 One API 的地址，将 API Key 填入配置文件的 keys.openai 部分，设置要使用的模型名称。用户可以通过 !model 命令来查看和切换可用的模型。

One API 的配置系统

One API 提供了极其灵活的配置系统，支持通过环境变量和命令行参数进行配置。

数据库配置

SQL_DSN 配置数据库连接字符串。MySQL 例如 root:123456@tcp(localhost:3306)/oneapi，PostgreSQL 例如 postgres://postgres:123456@localhost:5432/oneapi。SQL_MAX_IDLE_CONNS 设置最大空闲连接数（默认 100），SQL_MAX_OPEN_CONNS 设置最大打开连接数（默认 1000），SQL_CONN_MAX_LIFETIME 设置连接最大生命周期（默认 60 分钟）。对于高并发场景，这些参数的合理配置至关重要。

缓存和性能配置

REDIS_CONN_STRING 启用 Redis 缓存，大幅加速数据访问，支持 Redis 哨兵和集群模式。MEMORY_CACHE_ENABLED 启用内存缓存（会导致用户额度更新有延迟）。SYNC_FREQUENCY 在启用缓存时与数据库同步配置的频率。

渠道管理配置

CHANNEL_UPDATE_FREQUENCY 定期更新渠道余额的频率（分钟），CHANNEL_TEST_FREQUENCY 定期检查渠道可用性的频率（分钟），POLLING_INTERVAL 批量更新时的请求间隔（秒）。ENABLE_METRIC 启用基于成功率自动禁用渠道的功能，METRIC_SUCCESS_RATE_THRESHOLD 成功率阈值（默认 0.8）。

安全和限流配置

GLOBAL_API_RATE_LIMIT 设置全局 API 速率限制（默认单 IP 三分钟 180 次），GLOBAL_WEB_RATE_LIMIT 设置全局 Web 速率限制（默认单 IP 三分钟 60 次），RELAY_TIMEOUT 设置中继请求超时时间（秒）。

其他重要配置

THEME 系统主题设置，RELAY_PROXY 代理设置用于突破网络限制，INITIAL_ROOT_TOKEN 首次启动时自动创建 root 用户的令牌，INITIAL_ROOT_ACCESS_TOKEN 首次启动时自动创建管理令牌。

One API 的使用工作流

理解 One API 的使用流程有助于更好地利用这个系统。

第一步：添加渠道（管理员）

管理员需要先在「渠道」页面添加各个模型提供商的 API Key。例如，添加 OpenAI 的 API Key、Claude 的 API Key 等。系统会根据配置定期检查这些渠道的状态和余额。

第二步：创建令牌（管理员）

在「令牌」页面创建访问令牌。这些令牌可以分配给不同的用户、应用或客户，并可以设置额度限制、过期时间等限制条件。

第三步：使用令牌（最终用户/应用）

最终用户或应用使用这些令牌来调用 One API。调用方式与 OpenAI 官方 API 完全相同，只需修改 API Base URL 指向 One API 实例的地址。

第四步：监控和管理（管理员）

管理员可以在系统中查看每个令牌的使用情况和消耗的额度、各个渠道的状态和剩余余额、用户的邀请和奖励情况、详细的消费明细。这些信息有助于进行成本控制和系统优化。

适用场景

One API 特别适合以下场景：

API 分发平台：将多个模型提供商的 API 统一封装，对外提供一个统一的接口。
企业 AI 应用：企业内部统一使用 One API，而不是每个应用都直接管理 API Key。
SaaS 平台：在 SaaS 产品中集成 AI 功能时，通过 One API 提供统一的 AI 接口。
成本控制和优化：需要对 AI API 的成本进行精细控制和优化的组织。
模型试验：研究人员或企业想要快速试验不同的 AI 模型时，One API 提供了方便的切换机制。