OneAPI快速上手：Postman调用示例、curl命令测试、Python SDK接入指南

OneAPI快速上手：Postman调用示例、curl命令测试、Python SDK接入指南

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

1. 什么是OneAPI？

OneAPI 是一个强大的 LLM API 管理与分发系统，它通过标准的 OpenAI API 格式让你能够访问所有主流大模型。简单来说，它就像是一个"万能转换器"——无论你想用哪个厂商的AI模型，只需要学会一种调用方式（OpenAI格式）就能搞定所有。

这个系统支持包括 OpenAI、Azure、Anthropic Claude、Google Gemini、DeepSeek、字节豆包、ChatGLM、文心一言、讯飞星火、通义千问等在内的30多种主流模型。你不需要为每个模型学习不同的API调用方式，OneAPI帮你统一处理，开箱即用。

2. 核心功能亮点

2.1 多模型统一接入

OneAPI 最强大的地方在于它支持丰富的模型生态：

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

2.2 企业级功能

• 负载均衡：自动在多个渠道间分配请求
• Stream模式：支持流式传输，实现打字机效果
• 多机部署：支持分布式部署提升性能
• 令牌管理：精细控制访问权限和额度
• 用户分组：为不同用户设置不同倍率和权限

2.3 管理监控

• 额度明细：清晰查看使用情况
• 兑换码系统：支持批量生成和管理
• 报警通知：配合 Message Pusher 推送异常信息
• 自定义界面：支持自定义logo、页脚和页面内容

3. 快速安装部署

OneAPI 提供多种部署方式，最简单的就是使用 Docker：

# 拉取最新镜像 docker pull songquanpeng/one-api:latest # 运行容器 docker run --name one-api -d \ -p 3000:3000 \ -e SQL_DSN="mysql://root:password@tcp(localhost:3306)/oneapi" \ -v /home/ubuntu/data/one-api:/data \ songquanpeng/one-api:latest

部署完成后，访问http://你的服务器IP:3000即可进入管理界面。

4. Postman调用示例

4.1 准备工作

首先需要在OneAPI管理界面创建渠道和令牌：

1. 登录管理后台（默认账号root/123456）
2. 在"渠道"页面添加你想要使用的模型渠道
3. 在"令牌"页面创建访问令牌

4.2 基础聊天调用

在Postman中配置以下参数：

请求配置：

• Method:POST
• URL:http://你的OneAPI地址/v1/chat/completions
• Headers:
  • Authorization: Bearer 你的令牌
  • Content-Type: application/json

请求体（JSON）：

{ "model": "gpt-3.5-turbo", "messages": [ { "role": "user", "content": "你好，请介绍一下你自己" } ], "temperature": 0.7, "max_tokens": 500 }

4.3 流式传输调用

如果你想要实现打字机效果，可以使用stream模式：

{ "model": "gpt-4", "messages": [ { "role": "user", "content": "写一个关于人工智能的短故事" } ], "stream": true, "temperature": 0.8 }

在Postman中，你需要使用"Send and Download"功能来接收流式响应。

5. curl命令测试

5.1 基础聊天测试

curl http://你的OneAPI地址/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的令牌" \ -d '{ "model": "gpt-3.5-turbo", "messages": [ { "role": "user", "content": "你好，请问你能做什么？" } ], "temperature": 0.7 }'

5.2 流式传输测试

curl http://你的OneAPI地址/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的令牌" \ -d '{ "model": "claude-2", "messages": [ { "role": "user", "content": "解释一下机器学习的基本概念" } ], "stream": true }'

5.3 使用不同模型

只需要修改请求中的model参数，就可以切换不同模型：

# 使用文心一言 "model": "ernie-bot" # 使用通义千问 "model": "qwen-plus" # 使用讯飞星火 "model": "spark-v3"

6. Python SDK接入指南

6.1 安装依赖

OneAPI完全兼容OpenAI的Python SDK，你可以直接使用openai库：

pip install openai

6.2 基础配置和使用

