songquanpeng--one-api/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

中文 | English | 日本語

One API

✨ 通过标准 OpenAI API 格式访问所有 LLM，易于部署和使用 ✨

部署教程 · 使用方式 · 反馈 · 截图 · 在线演示 · 常见问题 · 相关项目 · 捐赠

警告：本 README 由 ChatGPT 翻译。如发现翻译错误，欢迎提交 PR。

注意：从 Docker 拉取的最新镜像可能是 alpha 版本。如需稳定性，请手动指定版本。

特性

1. 支持多种大模型：
   • OpenAI ChatGPT 系列模型 (Supports Azure OpenAI API)
   • Anthropic Claude 系列模型
   • Google PaLM2 和 Gemini 系列模型
   • 百度文心一言系列模型
   • 阿里通义千问系列模型
   • 智谱 ChatGLM 系列模型
2. 支持通过负载均衡访问多个渠道。
3. 支持流式模式，通过流式传输实现打字机效果。
4. 支持多机部署。详见此处。
5. 支持 Token 管理，可设置 Token 过期时间和使用次数。
6. 支持兑换码管理，可批量生成和导出兑换码。兑换码可用于账户余额充值。
7. 支持渠道管理，可批量创建渠道。
8. 支持用户分组和渠道分组，可为不同分组设置不同费率。
9. 支持渠道模型列表配置。
10. 支持额度明细查询。
11. 支持用户邀请奖励。
12. 支持以美元（USD）显示余额。
13. 支持公告发布、充值链接设置和新用户初始余额设置。
14. 提供丰富的自定义选项：
    1. 支持自定义系统名称、Logo 和页脚。
    2. 支持使用 HTML 和 Markdown 代码自定义首页和关于页面，或通过 iframe 嵌入独立网页。
15. 支持通过系统访问令牌访问管理 API。
16. 支持 Cloudflare Turnstile 用户验证。
17. 支持用户管理和多种用户登录/注册方式：
    • 邮箱登录/注册及通过邮箱重置密码。
    • GitHub OAuth.
    • 微信公众号授权（需额外部署 WeChat Server).
18. 其他主流模型 API 发布后即刻支持并封装。

部署

Docker 部署

部署命令： 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

更新命令：docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower -cR

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

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

Nginx 参考配置：

server{
   server_name openai.justsong.cn;  # Modify your domain name accordingly

   location / {
          client_max_body_size  64m;
          proxy_http_version 1.1;
          proxy_pass http://localhost:3000;  # Modify your port accordingly
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-For $remote_addr;
          proxy_cache_bypass $http_upgrade;
          proxy_set_header Accept-Encoding gzip;
   }
}

接下来，使用 Let's Encrypt certbot 配置 HTTPS：

# Install certbot on Ubuntu:
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
# Generate certificates & modify Nginx configuration
sudo certbot --nginx
# Follow the prompts
# Restart Nginx
sudo service nginx restart

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

手动部署

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

   git clone https://github.com/songquanpeng/one-api.git
   
   # Build the frontend
   cd one-api/web/default
   npm install
   npm run build
   
   # Build the backend
   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. 为所有服务器设置相同的 SESSION_SECRET。
2. 设置 SQL_DSN，并使用 MySQL 替代 SQLite。所有服务器应连接同一数据库。
3. 将所有非主节点的 NODE_TYPE 设置为 slave。
4. 为服务器设置 SYNC_FREQUENCY，以定期从数据库同步配置。
5. 非主节点可选择设置 FRONTEND_BASE_URL，将页面请求重定向到主服务器。
6. 在非主节点单独安装 Redis，并配置 REDIS_CONN_STRING，以便在缓存未过期时零延迟访问数据库。
7. 如果主服务器访问数据库也存在较高延迟，必须启用 Redis，并设置 SYNC_FREQUENCY 以定期从数据库同步配置。

有关环境变量的详细说明，请参阅环境变量章节。

在控制面板部署（如宝塔）

详细说明请参阅 #175。

如果部署后出现空白页面，请参阅 #97 获取可能的解决方案。

在第三方平台部署

在 Sealos 上部署

Sealos 支持高并发、动态扩缩容，可为数百万用户提供稳定运行。

点击下方按钮即可一键部署。👇

在 Zeabur 上部署

Zeabur 的服务器位于海外，可自动解决网络问题，免费额度足以满足个人使用需求。

