你大概率已经在终端里用 curl 把 DeepSeek 跑通了，但一挪进 C++ 工程就卡住：HTTP 客户端选哪个、JSON 怎么拼、链接报错一堆、流式输出切成一块块怎么接。这篇不重新讲协议兼容和客户端配置，只按工程落地的顺序，把可编译示例该包含的模块、参数该定在哪、出错先查哪一步讲清楚，让你能在自己项目里照着搭一个能跑、能观测、能降级的调用层。
你大概率已经在终端里用 curl 把 DeepSeek 跑通了，但一挪进 C++ 工程就卡住：HTTP 客户端选哪个、JSON 怎么拼、链接报错一堆、流式输出切成一块块怎么接。这篇不重新讲协议兼容和客户端配置，只按工程落地的顺序，把可编译示例该包含的模块、参数该定在哪、出错先查哪一步讲清楚。
目标很明确：让你能在自己项目里照着搭一个能跑、能观测、能降级的调用层。下面按依赖选择、请求构造、超时并发、日志降级四块走，每块都给判断标准和动手顺序，不给你抄了就跑的假代码。
HTTP 客户端与依赖怎么选，别一上来就纠结
常见三条路线：libcurl 生态最广、示例最多、跨平台；WinHTTP 这类系统库省依赖但绑平台；如果你已经有带 HTTP 的异步框架，顺手用就行。判断标准很简单——先看团队现有构建里已经带着谁，能省一个依赖就省一个，别为了「技术先进」多引一套。
- 能不能发 HTTPS：这是硬门槛，证书校验失败后面全是白搭
- 能不能单独设连接超时和读取超时：两者混在一起，长回答会被误杀
- 能不能拿到原始响应头：查状态码、看限流头、排错都靠它
- 链接期是否干净：静态库顺序、Windows 上的 SSL 证书路径，都是常见翻车点
构建这一关最容易出问题。CMake 里 find_package 找不到、静态库链接顺序错，先别怀疑代码，按「第三方类找不到」的思路定位：是头文件路径没进 include，还是链接阶段没连上。区分办法是看报错发生在预处理、编译还是链接阶段，一步一步往回缩。
一次请求该由哪几个部分组成
把一次调用拆成四块来写：配置、请求体构造、HTTP 发送、响应解析。配置里 base url、key、模型名从环境变量或配置文件读，别硬编码进源码；请求体构造单独一个函数，方便替换和单测；发送和解析各占一块。这样出问题时能单独替换某一块，而不用通读整段。
- 配置层从环境变量或配置文件读 key、base url、模型名；校验非空，缺失时给出明确报错而不是带着空 key 发出去。
- 请求体构造用 JSON 库构造，别手拼字符串。模型名、消息内容里带引号或换行时，手拼必然转义出错；采样参数集中在一个结构体里，方便按环境切换。
- 发送与解析非流式一次读完整响应体再解析；解析时按字段存在性判断，别直接下标取值，缺字段时返回错误而不是崩溃。
流式和非流式在 C++ 里差别很大。非流式简单，先跑通它；流式要在回调里按行切分增量，缓冲区必须留着处理被切断的半行，否则你会看到输出缺字或乱码。不确定就先别上流式。
| 模块 | 放什么 | 出问题先查哪 |
|---|---|---|
| 配置 | key、base url、模型名 | 环境变量是否读到、是否为空 |
| 请求体 | 消息数组、采样参数 | JSON 是否合法、字段名是否正确 |
| 发送 | HTTP 客户端、超时 | 连接是否成功、状态码是多少 |
| 解析 | 字段取值、错误分支 | 字段是否存在、编码是否对 |
接口地址、可用模型、当前计费口径到 /official-api/providers/deepseek 核对，别把示例里写死的东西当成长期事实——这些是会变的。
超时、重试、并发：参数定在哪一档
超时拆成两个：连接超时短一点，读取超时按你最长一次生成的预期给够。两者混成一个值，长回答会被误杀，短回答又等太久。这是最常被忽略但最容易踩的一档。
| 场景 | 连接超时 | 读取超时 |
|---|---|---|
| 交互式短问答 | 短 | 按最长回答给 |
| 批量后台任务 | 短 | 给足，允许排队 |
| 流式输出 | 短 | 按空闲间隔判断，而非总时长 |
- 重试只对可恢复情况做：连接失败、限流、网关类错误可以退避重试
- 参数错误、鉴权失败重试多少次都没用，直接报错给人看
- 重试要带抖动，否则多线程同一时刻一起打过去，等于自己给自己制造尖峰
- 并发放进 C++ 要点：线程池别开满，先用信号量或令牌桶把在途请求数卡住
跑批任务按批次发、批次之间留间隔，比一次性全发出去更容易稳定。并发上限、限流后的恢复节奏，按你自己的账号档位在控制台和 /sites 里对一遍再定，不要照抄别人的数字，那是别人的账号条件。
日志、降级与回归：让出问题时有据可查
日志最少记这几项：请求时间、模型名、是否流式、耗时、HTTP 状态码、错误体原文片段、重试次数。不要打印完整 key 和完整用户输入，安全和合规都不允许。没有这些字段，线上出问题你只能靠猜。
- 排错顺序先看有没有发出去（连接层），再看状态码（HTTP 层），再看响应体字段（业务层），最后看你的解析代码；顺序反了会浪费大量时间。
- 降级路由主模型失败换备用模型、换线路、缩短上下文，最后才回落到本地缓存或兜底文案；生产用网关转发时记得配好读超时。
- 回归验证改完提示词或换了模型，用一小批固定用例重跑，同一个输入比对新旧输出，避免「感觉变好了」但其实回归了。
想知道自己这边接口通不通、延迟基线多少，先用 /tools/verify 和 /tools/speed-test 量一遍，再回来调超时参数，比拍脑袋定数字靠谱得多。
能跑、能观测、能降级，比一次调通更重要——线上出问题时，你靠的是日志和降级，不是运气。下一步把接口地址、可用模型和当前计费口径核对清楚，再去量一遍你本地的延迟基线，然后回来定超时和并发参数。→
常见问题
C++ 调 DeepSeek 用什么 HTTP 库最稳？
没有统一答案，按你已有的构建环境选：能上第三方库就 libcurl，跨平台示例多、HTTPS 和超时都好控制；不想加依赖就用系统自带的 HTTP 栈，代价是绑平台、代码不好复用。关键是确认它能发 HTTPS、能设读写超时、能拿到响应头，这三条不满足后面排错会很难受。
示例编译不过、报找不到某个符号，先查哪？
按顺序查四步：头文件搜索路径加了没、库文件路径加了没、链接顺序对不对（依赖别人的库要放后面）、运行时 SSL 相关动态库在不在。Windows 上还常见证书路径没配、字符集没对齐。多数「找不到第三方类」的报错都是这四步里的前两步，跟接口本身没关系。
调用失败怎么快速判断是代码问题还是接口问题？
先看 HTTP 状态码：连不上、超时、DNS 失败是网络或地址写错；带鉴权类状态码去看 key 和请求头；参数类状态码是请求体结构问题；服务端错误才可能是对方抖动。同一个 key 用 curl 跑一遍，如果 curl 通而 C++ 不通，问题在你这边；两边都不通，再去查线路和账号额度。
