本地推理流式输出卡顿？从异步流到渲染优化全解析

最近在调一个本地推理项目把模型输出接到浏览器里做流式对话碰上一个特别能迷惑人的现象模型已经开始吐字了后台日志里 token 一个接一个往外刷可页面还是卡得跟幻灯片一样。异步流这条路我前前后后走了好几遍踩了不少坑今天就把这条链路从模型采样到屏幕渲染完整拆一遍讲清楚为什么吐字和卡顿可以同时发生以及怎么修。适合所有在折腾本地推理、自己搭 Web 聊天界面或者用 llama.cpp、transformers.js 做前端应用的人。先说一个容易被忽略的结论模型吐字和界面流畅是两件独立的事。前者只代表生产端开始产出数据后者取决于消费端能不能在这些数据的压力下稳定工作。很多人在这一步就把锅甩给模型性能或者怀疑是不是量化精度不够实际上大部分本地推理场景里真正的瓶颈根本不在模型而在你对“流”的无意识浪费。1. 先还原现场吐字和卡顿同时发生意味着什么1.1 生产与消费是两套链路把数据流想象成一条水管道。模型是水龙头界面显示是出水口。你看到水龙头已经出水了但水池还在往外漫原因不是水龙头没开而是水池到下水道这一段堵住了。模型每生成一个 token就好比水龙头挤出一滴水水已经在管路里流动了但如果消费侧处理不过来积水就会体现在界面上要么卡顿要么一阵一阵地涌出。这个类比能解释很多怪现象模型日志里 tokens/s 很稳定生成也没中断但 UI 长时间无响应或者模型回答刚吐了几个字就“停住”页面冻结两秒后突然冒出一大段。这两种情况其实都是消费链路的某个环节在积压只是积压的位置不一样。在深入代码之前先建立一个核心认知流式系统里必须关注每段的速度而不只是“有没有数据在动”。模型产出、网络传输、前端解析、DOM 渲染这四个环节速度各不相同任何一个环节吞吐不足都会让前方形成积压最后表现在用户眼前的就是各种形态的卡。1.2 本地推理的两种部署形态卡的位置完全不同本地推理接入网页按架构分基本是两种。搞清楚自己属于哪一种排查方向差很远。第一种是独立推理进程加浏览器前端。比如 llama.cpp 的 llama-server 跑在 127.0.0.1:8080Ollama serve 跑在本地端口前端通过 fetch 调用它的流式接口。这种形态下模型推理和浏览器 UI 是两个进程、两个线程体系模型再忙也不会直接占用浏览器主线程。如果你在这种架构下还是卡几乎可以断定是前端写得有问题或者网络请求路径上多了多余的缓冲层。第二种是模型直接跑在浏览器里。典型代表是 transformers.js模型权重加载进浏览器环境推理代码用 WebAssembly 或 WebGPU 执行。如果实现时把推理过程直接放在主线程跑那么模型每一次前向计算都会掐住页面界面必然冻结这不是任何流式渲染技巧能救的唯一的出路是把推理挪到 Web Worker。标题说的“本地推理”往往是第一种但文章后半部分我会把两种都覆盖到。实际项目里还有人混合着用比如浏览器里同时跑的模型负责轻量任务重量级生成走本地服务端。这种混合架构下排查起来更麻烦因为两边都可能引入阻塞需要逐个环节验证。1.3 模型速度和渲染速度之间差着一笔账本地推理的生成速度看硬件和模型规模通常落在 10 到 80 tokens/s 这个区间。拿常见的 7B Q4 量化模型举例M 系列芯片或者中高端独显上大概 25 到 40 tokens/s换算一下就是每个 token 间隔 25 到 40 毫秒。浏览器渲染的节奏是多少一帧 16.6 毫秒。也就是说模型每吐一个字你只有大约两帧的时间窗口去把这个字展示出来。如果前端处理一个 token 的成本是 2 毫秒看起来不痛不痒但如果你用了某些“方便”的写法比如每次到达就拼接整段 HTML、重新设置容器内容、再滚动到底部一次回调几百毫秒都可能页面立刻变成幻灯片。更隐蔽的是突发性。有的推理服务端为了效率会把生成的文本先攒在缓冲区里攒满或者停顿到一定长度才一次性 flush 给前端。模型日志看起来一直在吐但网络层看到的是一坨一坨的数据块。前端如果在每一块到达时全量渲染就会形成周期性卡顿页面流畅一两秒然后猛地跳一大段。这是本地推理里最容易误判为模型性能问题的情况其实换个传输方式或者改一下消费代码就解决了。2. 异步流到底在“异步”什么2.1 从模型到屏幕一条数据要经过四段接力任何一次流式输出从模型采样到用户看到文字都绕不开四个环节。第一段是模型采样循环。模型在 GPU 或 CPU 上不断做前向计算、采样下一个 token然后通过生成器或回调把 token 吐出来。这一段的速度完全由硬件和模型规格决定本地推理的瓶颈通常在这里但它不直接阻塞 UI。第二段是服务端序列化和传输。llama.cpp 这类 C 实现的 server 会把 token 包装成 SSE 格式也就是一行data: {token:...}通过 HTTP 流发给浏览器。这一段在本地回环地址上速度极快问题主要出在中间是否有反向代理、是否有缓冲机制后面会专门讲。第三段是浏览器接收、解码和协议解析。fetch 返回的 Response 对象有个 body可以拿到 ReadableStream用 reader.read() 逐块读取 Uint8Array 数据再用 TextDecoder 转成字符串然后按 SSE 协议解析出每个 token。这段代码如果写的糙会变成主线程的隐形杀手。第四段是把 token 渲染到页面上。包括更新输出容器、处理滚动、触发浏览器布局和绘制。这是本地推理流式输出的尾段也是大部分卡顿真正发生的地方。这里要特别指出一个常见误解很多人测试本地推理时只盯着第一段看模型日志里 tokens/s 正常就觉得没什么问题。实际上用户体感是第四段决定的前两段再快第四段慢一样白搭。我曾经遇到过一个人模型吞吐明明有 50 tokens/s页面却 5 秒都刷新不了一次抓包一看数据来得飞快问题是他的回调函数里做了整个聊天历史的 innerHTML 重绘每来一块数据就重绘全部对话那当然卡。2.2 事件循环不是并行异步回调依然在主线程这是必须掰开讲清楚的一点。很多人看到await fetch()脑子里默认它是“开了个线程去请求不占主线程”方向没错但reader.read()返回之后代码会在主线程继续执行。异步 API 只是把等待 I/O 的过程释放出去了并不代表回调里的代码也跑在主线程之外。浏览器 JavaScript 是单线程事件循环模型。主线程同一时刻只能执行一个任务其他任务在队列里排队。一个任务只要超过 50 毫秒就会被 Chrome 性能面板标成 Long Task用户的点击、滚动、动画全部等着。所以哪怕数据是“异步到达”的如果你在回调里处理数据时干了一堆重活界面依然卡死。常说“异步流”很多人把它理解成“并行处理”其实更像一种协作式调度。异步说的是你不必干等某个操作完成而是把这个操作的完成事件挂到队列里等主线程有空了再来处理。但它毕竟还是要回到主线程处理。管道里的水一直往回调里灌回调每个都处理 30 毫秒那么主线程的时间就被这些回调排满了哪里还有空渲染下一帧。2.3 解码、拼接、重排这些隐性开销远比想象中大流式渲染的技术点看起来不多但每一处都在偷偷消耗主线程。第一个被低估的是 TextDecoder 的使用方式。如果每次拿到 Uint8Array 都直接decoder.decode(value)而不传{stream: true}遇到多字节字符被切成两半就会出现乱码很多人为了省事就改成把整段文本攒到一定长度再统一解码结果反而制造了更大的长任务。第二个是字符串拼接。JavaScript 里字符串不可变理论上会创建新字符串。V8 对字符串拼接有优化短时间拼接几十次还好但输出累积到几百个 token每条都拿全量文本做一次拼接内存分配和 GC 压力会很快上来。最糟的写法是每次回调都做output.innerHTML fullText这等于把已经渲染过的内容全部推翻重来还伴随 HTML 解析、节点销毁和重建。第三个是布局重排。每次往容器里追加一个节点或者修改 textContent浏览器都可能重新计算布局。如果输出区域还在普通文档流里高度变化会波及周围元素再加上每次都要scrollTop scrollHeight强制滚动到底部性能直接雪崩。这里头的关键不是“多了一个字”而是“把整桌菜重新摆了一遍”。3. 实操让本地推理流真正流畅起来3.1 先搭一个会“吐字”的本地流式服务为了把问题隔离清楚我习惯先搭一个纯本地的假模型用固定间隔吐 token这样能排除真实推理引擎的变量专心调前端消费逻辑。真实项目里的 llama.cpp 或其他推理服务接口形态基本也是这种 SSE 流。下面用 FastAPI 写一个最小可跑的流式服务import asyncio import json from fastapi import FastAPI from fastapi.responses import StreamingResponse from pydantic import BaseModel app FastAPI() class ChatRequest(BaseModel): prompt: str async def token_stream(prompt: str): # 模拟本地模型输出的 tokens tokens [你, 好, , 这, 是, 一, 个, 流, 式, 输, 出, 的, 例, 子, 。] for token in tokens: payload json.dumps({token: token}, ensure_asciiFalse) yield fdata: {payload}\n\n await asyncio.sleep(0.03) # 模拟 30ms 出一个 token app.post(/v1/chat/stream) async def chat_stream(req: ChatRequest): return StreamingResponse( token_stream(req.prompt), media_typetext/event-stream; charsetutf-8 )如果接的是真实 llama.cpp server可以先做一个验证命令行里用 curl 请求它的 completion 接口确认是不是逐字返回。命令大概是curl -N http://127.0.0.1:8080/completion -d {prompt:你好,stream:true}能看到一行一行的data: {...}在滚动说明服务端流式输出本身没问题。这一步非常关键不然很容易去前端找半天 bug最后发现是服务端没开流式。前端要做的第一版最直白的写法是这样async function badStream() { const res await fetch(/v1/chat/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ prompt: 你好 }) }); const reader res.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\n); buffer lines.pop(); for (const line of lines) { if (!line.startsWith(data: )) continue; const data JSON.parse(line.slice(6)); // 这是最致命的写法 document.getElementById(output).innerHTML data.token; document.getElementById(output).scrollTop document.getElementById(output).scrollHeight; } } }这段代码在我演示的时候页面几乎是一帧一帧地跳。模型 30ms 一个 token本来是很舒服的节奏但每来一个 token 就innerHTML 一次浏览器要把整个输出区域的 HTML 重新解析一遍同时触发布局重排和滚动处理时间轻松超过 100ms。一个 token 卡 100ms十个 token 就把整个画面拖垮了。3.2 低效写法到底错在哪刚才那段代码集中犯了流式渲染的几大忌。第一innerHTML 不是增量追加而是把现有内容的序列化结果和新内容拼起来再全部重新解析一遍。输出越长每次操作的成本越大呈现明显的 O(n) 甚至 O(n^2) 趋势。第二每次迭代都读写 scrollTop会强制同步布局浏览器没法把滚动和重排批量合并。第三所有操作都塞在 await reader.read() 返回后的主线程回调里数据到达越密集主线程越累。本地推理场景有个特殊之处模型生成速度是稳定的数据是一点一点来的不像云端 API 那种一次性返回几百个 token。这个慢速流反而最容易暴露渲染代码的额外开销。每个 token 间隔几十毫秒理论上你有充足时间做增量更新但如果消费代码本身太重几十毫秒根本不够完成一次全量重绘。这也是我说“模型已经开始吐字不代表流是通的”的原因。数据在生产端流动得很顺畅到前端消费端被笨重的代码堵住了就像水龙头开着但水池下水口又细又缓。3.3 高效写法队列合并加文本节点增量追加正确的方向很朴素不要在回调里立刻渲染先把增量数据攒到一个队列用浏览器自己的渲染节奏来消费渲染时不要动旧内容只把新增部分追加到文本节点。下面这段代码是核心优化版仍然在主线程跑但已经能应付大多数本地推理场景了const output document.getElementById(output); let pendingTokens []; let scheduled false; function flushTokens() { scheduled false; if (!pendingTokens.length) return; const text pendingTokens.join(); pendingTokens []; const node document.createTextNode(text); output.appendChild(node); // 滚动操作放在同一帧且只做一次 output.scrollTop output.scrollHeight; } function onToken(token) { pendingTokens.push(token); if (!scheduled) { scheduled true; requestAnimationFrame(flushTokens); } }requestAnimationFrame 的节拍是 16.6ms 一帧正好跟浏览器渲染对齐。模型 30ms 出一个 tokenrAF 每帧最多消费一次一次至少合并 1 到 2 个 token实际渲染次数大幅减少。追加文本节点比innerHTML 轻得多浏览器只需要把新节点挂到目标元素下旧节点完全不动布局范围也小很多。如果输出文本特别长还有一种更保守的做法不要在 rAF 里直接 append 每个 token 批次而是维护一个完整文本每隔 50 到 100ms 把“上一次渲染点到当前点”的增量 append 一次。这个方案牺牲了一点实时性换来了主线程更平稳的负载适合生成速度特别快、输出量特别大的场景。3.4 彻底解耦把解析和拼接丢进 Web Worker队列加 rAF 能解决一半问题但解码、SSE 解析、字符串拼接仍然占着主线程。模型速度一高或者 prompt 变长主线程还是会周期性吃紧。要彻底治本就把网络读取和解析工作挪进 Web Worker主线程只负责接收纯文本增量并挂到 DOM 上。worker.js 大概长这样self.onmessage async (e) { const prompt e.data; const res await fetch(/v1/chat/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ prompt }) }); const reader res.body.getReader(); const decoder new TextDecoder(); let buffer ; let pending ; let tokensSincePost 0; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n\n); buffer lines.pop(); for (const line of lines) { if (!line.startsWith(data: )) continue; const data JSON.parse(line.slice(6)); pending data.token; tokensSincePost 1; // 攒够一批再发消息避免 postMessage 频率过高 if (tokensSincePost 8) { self.postMessage({ type: tokens, text: pending }); pending ; tokensSincePost 0; } } } if (pending) self.postMessage({ type: tokens, text: pending }); self.postMessage({ type: done }); };主线程里对应const worker new Worker(worker.js); const output document.getElementById(output); worker.onmessage (e) { if (e.data.type tokens) { output.appendChild(document.createTextNode(e.data.text)); output.scrollTop output.scrollHeight; } }; worker.postMessage({ prompt: 你好 });这个方案把真正消耗 CPU 的解析都挪走了主线程每次只干一件事加一个文本节点然后滚动。实测在 40 tokens/s 的生成速度下帧率基本稳定在 60fps。还有一类必须用 worker 的场景transformers.js 这类在浏览器里跑模型的库。推理前向计算是最吃 CPU 的部分如果不放在 Web Worker 里即使你的渲染代码写得再好模型每算一层都在抢占主线程页面照样卡死。很多人在浏览器里跑模型一卡就说“浏览器不行”其实是没把推理线程和 UI 线程分开。4. 常见问题与排查技巧实录4.1 字是一段一段蹦的不是连续吐——缓冲层在作怪症状模型日志显示 token 很均匀地生成但页面上一顿一顿有时空白 1 秒后“啪”地跳出一大段。这种问题八成不在前端消费代码而是运输途中有缓冲。检查顺序是先用 curl 直接打本地推理服务的接口看是不是逐字返回。如果 curl 正常再检查前面有没有 Nginx、Caddy 这类反向代理它们默认可能缓冲响应需要关掉缓冲或者把响应头X-Accel-Buffering: no设置好。如果 curl 也是一段一段的那就是服务端自己的问题。以 Python 写的推理服务为例同步生成器配合 StreamingResponse 通常没问题但如果你在生成器里用 print 调试或者中间套了一层缓存队列可能就有数据滞留。还有一个很容易踩的坑SSE 格式必须用\n\n结尾并且真的 flush 出去有些框架要对 response 显式flush()否则数据会卡在 socket 缓冲区里。这里再多说一句前端用 rAF 合并渲染确实会让输出显得“成块”但那种块是每一帧最多一次肉眼基本感觉不到如果你看到的是“空白一秒再跳一块”就别怀疑自己的 rAF 了问题一定在更早的环节。4.2 模型刚开吐就冻结恢复后内容一下全冒出来这个现象迷惑性最强。模型开始吐字说明第一次reader.read()已经返回了主线程应该没被网络阻塞。紧接着冻结往往是回调处理里出了一个同步大任务把主线程占死了等大任务跑完积攒的数据一次性涌进渲染。我在实际项目里见过两种典型诱因。一种是代码里每个 token 都调用了innerHTML 同时又做了全文 Markdown 渲染模型一开吐第一次数据处理就触发整个历史内容重渲染结果就是开吐瞬间开始卡卡完猛跳一段。另一种是模型本身在主线程跑比如没把 transformers.js 的推理代码放进 worker那模型开始生成后每次前向计算都会抢占主线程回调根本拿不到执行机会直到一段推理结束才把 token 交给渲染。解决思路也分两层。渲染类的用队列加 rAF 重写杜绝全量重绘。推理类的必须把模型推理挪出主线程。如果用的是 llama.cpp 这类独立进程那就直接减少前端的解析工作量该进 worker 的进 worker。4.3 多轮对话越用越卡DOM 在悄悄膨胀这是一个延迟问题不是单次流式渲染问题。很多本地推理 UI 把每一轮对话的每一个 token 都真实地塞进了 DOM聊了十几轮之后输出容器里积累了上千个文本节点。虽然每次追加都是增量操作但节点数量大了以后滚动、选中、样式计算都会变慢而且页面里的旧内容越来越多浏览器持有的内存也在涨。处理思路有两个方向。第一周期性地把旧消息折叠成纯文本块释放掉细粒度节点。对话记录仍然存在内存数组里但 DOM 层面不再为每条历史的每一个 token 都保留节点。第二给输出容器加content-visibility: auto让屏幕外的渲染工作延迟执行长对话下的滚动性能会有明显提升。对话界面如果做成虚拟列表那就是终极方案但对本地推理这种输出流动态变化的场景实现成本偏高。4.4 排查顺序与工具清单很多卡顿问题不用读代码就能定位。按这个顺序来省时很多。一先开 Chrome DevTools 的 Network 面板看接口响应。如果数据到达本身就是一顿一顿的方向直接转向服务端和网络层。二开 Performance 面板录制一段生成过程看主线程有没有长任务。如果长任务集中在“fetch 回调”里问题在解析和渲染如果长任务上面没有明显的网络标记而是一个叫做类似generate的匿名函数就要怀疑是浏览器里直接跑了推理。三把渲染部分先注释掉只看 console 输出如果这样模型吐字还是很流畅那渲染代码就是罪魁祸首。四用 DevTools 的 CPU 降速模拟慢机器放大问题比拿真机反复试高效得多。我做本地推理前端调试时必备的就是这三个工具Performance 面板看主线程、Network 面板看数据到达节奏、还有一个本地假模型服务来控制生成速度。这套组合拳基本能覆盖 90% 的卡顿问题。5. 最后说点个人体会5.1 异步流的心智模型踩过几次坑之后我现在的习惯是任何流式系统先画一条生产到消费的流水线标出每个环节的吞吐上限再决定怎么处理数据。本地推理尤其如此因为各个段的速度差异太明显了。模型每秒吐几十个 token本地回环传输几乎零延迟真正的变量全在消费端。异步流不是一句“用了 async 就不卡了”就能解释的。它只是允许你在等待 I/O 时腾出手脚但回调里的代码依旧要为主线程负责。理解了这一点很多奇怪现象会变得非常合理为什么模型吐字了页面还卡因为吐字是生产者的事卡不卡是消费者的事。生产者已经开工消费者却因为笨重的渲染逻辑堵住了两者完全可以同时发生。5.2 给项目留好扩展空间模型上下文越做越长未来的输出文本动辄几千字前端如果今天只靠小技巧硬撑很快会遇到天花板。我从一开始就在代码里坚持“增量更新”和“解析与渲染分离”两个原则宁可前期复杂一点也不把全部希望寄托在优化某个函数上。最后分享一个实用测试技巧所有 UI 改动我都用假的慢速生成器配合 CPU 降频来压测比如把生成间隔设为 30ms 并开启 4 倍 CPU 降速。真实模型反而会掩盖很多问题因为硬件够快、token 够少怎么糙的代码都看不出来。反倒是把速度调慢、CPU 降频之后那些潜在的执行阻塞会立刻暴露。这个方法帮我提前躲过好几个上线后才会出现的卡顿坑建议你也试试。