附录 2：工具箱、FAQ 与参数模板

内容概览

本附录聚焦“查得快、用得稳”：常见报错速查、转换参数模板、性能/质量 Checklist、术语字典、推荐资源与社区贡献规范。可作为日常开发随手翻阅的工具章节。

常见报错速查

分类	报错/现象	可能原因	排查步骤	解决建议
ATC	E19001: Op Not Supported	新算子/版本落后	确认 CANN 版本 + onnxsim 简化	升级/替换结构/自定义算子
ATC	Shape 推断失败	动态维度不明确	检查 --input_shape/动态参数	固定关键维度或提供范围
ACL	aclmdlLoadFromFile failed	权限/路径/模型损坏	校验文件 hash/权限	修正权限/重新生成 OM
Runtime	OOM / alloc 失败	Batch 或分辨率过大	统计输入分布	降 batch/分桶/复用内存
运行	推理输出 NAN	数值溢出/量化尺度错误	Dump 中间 Tensor	调整量化/保留 FP32 层
性能	Timeline 大量 gap	Host 阻塞/小算子	Profiling 分析	合并算子/异步预取
性能	H2D 高占比 >25%	多次小拷贝	合并缓冲	AIPP 下沉/批量化
精度	Top1 下降 >1%	预处理不匹配	对比 ONNX 输出	统一 Normalize & Layout
精度	mAP 不稳定	阈值或 NMS 误差	调整阈值/比对中间框	校准 NMS 公式/尺度
稳定	间歇 Crash	悬空指针/并发访问	启用 ASAN/日志回溯	修订生命周期/加锁
部署	模型加载慢	冷启动/IO 慢	预热/缓存	预加载 + 固态存储
安全	日志泄露敏感路径	直接 print	grep 审计	结构化日志脱敏

模型转换参数模板合集

分类模型 (ResNet)

atc --model=resnet50.onnx \
    --framework=5 \
    --output=resnet50_fp16 \
    --input_format=NCHW \
    --input_shape="input:1,3,224,224" \
    --soc_version=Ascend310B \
    --precision_mode=allow_fp32_to_fp16 \
    --log=info

YOLO 动态分辨率

atc --model=yolov5s.onnx \
    --framework=5 \
    --output=yolov5s_640_768 \
    --dynamic_image_size="640,640;768,768" \
    --input_format=NCHW \
    --soc_version=Ascend310B \
    --op_select_implmode=high_performance \
    --precision_mode=allow_fp32_to_fp16

INT8 量化（示例）

atc --model=resnet50.onnx \
    --framework=5 \
    --output=resnet50_int8 \
    --input_format=NCHW \
    --input_shape="input:1,3,224,224" \
    --soc_version=Ascend310B \
    --precision_mode=allow_mix_precision \
    --insert_op_conf=aipp.cfg \
    --enable_small_channel=true

性能与质量 Checklist（执行勾项）

性能：

• Profiling 无明显 Idle gap > 10%
• H2D + D2H 占比 < 25%
• Postprocess 占比 < 20%
• Stream 利用率平衡（无单流饱和）
• 使用内存池减少频繁 alloc/free

精度：

• ONNX vs OM Top1 差异 < 0.2%
• L1 平均误差 < 1e-3（FP16）
• NMS 输出框数量与基线差异 < 1 框/图（平均）
• INT8 校准集覆盖多场景

稳定性：

• 1h 稳态无 Crash / OOM
• 温度在安全区间 < 85°C
• 看门狗重启次数 = 0

安全：

• 日志无明文密钥
• 模型文件 hash 校验通过

术语表（扩展）

术语	说明
OM	Ascend 离线模型二进制格式
ACL	Ascend 计算语言 API 层
ATC	模型转换/编译工具
AIPP	自动图像预处理模块
Stream	异步任务调度通道
Profiling	性能采样分析工具体系
Fallback	算子未匹配优化实现退回通用实现
Quant Calibration	量化尺度统计过程
Baseline	初始标准对照性能/精度集
Drift	指标随时间未经预期的漂移

推荐资源与外部引用

• Ascend 官方文档入口（安装/算子列表/最佳实践）
• CANN Release Notes：版本兼容与已知问题。
• ONNX Operator 列表与语义说明。
• Open Model Zoo / ModelScope：获取预训练模型与许可信息。
• 学术资源：算子融合、低比特量化、蒸馏相关论文列表。

贡献指南摘要

流程：Fork -> 新分支 -> 修改/新增 -> 本地 lint & 生成脚本 -> PR（描述动机/影响面/验证方式）。 PR 要求：

要素	说明
标题	简明说明改动作用
描述	背景 + 修改点 + 风险
验证	性能/精度/功能截图或数据
回滚	若失败如何恢复
关联 Issue	追踪链接

FAQ

问题	回答
模型转换慢怎么办？	使用 SSD，关闭调试日志，检查不必要动态 shape。
精度下降如何定位？	离线脚本层级 Dump 比对，逐层二分。
如何减少内存占用？	启用内存池 + 减少中间冗余张量 + 固定 batch。
量化后收益不明显？	检查是否 Compute-bound，或激活分布集中导致尺度相近。
NMS 很慢？	合并小框批量处理/降低候选阈值/考虑 Device 版 NMS。

License 与引用

本书内容遵循 Apache 2.0 许可证。引用：

《昇腾310B实战：从入门到精通边缘计算与人工智能》（GitHub: zhouxzh/Ascend310）

版本路线回顾

版本	内容	目标
v0.1	结构框架	验证框架可行
v0.3	核心部署链路	形成可用主线
v0.6	案例与工程化	贴近实战
v1.0	全面审校发行	正式发布

实践任务

1. 为你的项目添加 1 条本地常见错误记录（含根因与解决）。
2. 复制分类 ATC 模板并改写为检测模型版本（含动态尺寸）。
3. 在术语表补充 3 个任务相关术语（并验证唯一性）。
4. 选取 FAQ 一条，写出更深入排查脚本思路。