第9章：AI项目交付闭环
9.1 章节总览
本章以“基于 COCO SSD300 的实验室实时检测告警系统”为贯穿案例，建立从需求澄清->指标体系->评测集->迭代节奏->资产沉淀->交付与回归的一套闭环方法论，让技术决策基于指标与风险敞口，而非经验臆测。核心理念：可量化、可比较、可复用、可追溯。
案例默认使用 Hugging Face 仓库 zhouxzh/SSD300 中的 ssd300_resnet50.onnx / ssd300_resnet50.om。其中 ssd300_ 表示输入尺寸为 300×300，和后续 ssd320_ SSDLite320 模型区分。实验室告警逻辑只基于 COCO 检测结果做后处理，例如 ROI 闯入、人数统计、背包/电脑/水杯等物品遗留提醒，不重新训练模型，也不额外构建专用数据集。
9.2 需求澄清 Canvas
| 维度 | 要素 | 问题提示 | 示例 |
|---|---|---|---|
| 场景 | 输入源/运行环境 | 摄像头？批处理？ | 实验室入口或设备区摄像头 |
| 目标 | 功能/业务价值 | 用户希望看到什么结果？ | SSD300 实时检测 + 规则告警 |
| 指标 | Latency/FPS/精度 | 哪些分位数重要？ | <80ms / >=25FPS / mAP>=0.6 |
| 约束 | 能耗/内存/带宽 | 上限是多少？ | 功耗<=15W 内存<=3GB |
| 风险 | 数据/硬件/算法 | 失败模式有哪些？ | 低光/遮挡/误报/摄像头抖动 |
| 合规 | 隐私/许可 | 是否需要脱敏？ | 仅上传事件元数据 |
| 成本 | 硬件/云 | ROI 衡量？ | 10 台板卡预算 |
输出：requirement.yaml（版本化），后续所有评审基于此文档。
9.3 指标分层与优先级
| 层级 | 类别 | 指标 | 说明 | 失败后果 |
|---|---|---|---|---|
| SLO A | 体验 | p95 延迟 | 端到端 | 体验差/丢帧 |
| SLO A | 性能 | FPS | 稳态吞吐 | 处理拥堵 |
| SLO B | 质量 | mAP/F1/Top1 | 任务正确性 | 无法满足业务 |
| SLO B | 稳定 | Crash/小时 | 可靠性 | 运维成本高 |
| SLO C | 资源 | 内存峰值/功耗 | 成本约束 | 设备异常/降频 |
| SLO C | 带宽 | 上行 kbps | 成本/合规 | 费用/拥塞 |
优先级：先保障 A（体验+功能可用），再稳定 B（质量/稳定），最后优化 C（资源效率）。
9.4 Baseline 策略与控制变量法
Baseline 目标：建立 “最小改动可运行” 标尺。原则：
- 不提前做微优化；
- 记录所有关键参数：模型版本、输入尺寸、预处理策略、硬件温度范围；
- 一次仅改变单个变量（batch、精度、线程数）。 基线存档：
baseline/<date>-<commit>/metrics.json；对比脚本生成差异报告。
9.5 评测集设计原则
| 原则 | 内容 |
|---|---|
| 代表性 | 涵盖主流场景/光照/角度 |
| 覆盖边界 | 极端尺寸、模糊、遮挡 |
| 可再现 | 文件命名规范 + 固定清单 |
| 可扩展 | 新增样本不破坏旧索引 |
| 标注一致 | 标注工具/规范/审校流程 |
目录示例：
dataset_eval/
images/
day/*.jpg
night/*.jpg
occlusion/*.jpg
annotations/
instances_train.json
instances_val.json
meta/
README.md
version.txt提供 Hash 列表，防止样本被替换而影响回归可信度。
9.6 迭代计划与看板
四阶段：
| Sprint | 目标 | 核心产出 | 风险控制 |
|---|---|---|---|
| 0 | 环境/基线 | baseline metrics | 依赖清单齐全 |
| 1 | 精度与功能稳固 | 精度报告 | 数据问题快速反馈 |
| 2 | 性能与稳定 | 性能对比表/监控上线 | Watchdog 验证 |
| 3 | 工程交付包装 | Release Notes/脚本 | 灰度计划制定 |
看板列：Backlog -> Doing -> Review -> Bench -> Done；性能/精度任务需进入 Bench 列执行对比脚本通过后才可 Done。
9.7 资产沉淀文档体系
| 文档 | 内容 | 更新频率 |
|---|---|---|
| README | 快速启动 | 版本变化时 |
| ARCHITECTURE | 架构图/模块说明 | 结构调整 |
| MODEL_CARD | 模型来源/许可/精度/限制 | 模型更新 |
| EVAL_REPORT | 数据与评测方法/指标 | 每次发布 |
| PERF_REPORT | 基线/优化对比 | 优化后 |
| CHANGELOG | 可见版本差异 | 每次版本 |
| RISK_LOG | 已知风险列表 | 动态 |
MODEL_CARD 需包含：数据来源、训练超参摘要、输入契约、已知局限、许可（如 Apache-2.0）、安全与偏见说明（若涉及识别敏感属性声明避免用途）。
9.8 交付目录与不可变产物
release/
v1.0/
manifest.json # 产物 hash / 版本矩阵
models/
ssd300_resnet50.om
classify.om
signature.json
scripts/
run.ps1
run.sh
watchdog.sh
configs/
default.yaml
docs/
model_card_ssd300.md
model_card_classify.md
QUICKSTART.md
reports/
perf.json
accuracy.jsonmanifest.json 字段：{version, commit, build_time, model_hashes, dependencies}。
9.9 上线前综合 Checklist
| 类别 | 检查项 | 通过标准 |
|---|---|---|
| 功能 | 核心用例 100% | 自动化用例通过 |
| 性能 | p95 < 目标 +5% | 连续 30min 稳定 |
| 精度 | mAP/Top1 回归差 < 阈值 | 与基线对比 |
| 资源 | 内存峰值 < 75% | 1h 稳态无泄漏 |
| 稳定 | Crash=0, 重启=0 | 守护日志清洁 |
| 安全 | 日志无敏感泄露 | 关键字段脱敏 |
| 配置 | 签名校验一致 | Hash 匹配 |
| 回滚 | 验证上一版本可用 | 切换 < 30s |
9.10 验收、回归与漂移监测
交付后 7 天加密监控：记录时延、精度漂移（采样对比模型输出变化）。 漂移检测：相同输入集合（Shadow Set）每天抽样跑一次 -> 统计 logits KL 散度/TopK 变化率，高于阈值（如 KL > 0.05）触发报警（潜在数据分布变化或模型文件损坏）。 回归集版本化：eval_set_vX；若需替换样本 -> 新增版本，不覆盖旧数据。
9.11 风险管理与决策日志
风险登记表：risk_log.md 每条包含：ID、描述、影响、概率、缓解、当前状态。决策日志（Decision Record, ADR）：记录架构/模型/精度策略选择及备选方案放弃理由，以便新成员快速建立上下文。
9.12 章节小结
方法论的核心不是流程文档堆砌，而是“指标驱动 + 资产沉淀 + 可回滚”三支柱。通过契约化需求、标准化 Baseline、规范化评测与回归体系，使团队协作更高效、风险暴露更透明、交付结果更可信。
9.13 实践任务
- 输出
requirement.yaml（含指标与约束）。 - 构建 30 张代表图像的 mini 评测集并附 Hash 列表。
- 生成 baseline
metrics.json与后一次优化对比 diff 报告。 - 制作一个 MODEL_CARD 模板并填写一个模型示例。
- 编写上线 Checklist 并模拟一项未通过情形与处置方案。