用 OpenAI SDK 接第三方兼容接口

第一步：换掉 base_url

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

两个细节先确认：

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

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

第二步：先用 curl 验证

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

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：

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)

不要把对话、工具、流式一起加进来。一次只加一个变量，出错时才分得清是哪一层的问题。第一次调用报错怎么读，见读懂一次报错；完整的首次调用流程见第一次 API 调用。

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

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

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

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

工具调用要对齐的部分见工具调用，结构化输出可参考强制 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 这类请求本身的问题重试没有意义。