OneAPI网关使用简介
全文链接 OneAPI网关使用简介
OneAPI 是 OpenAI 接口管理与分发系统，统一对接多家大模型服务，支持渠道管理、令牌与额度控制、计费与日志，便于在应用侧通过单一 API 访问不同模型或自建服务。
目录
- [1. 网关简介](#1. 网关简介)
- [2. 网关作用](#2. 网关作用)
- [3. 部署与使用](#3. 部署与使用)
- [3.1 部署](#3.1 部署)
- [3.2 账号初始化](#3.2 账号初始化)
- [4. 代理大模型服务案例](#4. 代理大模型服务案例)
- [4.1 渠道配置](#4.1 渠道配置)
- [4.2 令牌配置](#4.2 令牌配置)
- [4.3 代理使用](#4.3 代理使用)
- [5. 常见问题](#5. 常见问题)
- [5.1 初始化联网下载 token（tiktoken）](#5.1 初始化联网下载 token（tiktoken）)
1. 网关简介
- 项目地址 ：songquanpeng/one-api
- 定位：OpenAI 兼容接口的管理与分发系统，单可执行文件，提供 Docker 镜像，一键部署。
2. 网关作用
- 统一入口：应用侧只需对接 OneAPI 的 OpenAI 兼容 API，通过不同渠道或令牌访问多种大模型（OpenAI、Azure、DeepSeek、智谱、文心、通义等）或自建服务。
- 渠道与代理：为每个上游服务配置「渠道」，填写模型类型、名称、密钥、代理 URL，请求按渠道转发到对应后端。
- 令牌与权限：通过「令牌」控制访问权限、模型范围、额度与过期时间，便于多应用或多用户共享同一网关。
- 计费与日志：按 token 统计用量、限流与计费，支持兑换码、额度明细与操作日志。
3. 部署与使用
3.1 部署
sh
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 账号初始化
- 浏览器访问
http://<服务器IP>:3000/（端口以实际映射为准）。 - 首次登录：点击右上角「登录」，默认账号 root ，密码 123456。
- 登录后按提示重置密码，再次登录即可使用。
- 进入后台后可看到「渠道」「令牌」等菜单。
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 中预先下载并重新构建镜像，供内网部署使用。