OneAPI部署教程：青云QingCloud KubeSphere OneAPI部署实践

使用 root 用户初次登录系统后，务必修改默认密码 123456！

1. 什么是OneAPI？

如果你正在使用多个大模型服务，比如OpenAI的ChatGPT、百度的文心一言、阿里的通义千问等等，一定会遇到一个头疼的问题：每个平台都有自己的API格式、认证方式和调用方法，管理和切换起来特别麻烦。

OneAPI就是为了解决这个问题而生的。它是一个开源的LLM API管理和分发系统，可以用统一的OpenAI API格式访问几乎所有主流大模型。简单来说，你只需要学会一种API调用方式，就能访问几十种不同的AI模型。

想象一下这样的场景：你的应用需要同时调用多个AI模型，以前需要为每个平台写不同的代码，现在只需要配置一次OneAPI，然后用统一的接口就能调用所有模型，大大简化了开发流程。

2. 核心功能亮点

2.1 广泛的模型支持

OneAPI最强大的地方在于它支持几乎所有主流的大模型：

• 国际模型：OpenAI ChatGPT系列、Anthropic Claude、Google Gemini、Mistral等
• 国内模型：文心一言、通义千问、讯飞星火、ChatGLM、360智脑、腾讯混元等
• 新兴模型：DeepSeek、Moonshot、百川、零一万物等
• 自部署模型：支持Ollama等本地模型部署方案

这意味着你不需要为每个模型学习不同的API，OneAPI帮你统一了访问接口。

2.2 企业级管理功能

除了基本的API转发，OneAPI还提供了完整的管理功能：

• 用户和令牌管理：可以创建多个用户，设置不同的访问权限和额度限制
• 负载均衡：自动在多个渠道间分配请求，提高可用性和性能
• 统计和监控：实时查看使用情况、消费明细和系统状态
• 自定义配置：支持自定义界面、登录方式、支付设置等

2.3 开箱即用的部署

OneAPI提供Docker镜像和单可执行文件，支持多种部署方式：

# 最简单的Docker部署方式
docker run -d --name one-api \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v /home/ubuntu/data/one-api:/data \
  justsong/one-api

3. 在KubeSphere上部署OneAPI

3.1 环境准备

在开始部署之前，确保你的KubeSphere环境满足以下要求：

• KubeSphere集群正常运行
• 至少2GB可用内存
• 至少10GB存储空间
• 网络连通性正常

3.2 创建部署配置

登录KubeSphere控制台，进入目标项目，选择"应用负载" → "部署"，点击"创建"。

基本配置：

• 名称：one-api
• 别名：OneAPI服务
• 描述：统一大模型API管理平台

容器配置：

image: justsong/one-api:latest
资源限制：
  CPU：1核心
  内存：2GB
端口：3000（TCP）

环境变量配置：

- name: TZ
  value: Asia/Shanghai
- name: SQL_DSN
  value: /data/oneapi.db

3.3 配置持久化存储

为了保证数据安全，需要为OneAPI配置持久化存储：

1. 创建持久卷声明（PVC）

   • 名称：one-api-data
   • 存储类：根据实际情况选择
   • 容量：至少10GB
   • 访问模式：ReadWriteOnce

2. 挂载到容器

   • 挂载路径：/data
   • 子路径：oneapi

3.4 配置服务访问

创建Service暴露OneAPI服务：

apiVersion: v1
kind: Service
metadata:
  name: one-api-service
spec:
  selector:
    app: one-api
  ports:
  - protocol: TCP
    port: 80
    targetPort: 3000
  type: ClusterIP

如果需要外部访问，可以创建Ingress：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: one-api-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - host: oneapi.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: one-api-service
            port:
              number: 80

4. 初始配置和使用

4.1 首次登录和密码修改

部署完成后，通过配置的访问地址打开OneAPI管理界面：

1. 使用默认账号登录

   • 用户名：root
   • 密码：123456

