开发记录17_大模型不是应用资源_模型权重下载管理

Memoria 开发记录 17：大模型不是普通应用资源——权重下载、暂停恢复与状态快照

前言

端侧 AI 模型常常有几十 MB，视觉语言模型甚至可能达到数 GB。把所有权重直接打进安装包，会显著增加下载和更新成本；完全依赖运行时下载，又会遇到网络中断、空间不足、重复下载和版本不一致。

因此，模型权重需要被当作一种独立资产管理，而不是普通的 assets/ 文件。Memoria 为此加入模型权重管理页、下载进度、取消、暂停恢复和状态快照，并让运行时优先使用已验证的模型资源。

模型文件与普通下载有什么不同

普通图片下载失败，用户可以重新点击；模型下载到 95% 后失败，重新开始可能意味着浪费数百 MB 流量。更重要的是，下载完成并不代表模型可用，还需要检查：

• 文件大小和哈希是否正确；
• 模型版本是否与运行时代码兼容；
• 图片编码器与文本编码器是否成对；
• 临时文件是否已经原子替换为正式文件；
• 设备剩余空间是否足够。

所以模型下载状态至少包含：

未安装、下载中、已暂停、校验中、可用、损坏、版本过期、失败

从模型权重服务开始

提交 d9df02a 新增 AiModelWeightService 和管理页面。服务层负责描述模型清单、检测本地文件、下载和删除；页面只展示状态与操作。

这个分层很重要，因为模型使用方不应该自己拼下载 URL 或判断文件是否存在。推理服务只询问：“给我当前可用的某版本模型”，权重服务负责返回内置资源、本地下载文件或明确错误。

进度、取消与暂停恢复

提交 d599296 增加下载进度和取消支持。取消下载不能只停止 UI 更新，还要真正停止网络请求、关闭文件句柄，并决定是否保留临时文件。

随后 a6f96c3 增强暂停恢复。支持 Range 请求时，可以从已下载字节继续；服务器不支持时，则需要明确回退到重新下载。无论哪种情况，正式模型文件都不能在下载完成前暴露给推理服务。

推荐的文件流程是：

model.part -> 持续写入与记录进度
model.part -> 下载完成后校验
model.part -> 原子重命名 model.tflite
model.tflite -> 标记可用

这样应用崩溃时，最多留下 .part 文件，不会把半个模型误判为正式资源。

为什么需要下载状态快照

提交 9d7e42b 引入下载快照管理。下载状态如果只存在于页面内存，离开页面或应用重启后就无法解释当前文件：

• 这是完整模型还是残留临时文件？
• 上次下载到了多少？
• 用户暂停了，还是网络失败了？
• 当前 URL 和版本是否仍然匹配？

快照把这些信息持久化，使页面和后台服务都能恢复真实状态。它本质上与长时间 AI 任务的持久化恢复相同：不能把进程存活当作可靠条件。

内置模型与下载模型的优先级

模型管理还要处理内置资源与外部下载的关系。内置模型保证应用首次启动可用，下载模型则允许更新或提供更大能力。

合理优先级通常是：

1. 验证版本兼容的内置模型；
2. 验证完整且版本匹配的下载模型；
3. 明确提示用户下载缺失能力；
4. 绝不静默使用损坏或旧版本文件。

这避免用户删除下载模型后，应用连基础能力也无法启动。

总结

模型权重管理是端侧 AI 产品必须单独建设的基础设施。它连接网络、存储、版本、推理和用户体验。

关键经验包括：

• 模型文件应由专门服务管理；
• 下载完成后必须校验，再原子切换为可用状态；
• 进度、取消和暂停需要影响真实网络与文件操作；
• 下载状态要持久化，支持页面离开和应用重启；
• 推理服务只使用已验证模型；
• 内置与下载模型需要明确优先级和版本兼容策略。

对应提交：d9df02a、d599296、a6f96c3、9d7e42b。