📚 课程目录第3章模型包结构

3、模型包结构：标准目录布局、文件命名规范、版本管理以及多文件之间的依赖关系

Edge AI模型包并非单一文件，而是一个由模型权重、配置、签名、元数据、依赖清单等组成的结构化集合。若目录布局混乱、命名随意、版本失控，模型在跨设备部署、OTA升级或回滚时极易出现“找不到文件”“版本不匹配”“签名校验失败”等问题。本章围绕模型包的物理组织方式展开，重点解决三个问题：文件放在哪里、如何命名、如何管理版本与依赖关系。

3.1 标准目录布局：从“能跑”到“可维护”

一个合格的Edge AI模型包，目录结构应当让新加入的工程师在30秒内定位到任何关键文件。推荐采用“按职责分目录”的方式，而非“按文件类型堆叠”。标准布局如下：

model_package/
├── model/                  # 模型权重文件（可多格式并存）
│   ├── model.tflite        # 原始浮点模型
│   ├── model_quant.tflite  # 量化模型（INT8）
│   └── model_edgetpu.tflite# Edge TPU 编译版本
├── config/                 # 运行配置（JSON格式，便于解析）
│   ├── model_config.json   # 模型结构参数、输入输出张量定义
│   ├── preprocess.json     # 预处理参数（均值、方差、尺寸）
│   └── postprocess.json    # 后处理参数（阈值、类别映射）
├── signature/              # 安全相关文件
│   ├── model.sig           # 签名文件（对model+config的哈希签名）
│   ├── public_key.pem      # 验签公钥（部署端内置）
│   └── hash_manifest.json  # 各文件SHA-256哈希清单
└── metadata/               # 描述性信息
    ├── model_info.yaml     # 模型名称、版本、作者、训练框架
    ├── changelog.md        # 版本变更记录
    └── dependencies.json   # 运行时依赖（如TensorFlow Lite版本、算子库）

这种布局的核心价值在于：模型文件与配置分离，使得同一模型在不同硬件平台（CPU/GPU/NPU）上部署时，只需替换model目录下的文件，而无需改动config；签名与内容分离，便于在OTA传输时先校验签名再加载模型；元数据独立，方便版本管理和审计追踪。

  实践建议：对于轻量级场景（如MCU上的关键字识别），可适当精简目录，但至少保留model/、config/、metadata/三个目录。signature/在无安全要求的内部测试环境可暂缺，但生产环境必须包含。

3.2 文件命名规范：语义化、版本化、平台化

文件命名直接影响自动化脚本的编写和人工排障的效率。推荐遵循以下规则：

文件类型	命名模式	示例	说明
模型权重	{model_name}_{variant}.{ext}	yolov5s_quant.tflite	variant标识量化、剪枝、蒸馏等变体
配置文件	{purpose}_config.json	preprocess_config.json	明确配置用途，避免通用config.json
签名文件	{model_name}.sig	yolov5s.sig	与模型文件同名，便于关联
元数据	model_info.yaml	model_info.yaml	固定名称，便于工具链识别
依赖清单	dependencies.json	dependencies.json	固定名称，内容为JSON数组

命名中禁止使用空格、中文、特殊字符（下划线和连字符除外），版本号统一采用v{major}.{minor}.{patch}格式，如yolov5s_v2.1.0_quant.tflite。平台标识建议放在变体位置，如_edgetpu、_rknn、_cpu，方便自动化部署脚本按平台选择文件。

3.3 版本管理：语义化版本与模型演进

模型版本管理比软件版本管理更复杂，因为模型变更可能来自训练数据、网络结构、量化参数、编译选项等多个维度。推荐采用语义化版本+哈希双重机制：

语义化版本（SemVer）：MAJOR.MINOR.PATCH。MAJOR升级表示模型结构或输入输出协议不兼容；MINOR升级表示精度提升或功能增强但接口兼容；PATCH升级表示bug修复或量化参数微调。
内容哈希（SHA-256）：在metadata/model_info.yaml中记录每个文件的哈希值，用于精确追踪内容变更，防止“版本号没变但文件被替换”的隐患。
变更记录（changelog.md）：每次版本更新必须记录变更原因、影响范围、验证结果。

# metadata/model_info.yaml
model_name: "yolov5s"
version: "2.1.0"
semver:
  major: 2
  minor: 1
  patch: 0
files:
  model/model_quant.tflite: "sha256:3f9a..."
  config/model_config.json: "sha256:8c2b..."
  config/preprocess.json: "sha256:1a7e..."
dependencies:
  runtime: "tflite-runtime==2.14.0"
  ops: ["CONV_2D", "DEPTHWISE_CONV_2D", "RESIZE_NEAREST_NEIGHBOR"]

