大模型流式响应：fetch与ReadableStream协同原理与实战

发布时间：2026/11/4 21:45:22
大模型流式响应：fetch与ReadableStream协同原理与实战

1. 这不是“一起出现”，而是大模型前端流式响应的必然搭档

你第一次在大模型 Web 应用的控制台里看到fetch和ReadableStream同时报错，或者在调试 Network 面板时发现 Response 的body类型是ReadableStream，心里大概率会冒出一句：“这俩怎么又凑一块儿了？”——尤其当错误信息是TypeError: Failed to fetch或ReadableStream is locked时，那种“明明只写了三行代码，却像在解一道编译原理题”的挫败感特别真实。

这不是巧合，也不是框架故意设的障眼法。fetch是发起请求的“门卫”，ReadableStream是接收响应的“流水线工人”——而大模型的输出，天生就是一条不能停、不能倒带、必须边产边送的流水线。
你调用fetch('/api/chat')，后端返回的不是一整块 JSON 字符串，而是一段持续涌出的、以\n分隔的data: {...}块（SSE）或直接裸字节流（chunked transfer encoding）。这时候，fetch把连接通道交出来，ReadableStream就立刻接管，开始一帧一帧地读、解码、分发。它不等全部数据落盘，也不缓存整条消息体——因为大模型的 token 生成速度可能高达 50+ tokens/秒，等它吐完 2000 个 token 再解析，用户界面早就卡成 PPT 了。

我去年重构一个本地 LLM 聊天界面时，就栽在这点上。最初用await response.json()，结果每次提问都要等模型完全生成完毕才渲染，用户反馈“像在等煮开水”。改成response.body.getReader()+decoder.decode()后，首 token 延迟从 3.2 秒压到 480ms，且每 80ms 就能刷新一次 UI。这不是优化技巧，而是对大模型输出本质的尊重：它不是文件下载，是实时语音转文字式的流式生产。

关键词fetch和ReadableStream在大模型场景下高频共现，根本原因在于 HTTP 协议层与 AI 推理层的天然耦合——HTTP/1.1 的Transfer-Encoding: chunked和 HTTP/2 的流式 multiplexing，为 token 级别响应提供了传输基础；而浏览器原生Streams API则是唯一能在主线程安全、可控地消费这种流的机制。跳过ReadableStream直接text()或json()，等于让流水线工人把整条传送带拆下来扛回家再分拣——物理上就不可行。

提示：很多初学者误以为fetch返回的Response对象自带“自动流式解析”能力。事实是：response.text()、response.json()、response.blob()全部是consume 操作，它们会隐式调用response.body.getReader().read()直到done === true，并把所有 chunk 合并成单一大字符串/对象。这对小数据友好，对大模型输出就是灾难性阻塞。

2. 为什么fetch必须配ReadableStream？从 HTTP 协议底层看流式响应的刚性约束

要真正理解fetch和ReadableStream的绑定关系，得回到 HTTP 协议本身。大模型 API 的响应头里，你几乎总能看到这两行：

Content-Type: text/event-stream Transfer-Encoding: chunked

或者更现代的：

Content-Type: application/json Content-Encoding: identity

但关键不在类型，而在传输方式。HTTP/1.1 的chunked编码，是服务器在不知道总长度时，把响应体切成若干块（chunk），每块前带长度标识，末尾用0\r\n\r\n标记结束。浏览器收到第一个 chunk 就能开始处理，无需等待全部数据到达。HTTP/2 更进一步，每个 stream 可以独立发送多个 DATA 帧，天然支持多路复用和流式推送。

问题来了：浏览器如何把这种“边收边传”的字节流，变成前端 JavaScript 可操作的数据？
答案只有一个：ReadableStream。它是 WHATWG Streams 标准定义的、浏览器原生支持的异步迭代器接口，专为处理“不可知长度、持续到达、需逐段消费”的数据设计。fetch的Response.body属性，正是这个标准的落地实现——它不是一个缓冲区，而是一个可读流控制器（ReadableStreamDefaultReader）的入口。

