1. 流式输出为什么大模型应用都在抢这“几百毫秒”我先从一个真实场景说起。当时团队接入某个大模型问答服务测试时发现接口响应要等4到5秒才出第一个字最离谱的一次整个请求直接报了个idle timeout waiting for sse页面白屏用户把浏览器刷新了三遍。排查到最后发现问题不只在网关超时配置更深层的原因是我们把一次大模型请求当成了普通HTTP接口来处理——等模型推理完整个回复才一次性返回给前端。这就是不懂流式输出要付出的代价。LLMLarge Language Model大语言模型的推理逻辑是逐token生成的。你在对话框里问一句“今天上海天气怎么样”模型不是一次性把整句话算出来而是先算出“今”再算出“天”再往后推“上”“海”“天”“气”每一步都要借助前面已经生成的token做条件概率计算。这个过程在模型端天生就是“边推理边产出”的。但如果你用传统HTTP请求模式服务端会一直等模型算完最后一个token才把完整文本拼成一个字符串返回。问题立刻暴露出来了模型回复越长用户等待时间越长。一次生成800字的回答模型端耗时可能就要8到10秒用户盯着空白页面心里已经开始骂产品经理了。流式输出要解决的核心问题就是把这8到10秒的“静默等待”拆分成一个又一个token的“即时到达”。用户看到的是类似打字机效果第一个字不到1秒就出现在屏幕上后续内容持续滚动刷新。这不是什么炫技而是大模型应用的基本体验门槛。现在市面上的主流方案里SSEServer-Sent Events服务端推送事件是出镜率最高的一种。很多大模型API的流式接口、LangChain的流式回调、Dify里的流式响应配置底层都是走SSE。它不像WebSocket那样需要建立额外连接、做单独的协议协商而是建立在HTTP协议之上服务端把数据以特定格式“一段一段”推给客户端前端用几行代码就能接住。但SSE看起来简单实际踩坑的地方相当多。比如网关超时、缓冲被吞、EventSource不支持自定义Header、流式上下文里的SSE鉴权怎么做、Agent场景下多轮工具调用怎么保持流式输出不断……这些问题我在项目里一个不落全遇到了。这篇文章就把流式输出和SSE从原理到实战完整梳理一遍给正在做LLM应用接入的朋友一份可以直接抄作业的参考。2. 大模型推理链路先看懂token是怎么“蹦”出来的2.1 模型端到应用端一次完整的流式旅程要理解流式输出得先知道一次请求从头到尾经过了哪些环节。以目前最常见的架构为例大模型应用一般分三层模型端推理端负责真正跑模型推理把用户输入丢给模型模型逐token吐结果。这里说的推理服务可能是一台GPU服务器上的vLLM、TGI、SGLang也可能是云端托管的模型API。应用后端你的业务代码所在的地方负责接收前端请求、调用模型API、处理业务逻辑。LLM应用框架如LangChain、LlamaIndex以及Dify、FastGPT这类平台都跑在这一层。前端浏览器、小程序或者App界面负责把模型输出渲染给用户看。流式输出要做的事情就是把模型端已经“逐token产出”的特性贯穿到前端去。理想状态下模型端每生成一个token就立刻把数据传给应用后端后端再转发给前端前端立即渲染出来。但现实往往没这么美好。如果你的应用后端直接把完整响应攒到最后才返回那模型端的流式能力就被白白浪费了。这也是很多人调了SSE接口却发现前端还是一下子收到全部内容的原因——数据可能被某个中间环节缓存住了或者后端代码压根没做流式转发。2.2 token、缓冲与采样推理端的“打字机”速度有人可能会问为什么模型不能几毫秒内一次性输出全部内容答案是做不到也不应该这样做。大模型的生成过程本质上是自回归autoregressive。模型根据已有的token序列预测下一个token的概率分布采样得到一个token然后把它拼接到序列末尾再预测下一个。每一步都要做一次神经网络前向计算。虽然现代推理引擎做了很多优化比如KV Cache、连续批处理但生成一个token仍然需要时间一般在几十毫秒到几百毫秒之间。以GPT-4o这类模型为例输出速度大约在每秒100多个token。一次生成500字的回复中文字符约等于500到800个token在模型端就需要5到8秒。如果按传统HTTP请求用户要白等这么久。但如果做流式输出按下回车后大约1秒内就能看到第一个token后面每秒钟都有新内容陆续出现用户的感知完全不同。这中间还有个容易被忽略的点采样策略。模型生成token时存在随机性temperature参数越高生成越随机同时还有top_p、top_k等采样参数。这些参数影响的是token的多样性不影响流式输出的机制本身。但在工程上要留意有些推理服务和流式输出组合在一起时会出现一个现象如果采样参数设置不当模型可能一直在“思考”或者说生成空token流式接口半天不吐内容。遇到这种情况先排查采样参数再看推理服务的空闲超时配置。2.3 从轮询到长连接流式技术选型的来龙去脉流式输出在大模型时代才火起来但“服务端持续向客户端推送数据”这个需求其实早就存在。早期网页聊天室、股票行情、实时通知都在用各种手段解决这个问题。技术选型大体经历了几个阶段轮询Polling前端每隔几秒发一次普通HTTP请求问服务端“有新数据了吗”。实现简单但浪费带宽实时性差。大模型场景下如果每秒轮询一次对服务端压力不小而且每次请求都有网络开销token的实时到达效果也不好。长轮询Long Polling服务端收到请求后先挂起有数据了再响应。比普通轮询实时性好一些但每次响应后连接都要重建仍有较大的协议开销。WebSocket全双工长连接客户端和服务端可以互相推送消息。实时性最好但它是一个独立的协议需要额外握手服务端部署要考虑连接状态管理、心跳保活、断线重连等复杂问题。对于“主要让服务端单向推送”的大模型输出场景来说属于杀鸡用了牛刀。SSEServer-Sent Events基于HTTP的单向推送协议服务端可以持续向客户端发送事件。它不需要额外握手天然复用HTTP基础设施实现成本低。在大模型流式输出这个场景里SSE几乎是先天契合的——模型输出的方向是单向的服务端到客户端而SSE正好就是专为这种单向推送设计的轻量级方案。这也是今天绝大多数LLM API选择SSE作为流式协议的根本原因。3. SSE协议深度拆解一个被低估的HTTP“半成品”3.1 一次握手持续推送SSE的工作模型SSE全称是Server-Sent Events它的核心思想很朴素客户端发一个普通的HTTP请求但服务端不立刻结束这个响应而是在同一个HTTP连接上持续不断地把数据以特定格式推送给客户端。打个比方普通HTTP响应就像点外卖——你下单商家做好一次性全部送过来SSE则像在餐厅点了一份现做现上的菜——你下单后厨房做好一道菜服务员就先端一道上来后厨继续做做好再端直到上完为止。整个过程中你客户端和餐厅服务端只建立了“一次”联系但东西是分多次送过来的。这种模式下有几个关键特点连接复用一次HTTP请求对应一个持久连接不需要像WebSocket那样额外握手升级协议。文本协议SSE传输的是字符串格式的数据有特定的事件格式规范后面会详细讲。自动重连浏览器的EventSource接口内置了断线重连机制连接异常断开后能自动恢复。单向推送只能服务端向客户端推客户端不能通过这个连接往回发数据。如果需要双向通信得另想办法比如每个流式请求用独立的SSE连接或者混用WebSocket。我在实际项目里最喜欢的SSE用法是把它当成“流式HTTP响应”来看待——后端接口对外还是普通HTTP服务前端请求时它立即返回200然后分块把数据推下来。这样对网关、负载均衡、日志系统都是完全透明的运维成本非常低。3.2 事件流格式data、id、event、retrySSE的传输格式有明确的规范定义在HTML5标准里。最简单的SSE流示例长这样HTTP/1.1 200 OK Content-Type: text/event-stream Cache-Control: no-cache Connection: keep-alive data: 这是第一行数据 data: 这是第二行数据 data: 这是第二行数据的续行每一段事件数据用空行分隔每行以字段名加冒号开头。最常用的几个字段data: 数据内容。如果同一事件有多行data客户端会按换行符拼接浏览器EventSource会自动处理。event: 事件类型。默认是message可以自定义前端用addEventListener监听对应类型。id: 事件ID。客户端重连时会把Last-Event-ID头带回去服务端可以借此实现断点续传。retry: 重连时间毫秒告诉浏览器断线后多久重试一次。还有一类特殊行以冒号开头这是注释行。服务端定期发一条: keep-alive的注释可以防止某些代理服务器因为长时间无数据而中断连接。很多大模型API的流式响应格式本质上就是SSE。以OpenAI兼容格式为例每个事件的数据部分是一个JSON字符串大致长这样data: {id:chatcmpl-xxx,object:chat.completion.chunk,choices:[{delta:{content:你好},index:0}]} data: {id:chatcmpl-xxx,object:chat.completion.chunk,choices:[{delta:{content:},index:0}]} data: [DONE]注意这里是每行data带一个JSON最后用data: [DONE]标记流结束。客户端要做的就是逐行读取data解析JSON把delta里的content字段拼起来展示。3.3 SSE vs WebSocket vs 普通HTTP一张表看懂区别很多人在做技术选型时会纠结大模型流式输出到底该用SSE还是WebSocket。我把它们放到一张表里对比维度SSEWebSocket普通HTTP一次性响应协议基础HTTPWS/WSS独立协议HTTP通信方向单向服务端→客户端全双工一次性请求-响应连接建立普通HTTP请求握手成本低101切换协议额外握手普通HTTP请求浏览器兼容现代浏览器原生支持原生支持原生支持自动重连内置需自己实现无消息格式文本标准化格式文本/二进制皆可文本/二进制皆可服务端实现简单复用HTTP栈需处理连接态、帧处理最简单适合场景服务端单向推送大模型输出双向实时交互聊天室、游戏、协同编辑普通API请求大模型流式输出这个场景本质是“模型一直说用户偶尔打断”的单向推送SSE的优势非常明显实现成本低不需要额外维护连接状态也不存在跨域握手那种麻烦虽然SSE也有跨域限制但比WebSocket的跨域处理简单一些。不过SSE在Agent场景下有个天然短板如果用户想中途打断模型生成比如点“停止生成”按钮SSE本身没定义客户端主动发送控制消息的机制。实际项目中我们一般会另外提供一个普通的POST接口给前端调用来触发中断后端收到中断请求后主动掐断SSE流。这个设计后面细说。4. 实战把LLM流式输出接入你的应用4.1 环境约定与整体架构在动手写代码之前先梳理一下我们接下来的实验环境。这里我会用一套当前主流的开源技术栈来做示例后端框架Python FastAPI现代LLM应用里非常常见异步支持好天然适合流式输出。模型接入OpenAI兼容格式的API市面上大部分模型APIAzure OpenAI、DeepSeek、通义千问、Moonshot等都兼容这个格式。本地部署也可以用vLLM、Ollama等自建推理服务。前端用原生JavaScript演示方便你理解EventSource的本质不受框架约束。整体架构可以用一句话概括前端通过HTTP请求后端后端保持连接并流式转发模型API的SSE数据前端按事件逐行解析渲染。这种模式下后端充当了一个“流式代理”的角色。前端不直接对接模型API好处很多可在中间做鉴权、记日志、做业务加工还避免把模型API Key泄露给前端。4.2 后端实现FastAPI接入模型流式接口后端最核心的一件事就是把模型API返回的SSE流“透传”给前端。FastAPI里可以用StreamingResponse来实现代码非常简洁。先看一个最简版from fastapi import FastAPI from fastapi.responses import StreamingResponse import httpx app FastAPI() MODEL_API_URL https://api.example.com/v1/chat/completions MODEL_API_KEY your-api-key app.post(/v1/chat/stream) async def chat_stream(prompt: str): # 向模型API发起流式请求 headers { Authorization: fBearer {MODEL_API_KEY}, Content-Type: application/json } payload { model: gpt-4o-mini, messages: [{role: user, content: prompt}], stream: True # 关键开启流式 } async def event_generator(): async with httpx.AsyncClient(timeout60) as client: async with client.stream( POST, MODEL_API_URL, jsonpayload, headersheaders ) as response: async for line in response.aiter_lines(): if line.startswith(data: ): yield line \n\n return StreamingResponse( event_generator(), media_typetext/event-stream, headers{ Cache-Control: no-cache, X-Accel-Buffering: no, # 关闭Nginx缓冲很重要 } )这段代码做了四件事接收前端的POST请求组织给模型API的请求参数特别注意stream: True必须打开。用httpx.AsyncClient.stream向模型API发起流式请求这样后端不会等模型全部生成完才开始处理而是边接收边转发。逐行读取SSE响应判断数据行是否以data:开头如果是就原样转发给前端。用StreamingResponse把生成器包装成HTTP流式响应指定media_typetext/event-stream。这里有个极其重要的细节我必须用单独一段来强调有些模型API流式返回的数据行可能不会以data:开头。比如有些推理服务会在正式数据前发一个retry: 10000或者冒号注释行OpenAI兼容格式在流结束时还会发送data: [DONE]。你的后端转发逻辑不要死板地只认data:否则可能会漏掉结束标记。一般我建议直接把所有收到的行整体组织成SSE格式转发只在需要加工时针对性地解析data行。4.3 前端实现EventSource与fetch的取舍前端接SSE最省事的方案是浏览器原生的EventSourceconst eventSource new EventSource(/v1/chat/stream?prompt你好); eventSource.onmessage (event) { // event.data 就是服务端推过来的数据 const data JSON.parse(event.data); if (data.choices data.choices[0].delta data.choices[0].delta.content) { appendToChat(data.choices[0].delta.content); } }; eventSource.onerror (e) { // EventSource 会自动重连 console.error(SSE连接出错, e); };但这里有一个非常常见的坑EventSource只能发GET请求不支持自定义Header。这在鉴权场景下很麻烦——如果前端需要带一个Authorization头去请求后端接口用原生EventSource是做不到的。我当时的解决方案是换成fetchReadableStream手动解析async function streamChat(prompt) { const response await fetch(/v1/chat/stream, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${getUserToken()}, }, body: JSON.stringify({ prompt }), }); if (!response.ok || !response.body) { throw new Error(请求失败); } 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事件 const events buffer.split(\n\n); buffer events.pop(); // 最后一段可能不完整保留 for (const event of events) { const dataLines event .split(\n) .filter((line) line.startsWith(data:)) .map((line) line.slice(5).trim()); if (dataLines.length 0) continue; const data dataLines.join(\n); if (data [DONE]) return; const json JSON.parse(data); const delta json.choices?.[0]?.delta?.content; if (delta) appendToChat(delta); } } }这段手动解析代码有几点值得注意用TextDecoder(utf-8, { stream: true })解码应对中文字符可能被拆散在多个chunk里导致乱码的问题。SSE事件以空行分隔但网络传输时数据可能被任意切分所以要用buffer把不完整的事件暂存起来等下一批数据到达后再拼接。data行的解析要处理“一个事件多行data”的情况按协议规范用换行符拼接。[DONE]标记是很多模型API发送结束信号的约定方式收到后就应该结束循环。4.4 LangChain与Agent场景流式输出怎么配合工具调用如果你的应用不是直接调用模型API而是用LangChain或Agent框架流式输出的处理会稍微复杂一些。因为Agent在推理过程中会穿插工具调用比如先查数据库、再调外部API、再总结回答整个链路是“模型生成 → 工具调用 → 模型再生成”的循环。LangChain 2.0以后提供了基于stream_events的流式回调机制可以在不同环节产生不同事件。实际项目里我是这样处理的from langchain_openai import ChatOpenAI from langchain.agents import create_openai_tools_agent async for event in agent.astream_events(inputs, versionv2): kind event[event] if kind on_chat_model_stream: chunk event[data][chunk] if chunk.content: # 转成SSE格式推给前端 yield fdata: {json.dumps({type: token, content: chunk.content})}\n\n elif kind on_tool_start: tool_name event[name] yield fdata: {json.dumps({type: tool_start, tool: tool_name})}\n\n elif kind on_tool_end: output event[data][output] yield fdata: {json.dumps({type: tool_end, output: str(output)[:200]})}\n\n这种做法的核心思路是把Agent的各个阶段事件都封装成SSE的自定义事件类型前端可以据此展示不同的UI反馈——比如模型生成时显示打字机画面工具调用时显示“正在查询数据库”的Loading提示切换不同的卡片让用户看到Agent每一步在干什么而不是只看到一段干巴巴的最终回答。Agent场景下还要特别小心一个问题工具调用的中间结果往往很长比如数据库查询返回了几百行记录直接塞进prompt会让上下文变得很大拖慢后续生成速度也可能导致超时。这种情况下要么对工具输出做截断要么在进入下一个模型调用前设置一个较长的空闲超时时间并且用注释行: keep-alive保持SSE连接不断开。4.5 Dify等低代码平台的流式配置如果不想从头写后端用Dify这类LLM应用平台也能配置流式输出。在Dify里模型配置界面有一个“流式响应”的开关开启后Dify的应用API会自动把模型输出以SSE格式推送给前端。它的前端SDKdify/webapp-sdk内置了SSE解析逻辑接入时基本不需要关心底层协议。但配置文件里真正需要留意的是推理超时和节点超时参数。做过一次排查Dify工作流里加了多个模型节点整体执行时间超过30秒SSE连接在中间就被服务端掐断了。这种情况要把对应节点的超时时间调大并且确认网关层Nginx、Cloudflare等不会因为“空闲时间过长”断开连接。低代码平台的流式输出适合快速验证产品原型但如果要做深度定制比如自定义鉴权、Agent多工具流式展示、精细的token计数还是建议自己写后端可控性高得多。5. 关键避坑点SSE鉴权、超时与中间层缓冲5.1 SSE鉴权怎么做才安全搜索引擎热词里专门有一条“sse鉴权”确实SSE鉴权是大家最容易踩坑的地方。核心难点在于EventSource不支持自定义Header传统的Authorization头解决方案在原生SSE里行不通。实践中我有三套方案按推荐程度排序方案一一次性Token放在URL Query参数里推荐const token await fetch(/api/sse-token).then(r r.json()); const eventSource new EventSource(/v1/chat/stream?token${token.value});服务端在返回SSE流之前校验URL里的token校验通过才开始推送。关键点是这个token必须是短期有效的一次性凭证比如有效期30秒或只能使用一次防止URL泄露后被恶意重放。生成token的接口本身走正常的Authorization鉴权。方案二用fetch替代EventSource自定义Header就是我前面展示过的用fetchReadableStream手动解析请求头里正常带Authorization。这种方式不依赖EventSource所以不受Header限制是我在生产环境用得最多的方案。方案三先鉴权拿Cookie再用SSE如果后端和前端同域在SSE连接建立前先去鉴权接口登录服务端下发HttpOnly Cookie然后EventSource请求的时候浏览器会自动带上Cookie服务端校验Cookie完成鉴权。但注意SSE要处理跨域的话withCredentials必须设为true而且服务端要正确配置CORS跨域允许的Cookie凭据。另外无论哪种方案我强烈建议给SSE流式接口的对外暴露设置一层“API网关鉴权”比如在Nginx层做IP白名单限制或者在API网关配置访问凭证防止接口被未授权方以流式方式抓取数据。5.2 before completion: idle timeout waiting for sse的真相这个错误在搜索热词里直接出现了很有代表性。它看起来像是模型那边报的错实际上是网关或代理层的空闲超时导致的。大模型推理时间较长在一次流式请求中模型端可能持续几秒到几十秒没有生成新的token比如在思考、在等待工具调用结果此时连接上没有任何数据流过去。网关如果配置了“空闲超时”idle timeout以为连接死了就会主动切断于是报出idle timeout waiting for sse。从根本上解决这个问题需要从三个层面排查服务端持续发送心跳注释行。SSE规范里的冒号注释行就是为了应对这个场景。后端在转发生成器的循环里可以加一个定时器每隔15秒发一个: keep-alive\n\n告诉网关“连接还活着”。import asyncio async def event_generator(): last_activity asyncio.get_event_loop().time() while True: try: # 从模型流中取数据伪代码 chunk await model_stream.__anext__() yield fdata: {chunk}\n\n last_activity asyncio.get_event_loop().time() except StopAsyncIteration: break except asyncio.TimeoutError: current_time asyncio.get_event_loop().time() if current_time - last_activity 15: yield : keep-alive\n\n last_activity current_time调整网关超时配置。Nginx层面主要看proxy_read_timeout默认60秒对大模型场景不够建议调到300秒以上。如果是Kubernetes Ingress对应的是nginx.ingress.kubernetes.io/proxy-read-timeout。location /v1/chat/stream { proxy_pass http://backend; proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_buffering off; proxy_cache off; proxy_set_header Connection ; http_version 1.1; chunked_transfer_encoding off; }关闭中间层缓冲。这个问题极其隐蔽。Nginx默认会开启proxy_buffering它会帮你把后端返回的数据攒到一定量再一次性发给客户端。流式输出在这种配置下会变成“半天蹦一句”体验极差。解决办法是在Nginx关闭缓冲或者在后端响应头里加X-Accel-Buffering: noNginx认这个头看到后会自动关闭缓冲。我在前面FastAPI代码里已经加上了字段来源就在这里。Cloudflare这类CDN也会有类似的缓冲行为需要在缓存规则里对SSE接口做例外处理或者使用Content-Type: text/event-stream来触发CDN的流式直传逻辑。有些CDN对SSE有特殊优化但默认配置往往还是走缓冲这一点很容易被忽略。5.3 字符编码与乱码中文流式输出为什么出现豆腐块做中文大模型应用时一个高频问题是流式输出过程中出现乱码或者某个字显示成“”。根本原因在于网络传输是按字节流处理的而一个中文字符在UTF-8编码下占3个字节。SSE的数据在传输时TCP层会按任意大小切分一个中文字符的3个字节可能被拆到两个TCP包甚至是两个chunk里。前端如果直接对每个chunk做字节到字符串的解码就会把一个完好的中文字符截断导致乱码。解决方案就是在4.3节那段代码里写到的用TextDecoder的{ stream: true }模式进行增量解码。TextDecoder会内部缓存未完成的字节序列等后续字节到达后自动补全输出正确的字符串。这个参数必须设置否则默认的非流式模式会直接丢弃无法解码的字节照样乱码。用Python写后端转发时也会碰到类似问题。httpx的aiter_bytes()和aiter_lines()行为不太一样。aiter_lines()内部已经做了流式解码所以基于行的转发不容易出现中文截断问题。但如果你用aiter_bytes()自己做分片逻辑就要格外小心编码处理最好还是直接基于行来操作。5.4 SSE事件多行data的拼接陷阱按照SSE规范一个事件可以包含多行data字段这多行内容最终会被连接成一个字符串行与行之间用换行符拼接。很多大模型API在返回超长内容时会在内部把数据拆成多行data发出来。后端如果简单粗暴地“遇到一行data就转发一次”前端就会出现莫名其妙的断行。前端手动解析SSE时必须遵守规范先按空行切分事件再把每个事件内的所有data行取出来用\n拼接成一个完整的数据体最后再解析JSON或直接作为文本输出。我见过不止一个团队因为没按这个规范做导致流式输出在长回复情况下频繁断句、JSON解析报错。5.5 常见问题速查表现象根本原因解决方案页面等很久才出第一句话中间层缓冲或后端没有做流式转发关闭Nginx/CDN缓冲检查后端是否真正流式转发报idle timeout waiting for sse网关空闲超时模型端长时间无输出调大超时、加心跳注释行、关闭缓冲中文乱码/豆腐块UTF-8多字节字符被chunk截断TextDecoder流式解码后端按行转发EventSource带不了Authorization头原生EventSource不支持自定义Header用fetchReadableStream手动解析或一次性Token方案流式输出到一半突然中断服务端异常、请求超时或连接被掐检查服务端日志看是否异常退出调大超时增加重连机制收到[DONE]后页面还在转圈前端没有正确处理结束标记收到[DONE]后立即结束解析并关闭加载状态Agent工具调用环节卡顿工具执行耗时超过SSE连接的空闲时间工具调用期间发送心跳注释调大超时或把工具调用状态单独推给前端长上下文下响应越来越慢上下文过大模型端每次预计算耗时增长做上下文压缩/截断或用支持长上下文的模型版本6. 生产环境落地的三点心得整个接入过程中我自己踩坑最多也最有收获的几个点最后集中提一下第一个是关于“流式输出是否真的有必要”的判断。如果你的应用是异步批量处理场景比如生成日报后发邮件通知用户不关心中间过程那完全没必要用SSE普通接口反而更合适。流式输出适合交互式场景——聊天机器人、Copilot、人工审核辅助、代码自动补全等用户需要实时看到模型“正在做什么”这不仅仅是体验问题更是信任问题看到内容在滚动用户会认为系统没有卡死。第二个是关于“可测试性”的重要性。SSE的调试比普通HTTP接口麻烦很多我建议给后端流式接口预留一个“非流式兼容模式”加个?streamfalse参数返回一次性JSON。这样在本地开发、写接口文档、做自动化测试时直接用普通HTTP工具就能验证逻辑不用非逼着每个开发都去SSE调试器里干活。生产环境默认开流式测试接口用非流式两套跑通互不干扰。第三个是关于“降级”方案。虽然SSE是大模型应用的主流方案但它在复杂网络环境下确实存在连接不稳定、被企业防火墙截断等风险。我在生产环境做了一个自动降级机制前端如果发现SSE连接5秒内没有收到任何数据自动切换为轮询模式——每隔3秒向后端查一次“有新的输出没”后端把最近的流式输出缓存在内存里支持按偏移量增量拉取。这样在最坏情况下用户体验会退化但不会完全不可用。这套降级逻辑代码量不大但对可用性的提升非常明显。最后说一句流式输出这件事原理不难难的是把链路里所有的“隐性风险点”都排查干净。网关超时、缓冲关闭、字符编码、鉴权方案、连接保活每一个环节都可能让流式输出变成“假流式”或“坏流式”。希望这篇文章能把你在LLM流式接入这条路上可能踩的坑提前标记出来。 大模型流式输出与SSE实战：从原理到避坑指南
1. 流式输出为什么大模型应用都在抢这“几百毫秒”我先从一个真实场景说起。当时团队接入某个大模型问答服务测试时发现接口响应要等4到5秒才出第一个字最离谱的一次整个请求直接报了个idle timeout waiting for sse页面白屏用户把浏览器刷新了三遍。排查到最后发现问题不只在网关超时配置更深层的原因是我们把一次大模型请求当成了普通HTTP接口来处理——等模型推理完整个回复才一次性返回给前端。这就是不懂流式输出要付出的代价。LLMLarge Language Model大语言模型的推理逻辑是逐token生成的。你在对话框里问一句“今天上海天气怎么样”模型不是一次性把整句话算出来而是先算出“今”再算出“天”再往后推“上”“海”“天”“气”每一步都要借助前面已经生成的token做条件概率计算。这个过程在模型端天生就是“边推理边产出”的。但如果你用传统HTTP请求模式服务端会一直等模型算完最后一个token才把完整文本拼成一个字符串返回。问题立刻暴露出来了模型回复越长用户等待时间越长。一次生成800字的回答模型端耗时可能就要8到10秒用户盯着空白页面心里已经开始骂产品经理了。流式输出要解决的核心问题就是把这8到10秒的“静默等待”拆分成一个又一个token的“即时到达”。用户看到的是类似打字机效果第一个字不到1秒就出现在屏幕上后续内容持续滚动刷新。这不是什么炫技而是大模型应用的基本体验门槛。现在市面上的主流方案里SSEServer-Sent Events服务端推送事件是出镜率最高的一种。很多大模型API的流式接口、LangChain的流式回调、Dify里的流式响应配置底层都是走SSE。它不像WebSocket那样需要建立额外连接、做单独的协议协商而是建立在HTTP协议之上服务端把数据以特定格式“一段一段”推给客户端前端用几行代码就能接住。但SSE看起来简单实际踩坑的地方相当多。比如网关超时、缓冲被吞、EventSource不支持自定义Header、流式上下文里的SSE鉴权怎么做、Agent场景下多轮工具调用怎么保持流式输出不断……这些问题我在项目里一个不落全遇到了。这篇文章就把流式输出和SSE从原理到实战完整梳理一遍给正在做LLM应用接入的朋友一份可以直接抄作业的参考。2. 大模型推理链路先看懂token是怎么“蹦”出来的2.1 模型端到应用端一次完整的流式旅程要理解流式输出得先知道一次请求从头到尾经过了哪些环节。以目前最常见的架构为例大模型应用一般分三层模型端推理端负责真正跑模型推理把用户输入丢给模型模型逐token吐结果。这里说的推理服务可能是一台GPU服务器上的vLLM、TGI、SGLang也可能是云端托管的模型API。应用后端你的业务代码所在的地方负责接收前端请求、调用模型API、处理业务逻辑。LLM应用框架如LangChain、LlamaIndex以及Dify、FastGPT这类平台都跑在这一层。前端浏览器、小程序或者App界面负责把模型输出渲染给用户看。流式输出要做的事情就是把模型端已经“逐token产出”的特性贯穿到前端去。理想状态下模型端每生成一个token就立刻把数据传给应用后端后端再转发给前端前端立即渲染出来。但现实往往没这么美好。如果你的应用后端直接把完整响应攒到最后才返回那模型端的流式能力就被白白浪费了。这也是很多人调了SSE接口却发现前端还是一下子收到全部内容的原因——数据可能被某个中间环节缓存住了或者后端代码压根没做流式转发。2.2 token、缓冲与采样推理端的“打字机”速度有人可能会问为什么模型不能几毫秒内一次性输出全部内容答案是做不到也不应该这样做。大模型的生成过程本质上是自回归autoregressive。模型根据已有的token序列预测下一个token的概率分布采样得到一个token然后把它拼接到序列末尾再预测下一个。每一步都要做一次神经网络前向计算。虽然现代推理引擎做了很多优化比如KV Cache、连续批处理但生成一个token仍然需要时间一般在几十毫秒到几百毫秒之间。以GPT-4o这类模型为例输出速度大约在每秒100多个token。一次生成500字的回复中文字符约等于500到800个token在模型端就需要5到8秒。如果按传统HTTP请求用户要白等这么久。但如果做流式输出按下回车后大约1秒内就能看到第一个token后面每秒钟都有新内容陆续出现用户的感知完全不同。这中间还有个容易被忽略的点采样策略。模型生成token时存在随机性temperature参数越高生成越随机同时还有top_p、top_k等采样参数。这些参数影响的是token的多样性不影响流式输出的机制本身。但在工程上要留意有些推理服务和流式输出组合在一起时会出现一个现象如果采样参数设置不当模型可能一直在“思考”或者说生成空token流式接口半天不吐内容。遇到这种情况先排查采样参数再看推理服务的空闲超时配置。2.3 从轮询到长连接流式技术选型的来龙去脉流式输出在大模型时代才火起来但“服务端持续向客户端推送数据”这个需求其实早就存在。早期网页聊天室、股票行情、实时通知都在用各种手段解决这个问题。技术选型大体经历了几个阶段轮询Polling前端每隔几秒发一次普通HTTP请求问服务端“有新数据了吗”。实现简单但浪费带宽实时性差。大模型场景下如果每秒轮询一次对服务端压力不小而且每次请求都有网络开销token的实时到达效果也不好。长轮询Long Polling服务端收到请求后先挂起有数据了再响应。比普通轮询实时性好一些但每次响应后连接都要重建仍有较大的协议开销。WebSocket全双工长连接客户端和服务端可以互相推送消息。实时性最好但它是一个独立的协议需要额外握手服务端部署要考虑连接状态管理、心跳保活、断线重连等复杂问题。对于“主要让服务端单向推送”的大模型输出场景来说属于杀鸡用了牛刀。SSEServer-Sent Events基于HTTP的单向推送协议服务端可以持续向客户端发送事件。它不需要额外握手天然复用HTTP基础设施实现成本低。在大模型流式输出这个场景里SSE几乎是先天契合的——模型输出的方向是单向的服务端到客户端而SSE正好就是专为这种单向推送设计的轻量级方案。这也是今天绝大多数LLM API选择SSE作为流式协议的根本原因。3. SSE协议深度拆解一个被低估的HTTP“半成品”3.1 一次握手持续推送SSE的工作模型SSE全称是Server-Sent Events它的核心思想很朴素客户端发一个普通的HTTP请求但服务端不立刻结束这个响应而是在同一个HTTP连接上持续不断地把数据以特定格式推送给客户端。打个比方普通HTTP响应就像点外卖——你下单商家做好一次性全部送过来SSE则像在餐厅点了一份现做现上的菜——你下单后厨房做好一道菜服务员就先端一道上来后厨继续做做好再端直到上完为止。整个过程中你客户端和餐厅服务端只建立了“一次”联系但东西是分多次送过来的。这种模式下有几个关键特点连接复用一次HTTP请求对应一个持久连接不需要像WebSocket那样额外握手升级协议。文本协议SSE传输的是字符串格式的数据有特定的事件格式规范后面会详细讲。自动重连浏览器的EventSource接口内置了断线重连机制连接异常断开后能自动恢复。单向推送只能服务端向客户端推客户端不能通过这个连接往回发数据。如果需要双向通信得另想办法比如每个流式请求用独立的SSE连接或者混用WebSocket。我在实际项目里最喜欢的SSE用法是把它当成“流式HTTP响应”来看待——后端接口对外还是普通HTTP服务前端请求时它立即返回200然后分块把数据推下来。这样对网关、负载均衡、日志系统都是完全透明的运维成本非常低。3.2 事件流格式data、id、event、retrySSE的传输格式有明确的规范定义在HTML5标准里。最简单的SSE流示例长这样HTTP/1.1 200 OK Content-Type: text/event-stream Cache-Control: no-cache Connection: keep-alive data: 这是第一行数据 data: 这是第二行数据 data: 这是第二行数据的续行每一段事件数据用空行分隔每行以字段名加冒号开头。最常用的几个字段data: 数据内容。如果同一事件有多行data客户端会按换行符拼接浏览器EventSource会自动处理。event: 事件类型。默认是message可以自定义前端用addEventListener监听对应类型。id: 事件ID。客户端重连时会把Last-Event-ID头带回去服务端可以借此实现断点续传。retry: 重连时间毫秒告诉浏览器断线后多久重试一次。还有一类特殊行以冒号开头这是注释行。服务端定期发一条: keep-alive的注释可以防止某些代理服务器因为长时间无数据而中断连接。很多大模型API的流式响应格式本质上就是SSE。以OpenAI兼容格式为例每个事件的数据部分是一个JSON字符串大致长这样data: {id:chatcmpl-xxx,object:chat.completion.chunk,choices:[{delta:{content:你好},index:0}]} data: {id:chatcmpl-xxx,object:chat.completion.chunk,choices:[{delta:{content:},index:0}]} data: [DONE]注意这里是每行data带一个JSON最后用data: [DONE]标记流结束。客户端要做的就是逐行读取data解析JSON把delta里的content字段拼起来展示。3.3 SSE vs WebSocket vs 普通HTTP一张表看懂区别很多人在做技术选型时会纠结大模型流式输出到底该用SSE还是WebSocket。我把它们放到一张表里对比维度SSEWebSocket普通HTTP一次性响应协议基础HTTPWS/WSS独立协议HTTP通信方向单向服务端→客户端全双工一次性请求-响应连接建立普通HTTP请求握手成本低101切换协议额外握手普通HTTP请求浏览器兼容现代浏览器原生支持原生支持原生支持自动重连内置需自己实现无消息格式文本标准化格式文本/二进制皆可文本/二进制皆可服务端实现简单复用HTTP栈需处理连接态、帧处理最简单适合场景服务端单向推送大模型输出双向实时交互聊天室、游戏、协同编辑普通API请求大模型流式输出这个场景本质是“模型一直说用户偶尔打断”的单向推送SSE的优势非常明显实现成本低不需要额外维护连接状态也不存在跨域握手那种麻烦虽然SSE也有跨域限制但比WebSocket的跨域处理简单一些。不过SSE在Agent场景下有个天然短板如果用户想中途打断模型生成比如点“停止生成”按钮SSE本身没定义客户端主动发送控制消息的机制。实际项目中我们一般会另外提供一个普通的POST接口给前端调用来触发中断后端收到中断请求后主动掐断SSE流。这个设计后面细说。4. 实战把LLM流式输出接入你的应用4.1 环境约定与整体架构在动手写代码之前先梳理一下我们接下来的实验环境。这里我会用一套当前主流的开源技术栈来做示例后端框架Python FastAPI现代LLM应用里非常常见异步支持好天然适合流式输出。模型接入OpenAI兼容格式的API市面上大部分模型APIAzure OpenAI、DeepSeek、通义千问、Moonshot等都兼容这个格式。本地部署也可以用vLLM、Ollama等自建推理服务。前端用原生JavaScript演示方便你理解EventSource的本质不受框架约束。整体架构可以用一句话概括前端通过HTTP请求后端后端保持连接并流式转发模型API的SSE数据前端按事件逐行解析渲染。这种模式下后端充当了一个“流式代理”的角色。前端不直接对接模型API好处很多可在中间做鉴权、记日志、做业务加工还避免把模型API Key泄露给前端。4.2 后端实现FastAPI接入模型流式接口后端最核心的一件事就是把模型API返回的SSE流“透传”给前端。FastAPI里可以用StreamingResponse来实现代码非常简洁。先看一个最简版from fastapi import FastAPI from fastapi.responses import StreamingResponse import httpx app FastAPI() MODEL_API_URL https://api.example.com/v1/chat/completions MODEL_API_KEY your-api-key app.post(/v1/chat/stream) async def chat_stream(prompt: str): # 向模型API发起流式请求 headers { Authorization: fBearer {MODEL_API_KEY}, Content-Type: application/json } payload { model: gpt-4o-mini, messages: [{role: user, content: prompt}], stream: True # 关键开启流式 } async def event_generator(): async with httpx.AsyncClient(timeout60) as client: async with client.stream( POST, MODEL_API_URL, jsonpayload, headersheaders ) as response: async for line in response.aiter_lines(): if line.startswith(data: ): yield line \n\n return StreamingResponse( event_generator(), media_typetext/event-stream, headers{ Cache-Control: no-cache, X-Accel-Buffering: no, # 关闭Nginx缓冲很重要 } )这段代码做了四件事接收前端的POST请求组织给模型API的请求参数特别注意stream: True必须打开。用httpx.AsyncClient.stream向模型API发起流式请求这样后端不会等模型全部生成完才开始处理而是边接收边转发。逐行读取SSE响应判断数据行是否以data:开头如果是就原样转发给前端。用StreamingResponse把生成器包装成HTTP流式响应指定media_typetext/event-stream。这里有个极其重要的细节我必须用单独一段来强调有些模型API流式返回的数据行可能不会以data:开头。比如有些推理服务会在正式数据前发一个retry: 10000或者冒号注释行OpenAI兼容格式在流结束时还会发送data: [DONE]。你的后端转发逻辑不要死板地只认data:否则可能会漏掉结束标记。一般我建议直接把所有收到的行整体组织成SSE格式转发只在需要加工时针对性地解析data行。4.3 前端实现EventSource与fetch的取舍前端接SSE最省事的方案是浏览器原生的EventSourceconst eventSource new EventSource(/v1/chat/stream?prompt你好); eventSource.onmessage (event) { // event.data 就是服务端推过来的数据 const data JSON.parse(event.data); if (data.choices data.choices[0].delta data.choices[0].delta.content) { appendToChat(data.choices[0].delta.content); } }; eventSource.onerror (e) { // EventSource 会自动重连 console.error(SSE连接出错, e); };但这里有一个非常常见的坑EventSource只能发GET请求不支持自定义Header。这在鉴权场景下很麻烦——如果前端需要带一个Authorization头去请求后端接口用原生EventSource是做不到的。我当时的解决方案是换成fetchReadableStream手动解析async function streamChat(prompt) { const response await fetch(/v1/chat/stream, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${getUserToken()}, }, body: JSON.stringify({ prompt }), }); if (!response.ok || !response.body) { throw new Error(请求失败); } 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事件 const events buffer.split(\n\n); buffer events.pop(); // 最后一段可能不完整保留 for (const event of events) { const dataLines event .split(\n) .filter((line) line.startsWith(data:)) .map((line) line.slice(5).trim()); if (dataLines.length 0) continue; const data dataLines.join(\n); if (data [DONE]) return; const json JSON.parse(data); const delta json.choices?.[0]?.delta?.content; if (delta) appendToChat(delta); } } }这段手动解析代码有几点值得注意用TextDecoder(utf-8, { stream: true })解码应对中文字符可能被拆散在多个chunk里导致乱码的问题。SSE事件以空行分隔但网络传输时数据可能被任意切分所以要用buffer把不完整的事件暂存起来等下一批数据到达后再拼接。data行的解析要处理“一个事件多行data”的情况按协议规范用换行符拼接。[DONE]标记是很多模型API发送结束信号的约定方式收到后就应该结束循环。4.4 LangChain与Agent场景流式输出怎么配合工具调用如果你的应用不是直接调用模型API而是用LangChain或Agent框架流式输出的处理会稍微复杂一些。因为Agent在推理过程中会穿插工具调用比如先查数据库、再调外部API、再总结回答整个链路是“模型生成 → 工具调用 → 模型再生成”的循环。LangChain 2.0以后提供了基于stream_events的流式回调机制可以在不同环节产生不同事件。实际项目里我是这样处理的from langchain_openai import ChatOpenAI from langchain.agents import create_openai_tools_agent async for event in agent.astream_events(inputs, versionv2): kind event[event] if kind on_chat_model_stream: chunk event[data][chunk] if chunk.content: # 转成SSE格式推给前端 yield fdata: {json.dumps({type: token, content: chunk.content})}\n\n elif kind on_tool_start: tool_name event[name] yield fdata: {json.dumps({type: tool_start, tool: tool_name})}\n\n elif kind on_tool_end: output event[data][output] yield fdata: {json.dumps({type: tool_end, output: str(output)[:200]})}\n\n这种做法的核心思路是把Agent的各个阶段事件都封装成SSE的自定义事件类型前端可以据此展示不同的UI反馈——比如模型生成时显示打字机画面工具调用时显示“正在查询数据库”的Loading提示切换不同的卡片让用户看到Agent每一步在干什么而不是只看到一段干巴巴的最终回答。Agent场景下还要特别小心一个问题工具调用的中间结果往往很长比如数据库查询返回了几百行记录直接塞进prompt会让上下文变得很大拖慢后续生成速度也可能导致超时。这种情况下要么对工具输出做截断要么在进入下一个模型调用前设置一个较长的空闲超时时间并且用注释行: keep-alive保持SSE连接不断开。4.5 Dify等低代码平台的流式配置如果不想从头写后端用Dify这类LLM应用平台也能配置流式输出。在Dify里模型配置界面有一个“流式响应”的开关开启后Dify的应用API会自动把模型输出以SSE格式推送给前端。它的前端SDKdify/webapp-sdk内置了SSE解析逻辑接入时基本不需要关心底层协议。但配置文件里真正需要留意的是推理超时和节点超时参数。做过一次排查Dify工作流里加了多个模型节点整体执行时间超过30秒SSE连接在中间就被服务端掐断了。这种情况要把对应节点的超时时间调大并且确认网关层Nginx、Cloudflare等不会因为“空闲时间过长”断开连接。低代码平台的流式输出适合快速验证产品原型但如果要做深度定制比如自定义鉴权、Agent多工具流式展示、精细的token计数还是建议自己写后端可控性高得多。5. 关键避坑点SSE鉴权、超时与中间层缓冲5.1 SSE鉴权怎么做才安全搜索引擎热词里专门有一条“sse鉴权”确实SSE鉴权是大家最容易踩坑的地方。核心难点在于EventSource不支持自定义Header传统的Authorization头解决方案在原生SSE里行不通。实践中我有三套方案按推荐程度排序方案一一次性Token放在URL Query参数里推荐const token await fetch(/api/sse-token).then(r r.json()); const eventSource new EventSource(/v1/chat/stream?token${token.value});服务端在返回SSE流之前校验URL里的token校验通过才开始推送。关键点是这个token必须是短期有效的一次性凭证比如有效期30秒或只能使用一次防止URL泄露后被恶意重放。生成token的接口本身走正常的Authorization鉴权。方案二用fetch替代EventSource自定义Header就是我前面展示过的用fetchReadableStream手动解析请求头里正常带Authorization。这种方式不依赖EventSource所以不受Header限制是我在生产环境用得最多的方案。方案三先鉴权拿Cookie再用SSE如果后端和前端同域在SSE连接建立前先去鉴权接口登录服务端下发HttpOnly Cookie然后EventSource请求的时候浏览器会自动带上Cookie服务端校验Cookie完成鉴权。但注意SSE要处理跨域的话withCredentials必须设为true而且服务端要正确配置CORS跨域允许的Cookie凭据。另外无论哪种方案我强烈建议给SSE流式接口的对外暴露设置一层“API网关鉴权”比如在Nginx层做IP白名单限制或者在API网关配置访问凭证防止接口被未授权方以流式方式抓取数据。5.2 before completion: idle timeout waiting for sse的真相这个错误在搜索热词里直接出现了很有代表性。它看起来像是模型那边报的错实际上是网关或代理层的空闲超时导致的。大模型推理时间较长在一次流式请求中模型端可能持续几秒到几十秒没有生成新的token比如在思考、在等待工具调用结果此时连接上没有任何数据流过去。网关如果配置了“空闲超时”idle timeout以为连接死了就会主动切断于是报出idle timeout waiting for sse。从根本上解决这个问题需要从三个层面排查服务端持续发送心跳注释行。SSE规范里的冒号注释行就是为了应对这个场景。后端在转发生成器的循环里可以加一个定时器每隔15秒发一个: keep-alive\n\n告诉网关“连接还活着”。import asyncio async def event_generator(): last_activity asyncio.get_event_loop().time() while True: try: # 从模型流中取数据伪代码 chunk await model_stream.__anext__() yield fdata: {chunk}\n\n last_activity asyncio.get_event_loop().time() except StopAsyncIteration: break except asyncio.TimeoutError: current_time asyncio.get_event_loop().time() if current_time - last_activity 15: yield : keep-alive\n\n last_activity current_time调整网关超时配置。Nginx层面主要看proxy_read_timeout默认60秒对大模型场景不够建议调到300秒以上。如果是Kubernetes Ingress对应的是nginx.ingress.kubernetes.io/proxy-read-timeout。location /v1/chat/stream { proxy_pass http://backend; proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_buffering off; proxy_cache off; proxy_set_header Connection ; http_version 1.1; chunked_transfer_encoding off; }关闭中间层缓冲。这个问题极其隐蔽。Nginx默认会开启proxy_buffering它会帮你把后端返回的数据攒到一定量再一次性发给客户端。流式输出在这种配置下会变成“半天蹦一句”体验极差。解决办法是在Nginx关闭缓冲或者在后端响应头里加X-Accel-Buffering: noNginx认这个头看到后会自动关闭缓冲。我在前面FastAPI代码里已经加上了字段来源就在这里。Cloudflare这类CDN也会有类似的缓冲行为需要在缓存规则里对SSE接口做例外处理或者使用Content-Type: text/event-stream来触发CDN的流式直传逻辑。有些CDN对SSE有特殊优化但默认配置往往还是走缓冲这一点很容易被忽略。5.3 字符编码与乱码中文流式输出为什么出现豆腐块做中文大模型应用时一个高频问题是流式输出过程中出现乱码或者某个字显示成“”。根本原因在于网络传输是按字节流处理的而一个中文字符在UTF-8编码下占3个字节。SSE的数据在传输时TCP层会按任意大小切分一个中文字符的3个字节可能被拆到两个TCP包甚至是两个chunk里。前端如果直接对每个chunk做字节到字符串的解码就会把一个完好的中文字符截断导致乱码。解决方案就是在4.3节那段代码里写到的用TextDecoder的{ stream: true }模式进行增量解码。TextDecoder会内部缓存未完成的字节序列等后续字节到达后自动补全输出正确的字符串。这个参数必须设置否则默认的非流式模式会直接丢弃无法解码的字节照样乱码。用Python写后端转发时也会碰到类似问题。httpx的aiter_bytes()和aiter_lines()行为不太一样。aiter_lines()内部已经做了流式解码所以基于行的转发不容易出现中文截断问题。但如果你用aiter_bytes()自己做分片逻辑就要格外小心编码处理最好还是直接基于行来操作。5.4 SSE事件多行data的拼接陷阱按照SSE规范一个事件可以包含多行data字段这多行内容最终会被连接成一个字符串行与行之间用换行符拼接。很多大模型API在返回超长内容时会在内部把数据拆成多行data发出来。后端如果简单粗暴地“遇到一行data就转发一次”前端就会出现莫名其妙的断行。前端手动解析SSE时必须遵守规范先按空行切分事件再把每个事件内的所有data行取出来用\n拼接成一个完整的数据体最后再解析JSON或直接作为文本输出。我见过不止一个团队因为没按这个规范做导致流式输出在长回复情况下频繁断句、JSON解析报错。5.5 常见问题速查表现象根本原因解决方案页面等很久才出第一句话中间层缓冲或后端没有做流式转发关闭Nginx/CDN缓冲检查后端是否真正流式转发报idle timeout waiting for sse网关空闲超时模型端长时间无输出调大超时、加心跳注释行、关闭缓冲中文乱码/豆腐块UTF-8多字节字符被chunk截断TextDecoder流式解码后端按行转发EventSource带不了Authorization头原生EventSource不支持自定义Header用fetchReadableStream手动解析或一次性Token方案流式输出到一半突然中断服务端异常、请求超时或连接被掐检查服务端日志看是否异常退出调大超时增加重连机制收到[DONE]后页面还在转圈前端没有正确处理结束标记收到[DONE]后立即结束解析并关闭加载状态Agent工具调用环节卡顿工具执行耗时超过SSE连接的空闲时间工具调用期间发送心跳注释调大超时或把工具调用状态单独推给前端长上下文下响应越来越慢上下文过大模型端每次预计算耗时增长做上下文压缩/截断或用支持长上下文的模型版本6. 生产环境落地的三点心得整个接入过程中我自己踩坑最多也最有收获的几个点最后集中提一下第一个是关于“流式输出是否真的有必要”的判断。如果你的应用是异步批量处理场景比如生成日报后发邮件通知用户不关心中间过程那完全没必要用SSE普通接口反而更合适。流式输出适合交互式场景——聊天机器人、Copilot、人工审核辅助、代码自动补全等用户需要实时看到模型“正在做什么”这不仅仅是体验问题更是信任问题看到内容在滚动用户会认为系统没有卡死。第二个是关于“可测试性”的重要性。SSE的调试比普通HTTP接口麻烦很多我建议给后端流式接口预留一个“非流式兼容模式”加个?streamfalse参数返回一次性JSON。这样在本地开发、写接口文档、做自动化测试时直接用普通HTTP工具就能验证逻辑不用非逼着每个开发都去SSE调试器里干活。生产环境默认开流式测试接口用非流式两套跑通互不干扰。第三个是关于“降级”方案。虽然SSE是大模型应用的主流方案但它在复杂网络环境下确实存在连接不稳定、被企业防火墙截断等风险。我在生产环境做了一个自动降级机制前端如果发现SSE连接5秒内没有收到任何数据自动切换为轮询模式——每隔3秒向后端查一次“有新的输出没”后端把最近的流式输出缓存在内存里支持按偏移量增量拉取。这样在最坏情况下用户体验会退化但不会完全不可用。这套降级逻辑代码量不大但对可用性的提升非常明显。最后说一句流式输出这件事原理不难难的是把链路里所有的“隐性风险点”都排查干净。网关超时、缓冲关闭、字符编码、鉴权方案、连接保活每一个环节都可能让流式输出变成“假流式”或“坏流式”。希望这篇文章能把你在LLM流式接入这条路上可能踩的坑提前标记出来。