离线生成模型流式输出到Web页面时,SSE连接断开通常不是模型报错,而是链路空闲超时或客户端网络抖动:模型推理间隔长、反向代理空闲超时、浏览器节能策略都会让连接被服务端或中间设备关闭。解决思路是后端主动发送心跳维持连接,前端在断开后自动重连并携带Last-Event-ID恢复未完成输出。
前置条件
实施前先确认三点:
- 后端能暴露SSE端点,返回
Content-Type: text/event-stream,并设置Cache-Control: no-cache。 - 模型服务在离线环境,单次生成可能超过30秒,需要心跳来“占住”连接。
- 前端如果使用了反向代理(如Nginx),需要关闭代理缓冲,否则SSE流会被缓冲导致页面等不到数据。
后端:用注释行心跳维持连接
SSE规范里以冒号开头的行是注释,浏览器忽略,但能作为心跳。建议在模型输出的等待间隙,每5-15秒发送一行: heartbeat。注意,如果模型推理是阻塞的,心跳要放到独立任务或使用队列,否则模型算完前心跳也发不出去。
FastAPI的StreamingResponse可以直接输出SSE,最小骨架如下:
import asyncio
from fastapi.responses import StreamingResponse
async def event_stream():
# 每条SSE事件以空行结束
yield 'data: 开始生成\n\n'
for i in range(10):
# 实际生成时,这里替换为从模型读取
await asyncio.sleep(1) # 模拟生成耗时
yield 'data: chunk-' + str(i) + '\n\n'
if i % 5 == 0:
# 心跳注释行
yield ': heartbeat\n\n'
@app.get('/sse')
async def sse():
return StreamingResponse(event_stream(), media_type='text/event-stream')
如果模型推理是同步阻塞调用,建议把生成放到线程池,通过队列把分块和心跳发送出来。
前端:自动重连与Last-Event-ID
浏览器原生EventSource自带自动重连,且重连时会带上上一次收到的id字段。后端在每块输出前加id,前端断开重连后就能从断点继续。这个方案最简单,但EventSource不能自定义请求头,如果需要token认证,改用fetch+ReadableStream。
const es = new EventSource('/sse');
es.onmessage = (event) => {
// event.data 就是模型输出的分块
console.log(event.data);
};
es.onerror = (event) => {
// 连接异常时,EventSource 会按照协议自动重连
// 如果长时间连不上,可以在这里手动关闭并提示用户
if (es.readyState === EventSource.CLOSED) {
es.close();
// 可以设置重试按钮或自动重新创建连接
}
};
后端不必为心跳事件写id,注释行不会触发onmessage,也就不会干扰lastEventId。
验证:用curl和开发者工具确认
先不必打开页面,用curl验证后端是否正常输出心跳。以下命令会持续读取SSE流,看到: heartbeat说明心跳生效:
curl -N `--max-time` 120 http://localhost:8000/sse
如果透过Nginx,还需要看缓存是否关闭。在SSE响应中加上X-Accel-Buffering: no头,同时Nginx侧配置proxy_buffering off。然后打开浏览器开发者工具,在Network面板找到SSE请求,观察EventStream内容是否有心跳帧。
失败回退
如果后端无法做心跳,或者网络环境限制导致长连接不稳定,可退化为轮询:前端定时请求一个普通接口,后端将最近生成的结果暂存在内存里。代价是延迟增加和重复数据,但至少能完成展示。另一个方向是改用WebSocket,但需要处理连接状态、重连和协议切换,先确认心跳+重连解决不了再考虑。