第9章　接收数据与模型构建物并发布v0.3

v0.2已经能够采集带版本信息的真实传感器数据。本章从《人工智能数据科学》课程接收数据集版本和基线模型。项目把模型文件、预处理、类别、评价结果和适用边界组成发布包，并发布v0.3。

采集会话
→ 数据集版本
→ 训练与评价
→ 模型发布包
→ 工程接收检查
→ 仓库清单
→ v0.3

本章不重新讲解数据清洗、模型结构和训练算法。学生要查明模型所用的数据、代码和配置。还要核对输入输出、评价结果和二进制文件。项目应使他人在没有口头说明时取得同一模型。

只有源代码的项目可以从提交重新构建多数结果。数据集和模型文件通常体积较大，还可能受授权限制，不能只依靠普通源代码历史管理。清单、散列值和模型卡补足了来源关系，但也增加了存储与权限管理成本。

完成本章后，应当能够：

• 区分数据文件、数据集版本、训练运行和模型发布包；
• 使用构建物清单关联数据、代码、配置、模型与评价结果；
• 检查采集模式、预处理和模型输入是否一致；
• 选择适合二进制模型和大数据的存储方式；
• 使用文件散列验证构建物完整性；
• 阅读模型卡中的用途、指标、限制和风险；
• 拒绝缺少来源、版本或评价证据的模型文件；
• 让AI协助检查跨文件一致性，但不生成虚假指标；
• 通过合并请求接收跨课程成果；
• 固定v0.3的数据与模型工程基线。

9.1 模型不是一个文件

9.1.1 五个对象必须分开记录

一次模型开发至少产生五类对象：

只有model.tflite无法回答其来源和适用条件。两个同名文件可能来自不同数据和配置，同一个训练运行也可能导出多个设备格式。

9.1.2 工程版本关系

建议关系为：

采集会话清单
      ↓
数据集清单 ──→ dataset_version
      ↓
训练代码提交 + 训练配置
      ↓
训练运行记录
      ↓
评价结果 + 模型文件
      ↓
模型清单 ──→ model_version
      ↓
产品仓库v0.3

每条箭头都应有标识、文件路径或散列。模型进入产品仓库后，原训练仓库仍保留训练细节，产品仓库只接收发布所需证据和构建物。

9.1.3 从传递文件到交付构建物

只传递模型文件，接收者难以判断其来源和使用条件。用文件名追加日期或序号，也不能可靠关联数据、代码和评价结果。文件一旦被改名，原有关系还可能丢失。

模型发布包用构建物清单保存这些关系。散列值用于核对文件身份，模型卡说明用途和边界。维护这些记录会增加工作量，但能支持交付复现和版本比较。

9.2 接收数据集版本

9.2.1 数据集清单

数据科学课程提交datasets/dataset-manifest.json：

{
  "manifest_version": "1.0",
  "dataset_version": "dataset-0.2.0",
  "sensor_window_schema": "1.0",
  "source_sessions": [
    "session-001",
    "session-002"
  ],
  "sample_unit": "window",
  "labels": [
    "background",
    "target_event"
  ],
  "splits": {
    "train": {
      "artifact_id": "data-train-001",
      "sha256": "<actual-sha256>",
      "samples": 0
    },
    "validation": {
      "artifact_id": "data-validation-001",
      "sha256": "<actual-sha256>",
      "samples": 0
    },
    "test": {
      "artifact_id": "data-test-001",
      "sha256": "<actual-sha256>",
      "samples": 0
    }
  },
  "generation": {
    "repository": "<training-repository>",
    "commit": "<actual-commit>",
    "config_sha256": "<actual-sha256>"
  },
  "access": {
    "classification": "restricted",
    "authorization_record": "<record-id>"
  }
}

尖括号必须替换为真实值，样本数0表示模板尚未填写。正式数据集清单应填写实际正整数。训练集、验证集和测试集要有独立身份，不能只写一个总文件名。

9.2.2 检查数据来源和划分

本课程接收时检查：

[ ] source_sessions能追溯到v0.2采集记录
[ ] 传感器配置和窗口数据模式一致
[ ] 标签名称与模型输出计划一致
[ ] 划分文件有独立散列和数量
[ ] 测试集没有被训练流程覆盖
[ ] 数据访问和授权范围明确
[ ] 生成代码提交与配置可访问
[ ] 删除或排除规则已经记录

