大模型流式输出利器SSE：原理、实战与踩坑指南

如果你亲手搭过大模型对话应用，一定对“转圈圈”不陌生。用户发来一句话，你的后端去调LLM（大语言模型）接口，在拿到最终完整回复之前，前端页面只能一直loading。这个问题的根源在于LLM本身的生成机制——token是一个一个蹦出来的，而不是像普通接口那样一次性返回一块完整数据。而SSE（Server-Sent Events，服务端发送事件）就是目前解决LLM流式输出问题最主流、也最轻量的一套方案。

这篇文章我会从LLM为什么要流式输出讲起，把SSE协议拆开揉碎，再给出前后端完整可跑的代码实现，最后把我实际项目中踩过的坑和排查思路都列出来。适合正在做LLM应用开发、想搞懂流式输出原理、或者被“idle timeout waiting for sse”这类报错折磨过的同学。

1. 为什么大模型聊天总在“转圈圈”：流式输出的本质

理解流式输出之前，得先接受一个事实：LLM的推理过程和传统接口不一样。传统接口是“接收请求-计算-返回完整结果”，LLM是“接收请求-不断自回归生成-每次都只产生下一个token”。这个差异，决定了你的系统架构、前后端交互方式，甚至用户感知的产品体验。

1.1 LLM的推理机制决定了它天生着急不来

LLM生成文本可以粗略分成两个阶段：prefill（预填充）和decode（解码）。prefill负责把你输入的prompt一次性编码成KV Cache，这一步通常很快，几百毫秒到一两秒；真正耗时的是decode阶段，模型要一步一步地预测下一个token，每生成一个token都要做一次前向推理，而且当前token依赖前面生成的所有内容。

以主流模型为例，一个token大概是0.75个英文单词或0.4-0.5个汉字，生成速度根据模型尺寸和硬件不同，从每秒十几个token到每秒上百个token不等。一个300字的回答，至少需要600-800个token，光decode阶段就要好几秒甚至十几秒。如果你让用户一直等到全部生成完毕再展示，体验就是长时间的白屏或者loading转圈，用户会怀疑服务是不是挂了。

所以流式输出的核心价值就一句话：把总耗时从“用户无感知”变成“用户有感知的渐进过程”。第一个token越快到达，用户心理上的等待时间就越短。很多产品的体感优化，本质就是在做首token延迟（TTFT，Time To First Token）的优化。

1.2 阻塞式输出 vs 流式输出：用户体验差在哪

阻塞式输出的流程是：用户在输入框发送消息，后端调LLM接口并等待完整响应，完整响应返回后再一次性推给前端。前端拿到的是一个完整的句子，渲染上确实简单，但代价是交互体验非常差。

举两个实际场景。第一，用户问了一个长问题，模型要思考很久才产出一个4000字的答复，在阻塞模式下用户看到的是长达20秒的“发送中”状态，期间没有任何反馈，用户大概率会怀疑网络断了，然后刷新页面或重复发送。第二，用户其实已经看到前面生成的内容有方向性错误，想中途打断重新问，但阻塞模式下根本无法打断，只能等整套token生成完，浪费时间和算力。

流式输出则把这两个问题都解决了。用户能看到文字一个字一个字地打出来，像真人聊天一样，既降低了焦虑感，又能在发现方向不对的时候提前取消请求，节省资源。从产品层面说，流式输出已经是AI对话类应用的标配，没有流式输出的AI应用，竞争力直接少一半。

1.3 选型之前，先看三种传输方案的取舍

实现“服务器主动推送数据给浏览器”这件事，业内有三条技术路线：传统轮询、WebSocket、SSE。很多人一上来就想用WebSocket，但我不建议在纯LLM流式场景里首选它，后面会说原因。

轮询的问题在于浪费资源和延迟不可控，每隔几秒打一次接口，既做不到真正的实时，又对服务器造成额外压力。WebSocket虽然是全双工，但它的复杂度明显更高，需要处理连接升级、心跳保活、二进制帧解析、断线重连逻辑，而且很多SSE能自动完成的机制它都要你自己写。

