deepseek api接入流程

第一次接 DeepSeek 接口，卡点通常不在代码本身：Base URL 填哪个、Key 放哪、curl 通了但 SDK 报错、流式接一半断掉。这篇按接入顺序走一遍，从申请密钥到本地跑通再到接进项目，给出每一步该确认什么、出问题先查哪。适合已有基本 HTTP 调用经验、想一次接稳的开发者。

第一次接 DeepSeek 接口，卡点往往不在代码本身。Base URL 该填哪个、Key 放哪、curl 调通了但换成 SDK 就报错、流式输出接一半断掉——这些问题几乎每个人都遇到过一次。这篇按真实的接入顺序走一遍：从申请密钥、定协议，到本地最小请求跑通，再到接进项目、设置超时重试、控并发、加日志，最后给出上线前的验收清单。

适用范围先讲清楚：如果你已经有基本的 HTTP 调用经验，能看懂请求体和返回结构，这篇对你是够用的。如果你连鉴权头怎么写、状态码怎么区分都还没有概念，建议先补一遍 HTTP 基础再回来，否则下面的排查顺序对不上号。若你的项目对延迟极其敏感、或者有强合规要求，部分做法要按自己的实际情况调整，不用照搬。

第一步：拿 Key、定协议、确认调用形态

很多人一上来就打开编辑器，其实这一步没定清楚，后面全要返工。申请入口优先走官方开放平台；如果因为网络或支付条件选择走中转站，先到 /sites 看目录，再到 /tools/verify 实测可用性，别只看宣传页上的说法。中转站的实际表现会变，用之前测一次比看介绍靠谱。

开 Key 的时候就要顺手定两件事：走原生协议还是 OpenAI 兼容协议，以及你要调用的是对话补全还是嵌入模型。这两点决定后面 Base URL 怎么拼、请求体长什么样。定好之后别中途换，换了就要重测一遍。Key 只进环境变量或密钥管理系统，不要进代码仓库、不要进前端。前端直连的安全边界，站内关于 CORS 与 Key 暴露的说明里有更细的讲法。

第二步：先用最小请求打通，再上框架

不要一上来就装 SDK、写封装。先用 curl 或一个最简脚本发一条非流式请求，只带必需字段，看看返回结构里拿到的是真正的内容还是错误对象。这一步通过，说明 Key、地址、鉴权头都是对的，后面出问题就能缩小范围。

• 返回体对不上，先查三样：Base URL 是不是少写或多写了路径段、协议类型是不是选反、鉴权头名字对不对；逐一核对比盲改代码快。
• curl 通了再引入 SDK 或框架；如果这时报错，就用裸请求复现一次，能立刻区分是网络/密钥问题还是封装层问题。
• 测速和延迟基线到 /tools/speed-test 量一次，后面判断「快慢」才有参照，不靠感觉。
• 把请求成功时的原始返回存一份，作为后面接入的对照样本。

curl <BASE_URL>/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{"model":"<MODEL_ID>","messages":[{"role":"user","content":"ping"}],"stream":false}'

第三步：超时、流式与重试的工程设置

最小请求能跑通，不代表接进项目就没问题。这一步是把工程参数定下来。超时至少分三档设：连接超时、首字超时、整体超时。首字超时一定要单独给，别用整体超时兜底，流式场景下这两种超时是两回事，混在一起很难定位到底卡在哪一段。

如果要接流式输出，得处理分片粘包、心跳和中断重连。接了流式就别再沿用一次性读取的逻辑，两者对数据的处理方式完全不同。重试只对幂等或可安全重放的请求开，并且必须带指数退避与次数上限，否则偶发的失败会被重试放大成限流。

把这些参数写进一份配置文件而不是散在各处，换环境时只改一处，出事时也只查一处。

第四步：并发、限流与降级的实际做法

并发这块最常见的错误是「有多少任务就发多少请求」。正确做法是按账号额度给一个排队机制，让请求在队列里等，而不是一次性全部打出去。触发限流之后，处理顺序很重要：先降并发，再退避，最后才考虑换模型或换源。这个顺序反了，本来是可恢复的限流问题会被你搞成不可恢复的。

1. 压测前先定并发上限不要用实际业务请求去试探上限，先按额度估一个保守值，再小幅往上加。
2. 限流响应的识别在日志里把限流类的状态码单独标出来，方便统计频率和触发时段。
3. 降级路径要预留主模型超时或不可用时切到备选，切换动作记进日志，否则事后说不清哪次请求走了哪条路。
4. 批量任务分批跑一批跑完再发下一批，比一次性打满更容易稳定跑完，出错也更好定位。

降级不是「切了就行」，要保证切过去之后返回结构还是你的代码能处理的。这需要提前对两边的返回做一次对齐测试，别等线上真出事才试。

第五步：日志、验收与接入完成的标准

日志这一列最容易省，也最不该省。每次请求至少记：时间、模型标识、耗时、状态码、token 用量、是否走了降级。缺任何一列，复盘的时候就会缺一块。特别注意「是否走了降级」这一列，很多问题到最后就是因为它没记，导致无法还原现场。

接入完成的判断标准不是「跑通一次」，而是三件事：连续多次调用的成功率、限流情况下的表现、出错时返回的报错是否可读。跑通一次只能说明路径是通的，说明不了稳定性。上线前建议做一次模拟：断网、超时、用错误 Key、让返回为空，逐个看你的代码是报错退出还是静默失败。静默失败是最需要注意的一种。

最后提醒一句：价格与额度这类会变的信息，别写死在你的文档或代码注释里。要确认当时的数字，到 /official-api/providers/deepseek 和 /price-watch 去看，那里是持续跟踪的。写死的数字过一阵就不准了，还会误导后面接手的人。