YOLO11x 目标检测模型向昇腾 (Ascend) 910B2 NPU 的完整迁移工作目录。包含算子适配、 4 卡 DDP 训练、ONNX→OM 导出、四阶段精度评测与性能采集的全部脚本与验证产物。
运行环境:CANN 8.5.0 / torch 2.7.1 / torch_npu 2.7.1.post2 / ultralytics 8.4.x / Python 3.11。 硬件:8×Ascend 910B2。
yolo11-adaptation/
├── train_npu_ddp.py # 多卡 DDP 训练主脚本 (交付路径, best.pt 产出; BF16-fwd + FP32 master, 纯 eager)
├── train_npu.py # 单卡 NPU 训练参考脚本 (默认 eager; 历史 compile 实验需显式 NPU_ENABLE_COMPILE=1)
├── cpu_train.py # CPU 对照训练脚本 (无 torch_npu 依赖)
├── ascend_train.py / ascend_infer.py # 昇腾原生训练/推理参考实现
├── subset_coco.yaml / subset50_coco.yaml # 冒烟/评测数据子集配置 (指向真实 COCO)
├── npu_yolo/ # NPU 侧算子适配模块 (static_loss / static_collate / target_buckets)
├── scripts/ # 精度验证/性能采集/报告生成/自验证等工具脚本
├── scripts_cv/ # 阶段检查点校验脚本
├── docs/ # 适配报告、DDP 声明、OM 验证证据、优化方案、技能改进建议
├── tests/ patches/ tools/ # 单测、ultralytics 补丁、辅助工具
├── legacy/experiments/ # B0-B5 历史实验脚本存档(compile 不可用证据链;非交付链路,见其 README)
├── export_meta/ perf/ post_train/ wave3_layer_final/ # 导出/性能/训练后评测证据产物 (JSON/CSV)
├── *.json # 需求/模型/方法/限制扫描/AMP 配置/四阶段精度/门禁看板等分析产物
├── requirements.txt # 依赖预检清单
└── env_matrix.md # 环境收敛矩阵权重与训练 run 产物(*.pt/*.om/*.onnx/*.npy、各 npu_*/smoke_* run 目录、
编译缓存 kernel_meta/)为训练残留,已按交付规范排除,不在仓库内。
train_npu_ddp.py(纯 eager):BF16 权重 + FP32 master、StaticV8DetectionLoss、
手动 HCCL allreduce。全部精度指标与 best.pt 均出自此路径。train_npu.py(单卡参考脚本)默认 eager、与上述配置一致;历史 B0-B5 的
torch.compile(backend="npu") 路径仅当显式 NPU_ENABLE_COMPILE=1 时启用——compile 与 DDP backward
组合存在 FakeTensor 泄漏的已知 bug(见脚本头注与 docs/YOLO11x-NPU训练优化方案.md)。legacy/experiments/test_b5*.py 等为刻意保留的 B0-B5 历史实验脚本(内含 torch.compile 用法),
是当年判定 compile 不可用、转向 eager 的证据链;不在任何自动交付链路。2026-09-10 多轮验证收编时
从仓根整体迁入(内容零改动,见 legacy/experiments/README.md),以保持静态门禁扫描面干净。以下命令均在本目录下、于昇腾容器内执行;数据与预训练权重路径请按实际环境通过命令行参数传入
(脚本不含写死的绝对默认路径)。容器镜像与创建命令见指导书 §1.1(quay.io/ascend/cann:8.5.0-910b-ubuntu22.04-py3.11,aarch64 架构)。
-0. LFS 拉取(克隆后必做,否则 best.pt/onnx/om 均为 134B 指针):
git lfs install && git lfs pull
0. 依赖与补丁(一次性):pip install -r requirements.txt 后必须做 opencv headless 修复
(ultralytics 元数据强拉非 headless 版会破坏 import ultralytics,详见指导书 §2.1):
pip uninstall -y opencv-python && pip install --force-reinstall --no-deps opencv-python-headless==5.0.0.93
然后向 site-packages 的 ultralytics 应用本仓 patches/ 下 2 个本地补丁
(NPU 强制 TorchNMS 防 CPU 回退/超时丢框、check_amp NPU 短路;其余 NPU 支持为 8.4.115 官方自带,
详见 patches/patch_report.json,含补丁可还原性证明方法):
SP=$(python3 -c "import ultralytics,os;print(os.path.dirname(os.path.dirname(ultralytics.__file__)))") && \ grep -qE 'prediction.device.type not in' $SP/ultralytics/utils/nms.py || patch -p1 -d $SP < patches/07_nms_force_npu.patch; \ grep -qE 'device.type == "npu"' $SP/ultralytics/utils/checks.py || patch -p1 -d $SP < patches/08_amp_check_npu.patch; \ grep -qE 'PATCH-BF16' $SP/ultralytics/utils/torch_utils.py || patch -p1 -d $SP < patches/09_amp_bf16_npu.patch; \ grep -qE 'PATCH-CPUNMS' $SP/ultralytics/utils/nms.py || patch -p1 -d $SP < patches/10_nms_cpu_widehead.patch
(守卫式=已应用则跳过,重跑幂等;裸 patch 对已打补丁树会生 .rej 且退出码 1,2026-09-10 实测)
0.5. 数据树(一次性,幂等):python3 scripts/prepare_coco_yolo.py --coco-root /opt/data/datasets/coco --out dataset
(或接线复用工作站现网树:ln -sfn /opt/data/yolo11x-adaptation/yolo11_coco_finetune/dataset dataset);
训练统一使用 --data configs/coco.yaml。
python3 train_npu.py --model <yolo11x.pt> --data subset_coco.yaml --device npu:0 --batch 16 --epochs 1ASCEND_RT_VISIBLE_DEVICES 白名单,残留则先 unset,脚本防呆会提示):
HCCL_HOST_SOCKET_PORT_RANGE=30000-30999 HCCL_NPU_SOCKET_PORT_RANGE=31000-31999 \ torchrun --nproc_per_node=4 --master_port=29510 train_npu_ddp.py --model <yolo11x.pt> --data configs/coco.yaml --device npu:0,1,3,4 --num-devices 4 --epochs 10 --batch 16python3 scripts/export_onnx_om.py --weights <best.pt> --tag trained --outdir artifacts/export
(产物归置 artifacts/export/trained/yolo11x_trained.{onnx,om} + export_metadata.json;raw
YOLO().export() 落点在权重同目录,本脚本负责搬运归位,勿依赖权重目录外的导出路径)python3 scripts/verify_layer_precision.py --pt <best.pt> --device npu:0python3 scripts/collect_perf.py --weights <best.pt> --tag trainedpython3 scripts/self_verify.py(等价本地 harness);技能官方校验器见下。python3 scripts/manual_qa_inference.py --weights <best.pt> --images <val图片目录> --device npu:0(出 PASS/FAIL,退出码 0/1)| 指标 | 值 |
|---|---|
| 训练后 mAP@0.5:0.95 (best.pt, 5000 图) | 0.536124 |
| vs 预训练基线 0.530374 | +1.084%(无退化) |
| vs 论文基准 0.547 | −1.988%(<5% 门禁内) |
| 逐层精度 (Phase 2/3) | 358 层,激活 fail=0,权重 fail=0,最终输出 cos≈0.99999997 |
| ONNX vs PT 图等价 | cos≈0.99999988 |
| OM 导出 | 116.98 MB,soc=Ascend910B2,ATC status=PASS |
| OM 端到端直测 (pyACL vs PT, 2026-09-10) | cos=0.999997,mean_abs_diff=0.0055,verdict=PASS(scripts/verify_om_inference.py 已重写至 CANN 8.5 实测签名,旧"直测不可运行"限制消除) |
| 推理吞吐 (FP32 eager) | bs8 144.5 img/s,峰值显存 1689.5 MB |
| 门禁 | self_verify 21/21 PASS;产物自验证 5/5;git 交付验证 5/5 |
python3 scripts/self_verify.py
python3 <skill>/scripts/verify_artifact_self_validation.py --adaptation-dir .
python3 <skill>/scripts/verify_git_delivery.py --adaptation-dir .详细报告见 docs/adaptation_report.md;OM 正确性证据链见 docs/wave4_om_verification_evidence.md
(CANN acl Python 绑定与 NumPy 2.x ABI 冲突致 OM 直测段错误,采用 ATC+eager+ONNX-parity 三方代理)。
| 路径 | 内容 | Git 通道 |
|---|---|---|
| 根目录代码/文档/补丁 | 交付代码 (README 复现步骤 0-7) | git |
train_runs/npu_4card_10ep_r2/ | 4卡DDP eager 10epoch: weights/best.pt(109MB)、results.csv、args.yaml、train_batch*.jpg | LFS(*.pt) / git |
artifacts/export/ | yolo11x_trained.onnx(217MB)、yolo11x_trained.om(112MB, ATC PASS) | LFS |
eval/subset_val/ | 200 图真实评测子集, 实体文件 (F3 QA / mAP50 对照; 2026-09-10 由断链符号链接实体化, 与 prepare_coco_yolo 再生口径逐字节一致) | git |
evidence_small/ | 精选过程证据 (profiling 提炼结论, ≤5MB) | git |
未入库 (工作站容器 Yolov11:/opt/data/yolo11-adaptation 可查):23 个废弃冒烟/试验 run 权重 (~9GB)、原始 profiler trace (2.1GB, 单文件最大 791MB 超平台限制)、pretrain 导出物 (可由公开权重再生)、last.pt (非最优轮)、COCO→YOLO 标签树 (12.3 万小文件, 由 scripts/prepare_coco_yolo.py 按官方 COCO 确定性再生, 与交付训练所用 labels 10/10 逐字节等价抽查通过)。