OneAPI开源大模型网关入门必看：3步完成Docker部署，5分钟对接通义千问与混元

你是不是也遇到过这样的烦恼？公司项目想用通义千问，个人实验想试试腾讯混元，偶尔还要调用一下ChatGPT。每个模型都有自己的API地址、密钥格式和调用方式，光是管理这些密钥和接口就够头疼了，更别说还要在代码里写一堆if-else来判断该用哪个。

今天要介绍的OneAPI，就是来解决这个问题的。它就像一个“万能转换器”，让你用一套标准的OpenAI API格式，就能访问市面上几乎所有主流的大模型。无论是阿里的通义千问、腾讯的混元，还是百度的文心一言、字节的豆包，甚至是海外的Claude、Gemini，你都可以用同一种方式调用。

最棒的是，部署它只需要3步，对接一个新模型最快只要5分钟。接下来，我就带你从零开始，手把手搞定OneAPI的部署和基础使用。

1. 3步完成Docker部署，让OneAPI跑起来

部署OneAPI非常简单，如果你有一台安装了Docker的Linux服务器（云服务器或本地虚拟机都可以），整个过程不会超过10分钟。

1.1 第一步：拉取Docker镜像

打开你的服务器终端，执行下面这条命令。它会从Docker Hub上拉取最新的OneAPI镜像。

docker pull songquanpeng/one-api:latest

命令执行后，你会看到Docker开始下载镜像。等待片刻，直到出现“Status: Downloaded newer image for songquanpeng/one-api:latest”类似的提示，就表示镜像拉取成功了。

1.2 第二步：启动OneAPI容器

镜像拉取完成后，我们需要把它运行起来。这里我们通过一条docker run命令来启动容器，并配置好必要的参数。

docker run -d \
  --name one-api \
  -p 3000:3000 \
  -v /home/ubuntu/one-api/data:/data \
  -e TZ=Asia/Shanghai \
  songquanpeng/one-api:latest

我来解释一下这条命令的每个部分是干什么的：

  • -d：让容器在后台运行。
  • --name one-api：给这个容器起个名字，方便以后管理。
  • -p 3000:3000：把容器内部的3000端口映射到服务器的3000端口。这样你访问服务器IP:3000就能打开OneAPI的管理界面。
  • -v /home/ubuntu/one-api/data:/data：把服务器上的/home/ubuntu/one-api/data目录挂载到容器内的/data目录。这样OneAPI的所有数据（比如配置、数据库）都会保存在服务器上，即使容器删除了，数据也不会丢。你可以把/home/ubuntu/one-api/data换成你自己服务器上想存放数据的任何路径。
  • -e TZ=Asia/Shanghai：设置容器的时区为上海时间，这样日志和管理界面显示的时间就是正确的。
  • songquanpeng/one-api:latest：指定要运行的镜像名称和标签。

执行完这条命令后，你可以用 docker ps 命令查看容器是否已经正常运行。

1.3 第三步：登录并修改默认密码

现在，打开你的浏览器，访问 http://你的服务器IP地址:3000。

你会看到OneAPI的登录界面。首次登录请使用以下账号：

  • 用户名：root
  • 密码：123456

重要安全提醒：登录成功后，第一件事就是去修改这个默认密码！点击页面右上角的用户头像，进入“用户信息”或“修改密码”页面，设置一个强密码。这是保护你系统安全最关键的一步。

完成这三步，OneAPI就已经部署好并可以访问了。接下来，我们给它添加第一个大模型渠道。

2. 5分钟对接第一个大模型：以通义千问为例

OneAPI的管理界面很清晰。我们现在的目标是为它添加一个“渠道”，也就是告诉OneAPI去哪里调用真正的大模型。这里我们以阿里云的通义千问为例。

2.1 获取通义千问的API密钥

首先，你需要有一个阿里云账号，并在阿里云百炼平台开通大模型服务。开通后，在控制台你可以找到“API密钥管理”的地方，创建一个新的API密钥（Access Key），你会得到：

  • AccessKey ID
  • AccessKey Secret

请妥善保存这两个信息，下一步会用到。

