流式输出断开时，最先要确认的是已经收到什么
流式调用把一次完整结果拆成许多事件发送，网络连接中断并不表示模型没有输出。客户端可能已经收到前半段，代理可能缓存了几帧，服务端也可能已经生成完成但最后的结束事件没有到达。若前端只保存一个不断增长的字符串，重连后再拼一次，常见结果就是重复句子、缺少结尾或把半个 JSON 当成完整对象。
AI API 接入时，建议把“文本内容”和“传输事件”分开保存。模型调用管理至少要知道 request_id、事件序号、收到时间、finish_reason、错误类型和最后确认的序号。这样即使实际使用了 CCSwitch 配置或多个 AI 模型接口，也能判断是上游没有继续发送，还是本地重组逻辑漏了事件。
适用场景
适合聊天流式回答、长文档摘要、Codex 接入后的长任务日志、AI 自动化办公的逐步生成结果，以及通过代理或网关转发的 SSE、WebSocket 类调用。前提是客户端可以保存临时会话，服务端或上游能提供事件编号、游标或可查询的任务状态；如果上游没有恢复能力，也要明确采用“重新请求并去重”而不是假装支持续传。
操作步骤：用事件序号重组一段完整结果
- 先记录传输元数据。每次请求保存
request_id、provider、model、prompt_version、连接开始时间和客户端生成的 session_id。不要只把最后文本写入数据库。 - 为每个事件保留序号。无论上游字段叫 sequence、index 还是 event_id，都在自己的日志中转成统一字段，并保存原始事件摘要。相同序号再次出现时，按幂等规则覆盖或忽略。
- 区分已确认和仅收到。客户端收到事件后先写入临时缓冲，完成校验或持久化后再推进 last_acked_sequence。断线重连只从最后确认位置开始请求，不能从页面当前字数猜位置。
- 处理半截结构。若输出是 JSON、Markdown 表格或代码块，先按事件边界缓存，等结束事件或完整结构校验通过后再交给业务层。不要在半截 JSON 上触发自动化办公写回。
- 设置恢复上限。连续重连、事件序号回退、超过时间窗口或模型路由变化时，应转为人工复核或一次全量重试，并记录原因。
一个具体的失败表现
常见问题是浏览器显示了三段文字，刷新后又出现第二段两次。检查日志时发现第一次连接收到了序号 1 到 18，前端只在内存里保存了文本；第二次连接从序号 1 重新订阅，服务端返回的内容被直接 append。另一个问题是编码正常但最后一个工具调用事件缺失，业务误判为“模型已经完成”，于是把不完整结果写入工单。
排查可以从本地日志开始：rg "request_id|sequence|event_id|finish_reason|reconnect" logs src。若前端正常而服务端日志没有对应 request_id，应检查 AI API 网关和 CCSwitch 配置的实际路由；若服务端有完整序列而页面缺片段，再看代理缓冲、前端解码和事件分发。关于中文字节和流式分片，可参考 AI API 中文乱码与流式分片排查；关于重复任务，参考 超时重试的幂等设计。
常见问题 / 避坑
不要把 TCP 连接重新建立当成业务续传，连接恢复只解决网络层问题。不要只依赖前端内存，页面刷新、移动端切后台和浏览器崩溃都会丢失游标。不要在每个模型接口都使用不同的事件字段而不做归一化，否则切换模型后排错会变成猜测。还要注意代理层可能合并小事件，验收时应使用真实网络路径，而不是只在本机直连测试。
如果业务需要把流式结果交给 Codex、AI 自动化办公或其他开发者 AI 调用链路，最好在“完整结果已确认”之后再触发下一步。永沃云枢的实践口径是先保证可复核，再追求更快展示；https://ai.jn83.com 上的 AI 模型接口接入也应把传输状态与业务状态分开看。
检查清单
- 每个流式事件都有可追踪的 request_id 和统一序号。
- 临时缓冲、已确认序号和最终结果分别保存。
- 重复事件不会造成文本、工具调用或费用记录重复。
- 半截 JSON、代码块和表格不会直接触发下游写回。
- 断线重连有次数、时间和路由变化上限。
- 站内可继续查看 webhook 重放检查、HTTP 200 业务失败排查、AI API 接入专题 和 Codex 资讯栏目。
FAQ：上游没有事件序号还能恢复吗
可以做有限恢复，但不能称为精确续传。客户端可以为每次业务动作生成幂等键，重连后查询任务状态；如果只能重新生成，就需要按段落、工具调用或最终结果做去重，并接受少量重复计算。对于涉及费用、发送消息或写入文件的任务，宁可转人工确认，也不要用字符串相似度冒险合并。
流式接口的验收重点不是“页面会动”，而是中断、重连、重复事件和不完整结果都能被识别。做到事件级证据，AI API 接入和模型调用管理才真正可维护。