SSE的优势在于它建立在HTTP之上，协议简单，浏览器原生支持，自带断线重连和事件ID机制。LLM流式输出本质上是“服务器单向持续往客户端推送token”，这种单向模型和SSE的模式完美匹配。除非你的应用还需要客户端频繁往服务器发消息（比如多轮对话中的实时输入状态同步），否则不一定要引入WebSocket。

2. 扒开SSE的协议外衣

SSE不是什么新东西，它早在HTML5时代就定了标准，只是之前一直没有大规模应用。现在随着LLM流式输出成为刚需，SSE又焕发了第二春。要玩转它，你得先搞清楚它传输的数据长什么样，以及它的底层机制是怎么工作的。

2.1 SSE的格式与事件流

SSE的响应Content-Type是text/event-stream，它把服务器要推送的数据按特定格式切割成一块一块的“事件”（event）。每个事件可以包含多个字段，最常用的几个是：

• data:：事件的数据内容，可以多行，以空行结束当前事件
• event:：事件类型，默认是message
• id:：事件ID，用于断线重连时通过Last-Event-ID请求头续传
• retry:：告诉浏览器断线后多少毫秒重连

一个典型的SSE响应长这样：

data: 你好 data: 世界 data: 这是第二行 data: 拼接后的完整内容

浏览器端EventSource收到后，默认情况下会把一个事件块里的多行data:自动用换行符拼接成一个字符串，触发onmessage回调。注意看第二个块，它有两行data，最终回调拿到的值是“这是第二行\n拼接后的完整内容”。

这里最容易被忽略的就是空行的作用：空行是事件结束的标志。如果服务端没有在每条消息后输出空行，前端EventSource会一直等，不触发任何事件。很多人在写测试脚本时踩过这个坑，以为数据没推过来，其实是格式不合法。

2.2 为什么SSE和LLM是天作之合

大模型推理接口（比如OpenAI兼容接口、各家国产模型的API）的流式输出，绝大多数都采用了SSE格式或者类似SSE的分块格式。你去看LangChain、Dify这类框架的底层实现，它们在做流式转发时，本质就是在处理和转发SSE数据流。

SSE和LLM契合的点在于消息边界很清晰。LLM产出的token，我们希望拿到一个就推一个，但又不希望前端因为网络原因频繁重连导致消息错乱。SSE的id字段和retry字段天然解决了这个问题：浏览器断线后，会自动带上Last-Event-ID重新连接，服务端可以根据这个ID判断从哪里继续推送。

比如你已经推送了100个token，客户端掉线重连时带了Last-Event-ID: 99，服务端就知道该从第100个token开始继续，而不是从头再来。对于聊天这种弱状态场景，这个机制已经足够用。当然，LLM推理是一次性的，模型无法从中间状态恢复，所以实际生产中更多是靠前端的展示层做幂等去重，而不是真的续传未完成的token流，这一点后面讲Agent场景时会展开。

2.3 SSE鉴权：EventSource的天然短板怎么破

如果你直接用浏览器原生EventSource，很快会发现一个痛点：它不支持自定义请求头。很多后端接口为了安全，会把鉴权token放在Authorization头里，但EventSource只能通过URL参数或者withCredentials带上Cookie，这就很尴尬。

我常用的解决方案有三套：

第一，把token放到URL query参数或路径里，服务端从query取。比如/api/chat?token=xxx。简单粗暴，但token会暴露在网关访问日志里，生产环境要谨慎，建议配合短时有效的签名参数。

第二，用Cookie做鉴权，开启EventSource.withCredentials = true。前提是前后端同域，或者后端配置了对应的CORS跨域策略，允许携带凭证。好处是日志不会泄露token，缺点是Cookie本身有CSRF风险，需要做好防护。

