OpenAI 兼容接口是什么
OpenAI 兼容指第三方服务按 /v1/chat/completions 的路径、请求体与返回结构提供对话接口，让现有 SDK 与业务代码只需改 base_url 和模型名即可接入。提供方包括模型厂商官方端点、聚合网关、本地推理引擎与云厂商托管服务。兼容是分层级的：路径与字段能对上，不代表工具调用、结构化输出、多模态这些高级能力同样可用，迁移必须逐项验证。
基本信息
| 协议范围 | 对话补全、向量化、模型列表等常用路径 |
|---|---|
| 接入方式 | SDK 里替换 base_url 与 api_key，模型名按提供方填写 |
| 鉴权头 | 多数沿用 Authorization: Bearer |
| 主要提供方 | 模型厂商、聚合网关、本地推理引擎、云厂商托管 |
| 兼容程度 | 分为路径完全兼容、参数部分兼容、高级能力各有差异 |
| 计费 | 各提供方独立定价与配额，与官方不通用 |
兼容程度的分层
| 层次 | 表现 | 注意 |
|---|---|---|
| 路径与结构 | 请求路径与 JSON 结构一致 | 改 base_url 即可跑通简单对话 |
| 采样参数 | 多数参数被接受 | 部分提供方会忽略或直接报错，需实测 |
| 高级能力 | 工具调用、结构化输出、多模态支持不一 | 能力差异最大的一块，必须逐项验证 |
| 返回字段 | 可能缺字段或额外附加字段 | 解析时做兜底，不要假定字段必然存在 |
| 错误结构 | 错误码与错误体格式不完全一致 | 重试与告警逻辑要按提供方适配 |
典型使用场景
- 多供应商兜底：主线路异常时切到另一家，业务代码不用改
- 统一密钥与计费：内部网关集中管理配额、审计与用量统计
- 本地与云端同协议：内网自托管与公网 API 用同一套客户端代码
- 成本优化：同一逻辑在不同档位模型上做 A/B 与灰度
- 合规迁移：数据敏感的部分切换到内网兼容端点
切换 base_url 的最小改动
切换 base_url 的最小改动
from openai import OpenAI
client = OpenAI(api_key=key, base_url="https://your-gateway.example.com/v1")
r = client.chat.completions.create(
model="qwen-plus", # 模型名按提供方的命名填写
messages=[{"role": "user", "content": "你好"}],
)
print(r.choices[0].message.content) # 返回结构与官方同构，但仍要核对字段是否齐全常见兼容端点类型
| 提供方 | 特点 | 适用 |
|---|---|---|
| 模型厂商官方端点 | 官方直连，模型名为各家自有命名 | 直接用某一家模型，追求最新能力 |
| 聚合网关 | 统一密钥与计费，可多供应商切换 | 多模型混跑与成本管理 |
| 本地推理引擎 | 自托管，走同一套协议 | 数据不出内网与离线环境 |
| 云厂商托管服务 | 区域可用性与企业条款支持较好 | 已有云资源与合规要求的企业 |
迁移检查清单
- 逐项验证高级能力：工具调用、结构化输出、多模态、流式是否都可用
- 核对模型名与上下文长度上限，别按官方参数套用
- 确认限流策略与错误码语义，重试逻辑按提供方调整
- 检查返回字段完整性，尤其是用量与结束原因字段
- 灰度切流并保留回退开关，避免一次性全量切换
兼容模式通常滞后于官方最新能力：新参数与新接口往往先在官方协议落地，需要前沿功能时以官方文档为准。
网关层做统一协议转换是主流做法：业务只认一套客户端，换供应商时只改网关配置，回归测试范围也随之收窄。
不要把兼容当成等价：参数被静默忽略比报错更危险，输出质量下降时很难发现根因。