我们来拆解一次典型的大模型流式请求生命周期：

  1. fetch('/v1/chat/completions', { method: 'POST', body: JSON.stringify({ model: 'qwen2.5-7b', messages: [...] }) })发起请求；
  2. 服务端收到后，立即返回200 OK响应头，并开始向 TCP 连接写入数据块（如data: {"id":"chat-xxx","object":"chat.completion.chunk","delta":{"content":"你"},"index":0}\n\n）；
  3. 浏览器网络栈接收到第一个 TCP 包，解析出 HTTP 头，创建Response对象，其body属性被初始化为一个ReadableStream实例；
  4. 此时response.body并未读取任何数据，它只是“准备好接收”，就像打开水龙头但还没拧开阀门；
  5. 当你调用const reader = response.body.getReader()，才真正获取到读取器（reader），它持有对底层流的引用；
  6. reader.read()返回一个 Promise，resolve 时携带{ value: Uint8Array, done: false }—— 这个Uint8Array就是当前收到的 chunk 原始字节；
  7. 你用new TextDecoder().decode(chunk)把字节转成字符串，按 SSE 规则分割data:行，JSON.parse 内容字段，提取delta.content，更新 UI；
  8. 循环reader.read()，直到done === true（服务端关闭连接或发送终止标记）。

整个过程里，fetch只负责建立连接、发送请求、接收响应头并创建Response对象；真正的数据搬运工、解码器、分发器，全是ReadableStream及其 reader 在干活。如果你跳过它，用await response.text()，那么第 6 步会被封装成一个黑盒：fetch内部会自动调用reader.read()直到done，把所有Uint8Array合并、解码、拼接，最后返回一个完整字符串。这对 1KB 的 JSON 是秒级完成，但对 50KB 的流式响应（含数百个 chunk），意味着 UI 线程被阻塞，无法响应滚动、输入等交互。

注意：ReadableStream的locked状态是核心陷阱。一旦你调用response.text()、response.json()或response.blob()，response.body就被标记为 locked，后续再调getReader()会抛TypeError: Cannot read property 'getReader' of null。这是浏览器强制的单消费者约束——防止多个 reader 同时读取导致数据错乱。所以，选了text()就别想再流式读；选了getReader()就绝不能再碰其他 consume 方法。

3. 实战中的三大典型错误链：从failed to fetch到stream is locked的完整排查路径

我在帮三个不同团队做大模型前端集成时，发现 92% 的流式响应失败都集中在三个相互嵌套的错误模式里。它们不是孤立的报错，而是一条清晰的因果链。下面我用真实调试日志还原整个过程，告诉你怎么一步步定位根因。

3.1 错误链起点：Failed to fetch—— 表面是网络问题，实则是服务端流式中断

现象：控制台报TypeError: Failed to fetch，Network 面板里该请求状态为(cancelled)或Pending后消失，Response 标签页为空。

初学者第一反应是“网络不好”，于是反复刷新、换浏览器、关防火墙……其实这是最典型的服务端主动断连信号。大模型服务（如 Ollama、vLLM、FastChat）在流式响应中，如果遇到以下任一情况，会直接关闭 TCP 连接：

  • 模型推理超时（如--timeout 300设置过短，而长文本生成耗时 320s）；
  • 显存不足触发 OOM Killer 杀死 worker 进程；
  • 中间件（如 Nginx）配置了proxy_read_timeout 60，但模型生成需 90s；
  • 客户端发送了Connection: close头，服务端礼貌回应后断连。

验证方法：打开 Network 面板，点击该请求 → Headers → 查看Request Headers是否有Connection: close；再看Response Headers，若缺失Content-Type或Transfer-Encoding，基本确认服务端未进入流式响应阶段，而是直接返回了 5xx 错误（但被 fetch 框架吞掉）。

解决方案：

  • 服务端：检查日志，确认是否Killed process或timeout exceeded；调高--timeout和--num-gpu-layers（减少 CPU 推理压力）；
  • 代理层（Nginx）：在location /api/块中添加：
    proxy_http_version 1.1; proxy_set_header Connection ''; proxy_read_timeout 300; # 必须 ≥ 模型最大生成时间 proxy_buffering off; # 关闭缓冲，确保 chunk 立即透传
  • 客户端：fetch选项中显式设置keepalive: true（虽非强制，但明确意图）。

