流式 AI 输出与普通响应怎么选:原理、实现步骤与常见错误

文章目录

接入大模型接口时,几乎都会遇到同一个选择:让结果一次性返回,还是边生成边推给前端。前者实现简单,后者体感更快。但两者的差异远不止"快慢",它还会影响错误处理方式、能否使用结构化输出、网关与代理的配置,甚至影响调用成本。下面先把问题拆清楚,再给出可落地的实现步骤和边界判断。

两种响应形态的差异

一次性响应(普通响应)指服务端等上游生成完整结果后,再作为一个完整响应体返回。客户端拿到时,内容已经全部就绪。

流式响应指上游每生成一小段内容,服务端就把它转发给客户端,通常借助 HTTP 分块传输,配合 SSE(text/event-stream)、NDJSON 或 WebSocket 等格式。客户端边收边渲染。

两者的关键差异可以列成一张表:

维度一次性响应流式响应
用户看到首字的时机全部生成完成后第一个片段到达时
端到端总耗时基本不变基本不变
错误处理HTTP 状态码 + 完整响应体建连前用状态码,建连后只能用事件
结构化输出可直接解析完整 JSON需累积后解析,或增量解析
中间层兼容性好需关闭缓冲、注意压缩与空闲超时
取消与计费取消即放弃整次请求需显式中断上游生成
实现复杂度低中到高

最重要的一条是:流式输出并不会减少总耗时,它改变的是感知延迟。如果一次回答本身只需要很短时间,流式带来的收益有限,却要付出额外的复杂度。

选型:先看四个约束

在写代码之前,先回答四个问题,基本就能确定该用哪种形态。

  1. 用户是否必须等完整结果才能行动。 聊天、长文写作、代码生成这类场景,用户读到第一段就能判断方向对不对,适合流式。而"提交表单后返回一个 ID"这类场景,流式没有意义。
  2. 输出是否必须是严格结构化数据。 如果下游要直接消费 JSON、要校验字段、要触发函数调用,一次性返回更省事。流式下 JSON 是不完整的,中途解析会失败。
  3. 是否需要服务端先审核或校验再展示。 如果内容必须先过一遍敏感词、合规检查或格式校验,流式会把"未审核内容"提前暴露给用户,这时更适合非流式,或者采用"流式展示 + 结束后整体校验替换"的折中方案。
  4. 请求链路上的中间层是否可控。 反向代理、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() 之前不能有任何输出,否则头信息发不出去。

常见错误

  1. 缓冲没关干净。 代码里写了流式,但 Nginx、CDN 或压缩中间件把内容攒起来,用户看到的效果和一次性返回一样。排查方法是在每次 write 后打印时间戳,对比浏览器实际收到的时间。
  2. 按数据块边界解析。 网络分块与业务分片没有对应关系,一个 JSON 很可能被拆到两个 chunk 里。必须维护缓冲区,按行或按空行切分。
  3. 解码时没用流式模式。 TextDecoder 不加 { stream: true },中文字符跨块时会被解码成乱码。
  4. 流开始后才想用状态码报错。 头已经发出,500 无法回退,客户端可能把错误信息当正文渲染。
  5. 把结构化输出硬塞进流式。 直接对累积中的字符串调用 JSON.parse 必然失败;正确做法是累积完整后再解析,或者干脆改用一次性响应。
  6. 不处理断开。 用户关闭页面后上游仍在生成,既浪费额度,日志里也会留下"成功"的假象。
  7. 缺心跳或超时设置不合理。 长思考场景下连接被中间层判为空闲而切断,前端表现为"说到一半停住"。
  8. 误用 EventSource。 它只支持 GET,不能带自定义请求头,也无法发送请求体;需要 POST 时只能用 fetch 加流式读取。
  9. 取消后没有状态。 中途取消的请求在计费、审计、重试策略上都需要单独标记,否则统计口径会失真。

适用边界与折中方案

流式输出不是默认正确选项,它有明确的边界。

短回答不值得流式。 当完整结果很快就能返回时,流式的复杂度收益比很低。

强结构化场景优先非流式。 需要 JSON 校验、字段抽取、工具调用参数时,一次性返回加解析失败重试,逻辑要清晰得多。若必须流式展示,也要把"展示"和"消费"分开:展示可以增量,消费必须等完整后再做。

需要审核的链路要谨慎。 流式把内容提前暴露给用户,事后审核只能撤回不能预防。可以考虑后端先累积、审核通过后再一次性下发,或者对敏感场景直接使用非流式。

弱网与移动端要评估。 流式对连接稳定性更敏感,网络切换时更容易中断,需要前端做重连或重新请求的兜底。

一个实用的折中是同接口双模式:服务端保留 stream 参数,内部复用同一套上游调用与后处理逻辑,只在最外层决定逐段转发还是聚合返回。这样前端可以先上线非流式版本,等链路与监控稳定后再打开流式,出问题时也能快速切回。

最后提醒一点:无论选哪种,首片段延迟、总时长、取消率、错误事件数量这几项指标都值得记录。没有这些数据,关于"流式到底有没有用"的判断只能靠感觉。