让 Android AI 模型下载进度准确可信

直接回答

可信的模型下载进度只报告客户端实际观察到的情况。先定义制品身份和预期字节数的来源，再统计当前传输写入了多少字节；如果没有可信分母，就显示不确定进度。传输结束之后，还要把完整性校验、文件安装、运行时加载和离线任务就绪分开。除非针对对应传输情境验证过估算方法，否则不要把百分比转换成剩余时间承诺。HTTP 响应描述的是一个响应及其表示形式，不会自动证明收到的就是应用预期的最终制品。如果断点请求收到的是完整响应，而不是有效的部分响应，就不能把它追加在旧临时文件后面。若预期文件长度仍是占位数据，或服务器没有提供 Content-Length，界面应说明进度总量未知，不要假装能够计算百分比。 这一区分很重要，因为下载进度只是交付状态机中的一个阶段。用户可能已经收到预期字节，但配置的摘要值可能缺失，也可能仍在校验，校验还可能失败；最终文件尚未安装，运行时也可能拒绝加载。当前仓库的 ModelDownloader 会报告字节和总量，将数据写入临时文件；如果配置了 SHA-256，才执行摘要校验，随后尝试把临时文件改名并发出 Completed。当前 Gemma E2B 配置的 SHA-256 字段为空，因此该配置会跳过摘要校验。产品界面不能把传输达到 100% 描述为已通过密码学完整性校验，更不能说模型已加载成功。 进度分母必须绑定到明确来源，例如固定版本的清单、经过验证的响应长度，或有文档记录的已知长度资源。记录使用了哪个来源，以及响应是完整响应还是部分响应。部分响应的 Content-Length 通常表示本次范围响应的正文长度，不一定是整个文件长度；只有请求偏移和返回范围元数据相符时，才可以推导总量。如果临时文件来自旧版本或状态不明，本地偏移也不可信。重定向、代理或门户页面可能改变响应正文；在把字节记成模型字节之前，应检查响应状态和内容类型。文件名、四舍五入的营销容量和上一个模型版本都不能充当本次总量的证据。 也不要从最近一次速率样本显示精确剩余分钟数。移动网络速率可能受网络切换、无线电状态、服务器限流和系统其他活动影响。如果产品没有验证过估算器，应显示已传输字节、不确定总量，并提供暂停或取消。对于续传，说明计数是否包含上次已保存的字节，还是只统计本次会话。这样可避免进度条倒退，或在实际表示形式改变后看起来已完成。更换制品修订时，应清除旧版本的累计计数，不可跨版本相加。 至少把这些阶段分别建模：排队或等待约束、连接中、接收中、暂停或停止、传输结束、校验、安装、加载、就绪以及带有可恢复类别的失败。界面可以合并部分视觉阶段，但日志与测试仍应保留区别。Worker 被取消或系统停止后，状态不能显示为完成；通知被关闭时，通知是否可见也不是传输状态的权威来源。用户关闭页面后，进度所有权不应随着页面销毁而消失。 每次传输可以保存不含隐私内容的记录：制品键与修订、总量来源、HTTP 状态类别、完整或部分响应类型、持久化偏移、本次写入字节、校验状态、安装结果以及取消或失败类别。不要记录用户提示词、录音转写、凭据，或包含敏感令牌的完整下载地址。测试应覆盖零字节、未知总量、有效部分响应、服务器忽略 Range、制品版本变化、校验失败和安装成功等边界，并同时比较底层状态与界面文案。目标不是宣称某个下载速度，而是证明界面如实表达当前阶段。 ### 操作步骤 1. 固定制品身份和进度总量。记录不可变修订、预期字节数及其权威来源，并注明它是实测、正式发布还是占位值。没有可信总量时，选择不确定进度界面。 2. 定义响应计数规则。逐次记录状态码、范围元数据、正文长度、最终表示身份和已有偏移。续传只接受能够证明返回的是同一制品对应请求范围的响应；完整响应必须替换或重新开始临时文件，绝不能追加。 3. 把传输与后续状态拆开。分别记录字节接收、传输结束、摘要校验、最终路径提升、运行时加载和任务就绪。若没有可信 SHA-256，应明确未校验，而不是把跳过说成通过。 4. 用固定场景测试生命周期和订阅者。覆盖屏幕重建、重复观察者、Worker 停止与恢复、取消及通知关闭；后台任务所有者是权威状态源，界面订阅者销毁不能伪造完成或抹去进度。 5. 审核用户文案和诊断记录。逐项对照底层状态，记录制品修订、响应类别、字节数和校验安装结果；从日志中排除用户内容、认证头和敏感查询参数。 ### 验收标准 - 未知或占位总量不会生成虚假的百分比或剩余时间承诺。 - 断点追加前验证响应范围和制品身份，未验证的正文不计入进度。 - 界面及状态机区分已传输、已校验、已安装、已加载和离线就绪。 - 取消、观察者重建和通知设置都不能把未完成传输变成成功状态。 ### 状态对照 | 信号 | 能证明什么 | 不能证明什么 | |---|---|---| | 已写入字节 | 有多少数据写入临时文件 | 来源正确、完整性通过或运行时能加载 | | 清单或响应总量 | 本次进度计算使用的分母 | 服务器实际返回了预期表示形式 | | 校验和加载结果 | 实现单独报告的后续检查 | 其他设备上的普遍兼容或性能 | ### 常见问题 **收到最后一个字节时，进度条能否显示 100%？**可以，但必须明确标成“传输完成”。校验、安装和运行时加载可能仍未完成，因此应显示后续阶段，不能让用户误以为模型已可使用。如果只用一条进度条，也应保留当前阶段的文字说明。 **服务器没有提供 Content-Length 怎么办？**使用不确定进度；有帮助时可以显示已收到字节数，但不要凭空设置分母或完成时间。之后若可信清单提供了长度，可按该来源计算，同时向用户说明总量依据。 **能否根据当前速率估算剩余分钟？**只有在相关网络与传输条件下验证过估算器，并能解释误差时才考虑展示。移动网络波动很大；没有验证时，已传字节和阶段说明更可靠。 **100% 是否证明文件完整？**不能。它只描述字节计数关系。必须另行执行可信摘要或明确记录的验证；文案还应说明是否具备该检查，以及检查结果究竟是通过、失败还是未执行。