2.2 在OneAPI中添加通义千问渠道

回到OneAPI的管理界面（http://服务器IP:3000），用你修改后的root密码登录。

  1. 在左侧菜单栏，找到并点击 “渠道”。
  2. 在渠道列表页面，点击右上角的 “添加渠道” 按钮。
  3. 在弹出的表单中，填写以下信息：
    • 渠道名称： 给你这个渠道起个名字，比如“我的通义千问”。
    • 渠道类型： 在下拉菜单中找到并选择 “阿里云通义千问”。
    • API密钥： 这里需要填写一个组合字符串。格式为：sk-你的AccessKey ID#你的AccessKey Secret。 例如，如果你的AccessKey ID是LTAI5t1234567890abcd，Secret是ABCdef1234567890xyz，那么这里就填写： sk-LTAI5t1234567890abcd#ABCdef1234567890xyz
    • 模型： 这里可以填写通义千问支持的模型名称，比如 qwen-max、qwen-plus、qwen-turbo 等。你可以先填 qwen-max。如果不确定，也可以先留空，OneAPI有时会自动获取。
    • 其他参数： 如“权重”、“分组”等，初次使用可以保持默认。
  4. 填写完毕后，点击 “提交”。

稍等几秒钟，OneAPI会测试这个渠道是否连通。如果状态显示为“正常”，恭喜你，渠道添加成功了！

2.3 获取你的OneAPI访问令牌

渠道是给OneAPI用的，你自己的程序要调用OneAPI，还需要一个“令牌”（Token）。

  1. 在左侧菜单栏，找到并点击 “令牌”。
  2. 点击右上角的 “创建令牌”。
  3. 你可以设置令牌的名称、过期时间和额度。为了方便测试，额度可以设大一点或者不限制。
  4. 点击 “提交”。
  5. 创建成功后，务必立刻复制并保存好生成的这串密钥（格式如 sk-xxxxxx）。这个密钥只会显示一次，丢失后需要重新创建。

现在，你已经拥有了：

  • 一个运行中的OneAPI服务（地址：http://你的服务器IP:3000）
  • 一个可用的通义千问渠道
  • 一个属于你自己的API访问令牌

接下来，我们就可以像调用OpenAI一样，通过OneAPI来使用通义千问了。

3. 像用OpenAI一样调用所有模型：实战代码演示

这是OneAPI最核心的便利之处。无论后端对接的是哪个模型，你的调用代码几乎不用变。

3.1 调用通义千问的Python示例

假设你的OneAPI地址是 http://192.168.1.100:3000，令牌是 sk-abc123def456。

你可以使用官方的 openai Python库来调用，代码和调用真正的OpenAI API一模一样，只需要改一下 base_url 和 api_key。

from openai import OpenAI

# 初始化客户端，指向你自己的OneAPI服务器
client = OpenAI(
    api_key="sk-abc123def456",  # 替换成你在OneAPI创建的令牌
    base_url="http://192.168.1.100:3000/v1"  # 替换成你的OneAPI地址，注意加上/v1
)

# 发起聊天请求
response = client.chat.completions.create(
    model="qwen-max",  # 指定要使用的模型，对应你在渠道里设置的模型名
    messages=[
        {"role": "system", "content": "你是一个乐于助人的助手。"},
        {"role": "user", "content": "请用一句话介绍你自己。"}
    ],
    stream=False  # 非流式输出
)

# 打印结果
print(response.choices[0].message.content)

运行这段代码，你就会得到通义千问模型的回复。关键在于 base_url 指向了你自己的OneAPI服务器，而 model 参数填写的是你在添加通义千问渠道时设置的模型名称（如 qwen-max）。

3.2 再添一个渠道：快速对接腾讯混元

有了上面的经验，添加第二个模型渠道就更快了。我们以腾讯混元为例。

  1. 获取凭证：前往腾讯云混元大模型控制台，获取你的 SecretId 和 SecretKey。
  2. 添加渠道：在OneAPI的“渠道”页面，点击“添加渠道”。
    • 渠道类型：选择 “腾讯云混元”。
    • API密钥：填写格式为 sk-你的SecretId#你的SecretKey。
    • 模型：可以填写 hunyuan-lite、hunyuan-standard 等，根据你在腾讯云开通的模型来定。
  3. 测试调用：代码几乎不用改，只需要把 model 参数换成 hunyuan-lite 即可。