样本质量、类别分布和划分方法由数据科学课程给出分析；本课程检查这些结论是否随版本保存并能被后续发布引用。

9.3 定义模型发布包

9.3.1 发布包目录

产品仓库使用：

models/
└─ releases/
   └─ model-0.3.0/
      ├─ model-manifest.json
      ├─ model-card.md
      ├─ labels.txt
      ├─ preprocessing.json
      ├─ evaluation-summary.json
      ├─ golden-input.bin
      ├─ golden-output.json
      └─ model.tflite

文件名可以按课程工具链调整，但职责必须明确：

• 构建物清单连接所有文件与来源；
• 模型卡面向工程人员说明用途和限制；
• labels.txt固定输出索引与类别；
• 预处理文件固定窗口、缩放和量化要求；
• 评价摘要保存实际测试集结果；
• 基准输入输出用于集成一致性验证；
• 模型二进制是部署构建物。

9.3.2 模型清单

{
  "manifest_version": "1.0",
  "model_version": "model-0.3.0",
  "model_file": "model.tflite",
  "model_sha256": "<actual-sha256>",
  "format": "tflite",
  "dataset_version": "dataset-0.2.0",
  "training": {
    "repository": "<training-repository>",
    "commit": "<actual-commit>",
    "run_id": "<actual-run-id>",
    "config_sha256": "<actual-sha256>"
  },
  "input": {
    "sensor_window_schema": "1.0",
    "sample_rate_hz": 0,
    "window_samples": 0,
    "stride_samples": 0,
    "channels": ["x", "y", "z"],
    "dtype": "<actual-dtype>",
    "shape": [0]
  },
  "preprocessing_file": "preprocessing.json",
  "labels_file": "labels.txt",
  "output": {
    "dtype": "<actual-dtype>",
    "shape": [0]
  },
  "evaluation_file": "evaluation-summary.json",
  "golden_input_file": "golden-input.bin",
  "golden_input_sha256": "<actual-sha256>",
  "golden_output_file": "golden-output.json",
  "exported_at": "<actual-time>"
}

模型清单中的0和尖括号内容都是待填写位置，正式发布包的检查器必须拒绝这些值。形状、类型和参数来自实际导出模型，不从教材示例复制。model_version是项目分配的发布标识，model_sha256用于确认取得的二进制内容没有变化。

9.4 阅读模型卡

9.4.1 模型卡回答工程使用问题

model-card.md至少包含：

# 模型卡：model-0.3.0

## 目的
- 目标事件：
- 产品使用位置：
- 不适用用途：

## 输入
- 传感器与安装条件：
- 采样配置：
- 窗口和预处理：

## 数据
- dataset_version：
- 采集范围：
- 授权与限制：
- 已知缺口：

## 评价
- 测试集版本：
- 指标定义：
- 实际结果：
- 分类别结果：
- 评价脚本提交：

## 运行要求
- 模型格式：
- 输入输出类型：
- 所需算子：
- 已验证运行环境：

## 限制与风险
- 易混淆情形：
- 尚未覆盖的用户或环境：
- 错报与漏报影响：
- 需要人工确认的情况：

## 版本历史
- 本版本变化：
- 与上一版本兼容性：

模型卡不应只写一个总体准确率。项目还需要知道测试集、指标定义、分类别结果、场景限制和错误影响。

9.4.2 不把实验指标直接写成产品承诺

模型在固定测试集上的结果说明它在该评价条件下的表现。产品现场还受到传感器差异、安装方式、用户行为、网络和事件策略影响。

因此要区分：

模型指标
≠ 设备端数值一致性
≠ 产品事件准确性
≠ 用户场景效果

本章只接收模型评价证据。第10章测试设备端一致性和事件策略，第12章在试用场景中总结产品限制。

9.5 管理模型二进制和大数据

9.5.1 普通Git不适合反复保存大型二进制

文本文件可以逐行比较，二进制模型和数据文件通常只能整体替换。每个版本都直接提交到普通Git对象，会使仓库持续增大。

