端侧 LoRA 适配器与基础模型版本绑定策略

资产解耦引发的隐性耦合风险

端侧大模型推理为了减小更新包体积，常将基础模型权重与低秩适配器分开存储和分发。这种物理上的解耦掩盖了两者在数学结构上的强耦合关系。适配器的权重矩阵秩和插入层位置必须严格匹配基础模型的内部架构，否则在前向传播计算中会出现张量形状不匹配的错误。实际工程中，若开发者仅更新了基础模型而未同步调整适配器，推理引擎在尝试矩阵乘法时会抛出异常，导致应用直接闪退而非优雅降级。

除了明显的维度冲突，量化方案的差异构成了更隐蔽的风险。当基础模型采用整数量化格式部署时，其计算图依赖于特定的缩放因子和零点参数。如果 LoRA 权重是基于浮点格式训练且未进行相应的量化感知处理，即使维度完全一致，加载后的数值范围错配也会导致输出结果完全不可用。这种错误往往不会触发崩溃，而是表现为生成内容的乱码或逻辑混乱，极难在测试阶段被及时发现。

Tokenizer 的版本一致性同样关键，却常被忽视。模型输出的 logits 分布与 tokenizer 的词汇表大小及特殊标记索引紧密绑定。若基础模型升级时调整了词汇表，而适配器仍基于旧版 tokenizer 的假设进行后处理，生成的文本将出现大量未知标记或截断。因此，安全的资产绑定策略必须将 tokenizer 的版本标识纳入成组资产的管理范畴，确保解码端与编码端的协议一致。

成组资产契约的 Manifest 设计

为解决上述风险，需要为每个 LoRA 适配器定义一个独立的 manifest 文件，作为描述其与基础模型依赖关系的契约文档。该文件应声明适配器所依赖的基础模型资产摘要、关键架构维度、量化配置、所需后端类型以及适配器自身的秩信息。Manifest 必须与应用包独立存储，并受到完整性保护，防止被篡改后指向错误的模型文件或绕过校验逻辑。

在基础模型摘要字段的设计上，不宜使用简单的文件名或语义化版本号。文件名容易被混淆，而版本号可能未遵循严格的规范，两者都无法保证文件内容的唯一性。更可靠的做法是记录基础模型权重文件的密码学哈希值，如 SHA-256。这一做法借鉴了供应链安全中将产物摘要与声明绑定的思想，确保任何对模型文件的微小修改都会导致哈希值变化，从而被校验机制捕获。

维度约束字段应当至少包含隐藏层维度、注意力头数和 Transformer 层数。因为 LoRA 权重通常被注入到注意力机制的投影矩阵中，其形状直接依赖于这些架构参数。此外，如果适配器是针对特定量化精度训练的，manifest 中必须明确记录量化方法的名称或关键参数特征。这使得运行时能够对比基础模型的实际配置，主动阻止因量化方案不匹配导致的静默错误。

本地校验流程与执行顺序

部署阶段的校验必须在适配器首次加载前执行，且作为一个不可绕过的强制步骤。首先，校验器需要读取 manifest 文件自身，验证其数字签名或确认其位于应用信任的资产范围内。如果 manifest 本身未被签名保护，攻击者可以提供指向恶意基础模型的伪造 manifest，使得后续的摘要校验变成自洽的假象，从而失去防护意义。

摘要校验根据 manifest 中记录的哈希值定位基础模型文件，再用同一算法计算并比较。不匹配可能来自更新未完成、存储损坏或文件被替换。此时不应继续使用该资产组合，可提示重新下载或切换到已验证的本地基线，同时保存失败原因供排查。

接下来进行维度约束的比对。从基础模型目录下的配置文件中解析隐藏层维度、层数等关键字段，与 manifest 中声明的值进行严格相等比较。这一步骤不应进行任何容忍近似的处理，因为一个维度的微小差异就会导致矩阵乘法错误。最后，将当前运行时环境与 manifest 中的兼容后端列表做比对，若当前环境不在列表中，即便框架可能尝试加载文件，也应直接退出以防止未定义行为。

#!/usr/bin/env python3
import argparse
import hashlib
import json
import sys
import os

def load_manifest(path):
    """Load and parse the JSON manifest file."""
    if not os.path.isfile(path):
        print(f"Error: Manifest file not found at {path}")
        sys.exit(1)
    try:
        with open(path, 'r', encoding='utf-8') as f:
            return json.load(f)
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON in manifest: {e}")
        sys.exit(1)

