4、模型包格式与组成：常见模型包结构（权重、结构、元数据、配置文件）、打包规范与版本管理

Edge AI 模型从训练环境到设备端部署，并非简单拷贝一个权重文件，而是需要经过标准化封装、完整性校验与安全加载的完整链路。模型包（Model Package）作为这一链路的载体，其内部结构、打包规范与版本管理策略，直接决定了后续验签、解密、加载与推理的可靠性与安全性。本章将深入拆解模型包的常见组成要素、打包规范以及版本管理机制，为后续章节的验签与安全加载流程奠定基础。

上图展示了 Edge AI 模型包的标准内部布局。一个完整的模型包并非单一文件，而是由权重、结构、元数据、配置及安全校验文件共同组成的复合容器。理解每个组成部分的职责与格式，是实施安全加载的前提。

4.1 模型包核心组成要素

4.1.1 权重文件（Weights）

权重文件存储模型训练得到的参数张量，是模型包中体积最大的部分。在 Edge AI 场景下，权重文件通常采用以下格式之一：

• 原始二进制格式（.bin/.weights）：按层顺序连续存储，无额外头部信息，加载时需配合结构文件解析。
• TensorFlow Lite 格式（.tflite）：将权重与结构合并为单一 FlatBuffer 文件，内置算子调度信息。
• ONNX 格式（.onnx）：使用 Protobuf 序列化，包含权重与计算图，适合跨框架迁移。
• 量化权重（int8/uint8）：为适配边缘设备 NPU/DSP，权重常量化为 8bit，需额外存储缩放因子（scale）与零点（zero point）。

权重文件的组织方式直接影响加载效率。对于大模型（>100MB），建议将权重按层或按 Block 分片存储，便于流式加载与内存映射（mmap）。

4.1.2 结构文件（Structure）

结构文件描述神经网络的拓扑信息，包括层类型、层间连接、激活函数、池化参数等。在模型包中，结构文件与权重文件分离存储，便于在不修改权重的情况下调整网络结构（如剪枝后的结构更新）。常见的结构描述格式有：

• JSON 格式：可读性强，适合调试与版本对比，但解析开销较大。
• Protobuf 格式：二进制紧凑，解析效率高，适合生产环境。
• FlatBuffer 格式：零拷贝访问，适合内存受限的 MCU 设备。

结构文件还包含输入/输出张量的形状、数据类型、数据布局（NHWC/NCHW）等关键信息，这些信息是推理引擎分配内存和调度算子的依据。

4.1.3 元数据（Metadata）

元数据是模型包的“身份证”，以 YAML 或 JSON 格式存储，包含以下关键字段：

元数据在验签过程中扮演重要角色——签名时需将元数据中的关键字段（如版本号、哈希值）纳入签名范围，防止被篡改后绕过版本检查。

4.1.4 配置文件（Config）

配置文件定义模型在目标设备上的运行参数，与模型结构无关，但影响推理性能与资源占用。典型配置项包括：

{
  "inference": {
    "backend": "tensorrt",
    "precision": "fp16",
    "max_batch_size": 4,
    "workspace_size_mb": 256
  },
  "preprocess": {
    "resize": [640, 640],
    "normalize": {"mean": [0.485, 0.456, 0.406], "std": [0.229, 0.224, 0.225]},
    "color_format": "RGB"
  },
  "runtime": {
    "threads": 4,
    "memory_pool": "cuda",
    "enable_profiling": false
  }
}

配置文件允许同一模型包在不同硬件平台（CPU/GPU/NPU）上以不同参数运行，实现“一次打包，多端适配”。

4.2 打包规范与目录结构

4.2.1 标准目录布局

为保证跨平台兼容性与工具链一致性，建议采用以下目录结构：

model_package/
├── manifest.json          # 包描述文件（含文件清单与哈希）
├── weights/
│   ├── model_weights.bin  # 主权重文件
│   └── auxiliary.bin      # 辅助权重（如BN统计量）
├── structure/
│   └── model_structure.json
├── metadata/
│   └── metadata.yaml
├── config/
│   ├── config.json        # 推理配置
│   └── preprocess.json    # 预处理流水线
├── security/
│   ├── signature.sig      # 数字签名
│   ├── cert_chain.pem     # 证书链
│   └── checksums.txt      # 逐文件SHA-256
└── assets/                # 可选：标签文件、锚框、颜色映射等
    └── labels.txt

该布局将不同职责的文件分离，便于安全工具链对特定目录（如 security/）进行独立校验，同时避免将签名文件与权重文件混放导致验签逻辑复杂化。

4.2.2 打包工具链与流程

推荐使用 edge_model_packager 工具（或自研脚本）执行以下打包步骤：

