---
title: "用 OpenAI SDK 接第三方兼容接口"
description: "第三方兼容接口大多能直接复用 OpenAI SDK，但换地址只是第一步。本课用一次 curl 验证、一次最小请求和一层重试，把兼容层的坑逐个排掉。"
updated: 2026-11-13
canonical: https://docai.cc/learn/connect-openai-compatible/
markdown_mirror: https://docai.cc/learn/connect-openai-compatible.md
---
## 第一步：换掉 base_url

兼容接口复用的是 OpenAI 的协议形状，所以代码不用重写，改的是根地址。把 SDK 的 base_url 指向对方给的地址，再把 API key 换成对方签发的 key。

两个细节先确认：

- 地址末尾是否要带版本段。有的服务要求以 `/v1` 结尾，有的直接把版本写进域名。
- 不要把完整接口地址填进去。SDK 会在根地址后自己拼 `/chat/completions`，填多了会拼出重复路径。

建议把地址和 key 都走环境变量，不要写进仓库。key 的通用做法见 [API key 是什么](/concepts/api-key/)，地址与端点的区别见[端点](/concepts/endpoint/)。

## 第二步：先用 curl 验证

在改代码之前，先用一条 curl 确认「地址、key、模型名」这三件事同时成立：

```bash
curl -sS -X POST "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"'"$MODEL"'","messages":[{"role":"user","content":"ping"}]}'
```

看两样东西：HTTP 状态码和返回体的形状。状态码区分问题归属：404 多半是路径拼错，401 或 403 是 key 不对，400 是请求体字段不被接受。返回体则要确认 `choices` 里确实有内容。

curl 能通而 SDK 不通，问题就在 SDK 的拼接或环境变量上，不在服务端。这条分界线能省很多时间。

## 第三步：跑最小 SDK 请求

验证通过后，把同一组参数交给 SDK：

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["BASE_URL"],
    api_key=os.environ["API_KEY"],
)
resp = client.chat.completions.create(
    model=os.environ["MODEL"],
    messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)
```

不要把对话、工具、流式一起加进来。一次只加一个变量，出错时才分得清是哪一层的问题。第一次调用报错怎么读，见[读懂一次报错](/learn/read-an-error/)；完整的首次调用流程见[第一次 API 调用](/learn/first-api-call/)。

## 第四步：处理兼容层缺字段

能返回一句话，不代表上生产可用。兼容层常见只实现了一部分字段：

- 工具调用：`tools` 与 `tool_choice` 可能不支持，或者只支持单轮。
- 结构化输出：`response_format` 可能被忽略，模型照样输出自然语言。
- 用量统计：流式里可能不返回用量，或者字段名与官方叫法不同。
- 参数别名：同一个含义，有的服务只认其中一个名字。

处理办法不是猜，而是写探测：对每个要用到的字段发一次最小请求，记录支持、报错、静默忽略三种结果。静默忽略最危险——请求成功，行为却和预期不同。具体行为各家不一致，官方未说明的部分以实测记录为准。

工具调用要对齐的部分见[工具调用](/concepts/tool-use/)，结构化输出可参考[强制 JSON](/learn/force-json/)。

## 第五步：加重试

兼容层的失败模式比官方接口更杂。加一层有限重试，但要按错误分类：

- 429 与 5xx：等待后重试，间隔逐次拉长并加随机抖动。
- 连接超时、网络重置：确认请求可重复执行后再重试。
- 400、401、403、404：不重试，先修参数、凭证或地址。
- 长耗时请求：先设总超时，再决定重试次数，避免一个请求永远挂着。

多数 SDK 自带重试开关，默认次数和退避规则各不相同，官方未说明时以该 SDK 文档为准。重试次数要有上限，日志里记下每次尝试的状态码，否则你只会看到「偶发失败」这四个字。

## 自测

1. 问：SDK 报 404，先查地址还是先查 key？
   答：先查地址。404 通常说明路径拼错，或者 base_url 多了、少了一段；鉴权问题一般返回 401 或 403。

2. 问：兼容接口能跑通对话，为什么工具调用还会失败？
   答：兼容的是请求与响应的形状，不是全部字段。工具调用、结构化输出常只实现一部分，要以实际响应为准。

3. 问：哪些错误值得重试？
   答：429、5xx、连接超时和网络重置可以有限次重试；400、401、403、404 这类请求本身的问题重试没有意义。