AI对话流式渲染实战：SSE、Markdown增量渲染与Nginx防粘连

1. 从“打字机”说起AI 对话流式渲染到底难在哪第一次做 AI 对话界面的人几乎都会经历同一个心理落差后端接口明明已经跑通了模型也能正常返回内容但前端体验就是“不对劲”——用户点下发送按钮之后界面要愣住好几秒然后“啪”地一下把整段回答全吐出来。这种体验放在 2023 年之前或许还能忍但放到今天用户已经被各种逐字蹦出的对话产品养刁了胃口没有打字机效果产品气质立刻就掉一个档次。所谓“打字机”效果本质上是把大模型逐 token 生成的内容实时地、连续地推送到浏览器并且边接收边渲染。听起来简单但真正落地时会发现它牵扯到一整条链路传输层用什么协议、前端怎么解析、Markdown 怎么增量渲染、代码块没闭合怎么办、网络断了怎么续、反向代理层怎么防止缓冲把流“粘”成一坨。任何一个环节没处理好打字机就会变成“卡顿机”或者“闪断机”。这篇内容就是把这整条链路拆开讲清楚。适合正在做 AI 对话产品的前后端工程师、独立开发者也适合已经上线但被“流式输出不流畅”“Markdown 渲染错乱”“Nginx 后面流不动”这些问题折磨过的同学。我会从协议选型讲到组件实现再到 Nginx 配置的坑尽量把每一步背后的“为什么”说透而不是只丢一段能跑的代码。先给一个整体判断流式对话的核心不是“流”而是“状态”。传输只是管道真正决定体验的是前端如何维护一个不断增长的、可能随时中断的、格式还不完整的文本状态。想明白这一点后面所有技术选择都会顺理成章。2. 传输层选型为什么 SSE 成了 AI 对话的默认答案2.1 SSE 与 WebSocket 的本质差异一提到“实时推送”很多人第一反应是 WebSocket。但在 AI 对话这个场景里SSEServer-Sent Events几乎是压倒性的选择。原因不在于 SSE 更“高级”而在于它和对话场景的匹配度更高。WebSocket 是全双工协议客户端和服务端可以随时互相发消息适合聊天室、协同编辑、游戏这类双向高频交互。而 AI 对话的交互模式是典型的“一问一答”客户端发一次请求服务端持续推送一段时间的响应然后结束。这是单向流用全双工协议属于杀鸡用牛刀而且 WebSocket 需要额外的握手升级、心跳保活、连接管理复杂度明显更高。SSE 则天然贴合这个模型。它基于普通 HTTP 请求服务端返回Content-Type: text/event-stream然后以特定格式持续写入数据。浏览器端的EventSource会自动处理连接、断线重连、事件分发。更关键的是SSE 走的是标准 HTTP能天然穿过大多数代理、网关和负载均衡而 WebSocket 的升级握手在某些网络环境下容易被拦截或需要额外配置。对比维度SSEWebSocket通信方向服务端到客户端单向双向全双工底层协议HTTP/HTTPS独立协议需升级握手浏览器 APIEventSource自动重连WebSocket需手动管理代理兼容性好标准 HTTP一般需配置升级头适用场景推送、流式输出、通知聊天室、协同、游戏实现复杂度低中高不过 SSE 也有它的短板最典型的就是只能单向。如果对话过程中需要客户端中途打断比如用户点“停止生成”SSE 本身没法从同一条连接发指令得另开一个 HTTP 请求去通知服务端取消。这就是热词里提到的abort场景后面会专门讲。2.2 SSE 的数据格式与解析细节SSE 的报文格式看着简单但细节不少。一个标准的事件流长这样data: {content: 你} data: {content: 好} data: {content: } event: done data: [DONE]几个关键规则必须记牢。每条消息以data:开头后面跟内容以两个换行\n\n作为消息结束标志。如果一条消息有多行每行都要以data:开头浏览器会自动用换行拼接。event:字段可以自定义事件类型不写默认是message。以:开头的行是注释常被用作心跳保活。这里有个新手极易踩的坑服务端写入时忘记加两个换行。只写一个\n浏览器会认为消息还没结束一直等下一个换行结果就是前端“卡住不动”但网络面板里明明有数据在传。我见过不止一个团队在这上面耗掉半天。另一个坑是中文编码。SSE 默认按 UTF-8 解析如果服务端用了其他编码或者手动拼接字符串时把多字节字符截断了就会出现乱码。尤其是按字节流分片推送时一个中文字符占 3 个字节如果分片点正好落在字符中间前端就会收到半个字符。稳妥的做法是服务端按完整字符或完整 JSON 对象推送不要按字节切。2.3 前端 EventSource 与 fetch 流式读取的取舍浏览器原生提供了EventSource用起来很省心const es new EventSource(/api/chat?qhello); es.onmessage (e) { appendText(e.data); }; es.onerror () { // 自动重连但需要处理重复数据 };但它有两个硬伤。第一EventSource只支持 GET 请求没法带复杂的 POST body而对话内容往往很长塞进 URL 不现实。第二它的自动重连是“无脑重连”会把请求从头再发一遍导致重复内容。所以实际项目里更多人选择用fetchReadableStream手动读取const controller new AbortController(); const resp await fetch(/api/chat, { method: POST, body: JSON.stringify({ q }), signal: controller.signal, }); const reader resp.body.getReader(); const decoder new TextDecoder(); let buffer ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const parts buffer.split(\n\n); buffer parts.pop(); // 最后一段可能不完整留到下次 for (const part of parts) { const line part.replace(/^data:\s*/, ); if (line [DONE]) return; appendText(JSON.parse(line).content); } }这段代码里有三个关键点值得展开。decoder.decode(value, { stream: true })的stream: true参数是为了处理多字节字符跨分片的问题它会缓存不完整的字节序列等下一个分片到了再一起解码。buffer的存在是为了处理“一个 SSE 消息被拆到两个网络分片”的情况必须把最后一段不完整的留在缓冲区。AbortController则是实现“停止生成”的关键调用controller.abort()就能中断请求服务端也能感知到连接断开。提示用 fetch 流式读取时务必确认响应头里没有Content-Encoding: gzip之类的压缩否则浏览器会缓冲整个响应再解压流式效果直接消失。如果 Nginx 开了 gzip记得对text/event-stream关闭。3. Markdown 增量渲染流式场景下最容易被低估的难点3.1 为什么不能“收完再渲染”很多人第一版实现是这样的流式接收文本先原样显示纯文本等[DONE]之后再整体做一次 Markdown 渲染。这个方案能跑但体验很割裂——用户看着一堆**和#符号蹦出来最后才“变”成漂亮的格式观感很差。正确的做法是边接收边渲染但这里立刻会遇到一个数学问题Markdown 是上下文相关的语法而流式文本是“半成品”。比如**加粗只写了一半代码块还没闭合表格只写了表头没有分隔行。如果每收到一个字符就重新解析整段 Markdown不仅性能差还会出现“格式反复横跳”的闪烁。3.2 增量渲染的三种主流策略实际项目里处理这个问题大致有三种思路各有取舍。第一种是节流全量重渲染。维护一个完整的文本字符串每收到新内容就更新但渲染用节流控制比如每 50ms 或每积累 10 个字符才重新解析一次整段 Markdown。实现最简单兼容性最好缺点是长对话时每次都要重新解析全文性能会随文本增长而下降。对于几千字的回答这个方案完全够用。第二种是分块渲染。把文本按段落或按代码块边界切分已经“闭合”的块做一次渲染并缓存只有最后一块可能不完整每次重新渲染。这样大部分内容只解析一次性能好很多。难点在于如何判断“块边界”通常以空行、代码块围栏、标题行为界。第三种是AST 增量更新。用 Markdown 解析器生成语法树新内容只更新树的相关节点再 diff 到 DOM。性能最好但实现复杂度极高一般只有大型产品才会这么做。对绝大多数项目我的建议是节流全量重渲染 代码块特殊处理。先用简单方案跑通等真的遇到性能瓶颈再优化。过早优化是流式渲染里最常见的浪费。3.3 未闭合语法的兜底处理流式渲染最烦人的就是“半截语法”。用户看到**重要后面还没闭合如果直接渲染加粗不会生效星号会裸露出来如果等闭合再渲染又会有延迟感。几种常见处理方式代码块检测到奇数个时自动在末尾补一个闭合围栏再渲染这样代码块能正常显示等真正闭合时再重渲染。加粗/斜体可以容忍短暂裸露或者用正则临时补全。实测下来用户对加粗符号的裸露容忍度较高不必过度处理。表格表格必须有分隔行才能渲染流式过程中表头先到、分隔行后到中间会有一段“表格没成型”的时间。可以检测到表格起始后先按纯文本显示等分隔行到了再切换成表格。链接和图片[文字](url这种半截链接建议先按纯文本显示等)到了再渲染否则会生成错误的链接。function safeRender(md) { // 补全未闭合的代码块 const fenceCount (md.match(//g) || []).length; if (fenceCount % 2 1) { md \n; } return marked.parse(md); }注意补全只是“渲染时的临时手段”原始文本状态必须保持原样否则等真正闭合时会多出一个围栏导致格式错乱。渲染用的字符串和存储用的字符串要分开。3.4 Markdown 换行与常见语法坑热词里“markdown换行”出现频率很高这确实是个高频坑。标准 Markdown 里单个换行不会产生br需要两个空格加换行或者空一行分段。但大模型输出的文本经常是单换行用户期望看到换行效果。解决办法是在渲染器里开启breaks: true选项marked 和 markdown-it 都支持让单换行也转成br。另一个坑是代码块里的 HTML 转义。如果直接把渲染结果用innerHTML插入代码块里的script之类内容可能被当成标签执行存在 XSS 风险。必须用 DOMPurify 之类的库做一次净化或者让渲染器默认转义 HTML。还有表格转换的问题。热词里提到“markdown表格转换excel”“markdown表格复制”说明用户有把渲染后的表格复制出去的需求。如果表格是用table渲染的复制到 Excel 时格式容易乱。一个实用技巧是给表格加>let received ; async function streamChat(q, retry 0) { try { const resp await fetch(/api/chat, { method: POST, body: JSON.stringify({ q, prefix: received }), }); // ... 读取流追加到 received } catch (e) { if (retry 3) { await sleep(1000 * (retry 1)); return streamChat(q, retry 1); } showError(连接中断请重试); } }重连要有退避策略不能一断就立刻重连否则容易把服务端打爆。常见的做法是 1s、2s、4s 递增最多重试 3 到 5 次。4.3 用 AbortController 实现“停止生成”“停止生成”按钮是 AI 对话的标配。实现上前端用AbortController中断 fetch服务端通过监听连接关闭事件来停止模型推理。Node.js 里可以监听req.on(close)Python 的 FastAPI 里可以监听request.is_disconnected()。const controller new AbortController(); stopButton.onclick () controller.abort();这里有个细节abort()之后已经接收到的内容要保留不能清空。同时要把状态标记为“已停止”避免重连逻辑误触发。另外服务端收到中断信号后应该尽快释放模型资源否则并发一高资源会被“僵尸请求”占满。提示有些模型推理框架不支持中途取消只能等它生成完。这种情况下服务端可以“假装”取消——停止向前端推送但后台继续跑完并丢弃结果。虽然浪费算力但至少用户体验是即时的。5. Nginx 防粘连反向代理层的那些坑5.1 为什么流式输出到了 Nginx 后面就“粘”住了这是最经典的问题本地开发时流式效果完美一部署到 Nginx 后面就变成“等半天然后一次性全出来”。原因几乎总是代理缓冲。Nginx 默认开启proxy_buffering它会把上游响应先攒到缓冲区攒够一定大小或响应结束才发给客户端。对于普通请求这是优化对于 SSE 就是灾难。解决办法是关闭缓冲location /api/chat { proxy_pass http://backend; proxy_buffering off; proxy_cache off; proxy_set_header Connection ; proxy_http_version 1.1; chunked_transfer_encoding off; }proxy_buffering off是核心让 Nginx 收到多少转发多少。proxy_http_version 1.1配合Connection 是为了启用长连接和分块传输。chunked_transfer_encoding off在某些版本里也需要关掉否则 Nginx 可能重新分块。5.2 超时参数必须调Nginx 默认的proxy_read_timeout是 60 秒意味着上游 60 秒没数据就断开。模型生成慢的时候很容易超。建议调大proxy_read_timeout 300s; proxy_send_timeout 300s; send_timeout 300s;但光调大还不够因为中间可能还有别的网关。更稳的做法是前面说的心跳保活让连接始终有数据流动这样即使超时设得保守也不会断。5.3 gzip 与 SSE 的冲突如果 Nginx 开了 gzip并且对text/event-stream也压缩浏览器会缓冲整个响应再解压流式效果直接消失。必须在 gzip 配置里排除 SSEgzip on; gzip_types text/plain text/css application/json; # 不要包含 text/event-stream或者更直接地在 location 里gzip off;。这个坑很隐蔽因为响应头看起来正常但前端就是收不到流。5.4 负载均衡下的会话保持如果后端是多实例SSE 连接必须保持在同一实例上否则重连时可能连到另一个实例续传逻辑就失效了。可以用ip_hash做简单会话保持upstream backend { ip_hash; server 10.0.0.1:8000; server 10.0.0.2:8000; }但ip_hash在用户切换网络时会失效。更可靠的是在应用层用会话 ID 做路由或者干脆把流式服务单独部署不走负载均衡。Nginx 配置项默认值流式场景建议值作用proxy_bufferingonoff关闭响应缓冲proxy_cache视配置off关闭缓存proxy_read_timeout60s300s延长读超时proxy_http_version1.01.1启用长连接gzip视配置对 SSE 关闭避免压缩缓冲6. 常见问题速查与实操避坑清单6.1 流式渲染问题速查表现象可能原因排查方向前端一直不动网络面板有数据SSE 消息缺少双换行检查服务端写入格式中文乱码分片截断多字节字符用 TextDecoder stream 模式部署后流式消失Nginx 缓冲或 gzip关闭 proxy_buffering 和 gzip长回答中途断开代理空闲超时加心跳调大 timeoutMarkdown 格式闪烁每字符重渲染节流 未闭合兜底重连后内容重复无续传机制带偏移量或前端去重停止按钮无效未用 AbortController中断 fetch 并通知服务端代码块显示错乱围栏未闭合渲染时临时补全6.2 我踩过的几个真实坑第一个坑是在 Nginx 里开了proxy_buffering却不知道。当时本地怎么测都正常一上测试环境就“粘”查了两天才发现是运维的默认配置。后来养成习惯凡是流式接口先在 Nginx 配置里搜一遍buffering。第二个坑是用EventSource做 POST 请求。EventSource只支持 GET硬塞长文本进 URL 会被截断而且日志里全是超长 URL。换成 fetch 流式读取后清爽多了。第三个坑是Markdown 渲染的 XSS。早期直接innerHTML结果模型输出里带了img onerror...虽然只是测试环境但吓出一身冷汗。后来统一用 DOMPurify 过滤再也没出过问题。第四个坑是重连风暴。有次服务端抖动前端所有客户端同时重连瞬间把后端打挂。后来加了随机退避和最大重试次数才稳住。6.3 性能与体验的平衡建议流式渲染的性能优化优先级应该是先保证不卡节流再保证不错未闭合兜底最后才考虑快增量 AST。很多团队一上来就追求极致性能结果复杂度爆炸bug 一堆体验反而更差。对于大多数对话产品我的经验是节流间隔 30 到 50ms 是甜点区。太快了渲染压力大太慢了打字机效果不连贯。代码块和表格做特殊处理其他语法容忍短暂裸露。重连最多 3 次超过就提示用户手动重试。最后分享一个实用小技巧在开发阶段可以在前端加一个“原始流”开关把收到的原始 SSE 数据直接打印出来。排查问题时一眼就能看出是传输层没数据还是渲染层没处理。这个开关帮我省了无数次抓包的时间。这套链路我前后迭代过好几个版本从最初的“收完再渲染”到现在的增量渲染加断线续传最大的体会是流式对话的难点从来不在某一个技术点而在于整条链路的协同。传输、解析、渲染、代理任何一环掉链子用户看到的都是同一个结果——卡。所以排查问题时一定要从最外层往里查先确认数据有没有到浏览器再确认解析对不对最后才怀疑渲染。顺序反了很容易在错误的地方浪费时间。