自定义React前端调用本地模型API时处理流式响应追加内容和错误中断的方法

文章导读
在 React 前端里调用本地模型 API 做流式输出时,最常遇到的问题不是“连不上”,而是“连上了但不知道什么时候算完”。本地模型接口通常返回 SSE 格式的数据块,前端拿到后逐段追加到页面上。这里记录一下我在处理追加内容和错误中断时常用的判断方式,以及几个容易漏掉的边界。
📋 目录
  1. 一 结束标记比 fetch 完成更可信
  2. 二 按块解码时,残段和锁释放是核心
  3. 三 错误中断发生后,把状态改回 error 而不是 completed
  4. 四 辅助判断:心跳和 token 计数
A A

在 React 前端里调用本地模型 API 做流式输出时,最常遇到的问题不是“连不上”,而是“连上了但不知道什么时候算完”。本地模型接口通常返回 SSE 格式的数据块,前端拿到后逐段追加到页面上。这里记录一下我在处理追加内容和错误中断时常用的判断方式,以及几个容易漏掉的边界。

结束标记比 fetch 完成更可信

“渲染到一半突然停了”,这个现象大多数时候不是服务端没返回,而是前端把“连接关闭”当成了“正常结束”。

判断流式响应是否正常结束,不能仅依赖fetch的Promise完成,因为连接可能在body未读完时被中断。更可靠的方式是检查SSE格式中的`[DONE]`标记,或解析每行数据中的`finish_reason`字段。如果使用OpenAI兼容接口,通常最后一个data块会包含`finish_reason:"stop"`或`"length"`。如果服务端不提供这些标记,则需要自行约定,比如在结束前发送一段特殊标识。注意,浏览器网络面板中看到200状态码并不代表流已完整接收,可能只是响应头已返回。

所以在读取循环里,不能只等 response.body.getReader().read() 返回 done。要在每个 data 块中检查终止标记。下面的函数实现了这个过程:

async function readSSE(response, onDelta, onFinish, onError) {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  try {
    while (true) {
      const { done, value } = 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) {
        const trimmed = line.trim();
        if (trimmed.startsWith('data:')) {
          const payload = trimmed.slice(5).trim();
          if (payload === '[DONE]') {
            onFinish('done');
            return;
          }
          try {
            const json = JSON.parse(payload);
            if (json.choices && json.choices[0] && json.choices[0].finish_reason) {
              onFinish(json.choices[0].finish_reason);
              return;
            }
            const delta = json.choices?.[0]?.delta?.content;
            if (delta) onDelta(delta);
          } catch (parseError) {
            // 可能是多行 JSON 的中间片段,忽略本次
          }
        }
      }
    }
    onError(new Error('流意外结束,未收到结束标记'));
  } finally {
    decoder.decode();
    reader.releaseLock();
  }
}

这个函数放在 fetch 调用拿到 response 之后执行。验证方式是跑一次正常对话,看 onFinish 是否收到 done 或 stop。如果一直跑到 onError,优先检查服务端返回的原始报文里有没有 [DONE] 或 finish_reason。如果都没有,就需要按你的模型接口约定修改结束判断。

自定义React前端调用本地模型API时处理流式响应追加内容和错误中断的方法

按块解码时,残段和锁释放是核心

用 getReader 读流时,不能把每次读取到的字节直接当成一行。因为一个中文可能被拆在两个 chunk 里。下面这段是处理 SSE 时常见的做法,重点是缓存残段和释放 reader。

在React中处理流式响应,建议用fetch返回的response.body.getReader()创建可读流读取器,通过TextDecoder按块解码。解码后按换行符分隔,因为SSE数据以`data:`开头,每行一条。需要缓存未换行的残段,等下一块到达时拼接,避免中文被截断导致乱码。每解析出一条完整数据,就调用setState追加内容,同时记得将解码器重置为stream模式,如`decoder.decode(value, {stream: true})`,并在结束时调用`decoder.decode()`刷新残留。这一操作要放在try-finally中,确保finally里执行reader.releaseLock()。

下面是一个在 useEffect 中执行的可取消请求。组件卸载时通过 AbortController 中断 read,避免 setState 产生警告。

