大模型应用开发 / 系统课时
处理流式响应
处理流式响应
流式调用的难点不在“边生成边显示”,而在于正确处理任意分块、结束标记、网络中断和取消信号。本节用一个可运行的 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。
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`);
}预期输出
你好,世界
normal: completed
你
interrupted: connection reset切块位置是示例内部的人为设置;真实网络中的 chunk 大小和边界不可预测,但解析结果不应依赖这些边界。
处理结束、异常和主动取消
正常结束要同时满足“协议告诉你已经结束”和“客户端完成收尾”。如果连接直接关闭却没有协议结束标记,应把它视为不完整响应,而不是悄悄当成功。这样上层才能区分完整答案与被截断的答案。
网络中断后不要默认从头自动重试流式请求。若服务端已经生成并计费了一部分内容,简单重试可能产生重复文本或重复副作用。只有当请求本身可安全重放,并且你有去重、幂等键或服务端续传能力时,才适合自动恢复。
用户点击“停止生成”时,应通过 AbortController 或等价机制取消底层请求,并把“主动取消”转换成独立状态,而不是记录成系统故障。前端据此可以显示“已停止”,同时保留已接收文本。
前端追加不要等同于逐字符动画
模型返回的增量通常是 token 或短文本片段,不需要再人为逐字符延迟。最简单可靠的做法是每收到一个 delta 就追加到当前消息;高频更新时可以把多个 delta 暂存在内存中,再用 requestAnimationFrame 每帧批量刷新 DOM,减少重排。
前端还应维护 streaming、completed、cancelled、failed 等明确状态。只有收到协议结束标记后才能进入 completed;异常关闭进入 failed,用户主动中止进入 cancelled。这样 UI、日志和重试策略才不会混在一起。