系列编排日期为 2026 年 8 月；技术基线核对与教学代码 CPU 验证日期为 2026-10-12。适用 Hi3516CV610 与本系列注明的 SDK/工具版本，实测范围见第 12 章。
返回系列目录 · 本篇属于 12 章与 4 份附录。
排错时先确认失败发生在哪一阶段，再修改一个变量。保留同一输入和上一版产物，才能判断某次修改究竟改善了什么。
转换失败的定位顺序
| 阶段 | 典型现象 | 首先检查 |
|---|---|---|
| 环境启动 | 找不到命令或动态库 | source、工具路径、版本、库路径 |
| 文件读取 | ONNX 或图像不存在 | 容器挂载、清单路径、权限、外部权重 |
| 图解析 | opset、shape 或节点错误 | checker、算子规格、输入名、静态维度 |
| 校准 | 读图失败、数据大小错误 | 图像与特征输入类型、dtype、预处理 |
| 编译 | 某算子或资源约束失败 | 首个错误、节点属性、引擎限制、尺寸 |
| 模型加载 | OM 无法加载 | 目标芯片、运行库版本、模型完整性、内存 |
《ATC工具使用指南》5.2 的算子规格优先用于解释编译约束，第 6 章用于优化建议；运行时错误查《应用开发指南》。附录 C 提供更细的现象索引。
ATC 成功但结果错误
先核对输入通道和范围，再核对几何，之后核对输出类型、顺序与 stride，最后检查解码。RGB/BGR 错误可能仍然给出“有点像”的结果；重复归一化可能只留下极低分数；stride 错误可能让前几个数看起来正常，后续全部错位。
如果图像已经在 CPU 变成 FLOAT，再按 UINT8 路线送入 AIPP，错误不是量化可以修复的。相反，原始 ONNX 接收 FLOAT 也不代表板端必须传 FLOAT，关键是 AIPP 是否实现了正确的转换。
输出全部接近零时检查输入文件、模型加载、缓存和 raw tensor，而不是先降低检测阈值。只有确认数值链路正确后，阈值调整才有任务意义。
如何做最小复现
保留一份失败模型、一个输入、一条命令和完整环境记录。删除与失败无关的可视化、相机、网络传输和多模型调度。若裁图或裁网络来缩小问题，重新验证该简化仍然复现同一错误，避免把原始问题删掉后误判修复。
每轮实验说明唯一变化项，例如 quant_mode 0→1、RGB/BGR、固定输出节点或校准集版本。不要同时换模型、分辨率、量化模式和后处理，否则结果即使变好也无法解释原因。
性能先明确计时边界
|
冷启动还包括模型读取、加载和首次执行。分别报告冷启动、预热后的 execute 和完整业务耗时，并说明 CPU 频率、线程数、输入大小、重复次数、模型常驻情况和媒体负载。
平均值不能反映尾部卡顿，至少同时保留中位数、p95 和样本数量。预览帧率可能包含重复画面；显示 25 FPS 不能证明 NPU 每秒完成 25 次新推理。
从瓶颈出发优化
如果 NPU 执行占主导，分析算子、分辨率和模型结构；若后处理占主导，检查候选数量、数据布局和 NMS；若复制占主导，检查重复转换、分配和无效整图传输；若加载占主导，分析常驻与内存容量的取舍。
降低输入尺寸会改变小目标召回和输出位置数，删除检测分支会改变适用尺度。YOLO-P34 属于结构调整，不能只按“更快”验收。对于 LUVLi 一类复杂图，局部算子探针用于判断支持和代价，不能把探针性能直接当整网性能。
量化位宽、混合精度和后处理硬化都必须以任务精度与实板性能共同评估。A16W8 可能改善数值误差，也可能增加带宽和内存；不能只看到“16”就推断一定更好。
长期运行与回归
循环测试固定输入，再测试变化输入，观察是否出现持续内存增长、偶发加载失败、旧输出复用和运行时间漂移。随后加入真实业务并发，记录 NPU 与媒体资源竞争。
修复后至少回放原失败样本和独立验收集。错误现象消失、精度达标、性能达标应分别填写，不能用一个“通过”覆盖所有要求。