第三，抛弃EventSource，改用fetch+readable stream去手动读取SSE流。fetch支持自定义Header，代码层面也不会复杂太多。这也是我在实际项目里更推荐的做法，因为同时还能拿到HTTP状态码，方便处理401、429这种异常。我在下一节会给出具体实现。

3. 从零手写一套流式对话接口

理论说再多，不如直接看能跑的代码。这里我以Python FastAPI作为后端，前端分别演示EventSource和fetch流式两种方式，再把中间涉及的网关配置问题讲清楚。

3.1 整体架构与数据流设计

先画一下我们这套东西的数据流，不涉及具体组件，只讲链路逻辑：

浏览器发起流式请求。后端收到后，立刻返回200和text/event-stream响应头。后端内部调用大模型API，大模型API流式返回token块，后端每拿到一个token块，就往响应流里写一条data: {...}\n\n。浏览器从EventSource或fetch的reader里不断读取这些数据块，解析后append到页面上。

这里的关键是“立刻返回响应头”这件事。HTTP响应不是一次性发完的，只要服务端在拿到完整业务结果之前先把响应头flush给客户端，客户端就会进入流式接收状态。所以哪怕后端内部准备时间再长，只要响应头先出去了，前端连接就是活的，不会被认为是超时。

3.2 后端实现：FastAPI + 流式响应

FastAPI天然支持StreamingResponse，配合Python生成器可以非常优雅地实现流式推送。下面是一份简化的真实代码，我把注释写细一点。

import asyncio import json from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse app = FastAPI() async def llm_stream_gen(prompt: str): """模拟大模型流式返回token。实际项目里替换成对OpenAI/国产模型API的调用即可。""" result = f"这段话是为 '{prompt}' 生成的模拟回答内容，可以拆成很多个token分批吐出来。" for i in range(0, len(result), 5): # 模拟推理延迟，实际场景里这里是等待上游LLM的下一个token await asyncio.sleep(0.2) yield result[i:i+5] @app.post("/api/chat") async def chat(request: Request): body = await request.json() prompt = body.get("prompt", "") async def event_generator(): # 第一步：先发一个事件表示开始，前端可以用来标记本次请求开始计时 yield "data: {\"event\": \"start\"}\n\n" # 第二步：逐token推进，每个token都包装成SSE事件 async for chunk in llm_stream_gen(prompt): # 如果客户端断开，生成器再往下输出没有意义，及时退出 if await request.is_disconnected(): break payload = json.dumps({"event": "token", "content": chunk}, ensure_ascii=False) yield f"data: {payload}\n\n" # 第三步：发送结束事件，前端收到后知道自己组装完成 yield "data: {\"event\": \"done\"}\n\n" return StreamingResponse( event_generator(), media_type="text/event-stream", headers={ "Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no", # 重要：关掉Nginx等网关节点的缓冲 } )

几个容易踩的点，我直接标出来了：

第一，media_type必须是text/event-stream，否则浏览器EventSource不认。第二，Cache-Control: no-cache是必须的，不然有些浏览器或中间层会缓存整个响应体，导致前端等不到流式数据。第三，X-Accel-Buffering: no是给Nginx看的，告诉它别替我做缓冲，后面网关那一节我再展开。

如果是真实调用LLM接口，比如OpenAI兼容接口，llm_stream_gen里通常是这样的逻辑：

from openai import AsyncOpenAI client = AsyncOpenAI() async def llm_stream_gen(prompt: str): stream = await client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": prompt}], stream=True, ) async for chunk in stream: if not chunk.choices: continue delta = chunk.choices[0].delta.content if delta: yield delta

核心逻辑没变：上游怎么流式吐，我们就怎么转推给客户端。中间可以做增量解析、敏感词过滤、或者把token攒起来做统计，但不要为了统计去破坏流式节奏，请选择异步旁路。

3.3 前端实现：EventSource与fetch流式读取

前端最简单的方式是用EventSource，但它只能发GET请求，而且不能自定义Header。如果你的接口是POST（比如要传prompt字符串），EventSource就不太合适了。所以我把两种方式都写出来。

