One-API：让国内LLM、Coze等跑通仅支持OpenAI API的开源项目 | 保姆级教程、可配合免费LLM API使用！

Aitrainee | 公众号：AI进修生

🌟免责声明：本文仅用于技术研究和学习，根据《生成式人工智能服务管理暂行办法》的要求，请勿对公众提供一切未经备案的生成式人工智能服务。任何个人、团队和企业，无论以何种方式使用这些项目、对何对象提供服务，所产生的一切后果，本文作者均不承担任何责任。

这个项目可以将其他大模型的API调用格式转换为OpenAI的格式（可配合免费LLM API使用），从而在调试和部署OpenAI API相关项目时，可以利用其他大模型提供商（如Coze（免费的gpt-4o）、通义千文、Gemini）。

通过标准的 OpenAI API 格式访问所有的大模型，开箱即用。

下图我创建了几个模型供应商：

使用Coze（gpt-4o-128k）供应商配置One-API

具体有啥用的话，我们直接用一个部署实践来讲，可能比理解官方文档更快一些：

我们先去coze网站，随便创建一个机器人

把它发布到API勾上（config点进去记录key）

Docker 部署One API

# 使用 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
# 使用 MySQL 的部署命令，在上面的基础上添加 `-e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi"`，请自行修改数据库连接参数，不清楚如何修改请参见下面环境变量一节。
# 例如：
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

直接用第1行命令就行了，后面那行命令需要本机链接Mysql，第1行是轻量级的数据库，可以直接配置。要安装Docker的话，公众号消息菜单里有。

输入root 123456进入这个界面，然后点击添加渠道（就是准备添加其他的llm模型供应商）

模型类型选择coze，然后再把上面记录的key填入。

填入相关模型那一列需要填入coze bot的ID（就这个是特殊的,其他模型供应商就是常见的模型名称比如kimi、gpt-3.5、gpt4）

然后点击测试，通过之后，为不同的供应商模型添加令牌即可：

这一切做完之后，我们就可以测试了：

我写了个测试脚本(coze bot是可以接入联网功能，它有许多插件的我的脚本就让他搜索今天的ai新闻)

from openai import OpenAI

client = OpenAI(
  base_url="http://ip:3000/v1/",  # Ensure this URL is correct
  api_key="sk-cJ1N9fBX8WGxxxx"
)

# System prompt to guide the conversation
session_messages = [
  {"role": "system", "content": "搜索今天的ai新闻"}
]
print(session_messages[0]['content'])  # Display the initial system prompt

# Start a continuous conversation with an initial user message
completion = client.chat.completions.create(
  model="qwen-max",  # Replace with your model
  messages=session_messages,  # Include the initial system message
  temperature=0.8,
  top_p=1,
  max_tokens=1024,
  stream=True
)

# Output the conversation responses
for chunk in completion:
  if chunk.choices[0].delta.content is not None:
    print(chunk.choices[0].delta.content, end="")

它确实是搜索了今天的ai新闻，至此我们全部流程走完。

也就是说现在你可以用One-API提供的base_url（ IP：本机、服务器，具体看你把one-api部署在哪，请看脚本）、api_key去对应替换其他openai相关开源项目的原始base_url、api_key了（）

有些项目就只有Openai支持，可以直接把他的Openai依赖包改了（就用上面One-API的base_url ）：

▲ 在openai 的__init__py 里

其他相关项目：

相关项目

• • FastGPT: 基于 LLM 大语言模型的知识库问答系统
• • ChatGPT Next Web: 一键拥有你自己的跨平台 ChatGPT 应用

使用其他LLM供应商配置One-API

流程都是一样的，区别是，你得去找其他LLM供应商的base_url、api_key，最后配置完就生成了one-api提供的base_url、api_key

怎么找的话它其实是提供的，你就点击这里开始找就行了

当然，这上面的都是去他们官网申请付费api，我们其实可以使用其他的开源项目获取这些提供商的免费api（仅作学习研究，调试测试，免费的并不稳定）：去公众号底部菜单查看LLM API。

下面提供One-API官方的文档介绍、相关资源、部署教程等，进一步支撑你的行动，以提升本文的帮助力。

▲ 简单原理示图

功能

