deepseek openai 兼容接口怎么接

很多人拿到 DeepSeek 的 Key，第一反应是把官方 SDK 里那行 base_url 和模型名换掉就跑，结果要么报 404，要么返回内容对不上。问题通常不在 DeepSeek 本身，而在兼容层的写法细节：路径拼错、模型名对不上、参数被静默忽略。这篇按「先跑通一次最小调用，再逐项加固」的顺序走一遍，给出可复制的检查清单和排错顺序。

拿到 DeepSeek 的 Key 之后，大多数人的第一反应是把官方 SDK 里那行 base_url 和模型名换掉，然后直接跑。结果要么 404，要么返回内容跟预期对不上，要么请求发出去了但字段像是被吞了。问题基本不在 DeepSeek 这一侧，而在兼容层的写法细节：路径拼错、模型名对不上、参数被静默忽略这三类最常见。

这篇按「先跑通一次最小调用，再逐项加固」的顺序走一遍。先别急着改项目代码，先确认单次请求能通；通了之后再回头把 base url、模型名、参数、超时这几项逐个钉死。下面给的是可复制的检查清单和排错顺序，照着走能省掉大部分瞎试的时间。顺便说一句，如果你选的是中转站而不是官方直连，接入前的可信度判断是另一套逻辑，那部分去 /sites 看检测项的说明更合适。

先把「兼容」这两个字落到具体范围

「OpenAI 兼容」不是一个精确的技术标准，它只是说：请求路径的形状、鉴权头的格式、消息体的字段结构，这几层跟 OpenAI 的约定对齐。对齐的通常只有这几层，再往上就不一定了。所以判断自己的项目能不能直接切过来，关键不是「它说兼容」，而是「我的代码实际用了哪些字段」。

一个实用的自查动作：把项目里所有发请求的地方翻一遍，看有没有只属于某个厂商的专属字段。如果全是 messages、model、stream 这几个通用项，切换成本就很低；如果里面塞了自定义的顶层参数，那就要逐个确认对方认不认。

• 打开你封装请求的那个函数或类，把传进去的所有字段列出来
• 逐个对照目标平台的接口文档，标出「有文档说明」和「没提」的两类
• 没提的那几个字段，要么删掉，要么准备好对方静默忽略（不报错但不生效）
• 如果项目里有多处硬编码，统一收敛到一个配置文件，后面改起来只动一个地方

别一上来改项目，先跑通一次最小调用

改项目之前先发一条最简单的请求，目的只有一个：确认链路是通的。用 curl 或者十几行的脚本都行，只发一条纯文本，不要带流式、不要带工具、不要带任何自定义参数。看三件事：HTTP 状态码是不是成功，返回结构里有没有完整的 choices 和使用量字段，正文内容是不是非空。

curl -sS -X POST "$BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"model":"你的模型标识","messages":[{"role":"user","content":"说一句话"}]}' \
  -o resp.json -w "%{http_code}\n"

注意上面这个命令里 BASE_URL 到底要不要带 /chat/completions 后缀，取决于你用的是什么：curl 这种裸 HTTP 调用需要你写全路径，而多数官方 SDK 会自己补后缀。这个「谁负责补后缀」的问题下一节专门讲。这里的关键是：把 base url、鉴权头、模型名当成三个独立变量，一次只改一个，别同时改两处再去找原因。

1. 固定一个变量先用你确定正确的那一组（比如官方直连的地址和模型名）发通一次，把请求和响应原样存下来
2. 换 base url只换地址不换别的，重发一次。如果失败，问题在这一层，跟参数无关
3. 换模型名地址确认没问题后再换模型名，同样只改这一处
4. 存基线这次成功的原始响应存成文件，后面所有「跟以前不一样」的判断都拿它对比

base url 与路径拼接：最容易翻车的一步

兼容层最常见的 404 不是地址写错，而是路径被拼了两遍。SDK 的 base_url 参数通常指的是「根地址」，SDK 自己会在后面补上版本段和资源路径；如果你在 base_url 里就把整条接口路径写全了，最后拼出来就是重复的一长串，服务端当然找不到。

末尾带不带斜杠、带不带版本段，这两件事没有统一规矩，必须以目标平台给的示例为准。改完之后必须重新发一次探活请求，因为配置文件的改动不一定被进程重新读取，尤其在你用了环境变量或者本地代理的情况下。