课程环境可以选择两种方式之一。Git大文件存储（Git Large File Storage，Git LFS）用指针替代大型二进制内容。256位安全散列算法（Secure Hash Algorithm 256，SHA-256）可生成固定长度的散列值。

具体方式由环境卡规定。无论选择哪一种，克隆仓库后都必须能够按照README.md取得正确构建物，并用SHA-256散列值核对。散列值一致可以支持内容核对，但不能证明模型质量或安全性。

9.5.2 使用Git LFS时

若课程GitLab启用Git LFS：

git lfs install
git lfs track "models/releases/**/*.tflite"
git add .gitattributes

检查.gitattributes：

models/releases/**/*.tflite filter=lfs diff=lfs merge=lfs -text

再添加模型文件并检查：

git add models/releases/model-0.3.0/model.tflite
git lfs ls-files
git status --short

不要在已经多次普通提交大型文件后才直接添加跟踪规则；历史迁移会改写提交，需要由维护者单独评估。

9.5.3 使用受控构建物存储时

模型清单增加：

{
  "artifact": {
    "id": "<artifact-id>",
    "sha256": "<actual-sha256>",
    "bytes": 0,
    "access": "course-approved",
    "fetch_command": "python tools/project.py fetch-model model-0.3.0"
  }
}

取得命令不得在仓库中包含个人令牌。下载后由工具核对大小和散列，失败时不把文件标记为可用。

9.6 用散列验证模型身份

在PowerShell中可以执行：