1. 1. 支持多种大模型：
   • • OpenAI ChatGPT 系列模型（支持 Azure OpenAI API）
   • • Anthropic Claude 系列模型 (支持 AWS Claude)
   • • Google PaLM2/Gemini 系列模型
   • • Mistral 系列模型
   • • 百度文心一言系列模型
   • • 阿里通义千问系列模型
   • • 讯飞星火认知大模型
   • • 智谱 ChatGLM 系列模型
   • • 360 智脑
   • • 腾讯混元大模型
   • • Moonshot AI
   • • 百川大模型
   • • 字节云雀大模型 (WIP)
   • • MINIMAX
   • • Groq
   • • Ollama
   • • 零一万物
   • • 阶跃星辰
   • • Coze
   • • Cohere
   • • DeepSeek
   • • Cloudflare Workers AI
   • • DeepL
   • • together.ai
2. 2. 支持配置镜像以及众多第三方代理服务。
3. 3. 支持通过负载均衡的方式访问多个渠道。
4. 4. 支持 stream 模式，可以通过流式传输实现打字机效果。
5. 5. 支持多机部署，详见此处。
6. 6. 支持令牌管理，设置令牌的过期时间、额度、允许的 IP 范围以及允许的模型访问。
7. 7. 支持兑换码管理，支持批量生成和导出兑换码，可使用兑换码为账户进行充值。
8. 8. 支持渠道管理，批量创建渠道。
9. 9. 支持用户分组以及渠道分组，支持为不同分组设置不同的倍率。
10. 10. 支持渠道设置模型列表。
11. 11. 支持查看额度明细。
12. 12. 支持用户邀请奖励。
13. 13. 支持以美元为单位显示额度。
14. 14. 支持发布公告，设置充值链接，设置新用户初始额度。
15. 15. 支持模型映射，重定向用户的请求模型，如无必要请不要设置，设置之后会导致请求体被重新构造而非直接透传，会导致部分还未正式支持的字段无法传递成功。
16. 16. 支持失败自动重试。
17. 17. 支持绘图接口。
18. 18. 支持 Cloudflare AI Gateway，渠道设置的代理部分填写 https://gateway.ai.cloudflare.com/v1/ACCOUNT_TAG/GATEWAY/openai 即可。
19. 19. 支持丰富的自定义设置，
    1. 1. 支持自定义系统名称，logo 以及页脚。
    2. 2. 支持自定义首页和关于页面，可以选择使用 HTML & Markdown 代码进行自定义，或者使用一个单独的网页通过 iframe 嵌入。
20. 20. 支持通过系统访问令牌调用管理 API，进而在无需二开的情况下扩展和自定义 One API 的功能，详情请参考此处 API 文档。。
21. 21. 支持 Cloudflare Turnstile 用户校验。
22. 22. 支持用户管理，支持多种用户登录注册方式：
    • • 邮箱登录注册（支持注册邮箱白名单）以及通过邮箱进行密码重置。
    • • 支持使用飞书进行授权登录。
    • • GitHub 开放授权。
    • • 微信公众号授权（需要额外部署 WeChat Server）。
23. 23. 支持主题切换，设置环境变量 THEME 即可，默认为 default，欢迎 PR 更多主题，具体参考此处。
24. 24. 配合 Message Pusher 可将报警信息推送到多种 App 上。

部署

基于 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
# 使用 MySQL 的部署命令，在上面的基础上添加 `-e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi"`，请自行修改数据库连接参数，不清楚如何修改请参见下面环境变量一节。
# 例如：
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

其中，-p 3000:3000 中的第一个 3000 是宿主机的端口，可以根据需要进行修改。

数据和日志将会保存在宿主机的 /home/ubuntu/data/one-api 目录，请确保该目录存在且具有写入权限，或者更改为合适的目录。

如果启动失败，请添加 --privileged=true，具体参考 https://github.com/songquanpeng/one-api/issues/482 。

如果上面的镜像无法拉取，可以尝试使用 GitHub 的 Docker 镜像，将上面的 justsong/one-api 替换为 ghcr.io/songquanpeng/one-api 即可。

如果你的并发量较大，务必设置 SQL_DSN，详见下面环境变量一节。Nginx 的参考配置：

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;  # GPT-4 需要较长的超时时间，请自行调整
   }
}

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

# Ubuntu 安装 certbot：
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
# 生成证书 & 修改 Nginx 配置
sudo certbot --nginx
# 根据指示进行操作
# 重启 Nginx
sudo service nginx restart

初始账号用户名为 root，密码为 123456。

基于 Docker Compose 进行部署

