One API 统一调用 ChatGLM/文心一言等 20+ 大模型实践

1.2 权限与用量管理缺失，团队协作风险高

很多团队早期用个人 Key 硬编码在脚本里，结果出现：

• 某成员离职，所有服务因 Key 失效集体中断；
• 某个测试脚本疯狂调用，耗尽整月额度却找不到责任人；
• 客户 A 想用 Qwen，客户 B 只允许调 ChatGLM，但后端代码无法区分。

One API 内置完整的令牌（Token）生命周期管理：

• 为每个项目/客户端生成独立令牌，绑定额度、过期时间、IP 白名单；
• 支持按用户分组（default/vip/svip）分配可用模型池，VIP 组可调 Gemini+Qwen，普通组仅限 GLM；
• 所有调用自动记账，实时查看'谁在什么时间用了哪个模型多少 token'。

这不再是'能用就行'，而是真正具备生产环境所需的可观测性与可控性。

1.3 部署极简，但能力不妥协

它没有选择复杂微服务架构，而是以单二进制文件为核心：

• Docker 镜像仅 80MB，无 Python/Node.js 运行时依赖；
• 数据全落盘到 /data 目录，断电不丢配置；
• 管理后台自带 Web UI，无需额外搭建前端；
• 支持负载均衡——同一令牌请求可自动分发至多个渠道，防止单点故障。

一句话总结：它把企业级能力，压缩进了'一条 docker run 命令'的交付粒度里。

2. 三分钟完成部署：Docker 一键启动，不碰配置文件

部署 One API 不需要理解 Go 语言、不需配置 Nginx 反向代理、不需手动编译。你只需要确认两件事： ① 你的机器已安装 Docker（官网安装指南）； ② 你有权限创建本地目录（如 /opt/oneapi）。

下面提供两种最常用方式，任选其一即可。

2.1 方式一：单命令快速体验（推荐首次尝试）

打开终端，执行这一行命令：

docker run --name one-api -d \
  --restart always \
  -p 13000:3000 \
  -e TZ=Asia/Shanghai \
  -v $(pwd)/oneapi-data:/data \
  justsong/one-api

命令说明： -p 13000:3000 将容器内 3000 端口映射到宿主机 13000 端口（你可改为其他未占用端口）； -v $(pwd)/oneapi-data:/data 将当前目录下 oneapi-data 文件夹挂载为数据目录，确保重启后配置不丢失； justsong/one-api 是官方维护的 Docker 镜像，自动拉取最新稳定版。

等待 5 秒，访问 http://localhost:13000，你将看到登录页。 默认账号：root，密码：123456（登录后第一件事：立即修改密码！）

2.2 方式二：docker-compose 长期使用（推荐生产环境）

在任意目录新建 docker-compose.yml 文件，内容如下：

version: '3.8'
services:
  oneapi:
    container_name: oneapi
    image: justsong/one-api:latest
    restart: unless-stopped
    ports:
      - "13000:3000"
    volumes:
      - ./oneapi-data:/data
    environment:
      - TZ=Asia/Shanghai
    # 可选：添加健康检查
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

保存后，在该目录下执行：

docker-compose up -d

服务启动后，同样访问 http://localhost:13000 登录。 优势：便于版本锁定（如 justsong/one-api:v0.6.0）、集成健康检查、后续扩展日志/监控更方便。

3. 配置你的第一个模型通道：以 ChatGLM 和文心一言为例

登录后台后，你面对的是一个清晰的模块化界面。核心操作集中在两个地方：渠道管理（对接模型）和令牌管理（分发调用凭证）。我们以国内最常用的两个模型为例，演示如何让它们'听懂'你的 OpenAI 请求。

3.1 添加 ChatGLM 渠道（智谱 AI）

1. 左侧菜单点击 渠道管理 → 添加渠道；
2. 填写以下关键字段：
   • 类型：选择 Zhipu AI（智谱）；
   • 名称：输入 chatglm4-prod（自定义，用于识别）；
   • 分组：勾选 default（表示所有普通用户可用）；
   • 模型：自动列出 glm-4, glm-3-turbo 等，勾选你需要的；
   • 密钥：粘贴你在 https://bigmodel.cn 获取的 API Key；
   • 代理：留空（直连）或填写公司内部代理地址（如 http://proxy.internal:8080）。

提示：One API 会自动检测密钥格式有效性，填错会红色提示。保存后，右侧'状态'列显示绿色✔即代表通道连通。

3.2 添加文心一言渠道（百度）

1. 再次点击 添加渠道；
2. 填写：
   • 类型：Baidu ERNIE Bot；
   • 名称：wenxin-4-prod；
   • 分组：同样勾选 default；
   • 模型：勾选 ernie-bot-4（或 ernie-bot-turbo）；
   • 密钥：此处需填写 Access Token，不是 AK/SK！获取方式：
     • 访问 百度 AI 控制台 → 应用列表 → 创建应用；
     • 在'应用详情'页找到 Access Token 字段，复制完整字符串（形如 24.xxx.xxxxx）；
   • 代理：同上，按需填写。

注意：文心一言的 Token 有效期为 30 天，One API 支持自动刷新（需在系统设置中开启'自动刷新 Access Token'）。

3.3 验证通道是否生效