3.2 错误链中段：ReadableStream is locked—— 你以为在流式读，其实已偷偷 consume

现象：UI 无响应，控制台报TypeError: ReadableStream is locked，response.body.getReader()调用失败。

这是最隐蔽的坑。我见过最多的情况是：开发者为了“保险”，在流式读取前先尝试if (response.ok) { await response.json() }做状态校验——这一行就锁死了 stream。response.json()内部会调用response.body.getReader().read()直到done，即使你没 await 它，Promise 创建即触发消费。

另一个常见场景：使用 Axios。默认配置下，axios.post()返回的response.data是response.body经transformResponse处理后的结果，而transformResponse默认包含JSON.parse，这就等同于调用了response.json()。

排查步骤：

  1. 在fetch后立即打印response.body.locked—— 若为true，说明已被 consume；
  2. 检查代码中是否出现response.text()、response.json()、response.blob()、response.arrayBuffer()任意调用；
  3. 若使用封装库（如 SWR、RTK Query），查看其transform或parse配置，确认未开启自动 JSON 解析。

修复方案（二选一）：

  • 彻底放弃所有 consume 方法：从fetch开始，只走getReader()路线，用TextDecoder手动解码；
  • 改用response.clone()：response.clone().json()不影响原response.body，但注意 clone 会复制整个流，内存开销翻倍，仅适用于小响应体校验。

3.3 错误链终点：AbortError: The operation was aborted—— 用户手速太快，流被主动掐断

现象：用户快速连续发送多条消息，某次响应中途报AbortError，UI 停止更新。

这是AbortController的正常行为。当你为fetch配置signal，并在新请求发起时调用abortController.abort()，所有监听该 signal 的 Promise（包括reader.read()）都会 rejectAbortError。问题在于，很多代码没做错误隔离：

// ❌ 危险写法：未捕获 AbortError，导致整个组件崩溃 const reader = response.body.getReader(); while (true) { const { done, value } = await reader.read(); // 这里可能 throw AbortError if (done) break; appendToUI(decode(value)); }

正确做法是将流读取封装为独立可取消任务，并优雅降级：