仅启动方式不同，参数设置不变，请参考基于 Docker 部署部分

# 目前支持 MySQL 启动，数据存储在 ./data/mysql 文件夹内
docker-compose up -d

# 查看部署状态
docker-compose ps

手动部署

1. 从 GitHub Releases 下载可执行文件或者从源码编译：

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

2. 运行：

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

3. 访问 http://localhost:3000/ 并登录。初始账号用户名为 root，密码为 123456。

更加详细的部署教程参见此处。

多机部署

1. 1. 所有服务器 SESSION_SECRET 设置一样的值。
2. 2. 必须设置 SQL_DSN，使用 MySQL 数据库而非 SQLite，所有服务器连接同一个数据库。
3. 3. 所有从服务器必须设置 NODE_TYPE 为 slave，不设置则默认为主服务器。
4. 4. 设置 SYNC_FREQUENCY 后服务器将定期从数据库同步配置，在使用远程数据库的情况下，推荐设置该项并启用 Redis，无论主从。
5. 5. 从服务器可以选择设置 FRONTEND_BASE_URL，以重定向页面请求到主服务器。
6. 6. 从服务器上分别装好 Redis，设置好 REDIS_CONN_STRING，这样可以做到在缓存未过期的情况下数据库零访问，可以减少延迟。
7. 7. 如果主服务器访问数据库延迟也比较高，则也需要启用 Redis，并设置 SYNC_FREQUENCY，以定期从数据库同步配置。

环境变量的具体使用方法详见此处。

宝塔部署教程

详见 #175。

如果部署后访问出现空白页面，详见 #97。

部署第三方服务配合 One API 使用

欢迎 PR 添加更多示例。

ChatGPT Next Web

项目主页：https://github.com/Yidadaa/ChatGPT-Next-Web

docker run --name chat-next-web -d -p 3001:3000 yidadaa/chatgpt-next-web

注意修改端口号，之后在页面上设置接口地址（例如：https://openai.justsong.cn/ ）和 API Key 即可。

ChatGPT Web

项目主页：https://github.com/Chanzhaoyu/chatgpt-web

docker run --name chatgpt-web -d -p 3002:3002 -e OPENAI_API_BASE_URL=https://openai.justsong.cn -e OPENAI_API_KEY=sk-xxx chenzhaoyu94/chatgpt-web

注意修改端口号、OPENAI_API_BASE_URL 和 OPENAI_API_KEY。

QChatGPT - QQ机器人

项目主页：https://github.com/RockChinQ/QChatGPT

根据文档完成部署后，在config.py设置配置项openai_config的reverse_proxy为 One API 后端地址，设置api_key为 One API 生成的key，并在配置项completion_api_params的model参数设置为 One API 支持的模型名称。

可安装 Switcher 插件在运行时切换所使用的模型。

配置

系统本身开箱即用。

你可以通过设置环境变量或者命令行参数进行配置。

等到系统启动后，使用 root 用户登录系统并做进一步的配置。

Note：如果你不知道某个配置项的含义，可以临时删掉值以看到进一步的提示文字。

使用方法

在渠道页面中添加你的 API Key，之后在令牌页面中新增访问令牌。

之后就可以使用你的令牌访问 One API 了，使用方式与 OpenAI API 一致。

你需要在各种用到 OpenAI API 的地方设置 API Base 为你的 One API 的部署地址，例如：https://openai.justsong.cn，API Key 则为你在 One API 中生成的令牌。

注意，具体的 API Base 的格式取决于你所使用的客户端。

例如对于 OpenAI 的官方库：

OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://<HOST>:<PORT>/v1" 

可以通过在令牌后面添加渠道 ID 的方式指定使用哪一个渠道处理本次请求，例如：Authorization: Bearer ONE_API_KEY-CHANNEL_ID。注意，需要是管理员用户创建的令牌才能指定渠道 ID。

不加的话将会使用负载均衡的方式使用多个渠道。

环境变量

1. 1. REDIS_CONN_STRING：设置之后将使用 Redis 作为缓存使用。
   • • 例子：REDIS_CONN_STRING=redis://default:redispw@localhost:49153
   • • 如果数据库访问延迟很低，没有必要启用 Redis，启用后反而会出现数据滞后的问题。
2. 2. SESSION_SECRET：设置之后将使用固定的会话密钥，这样系统重新启动后已登录用户的 cookie 将依旧有效。
   • • 例子：SESSION_SECRET=random_string
