在 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。如果都没有,就需要按你的模型接口约定修改结束判断。
按块解码时,残段和锁释放是核心
用 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 标志是否在读取后立即检查。
错误中断发生后,把状态改回 error 而不是 completed
“输出一半”的界面最坑人的不是内容缺失,而是状态显示“已完成”。
一个常见坑是错误中断发生在部分内容已追加之后,前端没有回滚机制。用户会看到半句文本,且状态被标记为完成。解决方法是给每次请求生成唯一标识,在追加内容时同时记录已渲染的起始偏移量。如果捕获到网络错误或解析异常,立即抛出一个错误对象,并利用useState中的prevState回退到最近一次完整快照。如果回退成本高,至少要在UI上显示醒目的“输出中断”提示,并保留已接受内容——但需要将状态改为error,而不是completed,以防用户误判为最终结果。
实现时可以用一个 ref 记录最近一次完整内容,在每次追加前保存旧值。出错时回滚到旧值,并把 status 设为 error。下面的代码展示了这个思路:
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 状态。这样即使服务端某个字段延迟或缺失,界面也不会把半截内容当成最终结果。