EventSource方式：

const es = new EventSource(`/api/chat?prompt=${encodeURIComponent("你好")}`); es.onmessage = (event) => { const data = JSON.parse(event.data); if (data.event === "token") { container.innerText += data.content; } else if (data.event === "done") { es.close(); } }; es.onerror = () => { // 自动重连会触发onerror，如果业务上不希望重连，要在这里close es.close(); };

fetch + ReadableStream方式，这种方式更灵活，能解决POST、自定义Header、错误处理这三大难题：

const response = await fetch("/api/chat", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, }, body: JSON.stringify({ prompt: "你好" }), }); // 注意：fetch的响应体是ReadableStream，需要手动按块读取 const reader = response.body.getReader(); const decoder = new TextDecoder("utf-8"); let buffer = ""; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); // 按空行切分SSE事件，因为我们的服务端是用\n\n分隔每个事件的 const events = buffer.split("\n\n"); buffer = events.pop() || ""; for (const event of events) { const lines = event.split("\n").filter(line => line.startsWith("data:")); const data = lines.map(line => line.slice(5).trim()).join("\n"); if (data) { handleMessage(JSON.parse(data)); } } }

这段代码的关键是decoder.decode(value, { stream: true })。流式传输时，一个中文字符的UTF-8字节可能被拆在两个chunk里，如果直接按二进制转字符串，很容易出现乱码。TextDecoder的stream: true模式就是用来处理这种跨chunk的字节切割的，这是前端最容易忽略的细节。

3.4 网关与中间件：缓冲是流式输出最大的敌人

本地联调一切正常，一上测试环境就发现数据不往下吐，大概率是网关或反向代理在作怪。Nginx默认会缓冲上游响应，意味着它会等上游响应体攒到一定大小再一次性返回给客户端，这个行为对流式输出是致命的。

Nginx相关配置要打开：