3. 3. SQL_DSN：设置之后将使用指定数据库而非 SQLite，请使用 MySQL 或 PostgreSQL。
   • • 例子：
     • • MySQL：SQL_DSN=root:123456@tcp(localhost:3306)/oneapi
     • • PostgreSQL：SQL_DSN=postgres://postgres:123456@localhost:5432/oneapi（适配中，欢迎反馈）
   • • 注意需要提前建立数据库 oneapi，无需手动建表，程序将自动建表。
   • • 如果使用本地数据库：部署命令可添加 --network="host" 以使得容器内的程序可以访问到宿主机上的 MySQL。
   • • 如果使用云数据库：如果云服务器需要验证身份，需要在连接参数中添加 ?tls=skip-verify。
   • • 请根据你的数据库配置修改下列参数（或者保持默认值）：
     • • SQL_MAX_IDLE_CONNS：最大空闲连接数，默认为 100。
     • • SQL_MAX_OPEN_CONNS：最大打开连接数，默认为 1000。
       • • 如果报错 Error 1040: Too many connections，请适当减小该值。
     • • SQL_CONN_MAX_LIFETIME：连接的最大生命周期，默认为 60，单位分钟。
4. 4. LOG_SQL_DSN：设置之后将为 logs 表使用独立的数据库，请使用 MySQL 或 PostgreSQL。
5. 5. FRONTEND_BASE_URL：设置之后将重定向页面请求到指定的地址，仅限从服务器设置。
   • • 例子：FRONTEND_BASE_URL=https://openai.justsong.cn
6. 6. MEMORY_CACHE_ENABLED：启用内存缓存，会导致用户额度的更新存在一定的延迟，可选值为 true 和 false，未设置则默认为 false。
   • • 例子：MEMORY_CACHE_ENABLED=true
7. 7. SYNC_FREQUENCY：在启用缓存的情况下与数据库同步配置的频率，单位为秒，默认为 600 秒。
   • • 例子：SYNC_FREQUENCY=60
8. 8. NODE_TYPE：设置之后将指定节点类型，可选值为 master 和 slave，未设置则默认为 master。
   • • 例子：NODE_TYPE=slave
9. 9. CHANNEL_UPDATE_FREQUENCY：设置之后将定期更新渠道余额，单位为分钟，未设置则不进行更新。
   • • 例子：CHANNEL_UPDATE_FREQUENCY=1440
10. 10. CHANNEL_TEST_FREQUENCY：设置之后将定期检查渠道，单位为分钟，未设置则不进行检查。
11. 11. 例子：CHANNEL_TEST_FREQUENCY=1440
12. 12. POLLING_INTERVAL：批量更新渠道余额以及测试可用性时的请求间隔，单位为秒，默认无间隔。
    • • 例子：POLLING_INTERVAL=5
13. 13. BATCH_UPDATE_ENABLED：启用数据库批量更新聚合，会导致用户额度的更新存在一定的延迟可选值为 true 和 false，未设置则默认为 false。
    • • 例子：BATCH_UPDATE_ENABLED=true
    • • 如果你遇到了数据库连接数过多的问题，可以尝试启用该选项。
14. 14. BATCH_UPDATE_INTERVAL=5：批量更新聚合的时间间隔，单位为秒，默认为 5。
    • • 例子：BATCH_UPDATE_INTERVAL=5
15. 15. 请求频率限制：
    • • GLOBAL_API_RATE_LIMIT：全局 API 速率限制（除中继请求外），单 ip 三分钟内的最大请求数，默认为 180。
    • • GLOBAL_WEB_RATE_LIMIT：全局 Web 速率限制，单 ip 三分钟内的最大请求数，默认为 60。
16. 16. 编码器缓存设置：
    • • TIKTOKEN_CACHE_DIR：默认程序启动时会联网下载一些通用的词元的编码，如：gpt-3.5-turbo，在一些网络环境不稳定，或者离线情况，可能会导致启动有问题，可以配置此目录缓存数据，可迁移到离线环境。
    • • DATA_GYM_CACHE_DIR：目前该配置作用与 TIKTOKEN_CACHE_DIR 一致，但是优先级没有它高。
