DeepSeek流式返回内容不完整怎么排查

文章导读
DeepSeek 流式返回内容不完整,多数情况不是模型只写了半句,而是链路里某一层提前结束了连接、丢掉了增量,或者客户端把分块拼错了。判断时先分清三种可能:传输层被截断(代理、网关、空闲超时)、解析层丢包(按块解析没有处理跨块半行)、生成层本身停止(触到输出上限,或请求参数把 stream 关掉了)。这三种的表象相似,处理动作完全不同,所以要先定位再改配置。
📋 目录
  1. Ⅰ 先确认当前场景和目标
  2. Ⅱ 按这个顺序处理
  3. Ⅲ 改完后怎么验证
  4. Ⅳ 容易忽略的边界
A A

DeepSeek 流式返回内容不完整,多数情况不是模型只写了半句,而是链路里某一层提前结束了连接、丢掉了增量,或者客户端把分块拼错了。判断时先分清三种可能:传输层被截断(代理、网关、空闲超时)、解析层丢包(按块解析没有处理跨块半行)、生成层本身停止(触到输出上限,或请求参数把 stream 关掉了)。这三种的表象相似,处理动作完全不同,所以要先定位再改配置。

可先按这个顺序自查:请求是否确实带 stream 开关、客户端是逐块消费还是一次性读取、中间是否经过代理或网关、响应末尾是否出现结束标记与 finish_reason。适用自建接入和网关转发场景;如果直接用官方 SDK 仍不完整,优先看网络中断、输出上限和客户端超时,回退办法是先发一次非流式请求,确认内容本身是完整的,再回头修流式链路。

先确认当前场景和目标

排查前需要把几个前提确认清楚,否则容易在错误的方向上加配置。建议先回答下面几项:

  • 请求体里 stream 是否为 true,以及调用的是 SDK 的流式方法还是普通方法;
  • 客户端是边收边渲染,还是先收完再解析;前者更容易暴露截断,后者可能只是超时;
  • 中间是否存在 Nginx、Ingress、API 网关、CDN 或企业出口设备,这些层通常带缓冲和空闲超时;
  • 本次请求的 max_tokens 或等价输出上限设成多少,模型是否可能被这个上限截停;
  • 现象是稳定复现还是偶发,稳定复现多半是解析或参数问题,偶发多半是网络和超时。

判断条件可以简单对照:如果响应末尾缺少结束标记、也没有 finish_reason,问题更可能在传输或解析;如果能拿到 finish_reason 且值为 length 之类的长度截停信号,那属于输出上限,不是流式故障;如果非流式请求同样写不满,说明问题在提示词或模型输出本身,与流式无关。

按这个顺序处理

第一步先用非流式请求做对照,确认同一提示词下内容是否完整。这一步能快速排除模型和参数层面的问题,也能留下一个长度基准。

第二步绕开自己的客户端,用 curl 直接看原始响应。下面是一个可替换的通用请求片段,把地址、密钥和模型名换成本地环境的值,在能直连出口的机器上执行。-N 的作用是关闭 curl 自身缓冲,便于观察增量是否连续到达:

curl -N -s https://api.example.com/v1/chat/completions \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-chat","stream":true,"max_tokens":1024,"messages":[{"role":"user","content":"分几段介绍一下流式返回"}]}'

如果 curl 能收完整,问题就在自己的客户端或网关;如果 curl 也断在中途,继续往下查中间层。

第三步检查中间层的缓冲与超时。反向代理常见的处理是关闭响应缓冲、放行分块传输,并调大读超时;如果响应被 gzip 压缩或经过会缓存响应的网关,增量可能被攒到最后才吐出,看起来就像内容缺失。

第四步检查客户端解析。流式响应是逐行文本,同一行可能被拆到两个网络分块里,直接按分块做 JSON 解析会丢掉半行。下面是一段通用解析骨架,重点是保留未闭合的缓冲、只处理 data 行、遇到结束标记就停止:

buf = ""
for raw in resp.iter_lines(decode_unicode=True):
    if not raw:
        continue
    line = raw.strip()
    if not line.startswith("data:"):
        continue
    payload = line[len("data:"):].strip()
    if payload == "[DONE]":
        print("stream done")
        break
    obj = json.loads(payload)
    choice = obj["choices"][0]
    buf += choice.get("delta", {}).get("content") or ""
print("finish_reason=", choice.get("finish_reason"))
print("total_len=", len(buf))

如果是自己从 socket 读字节,需要先拼再切行,避免把半行当成完整行:

DeepSeek流式返回内容不完整怎么排查
carry += chunk.decode("utf-8", errors="ignore")
while "\n" in carry:
    line, carry = carry.split("\n", 1)
    handle_line(line)

改完后怎么验证

验证要盯住几个可观察信号,而不是只看“这次好像写完了”。建议同时记录:每个增量的到达时间、拼接后的总长度、最后一个 finish_reason、以及是否收到结束标记。预期信号是增量持续到达而不是长时间停顿后一次性吐出,末尾出现明确的结束标记,finish_reason 表示正常停止而不是长度截停,拼接结果与非流式请求的输出在长度和结尾上基本一致。

验证动作可以这样安排:先用同一提示词跑非流式请求记录长度,再跑流式请求做对比;然后用一个明显较长的输出要求(例如让对方写多个段落)压一下链路,看末尾是否仍被截断;最后在客户端人为放慢渲染速度,观察是否因为消费过慢触发超时。若只在长输出时复现,通常指向超时或输出上限;若短输出也断,多半是解析或代理缓冲。

容易忽略的边界

第一,输出上限不要当成 bug。命中长度上限时流式会正常结束但内容不完整,这种情况改解析代码没有意义,应调整 max_tokens 或把长任务拆成多次请求。

第二,客户端超时和自动重试会掩盖问题。重试通常从头发起,已经收到的增量不会保留,表现出来的“缺一段”其实是两次请求拼接的结果,排查时需要把重试关掉或打日志。

第三,浏览器端用 EventSource 只能发 GET,带鉴权和请求体时一般要用 fetch 加流式读取手动解析,这类实现里容易漏掉异常分支,导致中断时既不报错也不补数据。

第四,网关、WAF 和部分企业出口设备会对长连接的空闲时间做限制,模型思考停顿较长时可能被断开,这类限制通常不在应用日志里体现,需要结合网关侧日志确认。

回退建议:先把流式关掉,用非流式请求保证功能可用,再逐步恢复流式并观察;或缩短单次输出长度、分段请求。这些只是临时保证可用的手段,不构成性能方案。若排查后仍无法确定断点位置,建议在客户端、网关和应用三处同时记录首个增量和最后一个增量的时间戳,用时间差定位是哪一层先停。