添加完成后，回到 渠道管理 列表页，你会看到两个新条目。点击右侧 测试 按钮，输入一段测试消息（如'你好'），点击发送。 如果返回类似以下 JSON，说明通道已就绪：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1717021234,
  "model": "glm-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是 GLM-4，很高兴为你服务。"
      },
      "finish_reason": "stop"
    }
  ]
}

此时，你已成功将 ChatGLM 和文心一言'翻译'成了 OpenAI 协议。

4. 调用实操：用 Python/Shell/Postman，零改造接入

现在，所有模型对你而言，只剩下一个统一入口：http://localhost:13000/v1/chat/completions。 下面展示三种最常见调用方式，全部基于标准 OpenAI SDK 或 curl，无需任何修改。

4.1 Python 调用（兼容 openai==1.0+）

from openai import OpenAI

# 关键：只改 base_url 和 api_key，其余完全不变
client = OpenAI(
    base_url="http://localhost:13000/v1",  # 指向你的 One API
    api_key="sk-xxx-your-one-api-token"  # 从 One API 后台生成的令牌
)

response = client.chat.completions.create(
    model="glm-4",  # 指定调用 ChatGLM
    messages=[{"role": "user", "content": "用 Python 写一个快速排序"}],
    temperature=0.7
)

print(response.choices[0].message.content)

运行效果：输出 Python 版快排代码。你甚至可以将 model 参数换成 ernie-bot-4，同一段代码立即切换到文心一言。

4.2 curl 命令行调用（调试利器）

curl http://localhost:13000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxx-your-one-api-token" \
  -d '{
    "model": "qwen-max",
    "messages": [{"role": "user", "content": "请解释 Transformer 架构的核心思想"}],
    "stream": false
  }'

返回结果与 OpenAI 原生接口完全一致，可直接用现有 JSON Schema 校验。

4.3 Postman 配置（可视化调试）

1. 新建 Request，URL 设为 http://localhost:13000/v1/chat/completions；
2. Headers 添加：
   • Authorization: Bearer sk-xxx-your-one-api-token
   • Content-Type: application/json
3. Body 选择 raw → JSON，粘贴请求体；
4. 发送，查看响应。

支持自动保存环境变量，一键切换不同模型。

5. 进阶能力：让统一调用真正服务于业务

One API 的价值不仅在于'能调'，更在于'管得好、用得巧'。以下是三个高频实用场景的落地方法。

5.1 场景一：为不同客户分配专属模型池（权限隔离）

假设你为 A 公司提供 AI 客服，只允许调用 Qwen；为 B 公司做内容生成，需开放 GLM-4+Gemini。 操作路径：

1. 用户管理 → 添加用户，创建 a-company 和 b-company 两个账号；
2. 渠道管理 → 编辑对应渠道，在'分组'列取消勾选 default，改为新建分组 a-group / b-group；
3. 用户管理 → 编辑用户，将 a-company 的分组设为 a-group，b-company 设为 b-group；
4. 令牌管理 → 为各用户生成令牌，令牌自动继承其分组权限。

结果：A 公司令牌调用 ernie-bot-4 会返回 403 错误，B 公司令牌则可自由切换模型。

5.2 场景二：流式响应实现'打字机效果'

前端需要逐字返回，提升交互感？One API 原生支持 OpenAI 标准 SSE 流式协议：

response = client.chat.completions.create(
    model="glm-4",
    messages=[{"role": "user", "content": "写一首关于春天的七言绝句"}],
    stream=True  # 关键：启用流式
)
for chunk in response:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, flush=True)

输出效果：字符逐个打印，无需前端额外解析，兼容所有 OpenAI 流式 SDK。

5.3 场景三：失败自动重试 + 多渠道兜底

网络抖动导致某次文心一言调用超时？One API 默认开启：

• 单次请求失败后，自动按配置策略重试（最多 3 次）；
• 若配置了多个渠道（如同时添加了 Qwen 和 GLM-4），可设置'负载均衡策略'为 random 或 round-robin，自动 fallback；
• 在 渠道管理 → 编辑渠道 中，可单独为每个渠道设置'权重'，例如 Qwen 权重 80%，GLM-4 权重 20%，实现灰度发布。

6. 总结：统一接口，是 AI 工程化的起点而非终点

One API 解决的从来不是一个'能不能调'的问题，而是'要不要为每个模型重复造轮子'的效率问题。它把大模型接入的复杂性，封装成一次部署、两次配置、三次调用的确定性流程。

回顾本文实践，你已掌握：

• 如何用一条 Docker 命令，在 3 分钟内获得 20+ 模型的统一网关；
• 如何为 ChatGLM、文心一言等国产主力模型配置通道，并验证连通性；
• 如何用原生 OpenAI SDK，零代码改造调用任意后端模型；
• 如何通过分组、令牌、负载均衡，实现企业级的权限与稳定性管控。

真正的生产力解放，不在于追逐最新模型，而在于让已有能力快速、安全、可控地流动起来。当你不再为接口协议焦头烂额，才能真正聚焦于：如何用 AI 重构产品逻辑、优化用户体验、创造业务价值。

下一步，你可以： → 尝试添加通义万相（文生图）或 Qwen-VL（多模态）扩展能力； → 配置 Cloudflare Turnstile 防止恶意刷 Key； → 结合 Message Pusher，将额度告警推送到企业微信。

技术的价值，永远体现在它省下的那些本该用来 debug 的时间上。