从.pt到.om一条命令:Yolov11-ACC的ONNX→ATC导出链路与三方代理验证法
从.pt到.om一条命令:Yolov11-ACC的ONNX→ATC导出链路与三方代理验证法
Yolov11-ACC 是一套面向昇腾 Ascend 910B2 NPU 的 YOLOv11 目标检测模型迁移工程:一条命令完成 .pt → .onnx → .om 的完整导出链路,并用"三方代理"方法严谨证明部署模型(OM)与 PyTorch 权威输出数值等价。本文带你快速跑通这条导出链路,看懂每一环验证背后的证据链。
为什么需要 .pt → .onnx → .om 导出链路?
在昇腾 NPU 上部署深度学习模型,通常要走三步格式转换:
| 格式 | 含义 | 用途 |
|---|---|---|
.pt |
PyTorch 权重 | 训练产物(本仓 best.pt) |
.onnx |
开放中间表示 | 跨框架交换格式,ATC 编译的"来源图" |
.om |
昇腾离线模型 | 可直接被 NPU 硬件执行的最终部署格式 |
对新手来说,最头疼的不是转换本身,而是两件事:导出命令怎么配才不被算子卡住、转换后的 .om 精度到底可不可信。Yolov11-ACC 给出的答案分别是:一个封装好全部参数的导出脚本,以及一套"三方代理"验证法。
一条命令完成 ONNX→ATC 全链路导出
核心脚本是 scripts/export_onnx_om.py,它把两步工作打包进一条命令:
python3 scripts/export_onnx_om.py --weights <best.pt> --tag trained --outdir artifacts/export
脚本内部依次执行:
.pt → .onnx:调用 ultralytics 的YOLO.export(),固定opset=12、imgsz=640、simplify=True、dynamic=False(静态形状是 ATC 编译成功的关键);.onnx → .om:调用 ATC 编译器,关键参数为--framework=5(ONNX 框架)、--soc_version=Ascend910B2、--input_format=NCHW、--input_shape="images:1,3,640,640"、--enable_small_channel=1(YOLO 存在小通道卷积,此参数可避免编译失败)。
训练后权重 best.pt(4 卡 DDP 训练产物)的实测导出结果记录在 export_meta/trained_export_metadata.json:
| 指标 | 数值 |
|---|---|
| ONNX 大小 | 228.06 MB |
| OM 大小 | 116.98 MB |
| ONNX 导出耗时 | 49.9 s |
| ATC 编译耗时 | 52.5 s |
| 状态 | PASS |
同一目录还会生成 export_metadata.json 元数据(含 SHA 可追溯信息),仓库根目录的 model.onnx 与 model.om 即为该链路的最终交付产物,其指纹登记在 atc_meta.json。
为什么叫"三方代理"?OM 直测为什么一度跑不通
理想情况下,验证 .om 最直接的方式就是加载它跑推理、与 .pt 逐元素对比。但本项目环境(CANN 8.5.0)遇到一个环境级坑:
CANN 的
aclPython 绑定是按 NumPy 1.x 编译的,而容器内是 NumPy 2.4.6,直接执行.om会在加载路径触发段错误(已实测复现,并非模型问题)。
训练期间又不能随意降级 NumPy,于是采用三方代理——不直接测 OM,而是用三个独立证据叠加出传递性证明:
| # | 证据 | 度量 | 判定 |
|---|---|---|---|
| 1 | ATC 编译成功:.onnx 图在无 Python/NumPy 参与下完整 lower 到 Ascend910B2,算子全覆盖 |
OM 116.98 MB,status=PASS | ✅ |
| 2 | ONNX-vs-PT 数值一致:OM 的来源图忠实于 PT | cos=0.9999999,max_abs=0.0256 | ✅ |
| 3 | NPU-eager vs CPU 推理一致(同 50 图 COCO val2017) | 偏差 0.0743% < 1% | ✅ |
传递逻辑一句话讲清:OM = ATC(onnx),onnx ≈ pt,pt-on-NPU ≈ pt-on-CPU ⇒ OM 输出与 PT 权威输出在部署图层面等价。完整论证见 docs/wave4_om_verification_evidence.md。
证据链的三个落盘产物
三方代理不是口头论证,每个数字都有可复查的 JSON 落盘:
- ONNX 图等价:scripts/verify_onnx_parity.py 用相同 letterbox 预处理喂给
.pt和 ONNX Runtime,输出对比。训练后权重 30 图实测:cosine=0.99999988、max_abs=0.0299、mean_abs=4.07e-06,verdict=PASS,报告见 export_meta/onnx_parity_trained.json。 - NPU vs CPU 对齐:5000 图 COCO val2017 全量评测 + 同 50 图对照,mAP@0.5:0.95=0.530374,NPU 与 CPU 偏差仅 0.0743%,NMS 检测数量 20 图上完全一致(487 vs 487),详见 npu_pretrain_val_report.json。
- ATC 编译成功:OM 116.98 MB、
soc=Ascend910B2、53.1 s 编译通过,详见 export_meta/pretrain_export_metadata.json。
值得一提的是,后来 scripts/verify_om_inference.py 被重写为 CANN 8.5 新式 pyACL API 签名(load_from_file → mdl.execute),OM 端到端直测成功运行:PT↔OM 余弦相似度 0.999997、mean_abs_diff=0.0055、verdict=PASS——"直测不可运行"的限制正式消除,三方代理升级为"直测 + 代理"双保险。
端到端精度:验证过的 OM 到底准不准
把导出与验证串起来后,最终精度指标(四阶段全 PASS,见 four_phase_accuracy_summary.json):
| 指标 | 数值 |
|---|---|
| 训练后 mAP@0.5:0.95(best.pt,5000 图) | 0.536124 |
| vs 预训练基线 0.530374 | +1.084%(无退化) |
| vs 论文基准 0.547 | −1.988%(<5% 门禁内) |
| 逐层精度(358 层) | 激活 fail=0,权重 fail=0,最终输出 cos≈0.99999997 |
| OM 直测(pyACL vs PT) | cos=0.999997,verdict=PASS |
| 推理吞吐(FP32 eager) | bs8 144.5 img/s,峰值显存 1689.5 MB |
交付前还有一道人工 QA 推理门禁(scripts/manual_qa_inference.py),在真实评测图上前向出框、校验类别/置信度/框面积合理性,结果 PASS,见 post_train/manual_qa_inference.json。
快速复现:从零到 .om 的 6 步
- 克隆仓库并拉取 LFS 权重(否则
.pt/.om只是 134B 指针):git lfs install && git lfs pull - 安装依赖并打本地补丁:
pip install -r requirements.txt,随后对 ultralytics 应用 patches/ 下 4 个守卫式补丁(防 NMS CPU 回退、AMP 检查短路等); - 准备数据:
python3 scripts/prepare_coco_yolo.py --coco-root <COCO目录> --out dataset; - 训练产出
best.pt(4 卡 DDP 示例见 README 与 train_npu_ddp.py); - 一条命令导出:
python3 scripts/export_onnx_om.py --weights <best.pt> --tag trained --outdir artifacts/export; - 验证闭环:scripts/verify_onnx_parity.py(图等价)→ scripts/verify_om_inference.py(OM 直测)→ scripts/self_verify.py(21/21 门禁)。
相关文件速查
- 导出链路脚本:scripts/export_onnx_om.py
- OM 三方代理证据链:docs/wave4_om_verification_evidence.md
- 全量适配报告:docs/adaptation_report.md
- 导出元数据:export_meta/
- ATC 编译指纹:atc_meta.json
- 训练产物与权重:train_runs/npu_4card_10ep_r2/
- 推理回归结论:inference_regression_results.json
一句话总结:导出靠的是"一条命令 + 静态形状 + 小通道参数",可信靠的是"ATC 编译成功 × ONNX 图等价 × NPU/CPU 对齐"三方代理,外加重写后的 pyACL 直测兜底——这就是 Yolov11-ACC 把 .pt 变成可部署 .om 的完整方法论。


