AI 流式响应如何判断结束：增量片段、完成事件与断线续接

接入 AI 流式接口后，最容易出现的 bug 不是“模型没返回”，而是前端把某个增量片段误当成结尾：光标停住了，连接却还没收尾；或者网络抖动后同一段文字被追加两次。可靠做法是把文本片段和响应状态分开处理，只有收到最终完成事件并确认状态成功，才把答案标记为可提交。

先把“有文字”与“已结束”分成两件事

以 Server-Sent Events 为例，服务端会连续发出多个事件。文本增量到达时，客户端可以立即更新页面；但这只说明当前有一小段内容可显示。真正的结束信号应来自完成类事件，随后再查看最终状态字段。

官方流式事件文档把文本增量、文本完成和响应完成分开定义。工程上可以把它们理解成三层信号：内容层负责显示，内容块层负责封口，响应层负责给出最终结果。

客户端状态机应该记录哪些状态

不要只维护一个 isLoading 布尔值。至少要能区分“尚未开始”“正在接收”“等待最终状态”“成功完成”“失败”“被取消”和“等待恢复”。这样，网络断开时不会把半截答案误显示成完整结果。

用完成事件做最终验收，而不是猜最后一段文字

下面的伪代码刻意把“展示文本”和“结束判定”分开。实际 SDK 的事件名称可能略有差异，但判断顺序不应改变：

let text = "";
let state = "receiving";
const seen = new Set();

for await (const event of stream) {
  if (event.sequence_number && seen.has(event.sequence_number)) continue;
  if (event.sequence_number) seen.add(event.sequence_number);

  if (event.type === "response.output_text.delta") {
    text += event.delta;
    render(text, "generating");
  } else if (event.type === "response.output_text.done") {
    state = "finalizing";
  } else if (event.type === "response.done") {
    state = event.response.status === "completed" ? "completed" : "failed";
    finish(text, state);
  }
}

这里有两个关键点。第一，response.output_text.done 表示文本部分结束，不等于整个响应一定成功；第二，最终响应可能是失败、取消或不完整，业务层要把这些结果分别记录，不能统一显示“生成完成”。

断线续接：保留内容，但不要盲目重放

连接断开后，最危险的处理是重新发起请求并把新流直接拼到旧文本后面。若服务端已经生成了一部分内容，用户会看到重复句子。更稳妥的做法是保存响应标识、最后处理的事件序号和当前文本摘要，再根据服务端支持的恢复能力决定续接或重新生成。

1. 收到网络错误时进入 recovering，保留当前文本和最后事件序号。
2. 如果接口支持恢复，使用同一个响应标识请求未确认事件；新事件先经过序号去重。
3. 如果接口不支持恢复，明确提示用户“正在重新生成”，不要把两次结果伪装成一条连续响应。
4. 只有重新收到最终完成事件并核对成功状态，才允许保存或提交答案。

常见问题

收到文本完成事件后还要等响应完成事件吗？

要。文本完成只封闭文本内容，最终响应状态才决定这次请求是成功、失败、取消还是不完整。

为什么不能用空字符串或句号判断结束？

模型可能在任意位置停顿，最后一个片段也可能是标点或空白。内容特征不是协议状态，无法覆盖异常和取消场景。

断线重连一定能接着原来的流吗？

不一定，取决于服务端是否提供响应恢复或事件重放能力。客户端应把“可恢复”和“重新生成”设计成两个明确分支。

前端什么时候可以开放复制按钮？

至少等最终完成事件到达，并确认最终状态为成功；如果产品允许复制草稿，也要明确标记为未完成内容。

上线前的最小验收清单

测试时不要只覆盖正常长文本，还应人为制造短响应、空片段、重复事件、主动取消和连接中断。检查日志里是否能关联响应标识、事件序号和最终状态；检查页面上是否会出现两次相同句子，或者失败后仍显示“已完成”。

流式体验的核心不是把字更快地画出来，而是让每一段展示都有可追踪的状态，最终结果也有明确的协议依据。