离线生成模型流式输出到Web页面时SSE连接断开的自动重连与心跳实现

文章导读
离线生成模型流式输出到Web页面时,SSE连接断开通常不是模型报错,而是链路空闲超时或客户端网络抖动:模型推理间隔长、反向代理空闲超时、浏览器节能策略都会让连接被服务端或中间设备关闭。解决思路是后端主动发送心跳维持连接,前端在断开后自动重连并携带Last-Event-ID恢复未完成输出。
📋 目录
  1. 壹 前置条件
  2. 贰 后端:用注释行心跳维持连接
  3. 叁 前端:自动重连与Last-Event-ID
  4. 肆 验证:用curl和开发者工具确认
  5. 伍 失败回退
A A

离线生成模型流式输出到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,最小骨架如下:

离线生成模型流式输出到Web页面时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。

离线生成模型流式输出到Web页面时SSE连接断开的自动重连与心跳实现

验证:用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,但需要处理连接状态、重连和协议切换,先确认心跳+重连解决不了再考虑。