def calculate_sha256(file_path):
    """Calculate SHA-256 hash of a file."""
    sha256_hash = hashlib.sha256()
    try:
        with open(file_path, "rb") as f:
            for byte_block in iter(lambda: f.read(4096), b""):
                sha256_hash.update(byte_block)
        return sha256_hash.hexdigest()
    except FileNotFoundError:
        print(f"Error: Model file not found at {file_path}")
        sys.exit(1)

def verify_dimensions(manifest, config_data):
    """Verify architectural dimensions match."""
    required_dims = ['hidden_size', 'num_layers']
    for dim in required_dims:
        expected = manifest.get(dim)
        actual = config_data.get(dim)
        if expected is None or actual is None:
            print(f"Error: Missing dimension {dim} in manifest or config")
            sys.exit(1)
        if expected != actual:
            print(f"Error: Dimension mismatch for {dim}: expected {expected}, got {actual}")
            sys.exit(1)

def main():
    parser = argparse.ArgumentParser(description="Validate LoRA adapter against base model")
    parser.add_argument('--manifest', required=True, help='Path to LoRA manifest JSON')
    parser.add_argument('--model-dir', required=True, help='Directory containing base model files')
    args = parser.parse_args()

    manifest = load_manifest(args.manifest)
    
    # Verify Base Model Hash
    model_weights_path = os.path.join(args.model_dir, 'model.weights')
    expected_hash = manifest.get('base_model_sha256')
    if not expected_hash:
        print("Error: base_model_sha256 missing in manifest")
        sys.exit(1)
    
    actual_hash = calculate_sha256(model_weights_path)
    if actual_hash != expected_hash:
        print(f"Critical: Hash mismatch. Expected {expected_hash}, got {actual_hash}")
        sys.exit(1)
    
    # Verify Dimensions
    config_path = os.path.join(args.model_dir, 'config.json')
    if not os.path.isfile(config_path):
        print("Error: Base model config.json not found")
        sys.exit(1)
    
    with open(config_path, 'r', encoding='utf-8') as f:
        config_data = json.load(f)
    
    verify_dimensions(manifest, config_data)
    print("Validation successful: Asset integrity confirmed.")
    sys.exit(0)

if __name__ == "__main__":
    main()

供应链框架的辅助作用与边界

即使应用内实现了严格的本地校验，如果适配器 manifest 和模型文件经由不可靠渠道分发，攻击者仍可能同时替换两者，使校验比对变成自洽的假象。此时可引入独立于应用的完整性保护机制，例如 The Update Framework 提供的签名元数据系统。该规范要求客户端验证签名、版本号和过期时间，这些机制可用于保护 manifest 和模型文件的版本序列，防止攻击者回滚到旧的、不兼容的组合。

在构建侧，可以利用 SLSA 构建证明将适配器本身与基础模型依赖关系固化为不可篡改的记录。SLSA Provenance 通过绑定产物主体、构建者、外部参数和材料，能够回答该适配器是在什么环境、针对哪个基础模型编译而来的问题。将 provenance 随适配器一同发布，运行时可以核对适配器声明的基础模型哈希是否与构建记录一致，增强信任链。

需要强调的是，TUF 和 SLSA 都只能提供分发和构建环节的信任依据，无法单独保证运行时环境的安全性。如果设备已经被攻破，文件系统的哈希校验仍可被绕过。此外，这些框架并不规定模型架构兼容性的具体内容格式，仍需应用层定义具体的 manifest 结构。因此，这些框架应与其他系统完整性机制配合，作为资产版本契约层面的增强而非替代。

平台接口差异与兼容性证据

Google AI Edge 提供的 LLM Inference API 曾允许开发者将基础模型文件路径和独立的 LoRA 文件路径同时传入运行时。这一接口清晰展示了版本绑定的思想：运行时需要两者构成的完整输入才能工作。但该 API 目前处于维护模式，且手册明确限定 LoRA 只能用于特定格式的 GPU 后端。这意味着即使在同一个 Google 生态内，这种绑定方式也不具备跨平台或跨后端的通用性，开发者不能将其视为行业标准。

MediaPipe LLM Inference 的概览页面进一步说明，基础模型、可选的定制权重以及运行配置是一组相互依赖的执行输入。这里的相互依赖指的是缺少任何一部分都会导致初始化失败，而非运行时动态适配。因此，开发者不能寄望框架会自动忽略不适配的适配器，必须主动管理版本契约，确保传入的路径指向正确的成组资产。

