1. 流式输出为什么值得单独拎出来讲很多人第一次接触 Agent 开发注意力都放在模型选型、工具调用、记忆管理这些大件上流式输出往往被当成一个收尾环节——反正最后把结果打印出来就行了。但真正把 Agent 推到生产环境的人会发现流式管道这条链路出问题的概率比模型本身还高。用户看到的卡住不动打字机效果断断续续最后一段内容凭空消失十有八九不是模型的问题而是从StreamChunk到 UI 这一段的数据搬运出了岔子。这篇内容围绕 DeepSeek-Harness 这套 Agent 框架里的流式输出管道展开讲清楚一个 chunk 从模型侧产生之后经过怎样的解析、封装、传输最终变成前端界面上逐字浮现的文字。关键词里出现的StreamChunk、SSE、流式输出、流式消息解析基本就是这条链路的全部核心概念。适合两类人看一类是正在用 DeepSeek 系列模型搭 Agent、被流式问题折腾过的开发者另一类是准备自己封装一套流式接口调用逻辑、想少走弯路的人。我自己的经验是流式输出这件事写通一个 demo 只要半小时但要写得稳、写得能扛住真实网络环境和各种边界情况得反复调好几轮。下面把我踩过的、见过的坑连同背后的原理一并摊开讲。2. StreamChunk 到底是什么拆开一个数据块看内部2.1 从模型返回的原始分片说起大模型在流式模式下返回的不是一整段文本而是一连串的分片。每个分片里通常包含一小段增量文本可能是一个词、半个词甚至只是一个标点。以 DeepSeek 的接口为例流式响应里每个数据块的结构大致是这样的一个delta字段装着本次新增的内容一个finish_reason字段标记是否结束还有可选的usage统计信息。这里有个容易被忽略的点分片的边界和语义边界是不对齐的。模型可能把流式输出这四个字拆成流式输出四次返回也可能一次返回流式、下一次返回输出。如果你在前端直接按分片渲染用户看到的打字机效果会忽快忽慢因为每个分片的字符数不一样。更麻烦的是如果分片正好切在一个多字节字符或者一个 Markdown 语法中间渲染就会出乱码或者格式错乱。StreamChunk这个概念本质上就是对原始分片做一层抽象封装。它把模型返回了什么和业务需要什么解耦开。一个设计良好的StreamChunk结构通常包含这几个字段字段含义典型取值type块类型text/tool_call/reasoning/donecontent增量内容字符串或结构化对象index序号递增整数用于排序和去重finish_reason结束原因null/stop/length/tool_calls为什么要加type字段因为 Agent 场景下流里混着好几种东西模型正在思考的推理内容、正式回答的文本、要调用的工具参数。如果不区分类型前端就没法决定这段内容是直接显示、折叠起来还是拿去触发工具调用。这是 Agent 流式输出和普通聊天流式输出最大的区别。2.2 为什么不能直接把原始 JSON 丢给前端有人会想既然模型返回的就是 JSON那我直接把原始数据透传给前端让前端自己解析不就行了这个做法在 demo 阶段能跑但生产环境会出问题。第一原始 JSON 里包含大量前端不需要的字段比如模型版本、请求 ID、内部时间戳透传等于把内部实现细节暴露出去。第二不同模型供应商的流式格式不一样前端如果直接依赖原始格式换一个模型就得改前端代码。第三也是最关键的原始分片里可能包含工具调用的参数增量这些内容需要先在后端拼装完整、校验合法性才能决定是否执行直接丢给前端等于把安全校验的责任推给了不可信的一端。所以StreamChunk这层封装本质上是后端在扮演一个翻译官和守门人的角色。它把各家模型五花八门的流式格式统一成一套前端友好的协议同时在转发之前完成必要的校验和聚合。2.3 一个 chunk 的完整生命周期把视角拉长一个StreamChunk从产生到消失会经历这么几个阶段产生模型侧生成增量内容通过网络以 SSE 或类似协议推送到后端。解析后端逐行读取流把data:后面的 JSON 解析成对象提取出增量内容。封装把增量内容包装成统一的StreamChunk结构打上类型标记和序号。聚合对于工具调用这类需要完整参数才能执行的内容先缓存起来等参数拼完整再处理。转发通过 SSE 把StreamChunk推给前端。渲染前端接收、解析、按类型分发到不同的 UI 组件。收尾收到结束标记后关闭连接触发后续逻辑比如保存消息、更新状态。这条链路上任何一环出问题用户看到的就是卡住或者内容不全。下面几节会逐个拆解关键环节。3. SSE 这条传输通道的脾气3.1 为什么流式输出偏爱 SSE流式传输有好几种技术选型WebSocket、SSE、长轮询、HTTP 分块传输。Agent 场景下SSE 是出现频率最高的选择原因很实际。WebSocket 是全双工功能强但需要额外的握手和连接管理服务端要维护连接状态水平扩展时还得考虑连接粘性问题。而 Agent 的流式输出绝大多数时候是单向的——服务端推客户端收。用户中途打断、追加指令这些交互用普通的 HTTP 请求就能解决没必要为了这个上 WebSocket。SSE 基于普通 HTTP天然支持断线重连浏览器会自动重连实现简单服务端就是一个持续写入的 HTTP 响应。对于模型生成内容、前端逐字显示这个需求SSE 的匹配度最高。代价是它只支持文本二进制数据得先编码不过 Agent 场景下传的基本都是文本这个限制影响不大。3.2 SSE 的格式细节和常见误用SSE 的格式看起来简单但细节不少。一条标准的 SSE 消息长这样event: message data: {type:text,content:你好}注意几个点data:后面跟内容每条消息以两个换行结束event:字段可选但很有用。很多人第一次写 SSE栽在换行上——只写一个换行浏览器不会触发onmessage消息就一直堆在缓冲区里。还有一个高频误用在 data 里塞未转义的换行。如果content字段里本身包含换行符模型输出多行文本时很常见直接拼进data:会导致这条消息被截断成多条。正确做法是把内容 JSON 序列化换行符会被转义成\n这样就不会破坏 SSE 的帧结构。我在实际项目里见过一个 bug模型输出代码块时前端收到的内容总是缺几行。排查了半天最后发现是后端拼接 SSE 消息时代码块里的换行符没转义把一条消息切成了好几条前端只处理了第一条。这个坑很隐蔽因为普通文本不换行时完全正常只有多行内容才暴露。3.3 超时、断连与心跳SSE 连接是长连接中间可能经过各种网络设备。有些代理或网关会在连接空闲一段时间后主动断开这就是关键词里那个stream disconnected before completion: idle timeout waiting for sse的由来。解决办法是定期发送心跳。心跳可以是一条注释消息以:开头前端会忽略它但能保持连接活跃: heartbeat心跳间隔要小于链路上最短的空闲超时时间。常见的网关空闲超时是 60 秒那心跳设成 15 到 30 秒比较稳妥。设太频繁浪费带宽设太稀疏又起不到保活作用。除了心跳还要处理正常结束和异常结束的区分。正常结束时服务端应该发送一个明确的结束标记比如data: [DONE]或者一个finish_reason非空的 chunk然后关闭连接。前端收到这个标记才知道内容是完整的。如果连接在没有结束标记的情况下断了前端应该提示用户内容可能不完整而不是默默接受半截结果。提示判断流是否正常结束不要依赖连接关闭这个动作本身要依赖业务层的结束标记。连接关闭可能是正常结束也可能是超时断开两者在传输层看起来一样。4. 后端解析与封装把碎片拼成可用数据4.1 逐行读取流的正确姿势后端从模型接口读取流式响应时拿到的是一个字节流。这个流不能一次性读完也不能按固定大小读必须按行读。因为 SSE 的帧是以换行为分隔的按行读才能保证每次拿到一个完整的帧。不同语言的实现方式不一样。Python 里用httpx或requests的流式接口配合iter_lines()Node.js 里用fetch拿到response.body后通过TextDecoder逐块解码再按换行切分。这里有个细节网络传输的块边界和行的边界不对齐。一次网络读取可能拿到半行也可能拿到两行半。所以需要一个缓冲区把读到的内容累积起来遇到换行才切出一条完整消息剩下的留在缓冲区等下次。这个缓冲区逻辑写错了就会出现偶尔丢消息或者消息错位的问题。我建议把这段逻辑单独抽成一个函数配上单元测试用各种边界情况半行、多行、空行、超长行去验证。4.2 增量内容的聚合策略拿到每个分片后需要决定怎么聚合。这里分两种情况。纯文本内容直接拼接就行每个分片的content追加到累积字符串后面。但要注意拼接的时机和转发的时机可以不同。有些实现是攒够一定长度再转发减少网络往返有些是来一个转一个延迟最低。Agent 场景下我倾向于后者因为用户对首字延迟很敏感攒批会让打字机效果一顿一顿的。工具调用参数这个不能简单拼接。工具调用的参数是 JSON 格式模型会分多次返回参数的片段。比如调用一个查询天气的工具参数{city: 北京}可能分三次返回{ci、ty: 北、京}。你必须把这些片段按顺序拼起来等finish_reason变成tool_calls时再尝试解析成完整 JSON。如果解析失败说明参数不完整或者格式有问题需要走错误处理。这里有个容易踩的坑多个工具调用可能并行返回。模型一次可能决定调用两个工具它们的参数片段会交错出现在流里。这时候不能简单地往一个字符串上拼得用index字段区分是哪个工具调用的参数分别缓存。忽略这一点参数就会串在一起解析必然失败。4.3 封装成 StreamChunk 的字段设计把解析出来的内容封装成StreamChunk时字段设计要考虑前端的消费便利性。我的经验是字段宁少勿多但每个字段都要有明确用途。type字段是核心前端靠它决定渲染方式。content字段装实际内容文本类就是字符串工具调用类可以是结构化的对象。index字段用于排序防止网络乱序导致内容错位。finish_reason用于标记结束。还有一个可选但很有用的字段timestamp。加上它前端可以做打字速度的平滑处理也能在调试时定位延迟发生在哪一段。封装的时候要注意不要做过度加工。有些实现会在后端把 Markdown 渲染成 HTML 再传这是不对的。渲染是前端的事后端传原始文本就行。后端做渲染一是增加了耦合二是前端想换渲染库就得改后端三是渲染后的 HTML 体积更大传输成本更高。5. 前端消费从字节到屏幕上的字5.1 接收与解析的容错处理前端通过EventSource或者fetch的流式读取来接收 SSE。EventSource用起来简单但它有个限制只能发 GET 请求不能自定义请求头。如果接口需要鉴权就得把 token 放在 URL 参数里不太优雅。所以很多项目改用fetch加ReadableStream手动解析。手动解析的代码大概长这样const response await fetch(url, { headers: { Authorization: token } }); 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 lines buffer.split(\n); buffer lines.pop(); // 最后一行可能不完整留到下次 for (const line of lines) { if (line.startsWith(data: )) { const data line.slice(6); if (data [DONE]) return; handleChunk(JSON.parse(data)); } } }这段代码里buffer lines.pop()那行是关键它把可能不完整的最后一行留在缓冲区。漏了这行就会偶发解析错误。decoder.decode的{ stream: true }参数也很重要它保证多字节字符被正确解码不会因为分片切断而出现乱码。5.2 打字机效果的实现与性能拿到 chunk 后前端要把它渲染成逐字浮现的效果。最简单的做法是每收到一个 chunk 就更新一次 DOM。但这样有个问题如果 chunk 来得很快DOM 更新频率过高页面会卡顿。更好的做法是用 requestAnimationFrame 做节流。把收到的内容先放进一个队列每帧从队列里取一部分渲染。这样既能保证流畅度又不会因为频繁更新 DOM 拖慢页面。还有一个细节自动滚动。内容不断追加容器高度增长需要自动滚到底部。但如果用户手动往上滚了说明他在看历史内容这时候就不该强制滚动。判断逻辑是只有当滚动条已经在底部附近时才自动滚动。5.3 不同类型 chunk 的分发渲染前面提到StreamChunk有type字段前端要根据类型分发。文本类直接追加到消息气泡里推理类如果模型返回思考过程可以折叠显示用户想看再展开工具调用类需要特殊处理通常显示成一个正在调用 XX 工具的状态卡片等工具执行完再更新结果。这里有个体验上的技巧工具调用的参数不要实时显示。因为参数是分片返回的实时显示会看到一堆残缺的 JSON很难看。等参数拼完整、工具开始执行了再显示一个干净的调用状态。6. 那些让我熬夜的坑6.1 内容重复或丢失的排查链路有一次线上反馈用户说回答的最后一段偶尔会重复出现。这个问题复现概率不高但确实存在。排查过程是这样的先看后端日志确认后端发出的 chunk 序列是正常的没有重复。那问题就在传输或前端。抓包看 SSE 数据发现某个 chunk 在网络层被重传了。原因是连接在传输过程中抖动了一下触发了重连而重连后服务端从某个位置重新推送导致部分内容重复。解决办法是给每个 chunk 加index前端记录已处理的最大index收到小于等于它的 chunk 就丢弃。这个去重逻辑很轻量但能解决重连导致的重复问题。内容丢失的排查思路类似但方向相反。先确认后端是否发全了再看前端是否收全了。如果后端发全、前端没收全通常是缓冲区处理有问题或者连接提前关闭了。这时候要检查前端的读取循环是否正确处理了done状态以及服务端是否在发完所有内容后才关闭连接。6.2 工具调用参数解析失败的典型原因工具调用参数解析失败我遇到过三种原因。第一种是参数被截断。模型返回参数时如果达到 token 上限参数可能只返回了一半。这时候finish_reason是length而不是tool_calls前端如果只看内容不看结束原因就会拿半截 JSON 去解析必然失败。正确做法是检查finish_reason只有它是tool_calls时才认为参数完整。第二种是多个工具调用交错。前面提过并行工具调用的参数片段会交错必须用index区分。我见过一个实现把所有片段往一个字符串上拼结果两个工具的参数混在一起JSON 解析直接报错。第三种是模型返回了非法 JSON。这种情况少见但存在比如模型在参数里加了注释或者多余的逗号。稳妥的做法是解析失败时不要直接崩溃而是记录原始内容走降级逻辑比如提示用户重试或者用默认参数。6.3 长连接被中间层掐断idle timeout waiting for sse这个报错本质是链路上某个中间层认为连接空闲太久主动断开了。除了前面说的心跳还有一个容易被忽略的点首字节延迟。如果模型思考时间很长从请求发出到第一个 chunk 返回之间可能有几十秒的空白。这段时间连接上没有任何数据流动中间层就可能判定为空闲。解决办法是在请求发出后、模型返回第一个 chunk 之前先发一个正在处理的占位 chunk让连接保持活跃。这个占位 chunk 的type可以设成status前端收到后显示一个加载状态不往消息内容里追加。等真正的文本 chunk 来了再替换掉加载状态。7. 把管道做稳的几个工程习惯7.1 给流式链路加可观测性流式输出出问题时最难的是定位问题发生在哪一环。我的做法是在每个关键节点打日志请求发出时记录时间戳收到第一个 chunk 时记录首字节延迟每个 chunk 记录序号和长度结束时记录总耗时和总 chunk 数。这些日志平时看着冗余但出问题时能快速画出时间线。比如首字节延迟突然变大说明模型侧或网络侧有问题chunk 之间的间隔不均匀说明传输不稳定总 chunk 数和内容长度对不上说明有丢失。前端也可以加类似的埋点记录收到第一个 chunk 的时间、渲染第一帧的时间。这样端到端的延迟就能拆解成几段哪段慢一目了然。7.2 优雅处理用户中断用户可能在模型还在生成时就点了停止。这时候前端要主动关闭连接后端要感知到连接关闭并停止向模型请求。如果后端不处理模型会继续生成白白消耗 token。后端感知连接关闭的方式取决于具体框架。Python 的异步框架里可以通过监听请求的断开事件Node.js 里req.on(close)可以捕获。捕获到之后要取消对模型的请求释放资源。这里有个细节已经生成的内容要保留。用户中断不代表要丢弃已生成的内容通常的做法是把已生成的部分保存下来标记为已中断。下次用户继续对话时这部分内容还在。7.3 并发场景下的资源管理Agent 服务往往要同时处理多个用户的流式请求。每个请求都占用一个长连接和一定的内存用于缓冲和聚合。并发量上来之后资源管理就很重要。几个实践要点给每个连接设置最大存活时间防止僵尸连接占用资源限制单个请求的最大 chunk 数或最大内容长度防止异常情况下的资源耗尽用连接池管理对模型的请求避免每次请求都新建连接。还有一个容易忽略的点背压处理。如果前端消费速度慢于后端生产速度数据会在缓冲区堆积。SSE 本身没有背压机制需要应用层自己控制。简单的做法是给缓冲区设上限超过就暂停从模型读取等前端消费了再继续。8. 关于这套管道我自己的几点体会流式输出这条链路技术难度不算高但细节密度极大。每一个环节都有若干种出错的可能而且很多问题只在特定条件下才暴露——网络抖动、内容包含特殊字符、并发量突增。我自己的习惯是每次改动这条链路上的任何代码都要用几种极端情况回归一遍超长内容、包含大量换行和特殊字符的内容、中途断网、用户快速连续中断。StreamChunk这层抽象的价值随着项目复杂度上升会越来越明显。一开始可能觉得多此一举但当你要接入第二个模型、要支持工具调用、要做内容审核的时候就会发现统一的数据结构省了太多事。前端不用关心底层是哪个模型后端换模型时前端零改动这种解耦在长期维护里回报很大。最后分享一个调试小技巧在开发阶段可以写一个流回放工具把一次真实的流式响应录下来存成文件之后调试前端时直接回放这个文件不用每次都真的调模型。这样既省 token又能稳定复现问题。我靠这个工具定位过好几个只在特定内容下才出现的渲染 bug。