移动端模型更新怎样做到下载校验与原子启用

把模型更新定义成状态机而不是一次下载

移动端更新模型的风险不在于文件是否能下载，而在于多个阶段可能只完成一半。网络中断会留下截断文件，应用被系统终止会打断编译，清单和关联资源可能来自不同发布批次，切换时另一个线程仍在加载旧版本。若代码只用“文件存在”判断可用，半成品就可能进入推理路径。工程判断是把更新明确拆成发现、授权、下载、验证、兼容检查、编译或准备、候选冻结、原子启用和清理，每个状态都有唯一入口与失败出口。

状态机需要持久化，但持久化的不是模糊布尔值。至少记录目标版本、清单摘要、临时目录、已完成文件、候选目录、失败阶段、失败类别和最后尝试时间。应用重启后只能从可证明的阶段恢复：已下载文件重新做摘要校验，编译结果重新确认与候选匹配，未完成的活动切换则读取当前指针而不是猜测。任何无法解释的状态都回到旧活动版本，并把临时内容隔离等待下一次受控重试。

用户触发、后台任务和推送通知可能同时启动更新，必须由单一协调器串行化同一模型族的激活。锁只保护本地临界区，不能代替版本策略；服务端仍要防止把较旧版本、过期清单或不兼容候选发给客户端。放行证据应显示每次状态转换的输入摘要和结果，而不是只记录“更新成功”，这样故障时才能区分网络、供应链、兼容、编译还是切换问题。

可信清单必须先于模型文件进入决策

客户端不能从下载 URL 或文件名推断版本与可信度。The Update Framework specification 提供的更新思路包括验证角色签名、版本、过期时间和一致快照，用于处理回滚、冻结与元数据混搭风险。移动模型不一定直接采用完整 TUF 实现，但工程边界相同：先得到可验证的可信元数据，再依据元数据选择目标文件；不能先下载任意文件，最后只比较一个由同一不可信响应提供的摘要。

清单至少要绑定模型族、发布版本、目标平台、运行时要求、主模型及全部关联文件摘要、文件长度、兼容 schema、发布时间和过期时间。客户端还要保存已接受的最高版本或等价回滚状态，拒绝无授权的旧元数据。设备时间不可靠时，过期判断需要受控时间来源或服务端挑战，不能因为本地时间异常就永久绕过过期检查。任何签名或版本验证失败都应在下载之前停止。

一致性还涉及多文件发布。主模型、tokenizer、标签、归一化配置和业务规则必须来自同一候选清单，不能在缓存命中时随意混用上次文件。清单更新采用新的不可变版本目录，下载器按摘要寻址并在所有文件完成后冻结目录。工程判断是把“候选完整”定义为清单中每个必需成员都存在且摘要匹配，而不是主模型达到预期大小。

供应链证明绑定候选身份但不替代运行测试

SLSA Provenance v1.1 说明构建证明可以绑定产物主体、构建者、构建类型、外部参数和依赖材料。对移动模型发布，候选清单可引用模型文件摘要及对应 provenance，发布服务在下发前确认声明主体与实际候选一致。这样评审者能够回答模型由哪个受信构建流程产生、使用了哪些外部输入，而不是只看到一个无法追溯的二进制文件。

in-toto Attestation Statement v1 定义把产物摘要与有类型的声明负载放在同一 statement 中的通用结构。格式解决的是报告与产物如何绑定，不自动保证内容真实。客户端或发布服务仍需验证签名者、声明类型、策略字段和摘要，拒绝把另一个版本的测试报告附到当前模型。工程判断是移动端只接收最小化的放行结论与必要引用，完整供应链材料可由发布后台保存，但二者必须指向同一候选摘要。

provenance 与 attestation 不能证明目标设备上编译成功、输入输出语义正确或性能满足预算。构建来源可接受后，客户端还要执行平台兼容检查、运行时编译或解释器加载、元数据解析和代表性探针。项目没有真实构建证明时，应把来源状态标为未接入，继续做摘要与兼容门禁，但不能把普通 HTTPS 下载扩写成供应链验证已经完成。

全部文件先进入临时目录并逐项验证

