第16章 学生项目冲刺四：接入智能能力
v0.1已经用真实设备完成产品闭环。本周接入《人工智能数据科学》课程形成的模型发布包。模型运行器将替换基线判断。主机、设备和产品事件三层验证通过后，项目发布v0.5。
v0.1稳定接口
＋ 数据集版本
＋ 模型发布包
→ 接收检查
→ 模型运行器
→ 资源与数值验证
→ 事件策略
→ v0.5
一周内无法同时完成大规模重新采集、反复模型研究和多平台部署。本章首先检查输入是否已经具备；不具备时立即采用降级路线，而不是在周末才发现模型无法进入产品。
模型在测试集上的指标只描述规定条件下的表现。产品还要处理设备输入、运行资源、事件规则和用户反馈。模型接入把这些边界连接起来，因此可能暴露训练阶段未出现的问题，也会增加跨课程协调成本。
完成本章后，应当能够：
- 判断数据和模型是否达到工程接收条件；
- 固定标签、数据划分、预处理和模型包版本；
- 通过模型清单与散列值接收模型；
- 选择端侧、服务器或混合推理位置并保存理由；
- 使用基准输入输出验证运行接口；
- 测量目标硬件资源和时延；
- 保持模型输出与产品事件分离；
- 让AI生成受限集成代码和一致性检查；
- 在模型不满足时选择正确的跨课程调整；
- 发布包含智能能力的
v0.5.0。
16.1 执行周初接入门禁
必须回答：
[ ] 数据来自已记录采集会话
[ ] 正例、反例和主要干扰均有样本
[ ] 数据授权范围支持当前用途
[ ] 标签定义稳定
[ ] 采样率、单位、窗口和通道顺序已固定
[ ] 训练/验证/测试划分可追溯
[ ] 基线模型已有实际评价
[ ] 模型格式能被计划运行环境支持
[ ] 模型包交付时间不晚于本周中段
若前三项不满足，不能靠生成合成数字填补数据。可选择：
- 缩减为更少类别；
- 使用课程已批准公开数据验证工程接口，并明确场景差异；
- 保留
v0.1规则版本，把正式模型列入v1.1； - 更换为数据条件已经具备的项目范围。
降级决定写入技术决策记录和README.md。
16.2 固定数据和标签接口
16.2.1 数据集版本
dataset-manifest.json至少记录：
dataset_version
source_sessions
sensor_schema
sampling_configuration
label_definition_version
split_artifacts_and_hashes
generation_code_commit
access_and_authorization
标签定义文件说明：
- 每个类别的正面定义；
- 不属于该类别的条件；
- 边界和无法判断情况；
- 标注人员与复核方法；
- 主要混淆类别；
- 标签版本变化。
本课程不评价标注算法，但检查标签和产品event_type是否存在清楚映射。
16.2.2 输入一致性
| 参数 | v0.1设备 | 数据集 | 模型 | 处理 |
|---|---|---|---|---|
| 传感器/通道 | | | | |
| 单位 | | | | |
| 采样率 | | | | |
| 窗口长度 | | | | |
| 步长 | | | | |
| 数据类型 | | | | |
任何不一致必须显式转换或重新生成构建物。不能只修改文档数字。
16.3 接收基线模型发布包
最小发布包：
model-manifest.json
model-card.md
labels.txt
preprocessing.json
evaluation-summary.json
golden-input
golden-output
模型二进制或受控取得信息
接收检查：
python tools/project.py fetch-model <model-version>
python tools/project.py verify-model <model-version>
python tools/project.py model-golden-test <model-version>
记录：
model_version
model_sha256
dataset_version
training_commit
run_id
input/output
evaluation_file
known_limitations
评价摘要中的数字来自数据科学课程实际测试。产品团队不能为了满足发布要求自行补写。
16.4 决定模型运行位置
16.4.1 三种基本方案
| 方案 | 优点 | 主要代价 |
|---|---|---|
| 端侧推理 | 低网络依赖、原始数据可留在设备 | 资源、功耗和算子受限 |
| 服务器推理 | 资源充足、模型更新方便 | 网络、延迟、数据上传和隐私 |
| 混合判断 | 设备初筛，服务器进一步分析 | 接口和版本更复杂 |
选择依据：
- 用户结果允许的延迟；
- 断网要求；
- 原始数据能否上传；
- 模型资源；
- 功耗；
- 服务器可用性；
- 更新和回退；
- 课程时间。
沿用教师项目的端侧方案不一定适合所有学生项目。决定写入技术决策记录，并设定重新评估条件。
16.4.2 一周内的降级顺序
若端侧资源不满足：
- 检查集成错误和重复缓冲；
- 请求数据科学课程提供已评价的轻量发布包；
- 评估在隐私和网络允许时采用服务器推理；
- 继续使用
v0.1基线判断并记录限制。
不在本周无计划地更换多个推理框架和主控。
16.5 实现模型运行器
保持v0.1的DecisionEngine接口：
class ModelDecisionEngine final : public DecisionEngine {
public:
bool begin(const ModelPackage& package);
DecisionResult evaluate(const InputFrame& frame) override;
ModelResourceUsage resources() const;
};
初始化检查：
模型散列
输入输出形状
预处理版本
标签数量和顺序
运行时与算子
内存分配
模型版本日志
推理失败返回无效结果，不能复用上一次分数。
16.6 约束AI完成集成
规划请求：
任务：把<model-version>接入v0.1 DecisionEngine。
只读取：
- 模型清单、预处理、标签和基准样例文件
- v0.1 DecisionEngine接口
- 数据窗口配置
- 当前构建文件
先检查：
1. 输入、输出和标签是否一致；
2. 工具链是否支持模型格式；
3. 需要的文件和资源；
4. 计划修改范围；
5. 基准样例与资源验证方法。
禁止：
- 修改模型包和数据Manifest；
- 改变事件契约；
- 调整模型指标或策略阈值；
- 下载未知模型；
- 添加未批准依赖；
- 提交、推送和烧录。
实施后检查：
[ ] 没有复制另一套输入参数
[ ] 模型版本来自构建物
[ ] 缓冲区有上限
[ ] 量化与类型转换明确
[ ] 错误不会产生有效事件
[ ] 只修改当前议题文件
[ ] 本地构建命令可以复现
16.7 完成三层验证
16.7.1 主机接收验证
python tools/project.py verify-model <model-version>
python tools/project.py model-golden-test <model-version>
证明模型包、预处理和参考运行接口一致。
16.7.2 目标运行环境验证
端侧项目：
python tools/project.py build --profile golden
python tools/project.py flash
python tools/project.py monitor
服务器项目运行相同基准样例输入到部署服务。记录实际：
- 运行环境；
- 模型散列；
- 输入输出；
- 最大误差和批准容差；
- 闪存、RAM或服务器资源；
- 推理时间分布；
- 失败情况。
16.7.3 产品事件验证
模型分数经过事件策略后，使用：
- 固定分数序列；
- 数据回放；
- 真实正例、反例和主要干扰。
核对事件携带：
model_version
policy_version
firmware_or_service_version
event_id
event_type
模型正确运行不等于用户事件正确。三层结果分别保存。
16.8 选择初始事件策略
根据项目设置：
- 目标类别；
- 平滑方法；
- 触发阈值；
- 连续确认；
- 冷却；
- 无效输入处理；
- 模型失败降级。
每项参数来自数据验证或产品风险，不由AI凭经验给出。策略配置与模型版本绑定：
policy-0.5.0
↔ model-<实际版本>
↔ dataset-<实际版本>
修改参数建立议题，附数据或场景证据。
16.9 处理跨课程变更
模型输入与设备不一致
建立跨课程议题，列出三处实际值。由数据课程决定重新导出，或由硬件课程确认设备端转换。转换进入版本化预处理并重新评价。
模型资源超过预算
附构建映射、内存和时延实测。不要只写“模型太大”。比较轻量模型、服务器推理或硬件方案。
真实场景效果低于测试集
记录具体场景、硬件、模型和事件。数据课程分析分布和错误样本，产品团队检查安装与策略。本周不把全部问题归因于阈值。
模型包临时更新
已接收的模型文件不可原地覆盖。新内容使用新版本和散列，重新执行三层验证。
16.10 合并智能能力
建议合并请求：
数据与模型清单合并请求
→ 模型接收检查MR
→ `ModelDecisionEngine`合并请求
→ 事件策略MR
→ v0.5集成MR
模型、固件和事件策略由不同成员评审。合并请求说明AI参与、实际模型版本、验证层级和已知限制。
不要把大模型二进制的普通Git差异与大量集成代码混在一个无法审查的提交中。按课程规定使用Git LFS或受控构建物存储。
16.11 发布v0.5
README.md更新：
- 当前智能能力；
- 模型用途与不适用范围；
- 数据和模型版本；
- 推理位置；
- 取得和核对模型的方法；
- 资源与延迟实测；
- 事件策略；
- 已知错报、漏报和场景限制；
- 回退到
v0.1的方法。
发布检查：
[ ] 数据集与授权可追溯
[ ] 模型包完整且散列一致
[ ] 输入和输出接口一致
[ ] 主机基准样例测试通过
[ ] 目标环境基准样例测试通过
[ ] 资源有实际测量
[ ] 事件策略测试通过
[ ] 真实正例、反例和干扰有记录
[ ] 事件能追溯模型与策略
[ ] 回退路径可执行
[ ] README.md没有把模型指标写成产品承诺
创建：
git switch main
git pull --ff-only
git tag -a v0.5.0 -m "v0.5.0 integrated intelligent capability"
git push origin v0.5.0
16.12 本章小结
本章把数据科学课程的模型发布包接入学生项目。模型清单、散列值和基准样例固定输入输出。资源测量和事件策略把模型结果转化为产品能力。
模型未达到工程接收条件时，团队使用明确降级路线，而不是让AI补写数据、指标或接口。v0.5保留v0.1闭环，并为第17章的系统测试和用户试用提供智能版本基线。
16.13 综合实践
- 对数据和模型执行接入门禁。选择最危险的缺失项，形成继续、降级或延后的工程决定。
- 建立设备、数据集和模型输入一致性表。对一个不一致项提出跨课程议题，并附实际证据。
- 比较端侧、服务器和混合推理，依据本组约束选择方案。决定写入技术决策记录。
- 接入模型包，完成基准样例、资源和产品事件3层验证。说明每层能够和不能够证明什么。
- 用数据或风险证据确定事件策略参数，形成
v0.5.0发布说明，并追溯到数据集、模型和代码版本。