location /api/chat { proxy_pass http://backend; proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; # 避免长时间没有token导致超时断开 proxy_send_timeout 300s; chunked_transfer_encoding off; }

有些云厂商的负载均衡器也有类似的“响应缓冲”开关，需要在控制台或配置里找一下关闭。如果你用的是Kubernetes和Ingress，也要检查Ingress Controller的proxy-buffering设置。总的来说，凡是在客户端和后端之间的中转层，都要检查它是否对text/event-stream做了缓冲。

另外一个常见场景是接入Dify这类平台。Dify自身有流式输出能力，但你如果用自定义前端去调Dify的接口，要确认它返回的是不是标准SSE格式；我遇到过一次Dify返回的Content-Type被网关改成了application/json，前端怎么解析都是空的，最后排查到是入口网关的问题。

4. 实战中那些让人挠头的坑

这一节我整理了自己在实际项目中踩过、也帮别人排查过的典型问题，每一个都对应一条血泪经验。尤其那个“idle timeout waiting for sse”的报错，如果你经常用Python的requests或httpx去消费上游SSE接口，大概率见过它。

4.1 请求被网关切断：before completion: idle timeout waiting for sse

“before completion: idle timeout waiting for sse”这句报错，最常见于你用某种HTTP客户端（比如Java的OkHttp、Python的requests）去请求一个SSE接口时。它含义是：连接已经建立了，但没有数据到达，触发了底层socket的idle timeout。

为什么会没有数据到达？两个原因。第一，上游LLM在思考阶段很慢，第一个token迟迟没有推出来。比如你的prompt特别长或者模型在做复杂的reasoning，可能好几秒甚至十几秒都没有任何输出，而中间层的idle timeout设置为5秒，连接就被掐断了。第二，服务端处理逻辑里有阻塞，比如同步调用了另一个接口，这个接口卡住了，导致SSE响应流一条消息都没发。

解决思路：

• 在应用层面加心跳。SSE有个空注释行:\n\n可以当作心跳，它不会触发前端onmessage，但能重置idle timer。服务端可以每隔10秒发一个注释行保活。
• 调整网关、负载均衡、HTTP客户端的读超时时间，至少要大于LLM的最长首token延迟。
• 如果用的是Nginx作为反向代理，proxy_read_timeout默认只有60秒，对于慢思考场景要调大。

还有一种情况是客户端的问题。比如你用Python的requests库去读SSE，但requests不支持流式响应超时重置，如果设置了timeout=30，它指的是整个响应30秒，而不是每个块之间30秒。这时候换成httpx的Stream模式，或者直接用专门为SSE设计的库。

提示：如果服务端是Python，建议直接用httpx或者openai的SDK去消费上游SSE，不要用requests硬解析，省很多事。

4.2 断线重连与消息错乱：幂等设计要靠前端

EventSource自带重连机制，但这在LLM场景里也可能是个坑。假设用户发了一句话，后端生成到一半，用户的Wi-Fi闪断了，EventSource会自动重连，重连后从Last-Event-ID续传。问题在于，我们的大部分后端实现并不会真的实现“从第N个token继续生成”，因为模型推理是无法中断续跑的。

所以实际项目里的处理方式是：前端不要完全依赖EventSource的自动重连，而要在业务层做幂等。具体来说，每次发起请求时生成一个唯一的requestId，后端在处理时如果发现同一个requestId已经生成过一部分token，要么直接丢弃重连请求，要么把已经生成的完整结果一次性返回给前端做补偿。

如果你的后端是自己控制的LLM推理，还有另一种思路：把“正在生成的流”和“已经完成的缓存”分开。请求断开后，让后端生成任务在后台继续跑完，缓存到Redis里，客户端重连时如果发现生成已结束，就直接从Redis读完整结果。这样虽然不能真正续传中间状态，但至少不会让用户白等。

4.3 中文乱码、缓冲器与代理的三角关系

中文乱码通常不是SSE的问题，而是编码和压缩的问题。流式传输中，SSE消息体默认是UTF-8，前端解码时也要用UTF-8。如果你在服务端往流里写内容时用了ensure_ascii=False，前端却用ASCII去解，自然乱码。

另一个非常隐蔽的问题是压缩。有些网关或CDN默认开启gzip压缩，压缩本身没问题，但如果压缩实现是“攒够一定字节才压缩一次”，流式效果就被破坏了，前端会等很久才看到一块内容。更麻烦的是，gzip压缩是按块处理的，如果整段流一起压缩，前端必须等所有数据到达后才能解压，这就完全失去了流式的意义。

解决办法：对流式响应的路径关闭压缩，或者确保压缩是按chunk进行的。在Nginx里，可以针对text/event-stream类型禁用gzip：

gzip off;

或者更精细化地只在流式接口路径上关闭。很多CDN厂商对流式支持得不好，如果生产环境用了CDN，遇到SSE不工作，第一反应该去CDN控制台关掉缓冲和压缩，而不是改应用代码。

4.4 Agent场景下SSE的“流而不完整”问题

现在LLM应用很少是单纯的“一问一答”，更多是Agent形态，中间会调工具、查知识库、做RAG检索。这意味着流式输出不仅要有文本token，还要有工具调用状态、检索进度、错误信息等不同事件类型。如果所有事件都挤在默认的message事件里，前端解析起来会非常痛苦，而且很难判断“现在这个回答算不算结束”。

我的做法是约定一套事件类型体系：

前端根据event类型渲染不同的UI。为什么这个设计重要？因为Agent场景下一个很大的坑是：LLM生成完毕并不等于Agent任务完成。模型可能还要调用第二个工具，或者还要等RAG检索结果，如果前端把“流结束”当作“回答结束”，就会出现用户看到一句话，页面已经停止滚动，但后台其实还在工作的“假死”状态。

在事件里明确区分“流结束”和“任务结束”非常关键。我一般在LLM的token流结束后，不立刻发done，而是等Agent的整个执行链跑完，再发一个包含最终统计的done事件。中间如果有工具调用，就用status或tool_call事件通知前端。

5. 生产级流式输出的下一步优化

代码能跑和线上稳定运行是两回事。把流式输出真正放到生产环境，还需要考虑连接生命周期、资源释放、监控告警这些看起来不性感但非常致命的问题。

5.1 客户端断开时后端要及时“踩刹车”

流式输出最怕的不是慢，而是“客户端已经走了，服务端还在拼命生成”。用户等得不耐烦关掉了页面，或者切换了对话，如果后端不检测连接状态，LLM还会继续跑完剩余的所有token，白白消耗算力和钱。

FastAPI里可以通过request.is_disconnected()来检测客户端是否断开，我在前面的代码里已经演示过。但要注意，这个检测不是实时的，它依赖于底层ASGI服务器（比如uvicorn）的事件循环状态，调用一次只能知道那一刻的状态。所以更稳妥的方式是把检测放在每轮生成循环里，每拿到一个chunk都检查一次。

还有一种情况是客户端断开后，生成器抛异常而不是优雅退出。建议在生成器外层包一层try/except，确保断开时能关闭上游HTTP连接和释放其他资源。

async def event_generator(): try: async for chunk in upstream_stream(): if await request.is_disconnected(): break yield f"data: {chunk}\n\n" finally: # 确保关闭上游连接 await upstream_stream.aclose()

5.2 监控和日志：首token延迟是核心指标

流式服务有没有问题，不能只看接口成功率。你要关注这些指标：

• TTFT（Time To First Token）：从请求进入后端到第一个token返回给客户端的耗时。这个指标反映了上游模型推理速度和网关转发效率，通常希望控制在1-2秒以内。
• Token吞吐量：每秒向客户端推送了多少token。可以反映流式链路有没有被缓冲或拥塞。
• 平均token间隔：相邻两个token推送时间的间隔。如果这个间隔忽大忽小，说明上游或网络波动严重。
• Stream断流率：已经建立的SSE流在业务正常结束前被断开的比例。断流可能是用户关闭、网络抖动、超时等，需要分维度统计。

日志方面，建议给每个流式请求分配一个requestId，在开始、首token、结束、断开这几个关键节点打印日志，并带上累计耗时。这样排查问题的时候，可以通过一条日志串起整条链路，而不是在多个服务里捞上下文。

5.3 多路复用与HTTP/2的取舍

HTTP/1.1的规范里，同一个域名下的并发连接数通常限制在6个。如果你的页面同时有多个SSE流在跑，比如一个用于对话，一个用于进度通知，很容易把浏览器的连接数打满，导致其他资源加载变慢。

两个解决办法。第一，升级到HTTP/2，多路复用可以让多个流共用一条TCP连接，SSE在HTTP/2下的表现会更稳定。但这要求全链路都支持HTTP/2，包括你的反向代理和CDN。第二，在应用层做事件路由，只维持一个SSE连接，通过不同的event类型来区分业务，前端用一个EventSource接收所有消息，再内部转发给不同的处理器。

我个人的建议是：对话类的页面维持一个SSE连接就好，人多的时候不要为每个功能单独开连接。等你的流式场景复杂到单个连接无法满足时，再考虑HTTP/2和更复杂的方案。

作为一个被LLM流式输出折磨过很多次的人，我最后再分享一个体会：SSE本身协议很简单，真正的复杂度都在“链路环境”里。每一层——浏览器、Nginx、K8s Ingress、CDN、云厂商的负载均衡——都可能因为默认的缓冲策略、超时配置、压缩逻辑，不经意间把你的流式响应变成“假流式”。所以调试的时候不要只盯代码，记得看请求经过的每一跳，按“客户端 -> 网关 -> 服务端 -> 上游LLM”的顺序逐个排查，90%的问题都能定位出来。希望这篇文章能帮你少踩几个坑，把流式输出真正用好。