1. 收集产物：从训练平台导出权重、结构、元数据。
2. 生成配置文件：根据目标设备硬件规格自动生成 config.json。
3. 计算哈希：对每个文件计算 SHA-256，生成 checksums.txt。
4. 签名：使用私钥对 manifest.json（含文件哈希列表）进行签名，生成 signature.sig。
5. 压缩封装：将全部文件打包为 ZIP 或 TAR.GZ，并设置压缩级别（建议 weights 使用 store 模式避免重复压缩）。
6. 输出校验：解包验证文件完整性，确保打包过程无损坏。

4.3 版本管理策略

4.3.1 语义化版本号（SemVer）

模型包版本号遵循 主版本.次版本.修订号 格式，并附加预发布标识：

• 主版本（Major）：不兼容的模型结构变更，如网络层数变化、输入尺寸改变。
• 次版本（Minor）：向后兼容的功能新增，如增加新算子支持、优化量化参数。
• 修订号（Patch）：Bug 修复或精度微调，不影响接口。
• 预发布：-rc.1、-beta.2 等，用于测试阶段。

设备端 OTA 升级时，需根据版本号差异决定是否重新验签。例如，主版本升级必须重新执行完整验签流程，而修订号升级可仅校验哈希。

4.3.2 版本兼容性矩阵

版本管理还需考虑模型包与推理引擎（如 TensorRT、ONNX Runtime）的兼容性。建议在元数据中记录引擎的最低版本要求，并在加载时进行校验。

4.4 实战案例：智能摄像头模型包升级

4.4.1 背景与约束

某安防厂商部署了 5000 台边缘智能摄像头，运行人员检测模型 v1.2.0。现需升级到 v2.0.0，新模型将骨干网络从 ResNet18 替换为 MobileNetV3，输入分辨率从 512×512 提升至 640×640，并增加了行人属性识别分支。设备端存储空间仅剩 80MB，且 OTA 升级窗口仅有 30 分钟。

4.4.2 初始现象与目标

直接替换模型包后，部分设备出现加载失败，错误日志显示 structure.json 解析异常。进一步排查发现，新模型包中 structure.json 使用了 Protobuf 格式，而设备端推理引擎仅支持 JSON 格式。此外，新权重文件体积为 45MB，加上其他文件后总包体达 62MB，接近存储上限。

4.4.3 分析判断过程

通过对比 v1.2.0 与 v2.0.0 的 manifest.json，发现以下差异：

• 结构文件格式从 JSON 变为 Protobuf，未在元数据中标注格式类型。
• 权重文件从单文件拆分为 3 个分片，但 checksums.txt 未更新对应条目。
• 配置文件新增了 enable_quantization 字段，旧版引擎无法识别。

根因是打包流程未遵循版本兼容性规范，且缺少对目标设备引擎能力的探测。

4.4.4 实际操作步骤

1. 回滚至旧版本：通过 OTA 管理平台将设备回滚至 v1.2.0，恢复服务。
2. 修正打包配置：在打包工具中增加 --engine-compat 参数，自动检测引擎支持的格式。
3. 重新生成模型包：将 structure.json 转为 JSON 格式，合并权重分片为单文件，并更新 checksums.txt。
4. 压缩优化：对权重文件使用 LZ4 压缩（而非默认的 ZLIB），将包体从 62MB 降至 48MB。
5. 灰度发布：先向 100 台设备推送，验证加载成功率与推理延迟。
6. 全量升级：确认无误后，分批次升级剩余设备，每批 1000 台，间隔 10 分钟。

4.4.5 结果对比与复盘

复盘经验：模型包升级不仅是文件替换，必须进行设备端兼容性预检。建议在打包阶段生成“设备能力描述文件”，并在加载前比对引擎版本、可用内存、算子支持列表。同时，版本号应严格遵循 SemVer，主版本升级时需在元数据中声明 breaking changes。

4.5 常见误区与总结

4.5.1 常见误区

• 误区一：将权重文件与结构文件合并为一个二进制文件，导致结构更新时必须重新下载整个大文件。
• 误区二：忽略元数据中的框架版本信息，导致设备端引擎无法解析新算子。
• 误区三：打包时使用默认 ZIP 压缩，对已压缩的权重文件（如 .bin）再次压缩，浪费 CPU 且无体积收益。
• 误区四：版本号仅使用时间戳，无法表达兼容性关系，导致 OTA 升级策略难以制定。

4.5.2 总结复盘

模型包格式与组成是 Edge AI 安全加载的基石。一个规范的模型包应具备：

• 清晰的文件边界：权重、结构、元数据、配置分离，便于独立更新与校验。
• 完整的哈希与签名：确保包内容在传输与存储过程中未被篡改。
• 严格的版本管理：通过 SemVer 表达兼容性，配合设备能力探测实现平滑升级。
• 可追溯的元数据：记录训练环境、精度指标、许可证等关键信息，便于审计与合规。