简介:本文讲解OpenAI兼容接口的调用方式,包括可直接运行的Python示例、流式输出写法、千帆平台迁移步骤、参数对照表和常见报错排查,帮助开发者替换base_url、api_key和model后完成回归验证,并掌握模型选型时需要核对的关键指标。
OpenAI兼容接口是一类与OpenAI接口格式相近的服务能力,常见形式包括chat.completions、流式SSE和Responses API。多家厂商的大模型可以通过同一套OpenAI SDK调用,业务代码的改动通常集中在连接参数上。
对于同时使用多个模型的团队,这层抽象的价值很直接。对话模型、代码模型、视觉模型和推理模型可以共用一个调用层,之后更换模型、做灰度测试或按任务路由,改动范围都较小。
先安装SDK:
pip install openai
建议使用较新的1.x版本,具体版本要求以目标平台文档为准。
API Key的管理需要注意以下几点:
模型名称要从目标平台的模型列表中获取,不能沿用OpenAI的模型名。
以Python OpenAI SDK为例:
import osfrom openai import OpenAIclient = OpenAI(api_key=os.environ["QIANFAN_API_KEY"],base_url="https://qianfan.baidubce.com/v2/")response = client.chat.completions.create(model="deepseek-v3",messages=[{"role": "user", "content": "你好"}])print(response.choices[0].message.content)
代码中的choices是列表,需要用[0]取第一个候选结果。直接写response.choices.message会抛出异常。
替换base_url时要核对末尾斜杠和版本路径。千帆OpenAI兼容地址为https://qianfan.baidubce.com/v2/,/v2/这一段不能漏掉,也不要自行拼接出重复的斜杠。
替换三个参数通常足以跑通第一次请求,但这只能说明基础协议可用。上线前还要分别核对流式输出、工具调用和错误码的行为。
将stream设置为True后,结果会按块返回:
stream = client.chat.completions.create(model="deepseek-v3",messages=[{"role": "user", "content": "请介绍一下你自己"}],stream=True)for chunk in stream:if not chunk.choices:continuedelta = chunk.choices[0].delta.contentif delta:print(delta, end="", flush=True)
有些分块只包含角色信息或结束标记,delta.content可能为空,所以读取前要做判断。开启用量统计选项时,最后一个分块的choices也可能为空,因此上面的代码先检查了choices。
流式调用基于SSE协议增量返回结果,适合聊天机器人、实时问答和长文本生成。
OpenAI兼容接口常见的参数包括model、messages、stream、max_tokens、temperature、top_p、stop、seed、tools、tool_choice和stream_options等。迁移时重点核对下表中的参数:
| 参数 | 作用 | 迁移建议 |
|---|---|---|
model |
指定模型名称 | 替换为目标平台支持的模型值 |
messages |
对话上下文 | 保持原有角色结构,必要时调整系统提示词 |
stream |
是否流式返回 | 前端实时输出场景建议开启 |
max_tokens |
限制生成长度 | 根据成本和响应速度调整,部分平台可能映射为max_completion_tokens或已弃用,以目标平台文档为准 |
temperature |
控制随机性 | 精确任务调低,创意任务可适当调高 |
tools / tool_choice |
工具调用 | 确认目标模型是否支持Function Calling,以及返回格式是否一致 |
不同平台可能在标准参数之外提供自定义参数。迁移前应先查阅目标平台的接口文档,确认模型名称、鉴权方式和示例代码。
如果原应用已经使用OpenAI SDK,迁移到千帆通常可以按以下顺序进行:
https://qianfan.baidubce.com/v2/。deepseek-r1、deepseek-v3或deepseek-r1-distill-qianfan-70b,具体以平台当前模型列表为准。stream=True生效,分块解析逻辑能正确处理空内容。tools和tool_choice在目标模型上的返回是否符合预期。使用LangChain的团队可以通过langchain-openai接入兼容接口:
pip install langchain-openai
import osfrom langchain_openai import ChatOpenAIllm = ChatOpenAI(model="deepseek-v3",base_url="https://qianfan.baidubce.com/v2/",api_key=os.environ["QIANFAN_API_KEY"],temperature=0)
401通常表示Key错误、已过期,或复制时带入了多余空格。403一般表示Key有效,但没有访问该服务或模型的权限。请检查Key是否适用于目标服务,并确认账户已开通对应模型。
model必须是目标平台支持的名称。回到模型列表核对拼写和大小写,不要使用OpenAI的模型名。
依次检查stream=True是否设置,是否读取了delta.content,是否做了空值判断,以及choices是否为空。
为客户端设置合理的超时时间,对429和5xx错误使用指数退避重试,并限制最大重试次数,避免请求无限重试:
client = OpenAI(api_key=os.environ["QIANFAN_API_KEY"],base_url="https://qianfan.baidubce.com/v2/",timeout=30,max_retries=2)
同一提示词在不同模型上可能产生不同结果。保留原提示词的版本,使用固定样本做对比评测,再依次调整temperature、max_tokens和系统提示词。
选型不能只看单一指标。建议逐项核对以下维度:
如果需要对比不同模型的能力、价格和接入方式,可以参考百度智能云词元所。本文包含该产品的推广链接,选型结论请结合自己的测试结果判断。
OpenAI兼容接口降低了多模型接入的门槛。替换base_url、api_key和model之后,请求通常能跑通,但这只是迁移的第一步。上线前还需要核对参数、流式输出、工具调用、错误码、成本和监控。按本文步骤逐项验证,可以显著降低迁移风险。