版本管理的关键原则：版本号是承诺，哈希是事实。当两者冲突时，以哈希为准。部署系统应同时校验版本号和哈希，任何不匹配都拒绝加载。

3.4 多文件依赖关系：显式声明与自动校验

模型包内文件并非孤立存在，它们之间存在引用、校验、描述三类依赖关系。必须通过dependencies.json显式声明，避免“隐式依赖”带来的部署事故。

依赖类型	关系描述	校验方式	失败处理
引用依赖	config/model_config.json 中引用 model/model_quant.tflite	检查文件存在性、路径正确性	报错并终止加载
校验依赖	signature/model.sig 对 model+config 的哈希签名	使用公钥验签，比对哈希	拒绝加载并告警
描述依赖	metadata/model_info.yaml 描述所有文件的版本和哈希	逐文件比对哈希	标记为“不一致”并触发回滚

一个典型的依赖校验流程如下：

1. 读取 metadata/model_info.yaml，获取文件清单和哈希
2. 遍历清单，计算每个文件的SHA-256，与记录比对
3. 读取 signature/model.sig，使用 public_key.pem 验签
4. 解析 config/model_config.json，确认引用的模型文件存在
5. 全部通过 → 加载模型；任一失败 → 进入回滚流程

风险警示：切勿在config中硬编码路径（如/home/user/models/xxx.tflite），应使用相对路径（../model/model_quant.tflite）。路径会导致模型包无法迁移到其他设备或目录。

3.5 实战案例：智能摄像头模型包升级失败复盘

背景：某安防厂商的智能摄像头搭载Edge AI芯片，运行人员检测模型。一次OTA升级中，200台设备中有37台升级后无法启动，其余设备正常。

初始现象：设备启动日志显示Model file not found: /opt/edge/model/yolov5s_v2.1.0.tflite，但升级包中确实包含该文件。

关键输入数据：

升级包版本：v2.1.0（从v2.0.3升级）
失败设备固件版本：v1.9.x（旧版本）
正常设备固件版本：v2.0.x

分析判断过程：工程师检查升级脚本发现，脚本使用rm -rf /opt/edge/model/清空旧模型目录，再解压新包。但旧固件（v1.9.x）的启动脚本会在升级完成后、新模型解压前，尝试加载/opt/edge/model/下的模型文件。由于目录被清空且新文件尚未就位，启动进程崩溃。而v2.0.x固件增加了“模型文件就绪”检查，因此不受影响。

实际操作步骤：

修改升级脚本：先解压新模型包到临时目录/opt/edge/tmp_pkg/，校验签名和哈希通过后，再原子替换/opt/edge/model/目录（使用mv而非rm+cp）。
在dependencies.json中增加min_firmware_version: "2.0.0"字段，升级前检查固件版本，不满足则中止升级。
在model_info.yaml中补充upgrade_compatibility字段，标明该模型包兼容的固件版本范围。

结果对比：修复后重新推送升级，失败率降为0。后续所有模型包均强制包含dependencies.json中的固件版本约束。

风险与代价：37台设备需要现场人工恢复，耗时2天，损失约5万元。复盘经验：模型包不仅是“文件集合”，更是“部署契约”，必须显式声明所有依赖和兼容性约束。

3.6 常见误区与总结复盘

经验提醒：模型包结构设计应遵循“三提前”原则——提前定义目录规范、提前制定命名规则、提前建立版本校验机制。不要等项目上线后再补，否则历史包袱会让规范推行举步维艰。

常见误区包括：

误区一：所有文件平铺在一个目录。导致文件数量多时难以管理，且签名、配置、模型混在一起，安全审计困难。
误区二：版本号只写在文件名中。文件名中的版本号容易被复制粘贴时遗漏，应以metadata中的版本为准，文件名版本仅作辅助。
误区三：忽略依赖声明。认为“反正文件都在包里，不会缺”。实际部署时，不同设备可能只解压部分文件，或OTA增量更新时只传输变更文件，没有依赖清单就无法校验完整性。
误区四：签名只覆盖模型文件。攻击者可能篡改config中的预处理参数（如将均值改为0），导致模型精度下降或产生错误输出。签名应覆盖model+config+metadata中所有关键文件。

总结：模型包结构是Edge AI工程化的基石。标准目录布局提供物理组织框架，命名规范确保可读性和可脚本化，语义化版本+哈希双重机制保障版本可信，显式依赖声明让部署系统具备自动校验能力。建议团队在项目初期就制定《模型包结构规范》文档，并配套自动化构建工具（如Python脚本生成模型包），从源头保证一致性。