HarmonyOS AI会议助手踩坑笔记:优化篇 08 · 断网后文字重复闪动:流式输出、超时与请求代际管理【共创稿事节】

图:本篇 AI 智能应用主题封面。
给 AI 纪要加入流式输出以后,页面终于不再长时间空白。但很快出现更难定位的问题:用户取消生成后,旧内容仍往屏幕里追加;重新点击后新旧文字交叉出现;网络闪断时整个段落又从头生成了一次。某些实现还会在连接意外断开时把已有半截文本标记成“已完成”,用户复制后才发现最后一条结论被截断。流式输出看似只是改善体验,却把请求生命周期管理变成正确性的核心。
第八篇关注客户端和模型网关之间的协议,不限定某一家模型供应商。我们的服务端适配器负责把供应商返回的片段转换成自有 requestId、seq、delta、done 事件;HarmonyOS 客户端再通过与当前 SDK 匹配的网络接口接入。这里的 seq 是本项目约定,不是通用 SSE 标准字段;如果使用 WebSocket、HTTP 分块或者其他传输,也应先明确是否具有恢复序号与事件重发语义。
一、不能把每次收到的字节都直接 append
传输层一次收到的数据块不一定是完整 JSON,更不一定是完整汉字字符。对 SSE 来说,事件可能跨多个网络 chunk,多个事件也可能被合并进同一个 chunk。若收到一块就调用 JSON.parse,会因为截断而频繁报错;若按每个字节解码中文,可能出现乱码。正确的协议实现需要有文本解码缓冲、事件边界识别和字段级验证,只有得到完整的业务事件才进入 UI 状态管理。
模型供应商的流式格式也可能包括心跳、角色声明、内容增量和结束原因。有些服务返回的 delta 是新增片段,有些则会推送覆盖式快照。客户端必须先确认协议语义,不能把任何名叫 content 的字段都追加到字符串末尾。这与第三篇 ASR 的预览/最终片段问题相似,但网络生成还多了取消、重试、超时以及多请求交错这几个维度。
二、为每次生成分配独立 requestId
用户点击“重新生成”时,最先要做的不是清空文本,而是把上一代请求标记为过期。即使底层取消调用返回成功,已经排队的旧回调仍可能继续到达。客户端只接收当前 requestId 的事件;旧请求的任何数据都直接丢弃。不同会议之间更需要同时核对会议 ID 和来源文本版本,不能让 A 会议的迟到内容覆盖 B 会议的摘要区域。
// 来源:示例源码/src/stream.mjs(独立可测试的业务模块)
export class StreamAccumulator {
constructor() {this.activeId = null; this.nextSeq = 0; this.parts = []; this.status='idle';}
start(requestId) { this.activeId=requestId;this.nextSeq=0;this.parts=[];this.status='running'; }
push(requestId, seq, text) {
if (requestId !== this.activeId || this.status !== 'running') return false;
if (seq !== this.nextSeq) return false;
this.parts.push(String(text)); this.nextSeq++; return true;
}
complete(requestId) {
if (requestId !== this.activeId) return false;
this.status='complete'; return true;
}
fail(requestId) {
if (requestId === this.activeId) this.status='partial';
}
snapshot() {return {status:this.status,text:this.parts.join(''),count:this.nextSeq};}
}
StreamAccumulator 记录当前请求 ID、预期序号与接收片段数组。start 会更新代际,push 拒绝旧 ID 和不连续序号,complete 只有匹配当前请求才会改变状态。代码在 示例源码/src/stream.mjs,示例了旧事件不能污染新生成任务的核心规则。生产环境若需要丢包后的补帧,应该与网关约定重放协议,而不是在客户端擅自跳过序号。

图:流式请求生命周期的开发环境样式示意;非 DevEco Studio 实际运行截图,日志为界面示例内容。
三、取消并不等于服务端停止计费
用户按下取消按钮,界面通常可以立即停止展示,但后端模型计算是否真的停止,还取决于服务协议、断开连接是否透传给上游、网关是否识别取消信号。应将“本地已取消展示”和“上游已确认停止”区分记录。若没有上游确认,不宜在成本统计里当作零消耗;也不应让用户在取消后突然看到一份旧结果,因为那会让他们误以为取消无效。
超时也有不同含义。连接超时说明没有建立链路,首 token 超时说明连接建立后迟迟没有首个结果,总生成超时说明已输出一部分但尚未结束。把这三种情况都映射成“网络不好,请重试”会浪费排查时间。尤其当已经收到正文后再失败,界面应保留可见的草稿并标注“未完成”,让用户选择继续、重新生成或放弃,而不是自动把半截内容写进已确认纪要。
四、弱网重试需要懂得是否会重复生成
断线重连后直接重新发送同一个 prompt,不代表一定能从先前位置继续。多数模型调用并没有天然的逐 token 断点恢复能力。若网关不支持流式事件重放,正确做法是启动一个新的 requestId 进行完整重生成,并将旧草稿单独保存为失败版本,不要在旧文本后面接新输出。否则两个版本的句子会被拼在一起,内容既重复又不通顺。
如果网关确实支持恢复,必须约定 cursor、lastEventId 或等价机制,并验证事件幂等。客户端收到重复序号时忽略,收到缺失序号时等待补发或按协议要求重建任务;不能靠“字符串如果和上次结尾相同就截掉”的方法解决,因为正常会议也会反复使用同一句话。用文字相似度代替事件 ID 是一种不稳定的补丁。
五、UI 更新节奏同样会放大故障
每收到一个字就更新整个长篇纪要,容易让页面频繁布局和滚动,尤其在内容较长、还附带证据引用卡片时更明显。可以在接收缓冲中累积片段,以适当节奏批量刷新视图;但最终内容仍以事件序号和状态为准,不能为了动画平滑而丢事件。用户如果手动上滑查看前文,系统也不该强行将滚动位置不断拉到最底部。

