系列编排日期为 2026 年 8 月；技术基线核对与教学代码 CPU 验证日期为 2026-10-12。适用 Hi3516CV610 与本系列注明的 SDK/工具版本，实测范围见第 12 章。
返回系列目录 · 本篇属于 12 章与 4 份附录。
这张表按现象列出最先收集的证据和下一步检查。原因栏是待验证方向，不是看到现象就可以确定的结论。
环境与文件问题
| 现象 | 先收集 | 排查方向 |
|---|---|---|
atc: command not found |
command -v atc、环境加载命令 |
容器不对或尚未 source |
.so 找不到 |
动态库报告、实际工具路径 | LD_LIBRARY_PATH、包缺失、版本混用 |
| Python 模块缺失 | 解释器路径、包清单 | 导出环境与转换环境混淆 |
| ONNX 找不到权重 | 模型目录清单、external data 引用 | 外置权重未复制或相对路径改变 |
| 校准图片不存在 | 容器内清单内容与文件检查 | 宿主路径未映射到 /workspace |
| 输出权限失败 | 输出目录权限、UID/GID、挂载方式 | 目录不可写或容器用户不同 |
| 命令在下一行变成独立命令 | 原始脚本 | 反斜杠后有注释或空格 |
先修环境再更换模型。重新运行前确认输出目录是否留有旧 OM，避免一次失败后继续使用之前的产物。
图解析和编译问题
| 现象 | 先收集 | 排查方向 |
|---|---|---|
| 输入名称不存在 | audit 报告和完整 ATC 参数 | input_shape/image_list 名称不匹配 |
| shape 不可推导 | 出错节点和上游 shape | 动态维度、固定 reshape、导出分支 |
| 算子不支持 | 节点类型、opset、属性 | ATC 5.2 中该芯片与引擎约束 |
| 改小输入后执行失败 | 改图前后模型和 CPU 日志 | 仅改输入标签，grid/reshape 未更新 |
| 校准数据大小错误 | 文件字节数、dtype、输入类型 | UINT8/FP32 混淆或图像编码当 tensor |
| 编译内存或资源失败 | 首个错误、目标尺寸、结构 | shape 过大、引擎限制、复杂算子组合 |
能够在 ORT 执行只能排除一部分图问题。不能据此断言厂商转换器有缺陷；需要对照目标算子的规格和最小复现。
能运行但数值错误
| 现象 | 对照证据 | 优先检查 |
|---|---|---|
| 全部置信度很低 | CPU 原始输出和输入范围 | RGB/BGR、重复归一化、模型与 AIPP 配对 |
| 框整体偏移 | 原图、ROI、处理图和记录比例 | pad 偏移、ROI 原点、逆变换 |
| 框尺寸或数量异常 | shape、raw 输出、解码前候选 | 步长、锚框、转置、DFL、重复激活 |
| reshape 元素数不对 | 输出 bytes 与 stride | 把物理 padding 当连续 tensor |
| 前几项正常后续异常 | 原始二进制和描述日志 | 行步长、类型字节数、越界读取 |
| 输出顺序变化 | ONNX 与 ACL 名称列表 | output_reorder、指定输出节点、硬化 |
| 同图偶尔返回旧结果 | 输入哈希、执行序号、同步日志 | 缓存同步、异步生命周期、复用缓冲 |
| 余弦很高但结果差 | MAE、max_abs 和任务指标 | 幅值漂移、阈值附近差异 |
先确认原始输出，再解释最终业务结果。仅调阈值可能暂时增加检出数量，却没有修复输入或内存读取错误。
板端资源和性能问题
| 现象 | 应记录 | 下一步 |
|---|---|---|
| OM 加载失败 | 文件哈希、芯片、Runtime、空闲内存 | 版本兼容、文件损坏、模型与任务内存 |
| 单模型正常，级联失败 | 每个加载阶段内存、执行时序 | 常驻数量、task/work 生命周期与共享规则 |
| 冷启动很慢 | 读取、加载、首次 execute 分项 | 存储、加载策略和预热 |
| execute 快但业务慢 | 全流程分项时间 | ROI、复制、输出解码、显示或传输 |
| 长期内存上涨 | 加载/卸载计数、峰值和剩余内存 | 资源未释放或错误路径泄漏 |
| p95 明显恶化 | 负载、频率、并发、样本数 | 媒体争用、分配抖动、热状态 |
仿真时间不能用来填实板耗时。持续运行问题需要足够长的循环和业务并发，而不是单次成功截图。
提交问题时的最小材料
|
共享数据前按实际授权选择可公开样本，必要时使用仍能复现问题的合成输入。删去敏感数据后应重新验证复现能力；材料完整但无法复现同一错误，仍不足以定位原因。