SSE流式传输与Markdown增量渲染：AI对话打字机效果全链路实践

1. 从逐字蹦出的观感到数据流动的真相第一次看到大模型回答像打字机一样一个字一个字往外蹦的时候我承认我盯着屏幕看了很久。那种感觉跟早年用 56K 猫下载图片时一行行刷出来的体验有点像但又不完全一样——图片是像素在填充而这里是语义在生长。后来自己动手做 AI 对话产品才发现这个打字机效果背后其实是一条相当完整的工程链路从模型侧的分片输出到传输层的流式协议再到前端渲染的增量更新最后到网关层的连接保持每一环都有它自己的脾气。这篇文章想聊的就是这条链路。核心关键词是SSE 流式传输、Markdown 增量渲染和Nginx 防粘连配置。如果你正在做 AI 对话类产品或者单纯好奇为什么我调 API 的时候是一次性返回但网页上却能一个字一个字显示那这篇内容应该能帮你把整条链路串起来。我会从协议选型讲到前端组件设计再讲到生产环境里那些让人抓狂的连接中断问题尽量把每个决策背后的为什么说清楚。需要提前说明的是打字机效果本身并不是什么高深的技术它本质上就是把一次性的大响应拆成很多个小响应让前端有机会在收到每一小段后立即更新 UI。真正难的地方在于怎么拆、用什么协议拆、拆完之后前端怎么高效地拼回去、以及在生产环境里怎么保证这条长连接不被中间层掐断。这四个问题分别对应了 SSE、EventSource、Markdown 组件和 Nginx 配置这四个技术点。2. SSE 为什么成了 AI 对话流式输出的默认选择2.1 流式传输的三种方案对比在动手之前先要决定用什么协议来传这些分片数据。市面上能实现流式输出的方案主要有三种WebSocket、SSEServer-Sent Events和基于 HTTP 的分块传输chunked transfer encoding。我一开始也纠结过要不要直接上 WebSocket毕竟它听起来更实时但实际用下来SSE 在 AI 对话这个场景里几乎是压倒性的优势。先看一张对比表把三种方案在 AI 对话场景下的表现摊开来说维度WebSocketSSEHTTP 分块传输通信方向全双工单向服务端到客户端单向协议基础独立协议需握手升级基于 HTTP基于 HTTP自动重连需自己实现浏览器原生支持需自己实现消息格式二进制/文本帧纯文本固定格式任意代理兼容性部分代理不支持兼容性好兼容性好实现复杂度高低中适用场景双向实时通信服务端推送大文件下载AI 对话的数据流向其实非常明确用户发一次请求服务端持续推送模型生成的内容客户端只需要接收不需要在这条连接上再发东西。这种单向推送的特性正好是 SSE 的主场。WebSocket 的全双工能力在这里是浪费的反而带来了额外的握手开销和代理兼容性问题。2.2 SSE 的数据格式与 EventSource 的工作机制SSE 的协议格式简单到有点朴素。服务端返回的 Content-Type 是text/event-stream然后按照固定的文本格式往连接里写数据data: {content: 你} data: {content: 好} data: {content: } data: {content: 世界}每个data:行后面跟一个换行两个换行表示一个事件结束。浏览器端的EventSource对象会自动解析这个格式每收到一个完整事件就触发一次onmessage回调。这个自动解析能力是 SSE 相比裸 HTTP 分块传输的最大优势——你不用自己处理粘包和分帧。但EventSource有个硬伤它只支持 GET 请求不能自定义请求头。这意味着你没法在请求头里带 Authorization token也没法发 POST 请求体。对于 AI 对话来说用户的消息内容通常是要放在请求体里的这就很尴尬了。我试过几种绕法。一种是把消息内容塞进 URL query 参数但长文本会超出 URL 长度限制而且把用户输入暴露在 URL 里也不安全。另一种是用 Cookie 做鉴权但跨域场景下 Cookie 的 SameSite 策略又会带来新问题。所以实际生产环境里大多数团队会选择用 fetch ReadableStream 手动实现 SSE 的解析逻辑而不是直接用 EventSource。这样既能用 POST 发请求体又能自定义请求头还能配合 AbortController 实现中断。代价就是需要自己写一个解析器处理data:前缀、事件分隔、以及跨 chunk 的粘包问题。2.3 手动解析 SSE 流的关键细节自己解析 SSE 流的时候有几个坑我踩过不止一次。第一个是跨 chunk 的粘包问题TCP 传输不保证每次read()返回的数据正好是一个完整事件很可能一个事件被切成两半或者两个事件粘在一起。所以解析器必须维护一个缓冲区每次收到新数据就追加进去然后按\n\n分割最后一段不完整的留在缓冲区里等下次。第二个坑是流结束的判定。服务端发送完所有数据后会关闭连接reader.read()会返回done: true。但有时候服务端会发送一个特殊的结束标记比如data: [DONE]前端需要识别这个标记并主动结束读取而不是傻等连接关闭。第三个坑是错误处理。流式请求中途断开是家常便饭可能是网络抖动可能是服务端超时也可能是用户主动点了停止按钮。前端需要区分这几种情况用户主动中断应该静默处理网络错误应该提示重试服务端错误应该展示具体信息。async function streamChat(message, onChunk, signal) { const response await fetch(/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message }), signal }); const reader response.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.trim(); if (!line.startsWith(data:)) continue; const data line.slice(5).trim(); if (data [DONE]) return; try { const parsed JSON.parse(data); onChunk(parsed.content); } catch (e) { console.warn(解析失败, data); } } } }这段代码看起来不复杂但decoder.decode(value, { stream: true })这个参数很关键。如果不加stream: true当多字节字符比如中文被切在两个 chunk 之间时解码会出错出现乱码。这个坑我在处理中文流式输出时遇到过排查了半天才发现是解码器的问题。3. Markdown 增量渲染从纯文本到富文本的实时转换3.1 为什么不能等流结束再渲染最朴素的做法是等整个流结束后拿到完整文本再一次性渲染 Markdown。但这样就失去了打字机效果的意义——用户要盯着空白屏幕等好几秒体验很差。所以必须边接收边渲染。但增量渲染 Markdown 有个本质困难Markdown 语法是上下文相关的。比如一个代码块用三个反引号开始必须等到下一个三个反引号才知道它在哪里结束。如果流式过程中只收到了开始标记还没收到结束标记这时候去解析就会出错。我见过几种处理策略。最简单的是只渲染已完成的块级元素遇到不完整的语法就先用纯文本显示等后续数据到了再重新解析。这种策略实现简单但会出现闪烁——一段文字先是纯文本突然变成加粗或标题视觉上不够流畅。另一种策略是维护一个安全边界只解析到最后一个确定完整的段落。具体做法是找到最后一个\n\n段落分隔符只对这部分做 Markdown 解析后面的不完整内容用纯文本追加。这样能保证已渲染的部分不会因为后续数据而改变结构。3.2 增量解析的性能陷阱即使解决了正确性问题性能也是个大坑。如果每收到一个字符就重新解析整个 Markdown 文本当回答长度到几千字时解析开销会急剧上升。我实测过一个 3000 字的回答如果每个 chunk 都全量解析CPU 占用会飙到 40% 以上页面明显卡顿。优化思路是分块缓存。把已解析的 Markdown 按段落缓存成 HTML 片段新数据到达时只解析新增的段落然后追加到结果里。但这里又有个问题Markdown 的某些语法会跨段落比如列表项之间如果空行处理不当会被解析成两个独立的列表。我的做法是维护一个解析状态机记录当前是否在代码块内、是否在列表中、是否在引用块内。新数据到达时根据当前状态决定是追加到上一个块还是开启新块。这个状态机不需要很复杂覆盖代码块、列表、引用、表格这几种常见跨行语法就够了。3.3 代码高亮的时机选择AI 回答里经常包含代码块代码高亮是刚需。但高亮库比如 highlight.js 或 Prism通常需要完整的代码文本才能正确高亮。如果代码还在流式输出中每次新增一行就重新高亮整个代码块性能会很差。我的策略是流式过程中用纯文本显示代码等代码块结束后再触发高亮。具体来说当检测到代码块的结束标记三个反引号时才把这段代码交给高亮库处理。这样用户在代码生成过程中看到的是等宽字体的纯文本代码块结束后瞬间变成带高亮的效果视觉上反而有一种完成的仪式感。如果产品对实时性要求极高也可以做增量高亮——只高亮新增的行已高亮的行不动。但这需要高亮库支持增量接口实现复杂度会高不少。对于大多数场景等代码块结束再高亮是性价比最高的方案。3.4 表格和数学公式的特殊处理Markdown 表格在流式渲染里是个麻烦事。表格的列宽需要根据所有行的内容来计算如果只收到第一行根本没法确定列宽。我的处理方式是表格在流式过程中用简单的管道分隔文本显示等表格结束后再渲染成真正的表格。这样用户至少能看到内容在生成不会觉得卡住了。数学公式LaTeX也是类似的问题。行内公式$...$需要匹配到闭合的$才能渲染行间公式$$...$$更是需要等到结束标记。流式过程中如果遇到未闭合的公式标记我会先原样显示等闭合后再交给 KaTeX 或 MathJax 渲染。这里有个细节值得注意公式的闭合标记可能跨 chunk。比如$和后面的内容被切开了解析器需要能正确处理。我的做法是在缓冲区里保留最后几个字符确保不会因为分片而漏掉闭合标记。4. Nginx 防粘连生产环境里最容易被忽视的一环4.1 流式响应为什么会被 Nginx 粘住本地开发一切正常部署到生产环境后打字机效果消失回答变成一次性全部蹦出来——如果你遇到这个现象大概率是 Nginx 在中间做了缓冲。Nginx 默认会开启proxy_buffering它会把上游服务器的响应先攒在缓冲区里攒够一定大小或者上游关闭连接后才一次性发给客户端。对于普通请求这是优化对于 SSE 流式响应这就是灾难。解决方法是针对 SSE 的 location 关闭缓冲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_cache off防止响应被缓存。proxy_http_version 1.1和Connection 的组合是为了启用 HTTP/1.1 的长连接避免每次请求都重新建立连接。4.2 超时配置idle timeout 的坑即使关了缓冲还有一个更隐蔽的坑Nginx 的默认超时时间。proxy_read_timeout默认是 60 秒意思是如果上游服务器 60 秒内没有发送任何数据Nginx 就会断开连接。对于 AI 对话来说模型生成第一个 token 的时间TTFT可能就要好几秒如果遇到复杂问题模型思考时间更长很容易触发这个超时。我遇到过最典型的现象是用户问了一个需要长推理的问题前端等了 60 秒后收到stream disconnected before completion: idle timeout waiting for sse这样的错误。排查下来就是proxy_read_timeout没调够。location /api/chat { proxy_pass http://backend; proxy_buffering off; proxy_read_timeout 300s; proxy_send_timeout 300s; send_timeout 300s; }这三个超时分别对应Nginx 读上游响应的超时、Nginx 发送请求给上游的超时、Nginx 向客户端发送响应的超时。对于 AI 对话场景我一般会把它们都设到 300 秒以上给模型足够的生成时间。4.3 负载均衡与多实例下的连接一致性当后端有多个实例时还有个问题同一个对话的流式请求必须打到同一个实例上。如果第一个请求打到实例 A后续的流式数据却从实例 B 返回上下文就对不上了。Nginx 默认的轮询策略会导致这个问题。解决方案是用ip_hash或者基于某个请求头做一致性哈希upstream backend { ip_hash; server 10.0.0.1:8000; server 10.0.0.2:8000; }但ip_hash在用户切换网络比如从 WiFi 切到 4G时会失效。更稳妥的做法是在应用层做会话粘性比如用 Redis 存储对话状态任何实例都能读取。这样 Nginx 层面就不需要做会话保持用默认的负载均衡策略即可。4.4 压缩与分块传输的冲突还有一个容易被忽略的点gzip 压缩。如果 Nginx 对 SSE 响应开启了 gzip压缩算法会等待足够的数据才输出这又会破坏流式效果。所以 SSE 的 location 必须关闭 gziplocation /api/chat { gzip off; proxy_buffering off; # ... 其他配置 }同理chunked_transfer_encoding在某些 Nginx 版本上也会影响流式输出建议显式关闭。这些配置看起来琐碎但少一个都可能导致打字机效果在生产环境失效。5. 断线重连与中断控制让流式体验更可靠5.1 自动重连的正确姿势SSE 协议本身支持自动重连服务端可以通过retry:字段告诉客户端重连间隔。但 AI 对话场景下的重连比较特殊重连后不能从头开始生成否则用户会看到重复内容。所以重连逻辑需要配合服务端的会话状态管理。我的做法是在请求里带一个lastEventId服务端记录每个会话已发送的内容偏移量重连时从偏移量继续发送。这样即使连接断了用户也只会看到短暂的中断然后从断点继续。但实现这个需要服务端维护会话状态对于无状态的后端来说成本较高。另一种折中方案是重连后重新生成但前端去重——把已显示的内容和新收到的内容做比对跳过重复部分。这种方案实现简单但会浪费一些计算资源。5.2 AbortController 与用户主动中断用户点停止生成按钮时需要立即中断流式请求。AbortController是标准做法const controller new AbortController(); // 发起请求时传入 signal fetch(/api/chat, { signal: controller.signal, ... }); // 用户点击停止时 controller.abort();但abort()之后reader.read()会抛出一个AbortError需要在 catch 里识别并静默处理。同时服务端也需要感知到客户端断开及时停止模型推理避免浪费算力。这通常通过监听请求的close事件来实现。5.3 心跳保活与代理超时有些代理服务器比如某些云厂商的负载均衡会主动断开长时间没有数据传输的连接。如果模型生成过程中有较长的思考停顿连接可能被中间层掐断。解决方法是在流式响应中定期发送心跳注释: heartbeat以冒号开头的行是 SSE 的注释客户端会忽略但能保持连接活跃。我一般设置每 15 到 30 秒发一次心跳具体间隔取决于中间层的超时配置。6. 几个实际项目里踩出来的经验6.1 前端渲染的节流策略流式数据到达的频率可能很高如果每个 chunk 都触发一次 React 重渲染页面会卡。我的做法是用requestAnimationFrame做节流把多个 chunk 合并到一帧里更新。这样既保证了视觉上的流畅又避免了过度渲染。具体实现是维护一个待渲染缓冲区onChunk时把内容追加进去并标记需要渲染然后在requestAnimationFrame回调里统一更新状态。实测下来这种方式能把渲染次数降低 60% 以上。6.2 移动端键盘与滚动跟随移动端有个特殊问题流式内容不断增长时如果用户没有手动滚动页面应该自动跟随到底部。但如果用户主动往上滚了就不应该强制拉回底部。判断逻辑是当滚动位置距离底部小于某个阈值时才自动跟随。另外移动端键盘弹出时会改变视口高度导致滚动位置计算出错。需要在键盘弹出和收起时重新计算滚动位置或者用visualViewportAPI 来获取真实的视口高度。6.3 错误信息的友好展示流式请求出错时错误信息可能出现在流的中间。比如已经显示了一半内容突然收到一个错误事件。这时候不能把已显示的内容清空而应该在末尾追加一个错误提示并提供重试按钮。重试时从断点继续而不是从头开始。我在实际项目里会把流式响应的每个事件都带上类型标记比如type: content、type: error、type: done。前端根据类型分别处理这样扩展起来比较灵活。6.4 日志与可观测性流式请求的排查比普通请求困难得多因为问题可能出现在链路的任何一环。我的做法是在关键节点打日志请求发起时记录请求 ID每个 chunk 到达时记录时间戳和内容长度流结束时记录总耗时和总长度。这样出问题时能快速定位是模型慢、网络慢还是渲染慢。服务端也要记录每个请求的 TTFT首 token 时间和总生成时间这两个指标能反映模型和网络的健康状况。如果 TTFT 突然变长可能是模型负载过高如果总生成时间波动大可能是网络不稳定。7. 关于技术选型的一点个人看法整套链路做下来我最大的体会是打字机效果本身不难难的是让它稳定可靠地工作在各种网络环境和部署架构下。SSE 是个好协议但它的简单性也意味着很多能力需要自己补——重连、中断、心跳、状态管理这些在 WebSocket 生态里有成熟方案的东西在 SSE 里都要自己实现。Markdown 增量渲染也是个看似简单实则琐碎的活。如果产品对渲染质量要求不高用现成的流式 Markdown 库能省不少事但如果要处理代码高亮、表格、公式这些复杂语法自己维护一个解析状态机可能更可控。Nginx 配置是最容易被忽视的一环。很多团队在本地开发时一切正常部署到生产环境后才发现流式效果没了排查半天才发现是proxy_buffering没关。我的建议是在项目初期就把 Nginx 配置纳入版本管理和代码一起 review不要等到上线才发现问题。最后说个我自己的习惯每次做流式相关的功能我都会在本地用curl -N直接请求接口观察原始的数据流。这样能排除前端渲染的干扰快速判断问题出在服务端还是客户端。这个笨办法帮我省了很多排查时间。