这份指南用于把仓库展示为一组可验证的工程决策，而不只是一批训练脚本。
我参与的工业安全多类别检测项目整合了多个为不同任务单独标注的数据源。在联合场景中，经常出现一个类别有标签、另一个可见类别漏标的问题。训练时，这些漏标目标会被当作负样本。
我围绕多个单类别 Teacher 模型实现了一套保守的漏标恢复流水线。它首先在不使用 GPU 的情况下审计 YOLO 数据集，然后逐个加载 Teacher，以有限批次流式推理；预测框只与同类别原标签匹配，并根据分类别阈值进入 AUTO、REVIEW 或 IGNORE。整个过程不修改源标签。
真正困难的是保证长时间 K x N 扫描的工程可靠性。我实现了 CUDA OOM 后的事务式自适应批大小、原子检查点、签名校验断点续跑、幂等 CSV/标签写入、环境 manifest 和 HTML 证据报告。公开仓库还提供合成演示、测试和 CI，同时排除了私有数据与模型权重。
| 能力 | 仓库证据 | 面试讲解重点 |
|---|---|---|
| 数据工程 | audit 命令 |
标签结构、孤立标签、损坏图片与跨数据划分泄漏 |
| 计算机视觉 | IoU 匹配与类别映射 | 同类别原标签匹配和 NMS 去重为什么不是一件事 |
| GPU 工程 | Teacher 串行加载与自适应 batch | 峰值资源与总计算量的区别，如何安全处理 OOM |
| 可靠性 | state.json 与幂等写入 |
批次提交边界与崩溃重放语义 |
| MLOps | doctor 与 manifest.json |
如何复现 CUDA、依赖版本和运行参数 |
| 人机协同 ML | AUTO/REVIEW/IGNORE | 分类别阈值与精度优先的审核策略 |
| 评估与策略 | calibrate 命令 |
将人工审核结果转换为精度/召回约束的分类别策略 |
| 集成决策 | consensus 命令 |
独立证据、一对一匹配与覆盖率/风险取舍 |
| 可扩展相似度搜索 | cluster 命令 |
感知哈希、BK-tree 半径查询与保守碰撞防护 |
| 主动学习 | prioritize 命令 |
不确定性、动态类别平衡、视觉多样性与偏置抽样边界 |
| 人工审核闭环 | review-build/review-ui/review-apply |
GT/AUTO 全情况、同目标替换、评测集隔离与安全写回 |
| 软件质量 | Python 包、CLI、测试和 CI | 公开测试夹具、隐私扫描与 Release 构建 |
| 技术沟通 | HTML 报告与架构文档 | 将模型工作转化为可审核、可展示的证据 |
- 运行
python examples/create_synthetic_dataset.py --output .demo-dataset。 - 运行
yolo-label-recovery audit .demo-dataset --output-dir .demo-audit --hash-images --check-images。 - 打开
.demo-audit/dataset_audit.html，展示主动注入的类别错误、孤立标签和跨划分重复图片。 - 打开
examples/demo_output/report.html，在不泄露项目数据的情况下展示补标质量报告。 - 打开
examples/calibration/output/calibration.html，解释为什么每个类别需要不同阈值。 - 打开
examples/consensus/output/consensus.html，展示不受支持的 AUTO 如何降级。 - 打开
examples/near_duplicates/output/near_duplicate_report.html，展示审核压缩与跨划分泄漏。 - 打开
examples/prioritization/output/prioritization_report.html，展示有限预算六类审核队列。 - 生成公开审核样例并打开
.demo-review-result/review_summary.html，展示模型证据到人工授权的边界。 - 打开
.demo-review-result/START_REVIEW.bat，展示离线审核、自动保存与续审。 - 运行
yolo-label-recovery doctor，展示环境诊断能力。
该演示不需要 GPU 或私有权重。具备合适的公开模型与数据后，可将完整 Teacher 扫描作为第二阶段演示。
为什么不直接覆盖原标签？
源数据不可变可以保证实验可撤销、可审核、可对比。删除派生标签目录即可回到标注基线。
为什么扫描六遍，而不是同时加载六个模型？
总计算量仍约为 K x N，但逐个加载模型可以限制显存峰值。这是吞吐量与运行可靠性之间的主动取舍。
为什么每个类别使用不同 AUTO 阈值？
Teacher 的置信度校准和目标难度不同。吸烟、拖鞋等小目标不能直接沿用大型机械类别的阈值。阈值是一项需要验证数据支持的策略，而不是通用常量。
阈值不是拍脑袋决定的吗？
calibrate 命令对人工审核候选排序一次，再生成累计精度召回曲线。AUTO 选择在指定置信水平下 Wilson 精度下限达到目标、且满足最小样本数的最低阈值；REVIEW 选择保留目标正样本召回率的最高阈值，从而减少人工工作量。样本无法支持目标时，工具不会提供回退阈值。
断点续跑为什么安全？
只有当前批次标签与 CSV 全部落盘后，状态游标才前移。如果输出完成但状态尚未提交时发生崩溃，重放过程会检查稳定候选键和精确标签行，避免重复写入。
为什么不同时加载两个 Teacher，直接集成预测张量？
分开扫描可以保留单模型显存上限，并通过稳定 CSV 约定接入不同检测器。共识阶段采用一对一 IoU 匹配，保留可审核证据，并把未获支持的 AUTO 降级而不是删除。
高置信度预测就是正确标签吗？
不是。高置信度只代表更强的证据。域偏移条件下，置信度不能直接证明标签正确，因此项目保留 REVIEW 分流、可视化抽样和完整审计链路。
同类别 GT 与 AUTO 都指向一个目标时，为什么不能都留下？
两个尺度不同的同类框同时存在会制造重复目标和不一致监督。审核门控联合 IoU、IoS 和中心距离识别同目标存疑情况，只允许人工选择“用 AUTO 替换高亮 GT”或拒绝。写回前还会确认原 GT 未被其他人修改，避免审核依据漂移。
为什么近重复检测不直接两两比较全部图片？
暴力比较会按 O(N²) 增长。cluster 命令仅保存紧凑指纹，使用 BK-tree 做汉明距离半径搜索，再用 aHash、宽高比和低纹理亮度约束过滤。即便如此，每个分组仍只是人工审核证据，而不是自动删除决定。
主动审核队列能用来汇报模型精度吗？
不能。它会主动过采样不确定、稀缺和视觉多样的困难样本，因此通过率存在偏置。它用于提高每小时发现问题的数量；精度仍需单独的随机或分层随机审核样本。
- 不要声称 Teacher 能消除全部漏标。
- 不要声称默认阈值适用于所有数据集。
- 未经许可且没有严格测试定义时，不公开私有数据指标。
- 不要把 SHA-256 精确哈希去重描述为感知近重复检测。
- 不要把合成演示描述成生产基准测试。
如实说明项目边界，反而能让真正的工程贡献更可信。