最近在调一个本地推理项目，把模型输出接到浏览器里做流式对话，碰上一个特别能迷惑人的现象：模型已经开始吐字了，后台日志里 token 一个接一个往外刷，可页面还是卡得跟幻灯片一样。异步流这条路我前前后后走了好几遍，踩了不少坑，今天就把这条链路从模型采样到屏幕渲染完整拆一遍，讲清楚为什么吐字和卡顿可以同时发生，以及怎么修。适合所有在折腾本地推理、自己搭 Web 聊天界面，或者用 llama.cpp、transformers.js 做前端应用的人。
先说一个容易被忽略的结论：模型吐字和界面流畅是两件独立的事。前者只代表生产端开始产出数据，后者取决于消费端能不能在这些数据的压力下稳定工作。很多人在这一步就把锅甩给模型性能，或者怀疑是不是量化精度不够，实际上大部分本地推理场景里，真正的瓶颈根本不在模型，而在你对“流”的无意识浪费。
1. 先还原现场：吐字和卡顿同时发生意味着什么
1.1 生产与消费是两套链路
把数据流想象成一条水管道。模型是水龙头，界面显示是出水口。你看到水龙头已经出水了，但水池还在往外漫，原因不是水龙头没开，而是水池到下水道这一段堵住了。模型每生成一个 token，就好比水龙头挤出一滴水，水已经在管路里流动了；但如果消费侧处理不过来，积水就会体现在界面上，要么卡顿，要么一阵一阵地涌出。
这个类比能解释很多怪现象：模型日志里 tokens/s 很稳定，生成也没中断，但 UI 长时间无响应；或者模型回答刚吐了几个字就“停住”，页面冻结两秒后突然冒出一大段。这两种情况其实都是消费链路的某个环节在积压，只是积压的位置不一样。
在深入代码之前，先建立一个核心认知：流式系统里必须关注每段的速度，而不只是“有没有数据在动”。模型产出、网络传输、前端解析、DOM 渲染，这四个环节速度各不相同，任何一个环节吞吐不足，都会让前方形成积压，最后表现在用户眼前的，就是各种形态的卡。
1.2 本地推理的两种部署形态，卡的位置完全不同
本地推理接入网页，按架构分基本是两种。搞清楚自己属于哪一种，排查方向差很远。
第一种是独立推理进程加浏览器前端。比如 llama.cpp 的 llama-server 跑在 127.0.0.1:8080，Ollama 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_ascii=False) yield f"data: {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_type="text/event-stream; charset=utf-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 出一个 token，rAF 每帧最多消费一次，一次至少合并 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 降频之后，那些潜在的执行阻塞会立刻暴露。这个方法帮我提前躲过好几个上线后才会出现的卡顿坑，建议你也试试。
