文章

OneAPI网关使用简介

发表于
Preview Image
作者 handsomestwei
6 分钟阅读
OneAPI网关使用简介

OneAPI网关使用简介

OneAPI 是 OpenAI 接口管理与分发系统，统一对接多家大模型服务，支持渠道管理、令牌与额度控制、计费与日志，便于在应用侧通过单一 API 访问不同模型或自建服务。

目录

1. 网关简介

  • 项目地址：songquanpeng/one-api
  • 定位：OpenAI 兼容接口的管理与分发系统，单可执行文件，提供 Docker 镜像，一键部署。

2. 网关作用

  • 统一入口：应用侧只需对接 OneAPI 的 OpenAI 兼容 API，通过不同渠道或令牌访问多种大模型（OpenAI、Azure、DeepSeek、智谱、文心、通义等）或自建服务。
  • 渠道与代理：为每个上游服务配置「渠道」，填写模型类型、名称、密钥、代理 URL，请求按渠道转发到对应后端。
  • 令牌与权限：通过「令牌」控制访问权限、模型范围、额度与过期时间，便于多应用或多用户共享同一网关。
  • 计费与日志：按 token 统计用量、限流与计费，支持兑换码、额度明细与操作日志。

3. 部署与使用

3.1 部署

1
2
3
4
5

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，可按需修改宿主机映射（如 -p 8300:3000）。
  • 数据持久化目录为 /data，建议挂载到宿主机。

3.2 账号初始化

  1. 浏览器访问 http://<服务器IP>:3000/（端口以实际映射为准）。
  2. 首次登录：点击右上角「登录」，默认账号 root，密码 123456。
  3. 登录后按提示重置密码，再次登录即可使用。
  4. 进入后台后可看到「渠道」「令牌」等菜单。

4. 代理大模型服务案例

以代理 DeepSeek 或 华为昇腾服务化模型 为例：上游已提供 OpenAI 兼容接口，通过 OneAPI 配置渠道与令牌，应用侧改为请求 OneAPI 地址并携带令牌即可。

4.1 渠道配置

在「渠道」中新增渠道，示例配置如下：

页面配置项配置说明
类型选择与上游一致的模型类型，如 DeepSeek
名称填写实际使用的大模型名称，如 deepseek-r1-32b
分组选 default 或自定义分组
模型先清空默认模型列表，再填入自定义模型名称，如 deepseek-r1-32b
密钥若上游需要鉴权则填写，否则可填占位如 sk-aaa
代理填入上游服务 OpenAI 兼容接口的 base URL，如 http://6.145.54.20:1027

4.2 令牌配置

在「令牌」中新增令牌，用于应用侧调用：

页面配置项配置说明
名称便于识别的名称，如 deepseek-r1-32b
模型范围下拉选择该令牌可访问的模型（与渠道中配置的模型对应）
过期时间可按需设置，或点击「永不过期」
额度可按需设置，或点击「设为无限额度」

4.3 代理使用

在需要使用大模型的应用中，将 API 地址与 Key 改为指向 OneAPI：

配置项说明
API 域名OneAPI 网关地址，需带 /v1 后缀，如 http://6.145.54.21:8300/v1
API Key在 OneAPI 中配置的令牌内容

应用请求会发往 OneAPI，由 OneAPI 根据令牌对应的渠道转发到上游服务。

5. 常见问题

5.1 初始化联网下载 token（tiktoken）

现象：OneAPI 启动或首次统计用量时报错，提示需要下载 tiktoken 相关文件。

原因：OneAPI 在统计用量、计费、限流时按 token 数计算（与 OpenAI 计费方式一致），依赖 OpenAI 官方的 tiktoken 分词器。tiktoken 的数据文件是 BPE 词表（如 cl100k_base.tiktoken、o200k_base.tiktoken），用于将文本拆成 token 并计数。不同模型对应不同词表；OneAPI 启动时会按需从外网加载，内网或离线环境无法下载则会报错。

处理：

  • 方式一：在能联网的环境先运行一次，让 OneAPI 自动下载到数据目录，再将该目录挂载或打包到离线环境使用。
  • 方式二：使用 -e 等环境变量指定预置路径，或提前下载好对应 tiktoken 文件到挂载目录，再启动容器。
  • 方式三：在 Dockerfile 中预先下载并重新构建镜像，供内网部署使用。
AI, LLM
AI LLM OneAPI
本文由作者按照 CC BY 4.0 进行授权