LiteRT-LM 作为 Google 推荐的迁移方向，其 Android 集成要求应用显式选择受支持的模型包并初始化。指南中并未提及任何从旧 MediaPipe LoRA 文件自动迁移的机制，这意味着原先为 MediaPipe 构建的适配器不能直接用在 LiteRT-LM 上，版本契约必须重新建立。这进一步强化了成组资产观念：每对适配器与基础模型的组合都需要独立验证，不能假设向后兼容。

• 确认目标推理引擎是否支持独立的 LoRA 文件加载，还是需要合并权重。
• 检查引擎文档关于 GPU 与 CPU 后端对 LoRA 格式的具体要求差异。
• 验证引擎是否在初始化阶段自动检查模型与适配器的维度匹配。
• 确认迁移到新引擎时是否需要重新量化适配器权重。
• 审查引擎是否提供官方的 manifest schema 或元数据标准。
• 测试在缺失适配器文件时引擎的报错行为是否符合预期。

常见失败模式与工程预防

基础模型更新后，如果新 manifest 和适配器没有作为同一批次交付，设备可能同时持有新旧组件。服务端可维护已验证的模型与适配器组合，客户端下载完整组合并在本地一次性切换；校验失败时给出清晰的重新下载入口。

兼容字段不能只记录一个总体维度。适配器依赖哪些层与张量，就应从所用格式提取相应约束，并把字段缺失也视为未经验证。hidden_size、层数或注意力头数只是常见例子，不是适用于所有架构的固定清单。

存储空间不足或下载中断也可能造成资产缺失。加载前应检查 manifest 引用的每个路径、文件长度和摘要，再进行模型与适配器兼容核对。tokenizer 是否加入同一资产组属于另一项管线设计，需要单独的一手依据和版本契约，本文不把它作为 LoRA 绑定的既定要求。

资产清单与部署流水线集成

为了让成组资产契约真正发挥作用，构建系统需要自动化生成 manifest。构建脚本在产出 LoRA 适配器文件的同时，应当读取基础模型的权重摘要、架构配置和量化方法，写入一个 JSON manifest，并将该 manifest 连同适配器文件一起签名和发布。处理流程可减少人工录入错误，确保每次构建的契约信息准确无误，并与产物强绑定。

在移动应用侧，推荐将 manifest 和适配器文件作为应用资产的一部分打包，或在应用首次启动时通过安全通道获取。校验逻辑应尽可能早地执行，并在失败时向用户清晰展示结果和修复指引。由于不同端侧推理引擎对 LoRA 的实现有差异，无法制定统一的 manifest 行业标准，此处构建的契约只应视为具体项目内的约定，需针对特定引擎定制。

跨引擎迁移时，必须重新分析新引擎对适配器格式、注入方式和量化的要求，重新生成对应的 manifest，不能复用旧文件。工程判断认为，未来端侧模型市场可能向标准化资产包演进，但在统一规格出现之前，建立在文件摘要、维度和量化配置上的显式校验仍是最务实可靠的做法，能有效隔离因引擎差异导致的兼容性风险。

决策总结与重绑触发条件

若基础模型权重文件被替换或更新，需重新审查并更新 LoRA 适配器与基础模型的绑定契约。此外，若基础模型架构配置中隐藏层维度、层数或注意力头数发生变化，也需重新建立契约。基础模型的量化精度或方法改变，以及 tokenizer 词汇表或特殊标记集更新，同样是破坏性变更，需要将所有依赖的适配器重新训练或至少重新验证，确保资产组的整体一致性。

如果只是对 LoRA 适配器本身进行微调并保持注入结构不变，通常只需要更新 manifest 中的适配器摘要，版本绑定关系可维持。但任何基础模型侧的变化都应被视为版本契约的破坏性更新。在端侧环境中，还应考虑设备 GPU 驱动或推理引擎升级的影响，虽然这不直接改变模型文件，但可能导致运行时加载失败，理想情况下应将推理引擎版本列入 manifest 的兼容列表中。

加载决策以摘要、兼容字段和分发批次的校验结果为准。校验失败时停用当前组合，并切换到明确的重新下载或已验证基线流程，不在本地猜测修复。跨框架迁移时重新生成 manifest 和兼容矩阵，因为旧运行时的字段不能直接代表新环境。

• 确认 manifest 与适配器文件一同发布并受相同完整性保护
• 检查 manifest 中是否记录了 base_model_sha256、hidden_size、num_layers、lora_rank 和 quantization
• 部署时先于任何推理调用执行校验脚本，失败即终止并提示用户
• 更新基础模型后立即重新生成所有关联 manifest，并在服务端维护匹配对
• 为 manifest 和模型文件引入 TUF 签名，防止回滚攻击
• 在跨框架迁移时重新审查适配器兼容性，不沿用旧 manifest