• 先确认你用的是裸 HTTP 调用还是 SDK：前者自己写全路径，后者只管根地址
• 去目标平台的文档页找一个完整的请求示例，对照它确认路径形状
• 改完地址后检查环境变量，确认没有另一个变量把配置覆盖回去了
• 本地如果挂了代理，先临时绕过它直连一次，排除代理改写了 URL

模型名和参数：写对了才轮得到调优

模型名写错通常不会是含糊的报错，而是明确提示模型不存在。所以第一件事不是调参，是确认模型标识。这个标识会随平台更新而变化，别抄别人的配置也别凭记忆写，去当前平台的模型列表页面核对。各家的可用模型和价格是动态的，具体数字到 /price-watch 看当时的记录。

模型名确认之后再看参数。温度、最大输出长度这类采样参数的取值范围和默认值各家不同，把 A 家的经验值直接搬到 B 家，轻则效果不对，重则直接报参数越界。更隐蔽的是那些「不报错但也不生效」的参数——请求发成功了，返回也正常，但那个参数根本没被读取。

模型标识

决定调用哪个模型，写错会明确报错，改之前先去平台模型页核对

采样参数

取值范围各家不同，切换后建议从默认值重新调起，不要照搬旧配置

流式开关

会改变响应结构，切换时客户端解析逻辑必须同步改

最大输出长度

影响计费和截断行为，设置前先确认目标平台的上限

什么情况下这一节不适用？如果你的项目只用固定的模型、固定的参数、不做任何调优，那这部分确认一次就够了，不需要反复折腾。但只要你打算做 A/B 对比或者动态切换模型，参数对齐就得当成常规工作来做。

连通性验证：三个动作确认真的通了

「发出去有返回」不等于「接对了」。下面三个动作能帮你把「碰巧通了」和「真的通了」区分开。这三个动作做完，你手上应该有三份记录，后面出问题直接对比。

1. 发一次非流式短请求看返回结构里有没有完整的使用量字段。缺字段说明你用的可能是被裁剪过的兼容层，后面做计费统计会踩坑
2. 发一次流式请求确认分片能不能正常收完，最后一个分片有没有正常的结束标记。中间断了和正常结束是两种不同的故障
3. 故意制造两类错误用一个错误的 Key 发一次，再用一个不存在的模型名发一次，把两次的报错信息记下来。目的是确认你能区分「鉴权失败」和「模型不存在」——这两类问题处理方向完全不同

顺手把延迟也量一下，分成首字时间和整段耗时两项记。这个数字不用追求绝对值好看，它的价值在于当参照——等你后面发现「今天怎么变慢了」，有历史数据才能判断是整体波动还是你改坏了什么。想跟别的接入方式横向比，可以到 /tools/speed-test 看当时的测速数据。

报错了按这个顺序查，别乱试

排错最大的浪费是「同时怀疑三件事」。下面这个顺序的核心思路是先分类再定位：先看状态码属于哪一类，不同类别的处理方向根本不一样；类别定了再看请求体；请求体没问题最后才查链路。

一个高频的坑是类型不符：该是数组的字段写成了字符串，该是数字的写成了带引号的字符串。这类错误在有些兼容层上不报错，只是那个字段被忽略掉，表现成「参数调了没用」。所以查请求体的时候，逐字段对类型，别只看字段名。

• 第一步永远看状态码，不要先去看代码逻辑
• 参数类错误改完立刻重发，不要攒着几处一起改
• 限流类错误要确认退避策略真的在起作用，而不是无脑重试
• 链路类错误先直连排除本地代理，再回头看配置
• 每次排查记录一条：改了什么、结果怎么变了

跑通之后，上生产前还要补几件事

单次调用跑通跟能上生产是两码事。下面这几项不补，上线之后大概率会在某个不巧的时间点集中爆发：长文本请求卡死、失败重试把配额打满、出事之后翻日志发现什么都没记。

超时要分档设置。连接超时和读取超时不是一回事：前者是握手阶段，后者是等模型出结果。长文本请求的读取耗时可能远超你的预期，如果两个超时都用一个值，要么短请求被拖慢，要么长请求被误杀。重试也一样，不是所有错误都值得重试——参数类错误重试多少次结果都一样，只有限流类和部分网关类错误才适合退避重试。

还有一件事：如果你走的是中转站，接入方式和可用模型会随服务方调整，所以生产配置里的地址和模型名建议做成可配置项，别硬编码。至于怎么判断一个中转站值不值得长期用，站内另有一套检测和追踪的内容，到 /sites 看那份说明比在这里展开更合适。