进度条已满，模型却还没完成校验

一位旅行者在出发前下载可选模型。进度条已满，但应用还要校验摘要、提升最终文件路径并加载运行时。另一次下载可能从临时文件续传，而服务器对 Range 请求的响应也可能与上次不同。

决策

分别维护字节传输、响应验证、完整性、安装、加载和就绪阶段；当前响应无法支撑可信分母时，使用不确定进度。

预期结果

用户能准确看到已完成的阶段，并决定等待、取消、重试或使用备用方案，而不会把未验证文件误认为已就绪。

需要收集的证据

只有将以下证据与同一模型文件和测试运行关联起来，结论才可复核：

• 固定制品修订和总字节数来源
• HTTP 状态与范围响应
• 临时文件、校验及最终路径状态

收到完整字节流还不够；最终落盘、完整性、运行时加载和恢复路径也必须验证。

实施流程

1. 为进度分母注明来源. 把总量绑定到不可变制品清单或经过验证的响应规则，并将来源和修订一同保存。配置仍是占位值或响应没有可信总量时，显示不确定状态，不得借用另一模型版本的大小。
2. 区分完整响应和部分响应. 记录状态码、范围元数据、正文长度、最终表示身份和已有文件偏移。续传只有在响应证明返回的是同一制品的请求范围时才能接受。若收到完整响应，应替换或重建临时表示，不可接在旧字节后面。
3. 把传输、校验和就绪分开. 分别发出已收字节、传输结束、摘要校验、最终路径提升、运行时加载和任务就绪状态。未配置可信摘要时，应说明没有执行校验，而不是暗示校验已通过。失败时保留最后一个确实完成的阶段。
4. 覆盖生命周期和观察者场景. 测试屏幕重建、重复订阅、Worker 停止与恢复、取消及通知关闭。后台任务所有者应维护权威状态；通知是否显示不能代替实际任务状态，界面收集器脱离也不能伪造完成。
5. 核对文案和诊断数据. 将每条用户文案逐一对应到底层状态，并设计不含私密数据的事件字段，如制品修订、响应类型、字节数、校验和安装结果。日志应排除用户内容、授权信息以及带敏感令牌的参数。

让每个阶段的状态都可观察。失败信息应指出阶段、模型、运行时和恢复动作，同时避免记录用户私密内容。

验收标准

• 没有可信总量或总量仍是占位值时，不会出现虚假百分比或剩余时间承诺。
• 续传追加前校验范围响应和制品身份；未验证正文不会计入下载进度。
• 界面与状态机清楚区分传输、校验、安装、加载和离线就绪。
• 取消、界面重建或关闭通知均不会把未完成的任务伪装成成功。

决策对照表

需要避免的失败模式

• 把文件写完当成模型已就绪
• 用占位大小制造百分比
• 断点续传时把完整响应追加到旧字节后面

还要避免静默回退、版本未固定、缺少取消处理，以及把不同配置的结果混在一起下结论。失败运行也应与成功记录一并保存。

最小复现记录

发布检查表

• ☐ 主要搜索问题已回答，且没有未经支持的数字。
• ☐ 所有模型文件和运行时版本均已固定。
• ☐ 代表性任务和失败处理策略均有说明。
• ☐ 生命周期、取消、清理和回退均已测试。
• ☐ 用户内容与网络边界均有说明。
• ☐ 结论只适用于被记录的配置。
• ☐ 新增测试结果时链接到原始方法或证据。

来源与相关证据

• Cove Gemma 4 model page
• IETF HTTP 语义：范围请求与表示元数据
• Android WorkManager：管理与观察任务
• Android WorkManager 持久任务

中文部署与排错专题见。奇连 AI 端侧专题。

常见问题