长流式响应超时：从定位断点到安全恢复的七步排查

长回答输出到一半突然断开，先别把所有超时都改成无限。建议把排查拆成三个问题：谁关闭了连接、哪个计时器触发、已经生成的内容如何处理。通过 CodeRelay Hub 的统一入口调用模型时，也应分别检查客户端、业务服务和代理，而不是只调整模型请求参数。

1. 先给请求建立时间线

为每次请求记录请求标识、开始时间、响应头到达时间、首个有效内容到达时间、最后一次收到数据的时间，以及结束原因。建议使用单调时钟计算耗时，避免系统校时干扰判断。不要只保留一句“请求超时”，而要同时记录异常类型、所在层和已接收的数据量。

复现时，先观察故障发生在首段内容之前，还是持续输出之后。再比较客户端与服务端日志：两边最后一次收到数据的时间是否一致？把这个问题回答清楚，再修改配置。

2. 分清空闲超时与总时限

HTTPX 的读取超时限制的是等待下一块数据的时间，不是整个响应的持续时间；NGINX 的 proxy_read_timeout 同样针对相邻两次上游读取之间的间隔。因此，不能仅凭请求运行很久，就认定读取超时配置不足。([python-httpx.org](https://www.python-httpx.org/advanced/timeouts/?utm_source=openai))

建议单独管理连接超时、首段内容等待预算、读取空闲超时和端到端总预算。首段内容等待预算用于约束“连接成功但迟迟没有有效输出”的情况；总预算则负责限制整项任务。不要假定客户端的一个 timeout 参数已经覆盖这些不同目标。

3. 先设预算，再落到客户端

先根据业务可接受的等待时间确定总预算，再分配建立连接、等待首段内容和持续读取的空间。把这些数值集中配置，并按交互任务与后台任务分别管理。不要为了容纳长生成，顺手放宽连接池等待或建立连接的限制。

如果使用 HTTPX，请分别检查 connect、read、write 和 pool，而不是把它们当成同一个计时器。读取阶段的 read 参数约束等待数据块的时间；需要完整任务截止时间时，建议另外设置应用层取消机制。([python-httpx.org](https://www.python-httpx.org/advanced/timeouts/?utm_source=openai))

4. 沿链路检查代理与缓冲

画出实际链路：客户端、业务服务、反向代理、出口网关、模型入口。逐层列出空闲限制与最大请求持续时间，并标记哪些配置可以修改。排查时优先检查与实际断开时间接近的限制，再通过日志验证，避免同时修改多层而失去归因能力。

如果使用 NGINX，可在流式接口对应的位置评估 proxy_buffering off。开启代理缓冲时，NGINX 会先接收上游数据并存入缓冲区；不要把上游已经发送数据，直接等同于客户端已经收到数据。修改后应同时观察两侧到达时间。([nginx.org](https://nginx.org/en/docs/http/ngx_http_proxy_module.html?utm_source=openai))

5. 把连接存活与生成进度分开

对于采用 SSE 的链路，规范允许服务端发送注释行作为保活手段，并给出了定期发送注释的建议。若你控制中转服务，可以评估这种机制，但应先确认事件确实及时穿过代理到达客户端。([html.spec.whatwg.org](https://html.spec.whatwg.org/multipage/server-sent-events.html?utm_source=openai))

建议维护两个时间戳：最后收到网络数据的时间，以及最后收到有效生成内容的时间。心跳只更新前者；业务进度监控使用后者。同时保留总截止时间，不要让持续心跳替代任务完成条件，也不要预设入口一定提供心跳。

6. 明确中断后的恢复边界

建议把“尚未展示内容”和“已经展示部分内容”设为两种恢复状态。前者可以进入受限重试策略；后者应先保存部分结果并标记未完成，不要直接把重新生成的文本追加到原答案后面。每次尝试都保留独立标识，方便核对输出与请求记录。

检查应用层和客户端库是否同时承担重试职责，尽量只保留一个明确的控制层。续写时，应把已完成内容及待完成目标显式传入，并将其视为新请求。只有在接口明确支持恢复协议时，才把恢复当作原流的继续。

7. 用故障注入验收

上线前安排四类测试：延迟首段内容、输出中途暂停、持续少量输出但超过总预算，以及用户主动取消。为每类测试提前写出预期结果，核对部分内容是否保留、结束状态是否准确，以及应用是否停止继续读取。

最后，把超时类型、发生层、已输出内容量和恢复动作纳入监控。建议先在单个流式接口验证，再扩大配置范围。验收标准不应只是“这次没有断开”，而应包括发生中断时，系统能够解释原因并按预定策略收尾。

打开 CodeRelay Hub 免费工作区，验证你的流式超时策略。