1. 首先，Fork 代码仓库。
2. 前往 Zeabur, 登录并进入控制台。
3. 创建新项目。在 Service -> Add Service 中，选择 Marketplace，并选择 MySQL。记下连接参数（用户名、密码、地址和端口）。
4. 复制连接参数，并运行 create database `one-api` 以创建数据库。
5. 然后，在 Service -> Add Service 中，选择 Git（首次使用需要授权），并选择你 Fork 的仓库。
6. 将自动开始部署，但请先取消。进入 Variable 标签页，添加 PORT，值为 3000，再添加 SQL_DSN，值为 <username>:<password>@tcp(<addr>:<port>)/one-api。保存更改。请注意，如果未设置 SQL_DSN，数据将不会持久化，重新部署后数据会丢失。
7. 选择 Redeploy。
8. 在 Domains 标签页中，选择合适的域名前缀，例如 "my-one-api"。最终域名将是 "my-one-api.zeabur.app"。你也可以通过 CNAME 绑定自己的域名。
9. 等待部署完成，点击生成的域名即可访问 One API。

配置

系统开箱即用。

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

系统启动后，以 root 用户身份登录，以进一步配置系统。

使用说明

在 Channels 页面添加你的 API Key，然后在 Tokens 页面添加访问令牌（access token）。

随后即可使用访问令牌访问 One API。用法与 OpenAI API. 一致。

在使用 OpenAI API 的地方，请将 API Base 设置为你的 One API 部署地址，例如：https://openai.justsong.cn。API Key 应为在 One API 中生成的令牌。

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

graph LR
    A(User)
    A --->|Request| B(One API)
    B -->|Relay Request| C(OpenAI)
    B -->|Relay Request| D(Azure)
    B -->|Relay Request| E(Other downstream channels)

要为当前请求指定使用哪个渠道（channel），可以在令牌后附加渠道 ID，例如：Authorization: Bearer ONE_API_KEY-CHANNEL_ID。 请注意，只有管理员创建的令牌才能指定渠道 ID。

如果未提供渠道 ID，将使用负载均衡（load balancing）将请求分发到多个渠道。

环境变量

1. REDIS_CONN_STRING：设置后，将使用 Redis 作为请求频率限制的存储，而非内存。
   • 示例：REDIS_CONN_STRING=redis://default:redispw@localhost:49153
2. SESSION_SECRET：设置后，将使用固定的会话密钥（session key），确保系统重启后已登录用户的 Cookie 仍然有效。
   • 示例：SESSION_SECRET=random_string
3. SQL_DSN：设置后，将使用指定的数据库，而非 SQLite。请使用 MySQL 8.0 版本。
   • 示例：SQL_DSN=root:123456@tcp(localhost:3306)/oneapi
4. LOG_SQL_DSN：设置后，将为 logs 表使用独立的数据库；请使用 MySQL 或 PostgreSQL。
   • 示例：LOG_SQL_DSN=root:123456@tcp(localhost:3306)/oneapi-logs
5. FRONTEND_BASE_URL：设置后，将使用指定的前端地址，而非后端地址。
   • 示例：FRONTEND_BASE_URL=https://openai.justsong.cn
6. 'MEMORY_CACHE_ENABLED'：启用内存缓存可能导致用户配额更新出现一定延迟，可选值为 'true' 和 'false'。若未设置，默认为 'false'。
7. SYNC_FREQUENCY：设置后，系统将定期从数据库同步配置，单位为秒。若未设置，则不会进行同步。
   • 示例：SYNC_FREQUENCY=60
8. NODE_TYPE：设置后，指定节点类型。有效值为 master 和 slave。若未设置，默认为 master。
   • 示例：NODE_TYPE=slave
9. CHANNEL_UPDATE_FREQUENCY：设置后，将定期更新渠道余额，单位为分钟。若未设置，则不会进行更新。
   • 示例：CHANNEL_UPDATE_FREQUENCY=1440
10. CHANNEL_TEST_FREQUENCY：设置后，将定期测试渠道，单位为分钟。若未设置，则不会进行测试。
    • 示例：CHANNEL_TEST_FREQUENCY=1440
11. POLLING_INTERVAL：更新渠道余额和测试渠道可用性时，请求之间的时间间隔（单位为秒）。默认无间隔。
    • 示例：POLLING_INTERVAL=5
12. BATCH_UPDATE_ENABLED：启用批量数据库更新聚合可能导致用户配额更新出现一定延迟。可选值为 'true' 和 'false'，若未设置，默认为 'false'。 +示例： BATCH_UPDATE_ENABLED=true +如果遇到数据库连接过多的问题，可以尝试启用此选项。
13. BATCH_UPDATE_INTERVAL=5：批量更新聚合的时间间隔，单位为秒，默认为 '5'。 +示例： BATCH_UPDATE_INTERVAL=5
14. 请求频率限制：
    • GLOBAL_API_RATE_LIMIT：全局 API 速率限制（不含中继请求），每个 IP 在三分钟内的最大请求数，默认为 180。
    • GLOBAL_WEL_RATE_LIMIT：全局 Web 速率限制，每个 IP 在三分钟内的最大请求数，默认为 60。