# 使用同一个client，只需更改model参数
response = client.chat.completions.create(
    model="hunyuan-lite",  # 切换到腾讯混元模型
    messages=[
        {"role": "user", "content": "深圳今天天气怎么样？"}
    ]
)
print(response.choices[0].message.content)

看到了吗？你的应用程序代码完全不需要改动模型供应商的逻辑，只需要在OneAPI后台添加一个渠道，在代码里换一个 model 名称，就无缝切换到了另一个大模型。这就是统一API网关的巨大优势。

4. OneAPI还能为你做什么？更多实用功能一览

除了最基本的统一接口，OneAPI还内置了许多对开发者和管理员非常实用的功能，让你能更专业、更省心地管理大模型调用。

4.1 负载均衡与故障转移

如果你为同一个模型（比如 gpt-3.5-turbo）添加了多个渠道（可能来自不同供应商或不同API Key），OneAPI可以自动在这些渠道之间进行负载均衡。当一个渠道失败或达到速率限制时，它会自动切换到下一个可用的渠道，极大地提高了服务的稳定性和可用性。

4.2 精细化的令牌与额度管理

你可以创建多个令牌给不同的用户或应用使用，并为每个令牌设置：

  • 过期时间：令牌多久后失效。
  • 额度限制：该令牌最多能调用多少次或花费多少金额。
  • 模型白名单：限制该令牌只能访问某些特定模型。
  • IP白名单：限制该令牌只能从特定的IP地址调用。

这对于商业化分发或团队内部资源管控非常有用。

4.3 清晰的消费监控与统计

在OneAPI的管理后台，你可以清晰地看到：

  • 总消费额度的消耗情况。
  • 每个令牌的详细使用日志和消费记录。
  • 每个渠道的调用次数、成功失败率和消耗金额。

所有数据一目了然，方便你做成本分析和优化。

4.4 扩展性与自定义

OneAPI的架构考虑到了扩展性：

  • 管理API：系统提供了完整的API，让你可以不用修改源代码，就能集成用户系统、自动化创建令牌等。
  • 自定义界面：你可以修改系统名称、Logo、页脚，甚至用HTML自定义首页和关于页面。
  • 多机部署：当单台服务器性能不足时，可以参照官方文档进行多机部署，实现水平扩展。

5. 总结

回顾一下，我们今天完成了三件大事：

  1. 3步部署：通过Docker，我们用三条命令就成功搭建起了OneAPI服务，拥有了自己的大模型网关。
  2. 5分钟对接：我们以通义千问和腾讯混元为例，演示了如何快速将一个主流大模型接入OneAPI，整个过程就是“获取密钥 -> 后台填写 -> 完成测试”。
  3. 统一调用：我们看到了，无论后端对接了多少种模型，我们的应用程序只需要维护一套基于OpenAI格式的代码，通过改变model参数就能轻松切换，彻底告别了复杂的多套SDK和API格式。

OneAPI就像一个强大的“中控台”，它解决了大模型应用开发中“接口杂乱、密钥难管、监控缺失”的核心痛点。无论是个人开发者快速试验多种模型，还是企业统一管理对内外的大模型服务，它都是一个非常值得投入学习和使用的工具。

下一步，你可以尝试接入更多模型（如文心一言、讯飞星火等），探索负载均衡配置，或者利用令牌管理功能为你的多个小程序分配不同的调用权限。它的功能远不止我们今天介绍的这些，更多高级玩法等待你去挖掘。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek 上线审批门禁：如何平衡自动化与安全审查

avatar DeepSeek技术社区
cover

DeepSeek API 路由策略：代码硬编码 vs 动态配置的工程取舍

avatar DeepSeek技术社区
cover

DeepSeek RAG 索引增量更新：如何平衡实时性与资源开销

avatar DeepSeek技术社区