---
title: "OpenAI 兼容接口是什么意思"
description: "很多中转与国内厂商提供与 OpenAI 相同形状的接口：换掉 base_url 就能复用现有 SDK。这页讲清兼容的边界、常见缺失字段，以及怎么用最小请求验证。"
updated: 2026-11-13
canonical: https://docai.cc/concepts/openai-compatible/
markdown_mirror: https://docai.cc/concepts/openai-compatible.md
---
## 它是什么

OpenAI 兼容指的是：一个服务的 HTTP 接口照着 OpenAI 的形状实现。请求体用 `messages` 数组、`model`、`temperature` 这些字段，结果放在 `choices` 里，报错也尽量模仿同样的结构。

对调用方来说，好处是换掉 base_url 和 [API key](/concepts/api-key/)，现有的 OpenAI SDK 代码就能直接跑，不用重写请求封装。

但要分清：兼容的是**协议形状**，不是模型能力。同一个路径背后可以是另一家厂商的模型，输出质量、上下文长度、工具调用行为都各算各的。

## 怎么工作

调用链大致是这样：

```text
你的代码 → OpenAI SDK → base_url（兼容层）→ 厂商后端
```

SDK 按 OpenAI 的规则拼路径，通常是 `/chat/completions`；兼容层收到后翻译成自家请求，再把结果包装回 OpenAI 形状的 JSON。调用方看到的字段名不变，变的是字段背后的实现。

所以兼容层至少要处理三件事：路径映射、鉴权转换、响应包装。覆盖多少字段，决定了它是「能演示」还是「能上生产」。

## 常见缺失字段

「能跑通 hello world」和「生产可用」是两回事。下面这些字段经常只实现一部分：

- **工具调用**：`tools`、`tool_choice` 可能不支持，或者只支持单轮；流式返回里的 `tool_calls` 增量格式也可能对不上。机制见[工具调用](/concepts/tool-use/)。
- **流式 usage**：有的服务只在最后一个 chunk 给 `usage`，有的一直不给；`stream_options` 里的统计开关可能被直接忽略。
- **结构化输出**：`response_format` 只认 `json_object`，不认 `json_schema`；所谓 JSON 模式靠提示词约束，不保证合法。详见[结构化输出](/concepts/structured-output/)。
- **采样参数**：`seed`、`logprobs`、`n` 大于一这类参数可能被静默忽略。不报错，不代表生效。

静默忽略比报错更麻烦：代码没崩，行为已经变了。

## 怎么验证兼容度

先用 curl 打最小请求，再换 SDK：

1. `GET /v1/models` 确认地址和 key 能通。有的厂商不实现这个端点，官方未说明时以实际返回为准。
2. `POST /v1/chat/completions`，只放一条 `user` 消息，不开流式，检查 `choices[0].message.content` 和 `usage` 是否存在。
3. 打开 `stream: true`，确认每个 `data:` 行都能解析成 JSON，最后有结束标记。
4. 加一个最简单的工具定义，确认真能返回 `tool_calls`，而不只是接受参数。
5. 故意传一个未知参数，看它是报错还是忽略。忽略的记进兼容性清单。

把这几步写成脚本，换厂商时重跑一遍，比读宣传页可靠。这里只验证形状，不验证质量；质量要单独做评测。

## 常见误解

- **「兼容 OpenAI 就等于能力一样」**：协议一样，模型是另一套。评测、上下文、限流都要按这家厂商重新看。
- **「换 base_url 就行」**：模型名、路径前缀、鉴权头都可能不同，SDK 版本也会影响请求形状。
- **「报错格式也一样」**：不少兼容层只保证成功响应，错误体是自家格式，按 OpenAI 错误码写的分支会失效。

## 什么时候用

已有 OpenAI SDK 代码、想低成本接第二家供应商；或者自建服务，想让现成客户端直接连进来。两种情况都建议先做上面的最小验证。第一次调用的完整步骤见[发出第一个 API 请求](/learn/first-api-call/)。