AI API 流式输出中断后前端残缺怎么办？
AI API 接入流式输出时，如果网络中断、浏览器刷新或后端超时，应通过分片缓存、完成标记、重放接口和用户提示处理残缺内容。
真实问题
流式输出能让用户更快看到内容，但也会把“半成品”暴露给前端。一个资料摘要工具接入 AI API 后，用户刷新页面会看到一段没有结尾的报告，系统却把它当成完成结果保存。后续同事复制这段内容去做汇报，才发现关键结论缺失。问题不在流式本身，而在前端、后端和存储层没有区分 streaming、completed、interrupted 和 failed。
永沃云枢在 https://ai.jn83.com 的建议是，把流式输出当作一个有状态任务来管理，而不是简单把每个 chunk 追加到文本框。这样才能在 Codex 接入、开发者 AI 调用和 AI 自动化办公场景里同时兼顾体验与可靠性。
适用场景
适用于聊天回复、长文摘要、客服草稿、PPT 大纲、代码解释、知识库回答和运营文案生成。只要界面允许用户边生成边阅读，就要处理残缺输出。它也适合通过 CCSwitch 配置多个 AI 模型接口的团队，因为不同模型的首字延迟、分片间隔和超时表现可能不同，模型调用管理不能只看最终状态码。
操作步骤
第一步，为每次请求生成 response_id，并在数据库或缓存里保存 status、chunk_index、content_partial、finish_reason、updated_at。第二步，前端收到每个分片时只展示，不立即标记完成；后端收到结束事件或明确 finish_reason 后才写 completed。第三步，如果连接断开，将状态改为 interrupted，并保留已收到的分片和最后序号。第四步，提供重放接口：前端刷新后先读取 response_id，如果已完成就展示完整结果，如果中断就提示用户继续生成或重新生成。第五步，重新生成时使用幂等键和输入 hash，避免同一请求被重复扣费或重复写入。
实现时不要只依赖浏览器内存。浏览器刷新、移动端切后台、代理超时都会丢失内存状态。可以把分片缓存在 Redis、数据库临时表或任务日志里，保留时间按业务决定。对长内容，还可以每隔固定字符数保存 checkpoint，让 Codex 帮你检查恢复逻辑和前端状态文案是否一致。
排错路径
如果用户反馈“生成完成但少一截”，先查该 response_id 的 finish_reason 和最后 chunk_index。若没有完成标记，说明前端把 interrupted 当成 completed。若完成标记存在但文本缺尾，检查后端是否在流结束前关闭连接。若重复生成出两份结果，检查重试按钮是否复用了同一个幂等键。若费用异常升高，查看断线重连是否把完整上下文重新提交了多次。
流式输出排错还要关注代理层。Nginx、网关、Serverless 超时和浏览器 EventSource 限制都可能让连接提前断开。排查时分别记录模型开始时间、首个分片时间、最后分片时间、后端关闭时间和前端断开时间，才能判断瓶颈在 AI 模型接口、网络还是前端代码。
常见问题 / 避坑
问：残缺内容要不要自动续写？不建议默认自动续写，因为模型可能改变上下文，续写内容不一定和原生成一致。更稳的是让用户确认“继续生成”或“重新生成”。问：能否把每个 chunk 都入库？可以，但要控制写入频率，避免高并发下数据库压力过大。问：是否需要展示技术错误？用户侧只需要知道内容未完成，运维日志再保留错误码、request_id 和模型名。
检查清单
检查状态字段是否区分 streaming、completed、interrupted、failed；检查分片有序号；检查刷新页面能恢复状态；检查完成标记来自服务端结束事件；检查重试使用幂等键；检查用户界面不会把半截内容显示成正式结果；检查日志包含 response_id、模型名、耗时和断开原因。完成后再把流式输出纳入正式 AI API 接入流程。
验收与复盘
上线前可以做一次小型故障演练：让后端在第十个分片后主动断开，再刷新页面观察状态是否显示为中断；随后点击继续生成，确认不会把前半段内容重复写入，也不会把两个 response_id 混在一起。验收记录要包含浏览器刷新、移动端切后台、代理超时和用户主动取消四种情况。复盘时不要只写“已修复”，要说明最终采用了缓存还是数据库保存分片、保留多长时间、用户能看到什么提示，以及失败结果是否会进入业务表。这样后续更换 AI 模型接口或调整 CCSwitch 配置时，仍能快速判断流式链路是否健康。