AI API 流式输出页面卡住怎么办？
AI API 流式输出接上以后，用户最常反馈的不是“完全没有响应”，而是页面转圈、只显示半截、最后几行迟迟不出来，或者刷新后重复提交。这个问题可能在模型、代理、后端、前端任意一层，排查时要把数据流和用户状态分开看。
适用场景：接口在吐字，页面却像没动
这篇适合聊天窗口、客服摘要、长文生成、AI 自动化办公报告和知识库问答的流式输出页面。你可能看到浏览器 Network 里有数据，但页面不刷新；或者服务端日志显示模型已返回，用户端仍在等待。如果是连接中途断流，可先看 AI API 流式输出总是中断怎么办；如果同时出现 429 和排队变慢，则先参考 AI API 突然限流怎么办。
先拆链路：模型、后端、代理、浏览器
流式输出卡住，不能只说“模型慢”。模型可能正常返回 token，后端可能没有及时 flush，代理可能缓冲，浏览器可能因为解析器等待完整 JSON 才渲染，前端状态机也可能把完成事件丢掉。排查时按层记录时间点：请求发出、首 token、每段 chunk、结束事件、前端渲染和保存结果。
操作步骤：用可观测的事件替代猜测
1. 先用命令行复现流式响应
用 curl -N 或类似工具直连后端接口，观察是否能逐段输出。若命令行正常、浏览器卡住，优先查前端解析和代理头；若命令行也等到最后才输出，查后端 flush 或网关缓冲。为了保护 Key，不要把完整 Authorization 写进截图或日志，必要时只保留前后几位标识。
2. 检查代理和响应头
反向代理可能默认缓冲响应，导致服务端一段段写出，用户端却等到缓冲满才看到。检查 Content-Type、Cache-Control、压缩、Nginx buffering、HTTP/2 行为和超时设置。SSE 场景建议明确事件格式，普通 fetch stream 则要确认前端逐段读取 reader，而不是等待完整 body。
3. 前端要有断线和取消状态
只做“发送中”一个状态不够。建议拆成排队、生成中、断线重连、用户取消、服务端完成、保存失败。用户点击取消时，后端也要收到取消信号或把结果标记为废弃，避免模型继续消耗额度。需要看谁在消耗额度时，可参考 AI API 接入后怎么知道谁在消耗额度，把 request_id 和用户标识写进日志。
4. 不要把结构化结果和流式文本混在一起
有些页面一边流式显示文本，一边要求最后返回 JSON。这样很容易出现前面能看、最后解析失败的情况。开发者 AI 调用可以把展示流和保存结构分开：前端显示 token，后端在结束后再做结构化校验。JSON 字段契约可参考 开发者调用 AI 模型时怎么约定 JSON 输出。
常见问题/避坑：用户刷新不等于任务取消
第一个坑是用户刷新页面后，后台任务仍在跑，用户又发起第二次请求，最后生成两份结果。第二个坑是前端只根据连接关闭判断成功，却没有检查结束事件和保存状态。第三个坑是代理开启压缩后影响小 chunk 刷新。第四个坑是把所有超时都设成同一个值，短问答和长文报告被同一套规则误伤。
还有一个容易忽略的模型调用管理问题：不同 AI 模型接口的首 token 时间和输出节奏不同。通过 CCSwitch 配置多模型时，要记录模型名、首 token 时间、平均 chunk 间隔和总耗时，否则切换模型后很难判断是接口慢，还是前端状态处理有问题。
排查前端卡顿时，可以准备三组固定样本：一句话问答、一段两千字摘要、一份需要十几秒生成的报告。每组样本都记录首屏出现时间、滚动是否顺滑、取消后后台是否停止、刷新后历史结果是否可见。若只有长报告卡住，重点看前端累积字符串和渲染频率；若三组都等到最后才出现，重点看代理缓冲和后端 flush。固定样本能减少“今天感觉慢一点”这种无法复现的讨论。
检查清单：上线前跑一组流式用例
- 命令行直连、浏览器页面、代理路径是否分别验证过逐段输出。
- 日志是否记录首 token、结束事件、保存状态和 request_id。
- 用户刷新、取消、断网、重复点击时是否不会新增重复任务。
- 前端是否区分排队、生成中、断线、取消、完成和保存失败。
- 长文本任务是否有独立超时和长度预算。
- 页面是否在半截输出时也能提示用户稍后查看历史结果。
验收标准：慢可以解释，断可以恢复
合格的流式输出体验，不是每次都秒回，而是用户能看到进度，断线后知道是否已保存，后台能查到调用链路。永沃云枢建议把流式输出的检查命令、前端状态和日志字段写成固定模板，再与 AI API 接入专题、AI 自动化办公专题 连接起来。这样 https://ai.jn83.com 上的 AI 模型接口能力，才能支撑真实业务里的长任务。