OneAPI开源网关教程API文档自动生成Swagger UI集成配置你是不是也遇到过这样的烦恼团队里接入了各种大模型APIOpenAI、Claude、文心一言、通义千问……每个模型的调用方式都不一样文档分散在各个平台新同事上手要花好几天时间熟悉。更头疼的是API接口文档更新不及时前端开发同学总是来问“这个参数到底怎么传”今天我要分享的解决方案能让你用一个统一的接口访问所有主流大模型更重要的是它能自动生成清晰、规范的API文档并集成Swagger UI让接口调试和团队协作变得无比简单。1. 什么是OneAPI为什么你需要它简单来说OneAPI是一个开源的LLM API管理和分发系统。它的核心价值可以用一句话概括通过标准的OpenAI API格式访问所有主流大模型。想象一下你团队里同时用着ChatGPT写代码、Claude分析文档、文心一言做中文内容生成。以前你需要为每个模型单独申请API Key学习不同的调用方式处理不同的计费规则维护多套代码逻辑现在有了OneAPI你只需要部署一个OneAPI服务把所有模型的API Key配置进去用统一的OpenAI格式调用所有模型更棒的是OneAPI还提供了完整的API文档自动生成和Swagger UI集成。这意味着前端同学可以直接在网页上测试接口新同事能快速了解所有可用接口接口变更时文档自动更新减少沟通成本提升开发效率2. 快速部署10分钟搭建你的统一API网关2.1 环境准备OneAPI的部署非常简单支持多种方式。我们先从最常用的Docker部署开始。系统要求Linux/Windows/macOS都可以Docker和Docker Compose至少1GB内存网络能访问外网用于拉取模型API如果你还没有安装Docker可以先用这个命令检查# 检查Docker是否安装 docker --version # 检查Docker Compose是否安装 docker-compose --version如果显示版本号说明已经安装好了。如果没有安装可以去Docker官网下载对应系统的安装包。2.2 一键部署Docker方式这是最简单的部署方式适合大多数场景。创建一个docker-compose.yml文件version: 3.8 services: oneapi: image: justsong/one-api:latest container_name: one-api ports: - 3000:3000 volumes: - ./data:/data environment: - SQL_DSNsqlite:///data/oneapi.db - REDIS_CONN_STRINGredis://redis:6379 - SESSION_SECRETyour_session_secret_here restart: unless-stopped depends_on: - redis redis: image: redis:7-alpine container_name: one-api-redis restart: unless-stopped volumes: - ./redis-data:/data保存文件后只需要一行命令# 启动服务 docker-compose up -d # 查看日志确认服务正常启动 docker-compose logs -f oneapi看到类似下面的输出说明启动成功了one-api | 2024/01/01 12:00:00 One API 启动成功 one-api | 2024/01/01 12:00:00 监听端口: 30002.3 初次登录和配置服务启动后打开浏览器访问http://你的服务器IP:3000你会看到登录页面。重要安全提醒 使用root用户初次登录系统后务必立即修改默认密码123456登录后的操作流程点击右上角用户头像 → 修改密码输入旧密码123456设置一个强密码确认修改重新登录现在你的OneAPI服务已经运行起来了。但要让它能真正工作我们还需要配置模型渠道。3. 配置模型渠道接入所有主流大模型OneAPI最强大的功能就是支持数十种主流大模型。我们来看看怎么配置。3.1 添加第一个模型渠道以OpenAI为例登录OneAPI管理后台点击左侧菜单渠道 → 添加渠道填写渠道信息基础信息渠道名称OpenAI官方渠道类型选择OpenAI模型填写gpt-3.5-turbo,gpt-4,gpt-4-turbo用英文逗号分隔分组默认分组认证信息API Key填写你的OpenAI API Key以sk-开头代理地址可选如果你需要代理填写代理地址高级设置权重默认100用于负载均衡并发数根据你的需求设置自动禁用开启后如果连续失败会自动禁用该渠道点击提交你的第一个模型渠道就添加成功了。3.2 批量添加其他模型OneAPI支持批量添加渠道这对于管理多个API Key特别方便。准备一个CSV文件格式如下名称,类型,密钥,模型,分组,权重,代理 OpenAI官方,OpenAI,sk-xxx,gpt-3.5-turbo,默认,100, Claude官方,Anthropic,sk-ant-xxx,claude-3-opus,默认,100, 文心一言,百度文心一言,xxx,ERNIE-Bot,默认,100, 通义千问,阿里通义千问,xxx,qwen-turbo,默认,100,在渠道页面点击批量创建上传CSV文件系统会自动创建所有渠道3.3 测试渠道是否正常添加完渠道后需要测试一下是否配置正确# 使用curl测试OpenAI渠道 curl -X POST http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的OneAPI令牌 \ -d { model: gpt-3.5-turbo, messages: [ {role: user, content: 你好} ] }如果返回类似下面的响应说明配置成功{ id: chatcmpl-xxx, object: chat.completion, created: 1677858242, model: gpt-3.5-turbo, choices: [{ index: 0, message: { role: assistant, content: 你好有什么我可以帮助你的吗 }, finish_reason: stop }], usage: { prompt_tokens: 10, completion_tokens: 15, total_tokens: 25 } }4. API文档自动生成告别手动维护文档的烦恼配置好模型渠道后OneAPI会自动为所有接口生成完整的API文档。这是怎么做到的呢4.1 理解OneAPI的API结构OneAPI的API设计完全兼容OpenAI官方API这意味着接口路径相同如/v1/chat/completions请求参数相同响应格式相同错误码相同这种设计带来了巨大的好处任何兼容OpenAI API的客户端都能无缝接入OneAPI。4.2 查看自动生成的API文档OneAPI内置了API文档生成功能。访问以下地址可以看到OpenAPI规范文档http://localhost:3000/swagger/doc.jsonReDoc文档http://localhost:3000/redocSwagger UIhttp://localhost:3000/swagger这些文档是实时自动生成的基于你的实际配置。当你添加新的模型渠道或修改接口配置时文档会自动更新。4.3 API文档包含哪些内容自动生成的文档会包含接口列表聊天补全接口 (/v1/chat/completions)模型列表接口 (/v1/models)余额查询接口 (/dashboard/billing/credit_grants)图像生成接口 (/v1/images/generations)语音转文字接口 (/v1/audio/transcriptions)每个接口的详细信息请求方法GET/POST等请求路径请求头要求请求参数类型、是否必需、描述响应示例错误码说明认证信息Bearer Token的使用方式如何获取和管理Token5. Swagger UI集成可视化调试你的APISwagger UI是一个强大的API文档和测试工具。OneAPI已经内置了Swagger UI开箱即用。5.1 访问Swagger UI在浏览器中打开http://localhost:3000/swagger你会看到一个漂亮的交互式API文档界面左侧是接口列表右侧是接口详情和测试工具。5.2 使用Swagger UI测试接口我们以测试聊天接口为例找到/v1/chat/completions接口点击展开点击Try it out按钮在请求体中填写测试数据{ model: gpt-3.5-turbo, messages: [ { role: user, content: 用Python写一个快速排序算法 } ], temperature: 0.7, max_tokens: 1000 }点击Execute按钮查看响应结果和状态码Swagger UI的优势无需安装额外工具直接在浏览器中测试自动填充参数不用手动写JSON实时查看响应立即看到API返回结果支持认证可以设置Authorization头导出请求生成curl命令或代码片段5.3 配置Swagger UI可选OneAPI的Swagger UI支持一些自定义配置。你可以在环境变量中设置# docker-compose.yml中的环境变量 environment: - SWAGGER_HOSTapi.yourdomain.com # 设置Swagger显示的host - SWAGGER_BASE_PATH/v1 # 设置基础路径 - SWAGGER_SCHEMEShttps # 设置协议6. 实际应用场景团队协作的最佳实践现在你已经部署好了OneAPI配置了模型渠道也了解了API文档功能。我们来看看在实际团队协作中这些功能怎么用起来。6.1 场景一新同事快速上手问题新来的后端工程师需要调用大模型API但不知道有哪些接口可用参数怎么传。解决方案给他Swagger UI地址http://your-oneapi-domain/swagger让他自己浏览所有可用接口直接在页面上测试接口查看响应格式导出curl命令或代码片段直接用在项目里节省的时间至少2-3天的文档查阅和调试时间。6.2 场景二前端后端联调问题前端同学需要调用大模型接口但不确定请求格式和响应结构。解决方案后端在OneAPI中配置好所有模型渠道前端访问Swagger UI查看接口文档在Swagger UI中测试接口确认参数和响应根据测试结果调整前端代码好处减少沟通成本避免因为参数格式问题反复调试。6.3 场景三API版本管理和文档同步问题API有更新时文档没有及时更新导致调用方使用旧的接口格式。解决方案 OneAPI的文档是自动生成的基于实际的接口实现。这意味着接口有更新时文档自动更新不会出现文档和实际接口不一致的情况所有调用方都能看到最新的接口规范6.4 场景四多模型统一管理问题项目中使用多个大模型每个模型的调用方式都不一样。解决方案 通过OneAPI的统一接口所有模型都用同样的OpenAI格式调用只需要维护一套代码逻辑切换模型时只需要改model参数在Swagger UI中可以看到所有支持的模型7. 高级功能让API管理更强大OneAPI除了基本的API管理和文档生成还提供了很多高级功能让你的API网关更加强大。7.1 负载均衡和故障转移当你有多个相同模型的API Key时可以配置负载均衡# 配置多个OpenAI渠道 渠道1: OpenAI官方1 (权重: 50) 渠道2: OpenAI官方2 (权重: 30) 渠道3: OpenAI备用 (权重: 20)这样配置后请求会按权重分配到不同渠道如果某个渠道失败自动切换到其他渠道提高系统的可用性和稳定性7.2 速率限制和配额管理OneAPI支持细粒度的访问控制令牌管理为每个用户或应用创建独立的访问令牌速率限制设置每分钟/每小时的最大请求数配额管理设置每个令牌的总额度按Token或金额IP白名单限制只有特定IP可以访问这些功能对于商业应用或SaaS服务特别重要。7.3 监控和告警OneAPI提供了完整的监控功能实时统计查看每个渠道的使用情况、成功率、响应时间额度监控监控每个用户的剩余额度失败告警当渠道连续失败时发送告警审计日志记录所有API调用便于排查问题你可以配合Message Pusher将告警信息推送到微信、钉钉、飞书等平台。7.4 自定义和扩展OneAPI支持丰富的自定义界面自定义修改系统名称和Logo自定义首页和关于页面支持HTML和Markdown功能扩展通过管理API扩展功能支持Webhook通知可以集成到现有系统中8. 常见问题解答8.1 部署相关问题Q部署后无法访问Swagger UIA检查以下几点防火墙是否开放了3000端口Docker容器是否正常运行docker ps | grep one-api查看容器日志docker logs one-apiQ如何修改默认端口A在docker-compose.yml中修改端口映射ports: - 8080:3000 # 将外部8080端口映射到内部3000端口8.2 配置相关问题Q添加渠道后测试失败A按以下步骤排查检查API Key是否正确检查网络是否能访问对应API服务查看OneAPI日志中的错误信息尝试在渠道设置中启用代理Q如何查看API调用日志A在OneAPI管理后台点击日志菜单可以按时间、用户、渠道等条件筛选查看详细的请求和响应信息8.3 使用相关问题QSwagger UI中测试需要认证怎么设置A在Swagger UI页面点击右上角的Authorize按钮输入你的Bearer Token在OneAPI的令牌页面创建点击Authorize保存Q如何为团队不同成员设置不同权限AOneAPI支持用户角色管理管理员可以管理所有功能普通用户只能使用API不能修改配置通过用户分组实现更细粒度的权限控制8.4 性能优化建议Q如何提高API响应速度A几个优化建议启用Redis缓存OneAPI默认已配置配置多个渠道实现负载均衡根据业务需求调整超时时间对于高频接口考虑本地缓存结果Q如何监控系统性能AOneAPI提供了Prometheus metrics接口访问/metrics获取监控数据可以集成到Grafana等监控平台监控关键指标请求数、成功率、响应时间、错误率9. 总结通过这篇教程你应该已经掌握了OneAPI的核心功能和使用方法。让我们回顾一下关键点OneAPI的核心价值统一接口用OpenAI格式调用所有主流大模型简化管理一个平台管理所有API Key和渠道降低成本智能路由和负载均衡优化使用成本提升效率自动文档生成和Swagger UI集成部署和使用流程用Docker一键部署OneAPI服务配置你需要的大模型渠道使用统一的OpenAI格式调用API通过Swagger UI查看文档和测试接口给团队带来的好处新同事快速上手有完整的API文档和测试工具前后端高效协作接口规范明确减少沟通成本系统稳定可靠负载均衡和故障转移保证可用性成本可控可查详细的用量统计和配额管理OneAPI不仅仅是一个API网关它更是一个完整的大模型API管理解决方案。无论你是个人开发者、创业团队还是大型企业都能从中受益。现在就去部署一个OneAPI实例体验统一API管理和自动文档生成的便利吧。你会发现管理多个大模型API原来可以这么简单。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。