图:生成状态的手机界面设计示意,页面数据用于说明交互,非真机截图。
另一个细节是结束信号。不能根据“已经五百毫秒没有新字符”就认定生成完成,网络空闲并不表示服务端结束。只有收到协议定义的完成事件,且全部必要字段验证通过,才能将状态从 running 切换到 complete。如果数据被截断、结束标记缺失或结构化 JSON 不完整,就应进入 partial,允许用户查看但禁止作为正式摘要直接归档。
六、调试时用事件序列,而不是反复拔网线
设计一组可重复的本地事件:request A seq0、request A seq1、启动 request B、迟到的 request A seq2、request B seq0。预期最终页面只显示 B 的内容。再测试缺少序号、重复序号、完成后继续到达数据、用户取消后迟到的结束事件,以及同一次请求两次 complete。这些测试比主观感受“偶尔文字闪一下”更能直接定位状态错误。
真实设备上的网络切换仍需单独检查:Wi-Fi 转移动网络、飞行模式、应用退后台、系统回收进程、服务端限流和证书异常。不要在开发时把 API Key 放在客户端源码里,也不要为了解决调试不便关闭证书校验。客户端应通过受控网关获取最小必要的服务能力,敏感凭据保存在服务端;日志只保留请求关联标识和错误类别,避免记录完整私密原文。
七、把“可恢复”定义为用户可理解的操作
可恢复并不意味着必须自动重连。对于长会议摘要,自动重试可能带来额外调用成本、输出差异及隐私传输;对于用户已经编辑的草稿,自动重生成还可能覆盖人工修改。界面应该显示“已收到多少内容、是否完整、是否已经保存草稿”,然后提供明确的重新生成或继续操作。只有确认模型服务支持断点继续且用户同意时,才能真正以恢复方式继续旧任务。
八、再往下挖:流式协议的缓冲不是一个字符串就够了
SSE 的基本单位是以空行分隔的事件,但一次网络读取可能只拿到半行;UTF-8 多字节字符也可能刚好跨越读取边界。生产级实现应使用持续工作的文本解码器维护缓冲区,按事件分隔符提取完整记录,并为单事件大小设定上限。否则服务端异常发送一个永远不结束的事件,会让客户端缓冲无限增长,最终触发内存压力。缓冲上限和超时要与服务协议同时设计,而不是发布后才补救。
应用退后台时,网络请求是否继续、是否被系统限制,以及 UI 是否重建,都取决于应用形态和系统调度约束。无论具体行为如何,恢复到前台时都应重新读取持久化状态并校验当前请求代际。不能假设每次退后台都会收到相同的销毁回调,也不能在生命周期回调里执行漫长的网络保存。若允许用户主动中断,必须把中断原因和已保存片段一起记录,让下一次打开页面能解释它为什么是不完整版本。
“节流刷新”不等于“节流存储”。UI 每一小段时间渲染一次,可以减少重绘;持久化可以按稳定事件窗口或明确的中间检查点执行,具体频率需在数据安全和写入成本之间权衡。若只在最终 done 时保存,长达数分钟的生成在最后一刻失败会丢失全部草稿;若每个字节都写盘,则会放大存储压力。更合理的方案是分层缓冲、定期快照和明确的完整性标记。
最后要测试服务器返回错误数据的情况:一个事件缺少 requestId、一个序号跳过、连续两个完成标记、JSON 内嵌换行、超长字段和空的增量数据。客户端遇到不符合协议的事件,应显示可理解的失败状态并保留诊断关联 ID,不能把解析异常吞掉后继续显示“正在生成”。这类协议错误往往比纯断网更隐蔽,却更容易导致被用户复制的不完整纪要。
一条很实用的回归指标是“最后一个完整事件序号”,而不是“最后显示了多少字”。当用户反馈文字消失,工程可以通过请求 ID 和序号判断是 UI 渲染问题、协议丢事件,还是新请求覆盖了旧请求。为了保护隐私,日志只需要记录事件类别、长度、耗时和校验状态,未必需要保存正文。诊断能力建在协议元数据上,会比在用户资料里全文检索更加安全。
还需要区分服务端主动结束与客户端被动断线。服务端带明确结束原因的事件可以进入完成或已拒绝状态,网络中断却无法推断模型是否完成;若应用错把 Socket 关闭等价于“正常结束”,整个质量链路就会被污染。建议将 done、cancelled、partial、failed 分成明确的终态,分别控制复制、确认、重试与错误提示的入口。
流式场景的客户端还应监控处理速度。如果网关每秒发送大量短片段,而页面每次都执行复杂富文本解析,消息队列可能不断堆积。可以把网络接收与渲染调度解耦:协议层先确保事件完整与顺序,再按显示帧的节奏更新少量 UI 状态。遇到背压时,允许合并展示增量,但不能合并或丢弃决定业务结果的完成、错误与工具确认事件。
本篇结论:流式生成最重要的不是速度,而是代际隔离、事件完整性和失败语义。最后一篇将把整套会议助手放进上线门槛:录音与模型数据怎样最小化收集、删除是否彻底、评测是否覆盖关键风险。
资料核对说明:本系列部分涉及 HarmonyOS 原生能力,应以当前开发套件与华为官方文档为准;项目中的纯 JavaScript 代码属于业务示例,不等同于已完成端侧 SDK 对接。相关链接见根目录《官方资料索引.md》。
更多推荐

所有评论(0)