15. 编码器（encoder）缓存设置： +TIKTOKEN_CACHE_DIR：默认情况下，程序启动时会在线下载一些常见词元的编码，例如 'gpt-3.5 turbo'。在不稳定的网络环境或离线情况下，可能导致启动问题。可配置此目录以缓存数据，并可迁移到离线环境。 +DATA_GYM_CACHE_DIR：目前此配置与 'TIKTOKEN-CACHE-DIR' 功能相同，但优先级低于后者。
16. RELAY_TIMEOUT：中继（relay）超时设置，单位为秒，默认不设置超时时间。
17. RELAY_PROXY：设置后，使用此代理请求 API。
18. USER_CONTENT_REQUEST_TIMEOUT：用户上传和下载内容的超时期限，单位为秒。
19. USER_CONTENT_REQUEST_PROXY：设置后，使用此代理请求用户上传的内容，例如图片。
20. SQLITE_BUSY_TIMEOUT：SQLite 锁等待超时设置，单位为毫秒，默认为 '3000'。
21. GEMINI_SAFETY_SETTING：Gemini 的安全设置默认为 'BLOCK-NONE'。
22. GEMINI_VERSION：One API 使用的 Gemini 版本，默认为 'v1'。
23. THE：系统主题设置，默认为 'default'，具体可选值参见 [here] (./web/README. md)。
24. ENABLE_METRIC：是否根据请求成功率禁用渠道，默认不启用，可选值为 'true' 和 'false'。
25. METRIC_QUEUE_SIZE：请求成功率统计队列大小，默认为 '10'。
26. METRIC_SUCCESS_RATE_THRESHOLD：请求成功率阈值，默认为 '0.8'。
27. INITIAL_ROOT_TOKEN：如果设置了此值，系统首次启动时将自动创建一个值为该环境变量的 root 用户令牌。
28. INITIAL_ROOT_ACCESS_TOKEN：如果设置了此值，系统首次启动时将自动为 root 用户创建一个值为该环境变量的系统管理令牌。

命令行参数

1. --port <port_number>：指定服务器监听的端口号。默认为 3000。
   • 示例：--port 3000
2. --log-dir <log_dir>：指定日志目录。若未设置，则不会保存日志。
   • 示例：--log-dir ./logs
3. --version：打印系统版本号并退出。
4. --help：显示命令用法帮助及参数说明。

截图

常见问题

1. 什么是 quota（配额）？如何计算？One API 的配额计算是否存在问题？
   • Quota = 分组倍率 * 模型倍率 *（prompt token 数量 + completion token 数量 * completion 倍率）
   • completion 倍率对于 GPT3.5 固定为 1.33，对于 GPT4 固定为 2，与官方定义一致。
   • 若非 stream 模式，官方 API 会返回消耗的 token 总数。但请注意，prompt 与 completion 的消耗倍率不同。
2. 为何账户余额充足却仍提示「insufficient quota」（配额不足）？
   • 请检查 token 配额是否充足。它与账户余额是分开计算的。
   • token 配额用于设置最大使用量，可由用户自由设定。
3. 使用渠道时提示「No available channels」（无可用渠道），该怎么办？
   • 请检查用户与渠道分组设置。
   • 同时检查渠道模型设置。
4. 渠道测试报错：「invalid character '<' looking for beginning of value」
   • 该错误表示返回值不是有效的 JSON，而是一段 HTML 页面。
   • 最常见的原因是部署站点 IP 或代理节点已被 CloudFlare 封禁。
5. ChatGPT Next Web 报错：「Failed to fetch」
   • 部署时请勿设置 BASE_URL。
   • 请再次确认接口地址与 API Key 是否正确。

相关项目

• FastGPT: 基于 LLM 的知识问答系统
• VChart: 不只是跨平台图表库，更是富有表现力的数据叙事工具。
• VMind: 不仅自动，而且出色。智能可视化的开源解决方案。
• • CherryStudio: 集成多家服务商、支持本地知识库管理的跨平台 AI 客户端。

说明

本项目为开源项目。请遵守 OpenAI 的 Terms of Use 以及适用的法律法规使用，不得用于非法用途。

本项目基于 MIT 许可证发布。据此，页面底部须注明出处并附上本项目的链接。

基于本项目衍生的项目同样适用。

若不愿注明出处，须事先获得授权。

依据 MIT 许可证，用户应自行承担使用本项目的风险与责任，本开源项目开发者对此不承担责任。