from openai import OpenAI # 配置客户端 client = OpenAI( api_key="你的OneAPI令牌", base_url="http://你的OneAPI地址/v1" # 注意要包含/v1 ) # 发送聊天请求 response = client.chat.completions.create( model="gpt-3.5-turbo", # 可以替换为任何支持的模型 messages=[ {"role": "user", "content": "你好，请用中文回答"} ], temperature=0.7 ) print(response.choices[0].message.content)

6.3 流式传输实现

def stream_chat(): stream = client.chat.completions.create( model="claude-2", messages=[ {"role": "user", "content": "写一首关于春天的诗"} ], stream=True ) for chunk in stream: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end="", flush=True) stream_chat()

6.4 批量处理多个请求

import asyncio from openai import AsyncOpenAI async def batch_requests(): aclient = AsyncOpenAI( api_key="你的令牌", base_url="http://你的OneAPI地址/v1" ) tasks = [] for question in ["什么是AI？", "机器学习是什么？", "深度学习有什么应用？"]: task = aclient.chat.completions.create( model="gpt-3.5-turbo", messages=[{"role": "user", "content": question}], temperature=0.7 ) tasks.append(task) responses = await asyncio.gather(*tasks) for i, response in enumerate(responses): print(f"问题 {i+1}: {response.choices[0].message.content}") # 运行批量请求 asyncio.run(batch_requests())

7. 高级功能使用示例

7.1 负载均衡配置

OneAPI支持自动在多个渠道间进行负载均衡，你只需要在管理界面添加多个相同模型的渠道，系统会自动分配请求。

7.2 自定义模型映射

如果你需要将请求重定向到特定模型，可以使用模型映射功能：

# 即使请求gpt-4，实际会使用qwen-plus处理 response = client.chat.completions.create( model="gpt-4", # 映射到通义千问 messages=[{"role": "user", "content": "问题内容"}] )

7.3 使用绘图接口

OneAPI也支持DALL-E等绘图模型的调用：

# 生成图片 response = client.images.generate( model="dall-e-3", prompt="一只可爱的卡通猫在花园里玩耍", size="1024x1024", quality="standard", n=1 ) image_url = response.data[0].url print(f"生成的图片: {image_url}")

8. 常见问题解决

8.1 连接问题

如果遇到连接错误，首先检查：

• OneAPI服务是否正常运行
• 防火墙是否开放了3000端口
• 网络连接是否正常

8.2 认证失败

• 确认令牌是否正确
• 检查令牌是否已过期或被禁用
• 验证请求头中的Authorization格式是否正确

8.3 模型不可用

• 在管理界面确认对应渠道状态正常
• 检查渠道的额度是否充足
• 确认请求的模型名称与渠道配置一致

8.4 流式传输中断

• 检查网络稳定性
• 确认客户端正确处理流式响应
• 验证超时设置是否合理

9. 最佳实践建议

9.1 性能优化

• 使用连接池减少建立连接的开销
• 合理设置超时时间，避免长时间等待
• 启用流式传输提升用户体验

9.2 错误处理

try: response = client.chat.completions.create( model="gpt-3.5-turbo", messages=[{"role": "user", "content": "你好"}], temperature=0.7 ) except Exception as e: print(f"请求失败: {e}") # 这里可以添加重试逻辑

9.3 监控和日志

• 定期检查OneAPI管理界面的使用统计
• 设置报警通知，及时了解系统状态
• 记录重要操作的日志，便于排查问题

10. 总结

OneAPI 作为一个统一的AI模型网关，极大地简化了多模型接入的复杂性。通过本文介绍的三种接入方式，你可以快速开始使用：

1. Postman测试：适合快速验证和调试API调用
2. curl命令：方便在命令行环境中进行测试和集成
3. Python SDK：最适合实际项目开发，完全兼容OpenAI标准

无论你是个人开发者还是企业用户，OneAPI都能提供稳定、高效的模型接入服务。其丰富的功能如负载均衡、多机部署、精细权限控制等，让它成为构建AI应用的首选网关方案。

现在就开始使用OneAPI，享受"一次接入，多模型通用"的便捷体验吧！

获取更多AI镜像

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