async function readStream(reader, decoder, onChunk) { try { while (true) { const { done, value } = await reader.read(); if (done) break; onChunk(decoder.decode(value, { stream: true })); } } catch (error) { if (error.name === 'AbortError') { console.log('流读取被用户中断，忽略'); return; // 优雅退出 } throw error; // 其他错误仍需上报 } } // 使用时 const controller = new AbortController(); fetch('/api/chat', { signal: controller.signal }) .then(response => { const reader = response.body.getReader(); const decoder = new TextDecoder(); readStream(reader, decoder, appendToUI); }); // 用户点击“停止生成”时 controller.abort(); // 不会炸掉页面

这三条错误链，本质是 HTTP 流式协议、浏览器 Streams API、前端业务逻辑三者之间的摩擦。解决它们不需要新学框架，只需要理解：fetch是信使，ReadableStream是流水线，而你的代码，必须成为这条流水线上的合格调度员。

4. 手把手实现一个健壮的大模型流式读取器：从 raw bytes 到可渲染 delta

光说原理不够，我们来写一个生产环境可用的流式读取器。它要解决五个实际痛点：
① 正确处理 SSE（Server-Sent Events）格式；
② 兼容纯文本流（如text/plain）；
③ 自动处理 UTF-8 多字节字符边界（避免 `` 符号）；
④ 支持 abort 且不崩溃；
⑤ 提供 token 级别回调，便于 UI 实时渲染。

下面是我在线上项目中稳定运行 11 个月的LLMStreamReader类，已去除所有框架依赖，纯原生 JS：

class LLMStreamReader { constructor(response, options = {}) { this.response = response; this.decoder = new TextDecoder('utf-8'); this.onToken = options.onToken || (() => {}); this.onError = options.onError || console.error; this.onComplete = options.onComplete || (() => {}); this.sseMode = response.headers.get('content-type')?.includes('event-stream'); this.buffer = ''; // 存储未完成的 UTF-8 字符 } // 主入口：启动读取 async start() { if (!this.response.body) { throw new Error('Response has no body'); } const reader = this.response.body.getReader(); try { while (true) { const { done, value } = await reader.read(); if (done) { this.onComplete(); break; } this.processChunk(value); } } catch (error) { if (error.name === 'AbortError') { this.onError('Stream aborted by user'); } else { this.onError('Stream read error:', error); } } finally { reader.releaseLock(); } } // 处理单个 chunk 的字节 processChunk(chunk) { // Step 1: 将 Uint8Array 解码为字符串，处理 UTF-8 边界 let str = this.decoder.decode(chunk, { stream: true }); // Step 2: 合并上一次残留的 buffer（处理跨 chunk 的 UTF-8 字符） str = this.buffer + str; this.buffer = ''; // Step 3: 根据模式解析 if (this.sseMode) { this.parseSSE(str); } else { // 纯文本流：按行分割，每行视为一个 token const lines = str.split('\n'); for (let i = 0; i < lines.length; i++) { const line = lines[i].trim(); if (line && !line.startsWith(':')) { // 忽略 SSE 注释行 this.onToken(line); } } // 保存最后一行不完整部分到 buffer（如 "hel" + "lo" 跨 chunk） if (lines.length > 0 && str.endsWith('\n') === false) { this.buffer = lines[lines.length - 1]; } } } // 解析 SSE 格式：data: {...}\n\n parseSSE(str) { const lines = str.split('\n'); let currentEvent = ''; for (const line of lines) { if (line.startsWith('data: ')) { currentEvent += line.substring(6).trim(); } else if (line === '' && currentEvent) { try { const json = JSON.parse(currentEvent); if (json.delta?.content) { this.onToken(json.delta.content); } } catch (e) { this.onError('Invalid SSE JSON:', currentEvent); } currentEvent = ''; } // 忽略 event:、id:、retry: 等行 } // 未结束的 data 行存入 buffer if (currentEvent && !str.endsWith('\n')) { this.buffer = currentEvent; } } } // 使用示例 async function chatWithModel(messages) { const controller = new AbortController(); const response = await fetch('/api/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ messages }), signal: controller.signal, }); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } const reader = new LLMStreamReader(response, { onToken: (token) => { document.getElementById('output').textContent += token; // 这里可加光标闪烁、打字机效果等 }, onError: (msg, ...args) => console.warn(msg, ...args), onComplete: () => console.log('Stream finished'), }); await reader.start(); return controller; // 返回 controller 以便外部 abort } // 用户点击停止时 // const abortController = await chatWithModel([...]); // abortController.abort();

这个实现的关键细节：

  • UTF-8 边界处理：TextDecoder.decode(chunk, { stream: true })的stream: true参数至关重要。它告诉解码器“这可能不是完整的 UTF-8 序列”，避免将0xE4 0xBD 0xA0（“你”字）的前两个字节0xE4 0xBD当作无效字符输出 ``。未设置时，跨 chunk 的汉字必乱码。
  • SSE 状态机：不依赖正则全局匹配（易漏匹配），而是用currentEvent缓存未结束的data:行，确保{"content":"hello和world"}跨 chunk 也能正确拼接。
  • buffer 机制：this.buffer存储不完整行或不完整 JSON，是流式处理的基石。没有它，"你好\n世界"可能被切成"你好"和"世界"两次回调，破坏语义。
  • releaseLock()：reader.releaseLock()在 finally 块中调用，确保无论成功失败，流锁都被释放，避免内存泄漏。

提示：不要试图用response.body.pipeThrough(new TextDecoderStream())替代手动解码。TextDecoderStream是 TransformStream，它会创建新流，增加一层抽象，且对stream: true支持不如原生TextDecoder稳定。实测在 Chrome 120+ 中，TextDecoder.decode(chunk, { stream: true })的性能和兼容性均优于流式解码器。

5. 进阶：当fetch不够用——WebSocket 与自定义 HTTP Client 的取舍实战

fetch+ReadableStream是当前最主流的大模型流式方案，但它并非万能。当你的场景出现以下任一条件时，就得考虑替代方案：

  • 需要双向实时通信：比如用户边说边改提示词（real-time prompt editing），服务端需即时调整生成策略；
  • 长连接稳定性要求极高：fetch的 HTTP 连接在移动端易被系统回收，3G/4G 网络下断连率超 15%；
  • 定制化传输协议：如用 Protocol Buffers 序列化 token，而非 JSON/SSE，追求极致带宽压缩；
  • 服务端不支持 chunked：某些老旧网关或企业防火墙会 stripTransfer-Encoding头，强制转为Content-Length，导致流式失效。

这时，WebSocket和自定义 HTTP Client（如基于http模块的 Node.js 服务）成为备选。我用真实项目对比它们的适用边界：

5.1 WebSocket：适合“对话态强交互”场景，但增加运维复杂度

WebSocket 的优势在于全双工、低延迟、连接保活机制成熟。我曾为一个金融投研助手接入 WebSocket，实现“用户语音输入 → 实时转文字 → 模型流式生成 → 结果同步高亮原文段落”的闭环。整个链路端到端延迟压到 800ms 以内，fetch方案做不到。

但代价显著：

  • 服务端改造成本高：需部署 WebSocket server（如 ws 库），并维护连接池、心跳、重连逻辑；
  • CDN/反向代理穿透难：Cloudflare、阿里云 SLB 默认不支持 WebSocket upgrade，需额外配置；
  • 浏览器兼容性陷阱：iOS Safari 对WebSocket.binaryType = 'arraybuffer'支持不一致，导致 Protobuf 解析失败。

关键决策点：如果你的 UI 有“实时协作编辑”、“多人共享会话”、“语音打断重生成”等强交互需求，WebSocket 是刚需；如果只是“发消息→等回复→显示”，fetch更轻量可靠。

5.2 自定义 HTTP Client：Node.js 后端的终极控制权

前端fetch受限于浏览器安全策略（CORS、mixed content），而 Node.js 服务可以用http或undici模块直连大模型服务，完全掌控流式处理：

// Node.js 服务端示例（使用 undici，性能优于原生 http） import { request } from 'undici'; export async function streamToClient(req, res) { const { messages } = req.body; // 直连 vLLM 服务，绕过浏览器 CORS const { body, statusCode } = await request('http://localhost:8000/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen2.5-7b', messages }), }); // 将 vLLM 的流式响应，透传给前端 res.writeHead(statusCode, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', }); // pipe 透传，零拷贝 body.pipe(res); }

这种方式的优势：

  • 100% 控制流式头：可精确设置Content-Type、Cache-Control，避免浏览器代理篡改；
  • 无缝集成鉴权：在 Node.js 层统一处理 API Key、JWT，前端无需暴露密钥；
  • 错误熔断：undici支持retry、maxRedirections，比fetch的重试更可控。

但必须接受：你承担了反向代理的所有责任。包括连接池管理、超时控制、错误日志、负载均衡。一个没配置好的undiciclient，可能在高并发下创建数千个 TCP 连接，拖垮服务。

5.3 终极建议：80% 场景用fetch+ReadableStream，20% 特殊需求才升级

我的经验是：先用fetch+ReadableStream实现 MVP，跑通流式渲染、错误处理、用户中断。当真实用户反馈“在地铁切换基站时总断连”、“多人同时提问响应变慢”，再评估 WebSocket 或 Node.js 代理。过早引入复杂方案，只会让你在调试连接池和心跳包上浪费两周，而用户真正关心的是“回答准不准”。

最后分享一个血泪教训：某客户坚持用 WebSocket，结果上线后发现 iOS 16.4 的 Safari 存在一个 bug——WebSocket 连接在后台标签页恢复时，readyState保持OPEN但实际已断，send()不报错却无响应。我们花了 3 天定位，最终降级回fetch，用navigator.onLine+setTimeout模拟心跳，问题消失。技术选型，永远服务于真实场景，而非技术炫技。

我在实际使用中发现，最可靠的流式方案，往往是最朴素的那个：fetch建立连接，ReadableStream接收字节，TextDecoder解码，onToken更新 UI。它不酷，但足够稳；它不新，但经得起百万次并发考验。