大模型应用开发 / 系统课时

处理流式响应

处理流式响应

流式调用的难点不在“边生成边显示”,而在于正确处理任意分块、结束标记、网络中断和取消信号。本节用一个可运行的 SSE 消费器建立可靠的接收链路,并说明前端如何平滑追加增量文本。

学习目标

  • 区分网络分块、SSE 事件和模型增量内容,避免把一次 read() 当成一条完整消息。
  • 正确处理结束标记、UTF-8 跨块字符、异常中断和主动取消。
  • 将增量结果稳定地追加到前端,并明确何时允许重试。

先把流式数据拆成三层

一次流式响应通常要经过“字节块 → 协议事件 → 业务增量”三层解析。网络层可以在任意字节位置切块,所以一个 JSON 事件可能被拆成两次 read(),两个事件也可能合并在同一次读取里。消费者必须维护缓冲区,而不能逐块直接 JSON.parse()。

SSE 常用空行分隔事件,并用 data: 承载负载。本节示例约定 data: [DONE] 为结束标记;真实服务可能使用其他结束事件或字段,客户端应以具体协议为准。

流式响应从模型服务到前端的处理时序

实现一个可验证的 SSE 消费器

下面的 Node.js 20+ 示例不依赖外部服务:它先构造一个会故意切碎 UTF-8 字节和 SSE 边界的流,再用同一个消费器解析正常结束与异常中断两种情况。关键点是 TextDecoder.decode(..., { stream: true }) 和跨读取保留 buffer。

js
function makeStream(frames, failAfter = -1) {
  const bytes = new TextEncoder().encode(frames.join(""));
  const cuts = [5, 11, 19, 27, 36, bytes.length];
  let start = 0;
  let index = 0;

  return new ReadableStream({
    pull(controller) {
      if (failAfter >= 0 && index === failAfter) {
        controller.error(new Error("connection reset"));
        return;
      }
      if (start >= bytes.length) {
        controller.close();
        return;
      }

      const end = cuts[index] ?? bytes.length;
      controller.enqueue(bytes.slice(start, end));
      start = end;
      index += 1;
    }
  });
}

async function consumeSSE(stream, onDelta) {
  const reader = stream.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;

      // 保留解码器内部状态,避免中文等多字节字符跨块时被破坏。
      buffer += decoder.decode(value, { stream: true });

      let boundary;
      while ((boundary = buffer.indexOf("\n\n")) >= 0) {
        const event = buffer.slice(0, boundary);
        buffer = buffer.slice(boundary + 2);

        for (const line of event.split("\n")) {
          if (!line.startsWith("data:")) continue;
          const data = line.slice(5).trim();

          if (data === "[DONE]") return;
          const payload = JSON.parse(data);
          onDelta(payload.delta ?? "");
        }
      }
    }

    throw new Error("stream ended without [DONE]");
  } finally {
    reader.releaseLock();
  }
}

const normalFrames = [
  'data: {"delta":"你"}\n\n',
  'data: {"delta":"好,"}\n\n',
  'data: {"delta":"世界"}\n\n',
  'data: [DONE]\n\n'
];

await consumeSSE(makeStream(normalFrames), text => process.stdout.write(text));
process.stdout.write("\nnormal: completed\n");

try {
  await consumeSSE(makeStream(normalFrames, 4), text => process.stdout.write(text));
} catch (error) {
  process.stdout.write(`\ninterrupted: ${error.message}\n`);
}

预期输出

text
你好,世界
normal: completed
你
interrupted: connection reset

切块位置是示例内部的人为设置;真实网络中的 chunk 大小和边界不可预测,但解析结果不应依赖这些边界。

处理结束、异常和主动取消

正常结束要同时满足“协议告诉你已经结束”和“客户端完成收尾”。如果连接直接关闭却没有协议结束标记,应把它视为不完整响应,而不是悄悄当成功。这样上层才能区分完整答案与被截断的答案。

网络中断后不要默认从头自动重试流式请求。若服务端已经生成并计费了一部分内容,简单重试可能产生重复文本或重复副作用。只有当请求本身可安全重放,并且你有去重、幂等键或服务端续传能力时,才适合自动恢复。

用户点击“停止生成”时,应通过 AbortController 或等价机制取消底层请求,并把“主动取消”转换成独立状态,而不是记录成系统故障。前端据此可以显示“已停止”,同时保留已接收文本。

前端追加不要等同于逐字符动画

模型返回的增量通常是 token 或短文本片段,不需要再人为逐字符延迟。最简单可靠的做法是每收到一个 delta 就追加到当前消息;高频更新时可以把多个 delta 暂存在内存中,再用 requestAnimationFrame 每帧批量刷新 DOM,减少重排。

前端还应维护 streaming、completed、cancelled、failed 等明确状态。只有收到协议结束标记后才能进入 completed;异常关闭进入 failed,用户主动中止进入 cancelled。这样 UI、日志和重试策略才不会混在一起。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理流式响应

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通