17. 17. RELAY_TIMEOUT：中继超时设置，单位为秒，默认不设置超时时间。
18. 18. RELAY_PROXY：设置后使用该代理来请求 API。
19. 19. USER_CONTENT_REQUEST_TIMEOUT：用户上传内容下载超时时间，单位为秒。
20. 20. USER_CONTENT_REQUEST_PROXY：设置后使用该代理来请求用户上传的内容，例如图片。
21. 21. SQLITE_BUSY_TIMEOUT：SQLite 锁等待超时设置，单位为毫秒，默认 3000。
22. 22. GEMINI_SAFETY_SETTING：Gemini 的安全设置，默认 BLOCK_NONE。
23. 23. GEMINI_VERSION：One API 所使用的 Gemini 版本，默认为 v1。
24. 24. THEME：系统的主题设置，默认为 default，具体可选值参考此处。
25. 25. ENABLE_METRIC：是否根据请求成功率禁用渠道，默认不开启，可选值为 true 和 false。
26. 26. METRIC_QUEUE_SIZE：请求成功率统计队列大小，默认为 10。
27. 27. METRIC_SUCCESS_RATE_THRESHOLD：请求成功率阈值，默认为 0.8。
28. 28. INITIAL_ROOT_TOKEN：如果设置了该值，则在系统首次启动时会自动创建一个值为该环境变量值的 root 用户令牌。

命令行参数

1. 1. --port <port_number>: 指定服务器监听的端口号，默认为 3000。
   • • 例子：--port 3000
2. 2. --log-dir <log_dir>: 指定日志文件夹，如果没有设置，默认保存至工作目录的 logs 文件夹下。
   • • 例子：--log-dir ./logs
3. 3. --version: 打印系统版本号并退出。
4. 4. --help: 查看命令的使用帮助和参数说明。

演示

在线演示

注意，该演示站不提供对外服务：https://openai.justsong.cn

截图展示

常见问题

1. 1. 额度是什么？怎么计算的？One API 的额度计算有问题？
   • • 额度 = 分组倍率 * 模型倍率 * （提示 token 数 + 补全 token 数 * 补全倍率）
   • • 其中补全倍率对于 GPT3.5 固定为 1.33，GPT4 为 2，与官方保持一致。
   • • 如果是非流模式，官方接口会返回消耗的总 token，但是你要注意提示和补全的消耗倍率不一样。
   • • 注意，One API 的默认倍率就是官方倍率，是已经调整过的。
2. 2. 账户额度足够为什么提示额度不足？
   • • 请检查你的令牌额度是否足够，这个和账户额度是分开的。
   • • 令牌额度仅供用户设置最大使用量，用户可自由设置。
3. 3. 提示无可用渠道？
   • • 请检查的用户分组和渠道分组设置。
   • • 以及渠道的模型设置。
4. 4. 渠道测试报错：invalid character '<' looking for beginning of value
   • • 这是因为返回值不是合法的 JSON，而是一个 HTML 页面。
   • • 大概率是你的部署站的 IP 或代理的节点被 CloudFlare 封禁了。
5. 5. ChatGPT Next Web 报错：Failed to fetch
   • • 部署的时候不要设置 BASE_URL。
   • • 检查你的接口地址和 API Key 有没有填对。
   • • 检查是否启用了 HTTPS，浏览器会拦截 HTTPS 域名下的 HTTP 请求。
6. 6. 报错：当前分组负载已饱和，请稍后再试
   • • 上游渠道 429 了。
7. 7. 升级之后我的数据会丢失吗？
   • • 如果使用 MySQL，不会。
   • • 如果使用 SQLite，需要按照我所给的部署命令挂载 volume 持久化 one-api.db 数据库文件，否则容器重启后数据会丢失。
8. 8. 升级之前数据库需要做变更吗？
   • • 一般情况下不需要，系统将在初始化的时候自动调整。
   • • 如果需要的话，我会在更新日志中说明，并给出脚本。
9. 9. 手动修改数据库后报错：数据库一致性已被破坏，请联系管理员？
   • • 这是检测到 ability 表里有些记录的渠道 id 是不存在的，这大概率是因为你删了 channel 表里的记录但是没有同步在 ability 表里清理无效的渠道。
   • • 对于每一个渠道，其所支持的模型都需要有一个专门的 ability 表的记录，表示该渠道支持该模型。

知音难求，自我修炼亦艰

抓住前沿技术的机遇，与我们一起成为创新的超级个体

一键三连「分享」、「点赞」和「在看」

科技前沿进展日日相见 ~