useEffect(() => {
  let isCancelled = false;
  const controller = new AbortController();
  const decoder = new TextDecoder();
  let buffer = '';

  async function start() {
    let reader = null;
    try {
      const response = await fetch('/api/chat', {
        method: 'POST',
        body: JSON.stringify({ messages: [{ role: 'user', content: '你好' }] }),
        signal: controller.signal,
      });
      if (!response.ok || !response.body) throw new Error('请求失败');

      reader = response.body.getReader();
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        if (isCancelled) return;

        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 data = line.slice(5).trim();
          if (data === '[DONE]') {
            setStatus('completed');
            return;
          }
          try {
            const json = JSON.parse(data);
            const delta = json.choices?.[0]?.delta?.content;
            if (delta) setContent((prev) => prev + delta);
            if (json.choices?.[0]?.finish_reason) {
              setStatus('completed');
              return;
            }
          } catch (e) {
            // 忽略不完整 JSON
          }
        }
      }
      setStatus('error');
    } catch (error) {
      if (!isCancelled) {
        setStatus('error');
        setError(error);
      }
    } finally {
      decoder.decode();
      if (reader) reader.releaseLock();
    }
  }

  start();

  return () => {
    isCancelled = true;
    controller.abort();
  };
}, []);

注意这里 reader 是在 try 块内赋值的,finally 中可以直接访问它。验证方式是组件卸载时观察浏览器 Network 面板,请求应该被取消。如果取消后 catch 块仍然执行,检查 isCancelled 标志是否在读取后立即检查。

自定义React前端调用本地模型API时处理流式响应追加内容和错误中断的方法

错误中断发生后,把状态改回 error 而不是 completed

“输出一半”的界面最坑人的不是内容缺失,而是状态显示“已完成”。

一个常见坑是错误中断发生在部分内容已追加之后,前端没有回滚机制。用户会看到半句文本,且状态被标记为完成。解决方法是给每次请求生成唯一标识,在追加内容时同时记录已渲染的起始偏移量。如果捕获到网络错误或解析异常,立即抛出一个错误对象,并利用useState中的prevState回退到最近一次完整快照。如果回退成本高,至少要在UI上显示醒目的“输出中断”提示,并保留已接受内容——但需要将状态改为error,而不是completed,以防用户误判为最终结果。

实现时可以用一个 ref 记录最近一次完整内容,在每次追加前保存旧值。出错时回滚到旧值,并把 status 设为 error。下面的代码展示了这个思路:

自定义React前端调用本地模型API时处理流式响应追加内容和错误中断的方法
const lastGoodRef = useRef('');
const [content, setContent] = useState('');
const [status, setStatus] = useState('idle');

function appendDelta(delta) {
  // 在追加前保存当前内容作为最近完整快照
  lastGoodRef.current = content;
  const newContent = content + delta;
  setContent(newContent);
}

function rollback() {
  setContent(lastGoodRef.current);
  setStatus('error');
}

// 在 catch 或解析失败时调用 rollback()

这个实现的关键在于 appendDelta 里用 content 作为快照,但注意 React 的 state 是异步更新的,直接读取 content 可能拿不到最新值。要严格做到回退,最好把内容放在 ref 里,作为唯一数据源,state 只用于渲染。比如用 contentRef.current 保存最新内容,追加时同步更新 ref 和 state。上面代码只是演示,实际使用建议用 useReducer 管理。

辅助判断:心跳和 token 计数

如果服务端不提供结束标记,或者你想提前发现连接异常,可以在前端维护一个心跳计时器。比如设置 30 秒内没有收到任何数据块,就主动把状态改为 error。实现时用一个 setTimeout,每次成功解析一个 data 块就重置计时器。同时监听 readable 流的 cancel 事件和 AbortSignal 的 abort 事件,这些都能帮你区分是主动取消还是意外中断。

另外,如果你的模型接口支持在结束标记里携带 token 数量,可以拿到这个数字和本地计数器比对。但流式生成时最终内容未知,不能靠字符数校验完整性,只能当参考。

本地模型 API 的流式实现差异较大,最稳妥的方式是在代码里同时检查 [DONE] 和 finish_reason,并把异常中断统一映射为 error 状态。这样即使服务端某个字段延迟或缺失,界面也不会把半截内容当成最终结果。