豆包 api openai 兼容怎么接

很多人的代码是先照着 OpenAI 那套写的，现在想换成豆包，又不想重写一遍 SDK 和调用逻辑。麻烦通常出在三个地方：Base URL 拼错、鉴权头没换、返回结构里少数几个字段对不上。这篇按「先改配置、再跑最小请求、最后排错」的顺序走一遍，给你能直接照着做的步骤和排查顺序。

很多人的代码是先照着 OpenAI 那套写的，现在想换成豆包，又不想重写一遍 SDK 和调用逻辑。麻烦通常出在三个地方：Base URL 拼错、鉴权头没换、返回结构里少数几个字段对不上。这篇按「先改配置、再跑最小请求、最后排错」的顺序走一遍，给你能直接照着做的步骤和排查顺序。

下面所有步骤都假设一件事：你手里已经有一个能跑通原通道的最小 demo，哪怕只有十几行。没有这个基线，后面出问题你分不清是兼容层的问题还是自己业务代码的问题。先保证旧通道能跑，再动手改配置，这是省时间的关键。

先搞清楚「兼容」到底兼容到哪一层

所谓 OpenAI 兼容，通常指请求路径、鉴权头、请求体字段、响应体结构这几层能对上，不等于所有参数和返回字段都一模一样。有些兼容层只保证基础对话能用，像函数调用、结构化输出、多模态这类能力，支持程度各家不一样。动手前先去站内 /openai-compatible-api-shape 看请求响应长什么样，再去 /openai-api-compat-fields 确认哪些字段保留、哪些缺失。

• 路径层：确认是复用 /v1/chat/completions 这类标准路径，还是兼容层自己加了前缀
• 鉴权层：确认 Auth 头是不是 Bearer，有没有额外的签名或项目标识要求
• 请求体层：确认你常用的字段（如 temperature、max_tokens、tools）在不在支持范围内
• 响应体层：确认 choices、finish_reason、usage 这些结构是否完整，少字段最容易在业务侧炸
• 能力层：函数调用、流式、多模态是否等价，这块差异最大，别默认全兼容

拿不准具体口径时，到 /official-api/providers 翻对应厂商页面的接入说明，别照抄别人的博客。厂商文档更新频率高于大部分教程，博客里的字段名可能是旧版本的，抄下来只会多绕一圈。

改造清单：只动这几处，别大改代码

兼容接入的核心思路是「把变化收敛到配置层」。凡是硬编码在业务逻辑里的域名、密钥、模型名，都值得提出来变成配置项。这样换供应商只是改一个配置文件，而不是翻遍整个仓库。

1. 换 Base URL多数兼容层是在标准路径后面换域名或加前缀。先把完整的请求 URL 打印出来，跟文档里的示例逐段比，写错了直接 404，纠正写法对照 /openai-compatible-base-url-fix
2. 换 Key 与鉴权头确认是 Bearer 还是别的形式，环境变量名保持独立，比如 DOUBAO_API_KEY 和原来的 OPENAI_API_KEY 分开存，别混用；切换时只改读取哪个变量
3. 挑模型名先去 /models 查当前可用标识，不要在代码里写死某个版本字符串；模型标识变更时只会改配置，不用重新发版
4. 保留一个开关用配置项切换供应商，出问题能一键切回原通道，别把原代码删干净；这一步几乎不花成本，但排障时能救命

改完之后不要急着跑全量业务，先用一条最简单的请求验证。配置层改动最容易犯的错是「以为改对了」，实际拼出来的 URL 多一个斜杠或者少一段前缀。

最小可跑通验证：先非流式，再流式

验证顺序很重要：先用非流式发一条最短请求，把返回的原始 JSON 打印出来，别急着解析成业务对象。原始 JSON 能让你一眼看到字段名和类型，很多「解析报错」其实是字段名对不上，不是接口没通。

curl -sS -X POST "$BASE_URL/chat/completions" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"你的模型标识","messages":[{"role":"user","content":"hi"}]}'

这条命令跑通代表三层都没问题：网络可达、鉴权通过、请求体结构被接受。跑通后再开流式，注意兼容层在分块边界和结束标记上的差异，参考站内 /streaming-vs-nonstreaming-api。流式最常见的坑是把分块当成完整 JSON 解析，以及结束标记判断写错导致连接不关。

接口本身慢不慢、稳不稳，可以到 /tools/speed-test 量一条延迟基线，作为后面判断「变慢了」的参照。基线要在网络状况稳定的时候量，否则后面所有对比都没意义。

报错排查顺序：从最外层往里查

报错别看到一条改一条，按从外到内的顺序查：先确认请求发出去了没有，再看鉴权，再看路径，最后才看返回体字段。这个顺序能避免你在业务代码里改半天，结果是 URL 拼错。

• 先看 HTTP 状态码，它决定往哪一层查，不要跳过
• 再看响应体里的错误消息，很多兼容层会直接告诉你缺哪个字段
• 再核对请求体，把你实际发出去的 JSON 和文档示例并排看
• 最后才是业务解析逻辑，前面三层都确认过了再动这里

如果同一段代码在原通道正常、切到兼容层就报错，基本可以锁定在配置或字段差异上，而不是你的业务逻辑。反过来，如果两边都报错，先修业务代码，别把两个问题混在一起查，那样只会越查越乱。