要处理本地大模型流式输出中断,客户端不能只做一次请求就放弃。中断可能来自模型进程崩溃、推理服务连接重置、代理超时,或本机网络抖动;不同原因对应不同对策。先判断中断位置,再决定是重连同一条请求、重发完整请求,还是把已生成内容拼回 prompt 继续生成。
前置条件:先确认中断发生在哪一层
在修改客户端之前,先用直连测试绕开代理和客户端逻辑。在模型服务所在机器执行以下 curl 命令,确认基础链路是否正常。
curl -N 'http://127.0.0.1:8000/v1/chat/completions' -H 'Content-Type: application/json' -d '{"model":"local-model","messages":[{"role":"user","content":"ping"}],"stream":true}'
这条命令把服务地址和 model 名替换成实际值。如果直连也中途断开,问题在模型服务或本机网络;如果直连稳定,只在客户端和代理场景下断,才需要按下文调整。
同时检查三类日志:模型进程日志看有没有 CUDA OOM、Killed、segfault;推理服务日志看有没有超时和连接异常;经过 nginx 的话看 access/error log 中的 499、504 状态码。
客户端重连逻辑:超时、退避和结束标记
客户端重连要解决三个问题:识别断流、控制重试频率、避免重复输出。识别断流以 finish_reason 为准,不要只判断 TCP 是否断开。如果响应中途 EOF,服务端没有返回 finish_reason,就应触发重试。重试采用指数退避,给服务端恢复时间;连续失败超过阈值后必须停下来,避免把故障放大。
import requests, time, json
def stream_chat(url, payload, max_retries=5):
for attempt in range(max_retries):
try:
resp = requests.post(url, json=payload, stream=True, timeout=(10, 120))
resp.raise_for_status()
received = ''
final_reason = None
for line in resp.iter_lines(decode_unicode=True):
if not line or not line.startswith('data:'):
continue
data = line[5:].strip()
if data == '[DONE]':
break
chunk = json.loads(data)
delta = chunk['choices'][0].get('delta', {}).get('content', '')
if delta:
received += delta
final_reason = chunk['choices'][0].get('finish_reason')
if final_reason is None:
raise ConnectionError('stream ended without finish_reason')
return received
except (requests.exceptions.ConnectionError, TimeoutError) as exc:
wait = min(2 ** attempt, 15)
print(f'attempt {attempt+1} failed: {exc}; retry in {wait}s')
time.sleep(wait)
raise RuntimeError('retry exhausted')
这段代码假定原 payload 可以重复发送。如果请求里带随机采样参数,重连可能得到不同输出;需要可重复结果时固定 temperature 或 random seed。常见的后续处理有三种:
- 没有输出就断开:直接按原 payload 重连。
- 已有部分输出且接受重新生成:原 payload 重连,并在界面提示“生成中断,已重新开始”。
- 已有部分输出但必须接续:把已生成内容作为 assistant 消息追加到 messages,再要求模型从断点继续;这样不保证和原流完全一致,但能避免完全推倒。
服务端和代理层配合:防空闲断开
本地模型服务如果空闲超时设置太短,长文本生成时也会被主动断开。流式接口适合用长连接:模型端定时发送 SSE 心跳,代理端关闭缓冲并拉长读写超时。这不能解决模型进程崩溃,但能降低因设备或代理误判空闲而切断连接的概率。
如果请求经过 nginx,可以调整对应 location 的代理参数:
location /v1/ {
proxy_pass http://127.0.0.1:8000;
proxy_buffering off;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
如果本机直连服务,不需要这层配置。服务端需要在流式响应中周期性发送 `: ping` 这样的 SSE 注释行,客户端循环里要忽略非 data: 开头的行,避免把心跳当作结束。
验证清单
- 直连 curl 能完整走到流结束,日志里出现 `finish_reason":"stop` 或服务端约定的完成标记。
- 在隔离测试环境模拟断网:客户端连接建立后,用 `sudo iptables -A OUTPUT -p tcp `--dport` 8000 -j DROP` 丢弃连接,等待几秒再 `sudo iptables -D OUTPUT -p tcp `--dport` 8000 -j DROP` 恢复,观察客户端是否按退避时间重连并拿到完整输出。
- 查看客户端重试日志,确认没有在 1 秒内大量重试,也没有超过预设最大次数。
- 用长文本提示触发 5 分钟以上生成,确认连接没有被代理或系统空闲超时切断。
回退与风险边界
自动重连不是万能药。若模型进程反复 OOM 或内核杀死,先修稳定性而不是加重试;用 `dmesg | tail` 和模型日志确认。如果同一请求重发会重复生成,在客户端接口层为每个请求保留 request_id 或会话状态,避免下游重复写入。对生成质量要求高的场景,可暂时关闭流式,把请求体里的 `stream` 设为 false,等完整返回再展示;稳定后再改回 true。不要对同一个请求无限重试,连续失败时应进入人工处理或服务健康检查流程。