Get-FileHash -Algorithm SHA256 `
  models\releases\model-0.3.0\model.tflite

在课程统一工具中执行：

python tools/project.py verify-model model-0.3.0

工具至少检查：

1. 构建物清单所列文件全部存在；
2. 模型文件散列一致；
3. 标签文件非空且顺序明确；
4. 预处理文件版本正确；
5. 评价摘要指向同一数据集；
6. 基准输入输出散列一致；
7. 不存在未声明的发布文件。

散列证明文件内容与记录一致，不证明模型质量、安全性或适用性。质量仍由评价与使用边界说明。

9.7 检查数据、模型与固件契约

9.7.1 输入一致性表

将三处参数放在同一检查表中：

任何一行不一致都要先判断：

• 是文档错误；
• 是需要显式转换；
• 是数据集与模型不兼容；
• 还是v0.2采集配置已经变化。

不能让AI通过修改一方参数使表格“看起来一致”，而不重新生成数据或模型。

9.7.2 输出类别一致性

labels.txt中的行号对应模型输出索引：

background
target_event

服务器、用户端和事件策略不应各自维护另一份不同顺序。可以在构建时由模型包生成只读的类别常量，或由集成脚本检查多处一致。

更改标签名称、顺序或数量属于模型接口变化，需要：

• 新模型版本；
• 新模型清单和评价；
• 更新事件策略和用户显示；
• 更新基准样例测试；
• 说明兼容性。

9.8 使用基准输入输出建立接收测试

9.8.1 基准样例的作用

数据科学课程选择一个经过授权的固定输入。该输入不得带来个人身份风险，并应保存参考运行环境的输出。产品仓库取得模型后，先在主机环境运行相同输入：

python tools/project.py model-golden-test model-0.3.0

检查：

• 模型可以加载；
• 输入形状和类型正确；
• 预处理版本正确；
• 输出形状和类别数正确；
• 数值与参考输出在约定容差内。

基准样例测试不是模型准确率测试。一个样本一致只能证明导出文件、预处理和运行接口没有明显偏离。

9.8.2 容差必须由数值格式决定

浮点与量化运行可能存在小差异。容差由数据科学课程依据导出格式和参考运行确定，并记录在golden-output.json，不能为了让测试通过临时放宽。

9.9 让AI生成检查器而不是生成指标

9.9.1 一致性检查任务

任务：为模型发布包实现静态接收检查。

读取：
- datasets/dataset-manifest.json
- models/releases/model-0.3.0/model-manifest.json
- models/releases/model-0.3.0/preprocessing.json
- models/releases/model-0.3.0/labels.txt
- firmware/config/data_window.json

只允许修改：
- tools/model_package_check.py
- tests/tools/test_model_package_check.py

检查：
1. 必需文件和散列字段；
2. 数据集版本关系；
3. 采样率、窗口、步长和通道顺序；
4. 标签数量与输出形状；
5. 评价文件和基准样例文件引用；
6. placeholder或pending不得进入正式发布包。

禁止：
- 修改模型、数据清单和固件配置；
- 生成或补写评价指标；
- 自动下载未知来源模型；
- 提交和推送。

AI生成检查器后，人工构造一个参数不一致的测试包，确认脚本确实失败。只在正确样本上运行，不能证明错误检测有效。

9.9.2 防止“填满表格”的幻觉

重点搜索：

git diff
git grep -n -E "pending|placeholder|TBD|<actual|<approved"

正式模型包不应保留模板占位符。若资料确实缺失，应拒绝接收或明确标记为候选模型，不能让AI推测一个看似合理的数值。

9.10 通过合并请求接收模型包

模型交付议题至少写明：

# 接收model-0.3.0

## 来源
- dataset_version：
- training repository/commit：
- run_id：
- exporter version：

## 文件
- 模型清单：
- 模型卡：
- 模型二进制：
- 预处理与标签：
- 评价摘要：
- 基准输入输出：

## 接收条件
- [ ] 文件散列一致
- [ ] 输入契约与v0.2一致
- [ ] 输出类别一致
- [ ] 模型卡说明限制
- [ ] 主机基准样例测试通过
- [ ] 存储和访问方式符合课程规则
- [ ] 没有未授权数据

评审角色：

评审者提出修改时，不直接在产品仓库重新训练或替换模型。来源课程形成新发布包后，再更新当前合并请求。

9.11 更新追踪与版本

合并模型包后更新：

PR-01
→ 数据窗口规格
→ dataset-0.2.0
→ model-0.3.0
→ 基准样例接收测试
→ 待完成的设备部署议题

README.md中增加：

• 如何取得模型文件；
• 如何验证散列；
• 如何运行主机基准样例测试；
• 当前模型目标和限制；
• 尚未完成端侧部署的事实。

发布前检查：

[ ] 数据集清单可追溯
[ ] 模型发布包文件完整
[ ] 模型卡有实际评价和限制
[ ] 模型二进制存储方式明确
[ ] SHA-256核对通过
[ ] 采集、数据集和模型输入一致
[ ] 输出标签顺序唯一
[ ] 主机基准样例测试通过
[ ] 未授权数据没有进入仓库
[ ] 没有模板占位值或虚假指标

创建：

git switch main
git pull --ff-only
git tag -a v0.3.0 -m "v0.3.0 versioned dataset and model package"
git push origin v0.3.0

v0.3表示产品工程已经能取得、核对和运行基线模型，不表示模型已经在设备端满足资源和时延要求。

9.12 本章小结

本章把数据集和模型作为工程构建物接入项目。每项构建物都带有来源、版本、散列、接口、评价和限制。模型二进制只是发布包的一部分。构建物清单和模型卡说明它的来源、运行方法和适用范围。

AI用于编写一致性检查器和发现跨文件矛盾，不用于填补缺失指标。v0.3固定了数据—训练—模型—产品仓库之间的版本关系。

第10章将把model-0.3.0部署到真实设备。项目将测量闪存、内存和推理时间，核对基准输出。随后把连续模型结果转化为受控产品事件。

9.13 综合实践

1. 从《人工智能数据科学》课程接收一个模型，形成数据集清单、模型清单、模型卡和散列值记录。不得补写没有来源的指标。
2. 比较Git LFS与受控构建物存储。根据文件大小、访问授权和复现要求，选择一种方案并保存技术决策记录。
3. 人为构造一种输入形状、标签顺序或预处理不一致。设计接收检查，使不合格模型在进入主分支前被拒绝。
4. 与另一组交换模型发布包。对方应只依据仓库内容完成来源追踪和取得过程，并记录缺失信息。
5. 根据接收结果形成v0.3.0发布说明，明确该版本已经证明和尚未证明的事项。

9.14 拓展阅读

• 校内GitLab的Git LFS使用说明；
• 所选端侧模型格式的官方文档；
• 数据与模型课程发布的模型卡编写规范。