2. 重要：立即修改默认密码

   • 点击右上角用户头像 → "修改密码"
   • 设置强密码并妥善保管

4.2 添加第一个模型渠道

登录后，首先需要添加模型访问渠道：

1. 进入"渠道"页面，点击"添加渠道"
2. 选择模型类型（如OpenAI）
3. 填写API密钥和其他必要信息
4. 设置权重和优先级
5. 测试连接并保存

4.3 创建访问令牌

为用户创建API访问令牌：

1. 进入"令牌"页面，点击"创建令牌"
2. 设置令牌名称和权限
3. 指定可访问的模型和额度限制
4. 生成令牌并妥善保存

5. 实际使用示例

5.1 通过统一API调用不同模型

配置好OneAPI后，你可以用统一的OpenAI格式调用任何支持的模型：

import openai

# 配置OneAPI端点
openai.api_base = "http://your-oneapi-domain.com/v1"
openai.api_key = "your-token-here"

# 调用ChatGPT
response = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "你好，请介绍一下你自己"}]
)

# 调用文心一言
response = openai.ChatCompletion.create(
    model="wenxin",
    messages=[{"role": "user", "content": "你好，请介绍一下你自己"}]
)

5.2 负载均衡配置

OneAPI支持自动负载均衡，你可以在多个相同模型的渠道间分配流量：

1. 添加多个相同类型的渠道（如多个OpenAI账号）
2. 设置不同的权重值
3. OneAPI会自动按权重分配请求

5.3 模型映射和重定向

如果需要将用户请求的模型映射到实际可用的模型：

{
  "gpt-4": "gpt-4-0613",
  "claude-v1": "claude-instant-v1"
}

6. 运维和监控

6.1 系统监控

在KubeSphere中监控OneAPI的运行状态：

• 资源使用：查看CPU、内存、存储使用情况
• 日志查看：实时查看容器日志，排查问题
• 性能指标：监控请求延迟、错误率等关键指标

6.2 数据备份

定期备份OneAPI的数据：

# 备份数据库文件
kubectl cp <namespace>/<pod>:/data/oneapi.db ./oneapi-backup.db

# 或者使用Velero等工具进行整体备份

6.3 版本升级

当新版本发布时，可以平滑升级：

1. 更新Docker镜像版本
2. 逐步滚动更新实例
3. 验证新版本功能正常

7. 常见问题解决

7.1 部署问题

Q: 容器启动失败怎么办？ A: 检查日志确认具体错误，常见问题包括：

• 端口冲突：确保3000端口未被占用
• 权限问题：检查存储卷挂载权限
• 资源不足：增加内存或CPU分配

Q: 无法访问管理界面怎么办？ A: 检查网络配置：

• Service和Ingress配置是否正确
• 防火墙规则是否允许访问
• DNS解析是否正常

7.2 配置问题

Q: 模型渠道测试失败怎么办？ A: 检查以下配置：

• API密钥是否正确
• 代理设置（如果需要）
• 网络连通性

Q: API调用返回错误怎么办？ A: 查看详细错误信息：

• 令牌是否有效且有足够额度
• 请求的模型是否已配置渠道
• 参数格式是否符合要求

8. 总结

通过本文的教程，你应该已经成功在KubeSphere上部署了OneAPI，并了解了如何配置和使用这个强大的大模型统一管理平台。

OneAPI的价值在于它极大地简化了多模型管理的复杂性，让你可以用一套接口访问几乎所有主流AI模型。无论你是个人开发者还是企业用户，都能从中获得以下好处：

• 降低开发成本：只需学习一种API格式
• 提高可用性：支持负载均衡和故障转移
• 精细化管理：完整的用户、令牌、额度管理
• 灵活扩展：支持自定义配置和功能扩展

在实际使用中，建议先从简单的配置开始，逐步添加更多模型渠道和高级功能。记得定期备份数据，监控系统运行状态，确保服务的稳定性和安全性。

---

获取更多AI镜像

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