下载目录与活动目录必须物理分离。每个候选使用不可猜测但可审计的临时目录，文件下载时使用临时扩展名，写入完成后刷新文件内容与目录元数据，再进行长度和摘要校验。客户端只接受可信清单列出的相对路径，拒绝绝对路径、父目录跳转、符号链接和重复成员，避免关联文件越过候选根目录或覆盖活动指针。

摘要应在流式写入或完成后从磁盘重新计算，而不是信任网络库返回的校验值。若支持分片续传，每片验证只能证明片段未损坏，最终仍要对完整文件计算清单指定摘要。失败文件保留与否取决于是否能够安全复用，任何没有明确摘要身份的残片都不能被下一次请求直接当成已完成。存储空间不足时先停止候选准备，不应删除当前活动版本来换取下载空间。

LiteRT model metadata 说明模型元数据可以携带输入输出描述、归一化参数、标签和关联文件。这个事实意味着更新校验不能只覆盖主模型；tokenizer、词表、标签、预处理参数和其他关联资产都可能改变推理语义。候选完整性表应逐项列出用途、摘要、长度和兼容版本，未知额外文件默认不进入运行目录，缺少必需成员则整个候选失败。

• 下载目录与活动目录完全分离
• 清单路径经过规范化且不能越过候选根目录
• 每个文件从落盘内容重新计算摘要
• 分片完成后仍执行完整文件摘要
• 主模型和全部关联资产属于同一清单
• 空间不足不会删除唯一可用活动版本

兼容检查和运行时准备必须在切换之前

Download and compile Core ML models 描述动态 Core ML 模型先下载到本地、编译，再从编译产物初始化的路径。工程上应把编译输出视为候选派生产物，而不是下载成功的附带结果。输入模型摘要、编译工具或系统版本、编译目录和初始化结果都要与候选版本绑定；只有从编译产物成功创建模型并通过受控探针，候选才进入可切换状态。

其他运行时也有各自兼容条件，包括算子集合、delegate、硬件架构、量化方式、输入 shape 和元数据 schema。静态清单可以提前排除已知不兼容组合，真实设备试加载负责捕捉运行时差异。探针应使用公开安全、固定且不包含用户数据的输入，检查输出结构、有限数值和必要业务不变量；它不能证明全部模型质量，却能阻止无法加载或接口明显变化的候选进入活动路径。

Manage Core AI model caching 说明模型缓存可能随源模型、OS 版本、存储压力和清理策略失效或重建。该语义不能外推到所有 Core ML 或 Android 运行时，但提示团队不要把已有缓存当成永久有效证据。候选启用记录应区分源模型、编译产物和运行时缓存，缓存缺失时能够安全重建，缓存命中时也要确认其来源版本与当前候选一致。

活动指针只在全部门禁后原子替换

原子启用不等于把整个大目录瞬间复制到活动位置。更可靠的做法是候选目录一旦验证通过就变为不可变，活动状态只保存一个很小的版本指针。新指针先写入同一文件系统中的临时文件，刷新内容与父目录后，再用原子重命名替换活动指针。推理请求开始时读取一次指针并固定对应目录，整个请求生命周期不再跟随指针变化。

同一文件系统是关键边界，跨卷移动可能退化为复制和删除，不能假定具有原子语义。进程内还要协调并发：激活线程替换指针不应关闭已有模型实例，新的请求读取新版本，旧请求继续持有旧快照直到完成。多进程应用需要使用所有进程都能观察到的指针与版本租约，并在应用重启时重新读取指针和验证候选目录。

下面示例验证 manifest 中全部文件的相对路径、长度和 SHA-256，确认候选版本后，把 JSON 指针写到同目录临时文件并使用 os.replace 原子替换。它不验证发布签名，也没有实现平台模型编译，因此只能解释“完整候选到活动指针”的最后一步。真实应用还要在调用函数前完成可信清单验证、兼容测试和持久化刷新策略，并把 base_dir 限定在应用私有数据目录。

• 候选目录验证完成后保持不可变
• 指针临时文件和活动指针位于同一文件系统
• 替换前刷新指针内容和必要目录元数据
• 每个推理请求固定一次版本快照
• 旧实例不会在处理中被强制关闭
• 应用重启后从活动指针恢复而非猜测版本

from pathlib import Path
import hashlib
import json
import os
import sys

if len(sys.argv) != 3:
    raise SystemExit("usage: activate.py model_root manifest.json")

