接入大模型接口时,几乎都会遇到同一个选择:让结果一次性返回,还是边生成边推给前端。前者实现简单,后者体感更快。但两者的差异远不止"快慢",它还会影响错误处理方式、能否使用结构化输出、网关与代理的配置,甚至影响调用成本。下面先把问题拆清楚,再给出可落地的实现步骤和边界判断。
两种响应形态的差异
一次性响应(普通响应)指服务端等上游生成完整结果后,再作为一个完整响应体返回。客户端拿到时,内容已经全部就绪。
流式响应指上游每生成一小段内容,服务端就把它转发给客户端,通常借助 HTTP 分块传输,配合 SSE(text/event-stream)、NDJSON 或 WebSocket 等格式。客户端边收边渲染。
两者的关键差异可以列成一张表:
| 维度 | 一次性响应 | 流式响应 |
|---|---|---|
| 用户看到首字的时机 | 全部生成完成后 | 第一个片段到达时 |
| 端到端总耗时 | 基本不变 | 基本不变 |
| 错误处理 | HTTP 状态码 + 完整响应体 | 建连前用状态码,建连后只能用事件 |
| 结构化输出 | 可直接解析完整 JSON | 需累积后解析,或增量解析 |
| 中间层兼容性 | 好 | 需关闭缓冲、注意压缩与空闲超时 |
| 取消与计费 | 取消即放弃整次请求 | 需显式中断上游生成 |
| 实现复杂度 | 低 | 中到高 |
最重要的一条是:流式输出并不会减少总耗时,它改变的是感知延迟。如果一次回答本身只需要很短时间,流式带来的收益有限,却要付出额外的复杂度。
选型:先看四个约束
在写代码之前,先回答四个问题,基本就能确定该用哪种形态。
- 用户是否必须等完整结果才能行动。 聊天、长文写作、代码生成这类场景,用户读到第一段就能判断方向对不对,适合流式。而"提交表单后返回一个 ID"这类场景,流式没有意义。
- 输出是否必须是严格结构化数据。 如果下游要直接消费 JSON、要校验字段、要触发函数调用,一次性返回更省事。流式下 JSON 是不完整的,中途解析会失败。
- 是否需要服务端先审核或校验再展示。 如果内容必须先过一遍敏感词、合规检查或格式校验,流式会把"未审核内容"提前暴露给用户,这时更适合非流式,或者采用"流式展示 + 结束后整体校验替换"的折中方案。
- 请求链路上的中间层是否可控。 反向代理、CDN、负载均衡、压缩中间件都可能缓冲响应,导致流式变成"一次性到达"。如果这些层不受你控制,流式的收益可能被完全吃掉。
经验上可以这样划分:面向人的长文本、对话、代码补全倾向于流式;面向程序的批处理、结构化抽取、需要二次加工的任务倾向于非流式。
服务端转发:可操作步骤
多数应用不会让浏览器直连模型服务,而是经过自己的后端转发。转发层要做的事比想象中多。
第一步,明确接口契约。 建议用同一个端点加 stream 布尔参数,或拆成两个端点,但响应格式要写进文档:是 SSE 帧、还是每行一个 JSON。约定好结束标记(例如 event: done 或 [DONE])和错误事件格式。
第二步,设置正确的响应头。 至少包括:Content-Type: text/event-stream; charset=utf-8、Cache-Control: no-cache, no-transform。no-transform 用于阻止中间层改写或压缩内容。
第三步,关闭缓冲。 这是最常见的失败点:
- Nginx 需要
proxy_buffering off;,也可以用响应头X-Accel-Buffering: no提示它; - 压缩中间件可能为了压缩效率而攒批,需要对该路由关闭 gzip,或至少关闭压缩缓冲;
- PHP 需要清理输出缓冲(
ob_end_flush()等)并在每段输出后flush(); - 不要在流式处理函数外面套会读取完整响应体的中间件。
第四步,加心跳。 上游思考时间较长时,连接可能空闲很久,被代理按空闲超时切断。定期发送一行注释(SSE 中以 : 开头的行)即可保活。
第五步,处理客户端断开。 监听连接关闭事件,主动中断上游请求,否则用户关掉页面后上游仍在生成,白白消耗额度。
第六步,错误分两段处理。 响应头发出之前出错,可以返回普通状态码;响应头发出之后出错,HTTP 状态码已经无法更改,只能通过一个 error 事件把错误告诉客户端。这一点必须在协议设计阶段就定好。
第七步,结束后再落库。 日志、计费、审计要等流真正结束(或确认被取消)之后再写,并且记录首片段时间和总时长,便于排查。
代码示例:Node.js 转发与浏览器解析
下面是一个最小化的服务端转发骨架,使用 Node.js 原生 http 与全局 fetch,重点在缓冲、心跳、断开与半包处理。
const http = require('node:http');
const server = http.createServer(async (req, res) => {
if (req.method !== 'POST' || req.url !== '/api/stream') {
res.writeHead(404).end();
return;
}
res.writeHead(200, {
'Content-Type': 'text/event-stream; charset=utf-8',
'Cache-Control': 'no-cache, no-transform',
'X-Accel-Buffering': 'no',
});
const heartbeat = setInterval(() => res.write(': ping\n\n'), 15000);
const controller = new AbortController();
// 客户端断开时,停止上游生成
res.on('close', () => {
clearInterval(heartbeat);
controller.abort();
});
try {
const upstream = await fetch(process.env.AI_ENDPOINT, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.AI_KEY}`,
},
body: JSON.stringify({ model: 'your-model', stream: true, messages: [] }),
signal: controller.signal,
});
if (!upstream.ok) {
// 响应头已发出,只能用事件报错
res.write(`event: error\ndata: {"message":"upstream ${upstream.status}"}\n\n`);
return;
}
const reader = upstream.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop() ?? ''; // 最后一行可能不完整,留到下一轮
for (const line of lines) {
if (!line.startsWith('data:')) continue;
const payload = line.slice(5).trim();
if (payload === '[DONE]') {
res.write('event: done\ndata: {}\n\n');
continue;
}
let delta = '';
try {
delta = JSON.parse(payload).choices?.[0]?.delta?.content ?? '';
} catch {
continue; // 单个分片解析失败不应中断整条流
}
if (delta) res.write(`data: ${JSON.stringify({ delta })}\n\n`);
}
}
} catch (err) {
if (err.name !== 'AbortError') {
res.write('event: error\ndata: {"message":"stream failed"}\n\n');
}
} finally {
clearInterval(heartbeat);
res.end();
}
});
server.listen(3000);浏览器端用 fetch 而不是 EventSource,因为需要 POST 和自定义请求头。解析时要按 SSE 的空行分帧,并保留不完整尾部:
async function streamChat(body, onDelta) {
const res = await fetch('/api/stream', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const frames = buffer.split('\n\n');
buffer = frames.pop() ?? ''; // 保留未完成的帧
for (const frame of frames) {
let event = 'message';
const data = [];
for (const line of frame.split('\n')) {
if (line.startsWith('event:')) event = line.slice(6).trim();
else if (line.startsWith('data:')) data.push(line.slice(5).trim());
}
const text = data.join('\n');
if (event === 'error') {
throw new Error(text || 'stream error');
}
if (event === 'done') return;
if (text) onDelta(JSON.parse(text));
}
}
}如果后端是 PHP,头设置类似:
<?php
header('Content-Type: text/event-stream; charset=utf-8');
header('Cache-Control: no-cache, no-transform');
header('X-Accel-Buffering: no');
while (ob_get_level() > 0) { ob_end_flush(); }
set_time_limit(0);
// 每输出一段后调用 flush(),并检测 connection_aborted()注意 header() 之前不能有任何输出,否则头信息发不出去。
常见错误
- 缓冲没关干净。 代码里写了流式,但 Nginx、CDN 或压缩中间件把内容攒起来,用户看到的效果和一次性返回一样。排查方法是在每次
write后打印时间戳,对比浏览器实际收到的时间。 - 按数据块边界解析。 网络分块与业务分片没有对应关系,一个 JSON 很可能被拆到两个 chunk 里。必须维护缓冲区,按行或按空行切分。
- 解码时没用流式模式。
TextDecoder不加{ stream: true },中文字符跨块时会被解码成乱码。 - 流开始后才想用状态码报错。 头已经发出,
500无法回退,客户端可能把错误信息当正文渲染。 - 把结构化输出硬塞进流式。 直接对累积中的字符串调用
JSON.parse必然失败;正确做法是累积完整后再解析,或者干脆改用一次性响应。 - 不处理断开。 用户关闭页面后上游仍在生成,既浪费额度,日志里也会留下"成功"的假象。
- 缺心跳或超时设置不合理。 长思考场景下连接被中间层判为空闲而切断,前端表现为"说到一半停住"。
- 误用
EventSource。 它只支持 GET,不能带自定义请求头,也无法发送请求体;需要 POST 时只能用fetch加流式读取。 - 取消后没有状态。 中途取消的请求在计费、审计、重试策略上都需要单独标记,否则统计口径会失真。
适用边界与折中方案
流式输出不是默认正确选项,它有明确的边界。
短回答不值得流式。 当完整结果很快就能返回时,流式的复杂度收益比很低。
强结构化场景优先非流式。 需要 JSON 校验、字段抽取、工具调用参数时,一次性返回加解析失败重试,逻辑要清晰得多。若必须流式展示,也要把"展示"和"消费"分开:展示可以增量,消费必须等完整后再做。
需要审核的链路要谨慎。 流式把内容提前暴露给用户,事后审核只能撤回不能预防。可以考虑后端先累积、审核通过后再一次性下发,或者对敏感场景直接使用非流式。
弱网与移动端要评估。 流式对连接稳定性更敏感,网络切换时更容易中断,需要前端做重连或重新请求的兜底。
一个实用的折中是同接口双模式:服务端保留 stream 参数,内部复用同一套上游调用与后处理逻辑,只在最外层决定逐段转发还是聚合返回。这样前端可以先上线非流式版本,等链路与监控稳定后再打开流式,出问题时也能快速切回。
最后提醒一点:无论选哪种,首片段延迟、总时长、取消率、错误事件数量这几项指标都值得记录。没有这些数据,关于"流式到底有没有用"的判断只能靠感觉。