model_root = Path(sys.argv[1]).resolve()
manifest_path = Path(sys.argv[2]).resolve()
manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
version = manifest.get("version")
files = manifest.get("files")

if not version or not isinstance(files, list) or not files:
    raise SystemExit("manifest has no versioned file set")

candidate = (model_root / "candidates" / version).resolve()
if candidate.parent != (model_root / "candidates").resolve():
    raise SystemExit("candidate path escaped the model root")

for entry in files:
    relative = Path(entry.get("path", ""))
    expected = entry.get("sha256", "")
    if relative.is_absolute() or ".." in relative.parts:
        raise SystemExit(f"unsafe manifest path: {relative}")
    target = (candidate / relative).resolve()
    if candidate not in target.parents or not target.is_file():
        raise SystemExit(f"candidate file missing: {relative}")
    if target.stat().st_size != entry.get("length"):
        raise SystemExit(f"candidate length mismatch: {relative}")
    actual = hashlib.sha256(target.read_bytes()).hexdigest()
    if actual != expected:
        raise SystemExit(f"candidate digest mismatch: {relative}")

pointer = model_root / "active.json"
staged = model_root / "active.json.next"
staged.write_text(json.dumps({"version": version}), encoding="utf-8")
with staged.open("rb") as handle:
    os.fsync(handle.fileno())
os.replace(staged, pointer)
print(f"activated verified model version {version}")

失败回退与坏版本抑制要提前设计

最安全的失败动作通常是继续使用上一已知可用版本，而不是立即删除候选或退回应用内置模型。上一版本必须在启用新版本后保留一段稳定观察期，且其文件、编译产物和必要关联资产保持完整。若新版本在真实请求中出现加载失败、输出不变量破坏或错误预算越界，回退只需把活动指针原子切回已验证版本，新请求使用旧版本，正在执行的请求按原快照完成。

坏版本需要抑制，否则服务端持续返回同一候选会造成下载、编译、失败和回退循环。客户端可记录候选摘要、失败阶段、错误类别、设备兼容条件和下一次允许重试时间，只有清单版本、候选摘要、运行环境或服务端策略发生可解释变化后才重试。记录不应包含模型内容或用户输入，服务端也不应把客户端单次失败自动扩大成所有设备不兼容。

回退本身也受版本策略约束。TUF 风格的回滚保护用于拒绝未授权旧元数据，不应阻止客户端在本地两个已授权候选之间执行安全回退。工程判断是分别维护“可接受发布版本集合”和“当前活动版本”，回退目标必须仍在授权集合、未过期策略允许范围内且具有本地完整证据。没有目标版本文件或证据时，不能只修改字符串指针。

旧版本清理要晚于引用释放和证据归档

清理与启用如果在同一临界区执行，最容易把回退能力和在途请求一起删除。新版本切换后，旧模型实例可能仍被当前请求、后台任务或另一个进程持有。版本目录应有租约或引用记录，清理器只处理不再活动、没有有效租约、已过稳定观察期且不属于保留回退集合的候选。无法确认引用状态时宁可延迟清理，也不能凭目录修改时间推断无人使用。

缓存需要单独建账。Manage Core AI model caching 指出缓存可能因源模型、系统版本、存储压力或清理策略失效，因此缓存不应承担唯一模型副本或回退证据的职责。清理时先区分可信源文件、运行时编译产物、可重建缓存和下载残片；存储压力下优先移除可重建、非活动且无租约的内容，唯一已知可用版本应受到保护。

发布记录最终应绑定清单摘要、全部文件摘要、供应链声明引用、目标设备条件、编译或加载回执、活动指针变更、回退演练和清理边界。结论只能写到真实证据覆盖的范围，例如指定候选在列出设备与状态机路径上通过，不能宣称所有设备永久无故障。准备评估时，可通过御盾中央平台提交模型清单、关联文件、运行时矩阵和更新状态机，由双方先固定候选身份与验收范围。

• 活动版本和上一已知可用版本不会被容量清理
• 跨线程与跨进程引用都有可判断租约
• 源模型、编译产物、缓存和残片分类清楚
• 清理失败不会影响当前推理路径
• 回退演练完成后再缩短旧版保留窗口
• 发布与清理记录都绑定同一候选摘要