[Issue #51] YOLO-Master-EsMoE-N 在 VisDrone 上的 ONNX/NCNN 边缘部署与一致性验证

[CressBoy]

部署仓库：CressBoy/yolo-master-visdrone-edge

对应课题：Tencent/YOLO-Master Issue #51

1. 项目目标

本项目在 VisDrone2019-DET 上微调 YOLO-Master-EsMoE-N，并完成
PyTorch → ONNX（onnxsim）→ NCNN（PNNX）的部署链路。重点验证三个问题：

1. 导出后是否保持检测精度；
2. 固定输入、线程数和计时边界后，导出运行时是否真正加速；
3. 同一份 NCNN C++ 代码能否在 Windows x86_64 与 Linux x86_64 上构建和运行。

2. 训练与模型

• 数据集：VisDrone2019-DET，6471 张训练图、548 张验证图；
• 输入：固定 640 × 640 Letterbox；
• 模型：YOLO-Master-EsMoE-N；
• 训练：100 epochs、batch 16、seed 42、AMP、close_mosaic=10；
• 最佳 checkpoint：epoch 81；
• 最佳训练器验证指标：mAP50=0.35049，mAP50-95=0.20263。

同一次正式训练中，epoch 10 到最佳 epoch 81 的 mAP50-95 从 0.13187
提升到 0.20263，绝对提升 0.07076，相对提升 53.66%。epoch 100
略回落到 0.19830，因此部署使用 best.pt。

需要说明：COCO 80 类源权重与 VisDrone 10 类微调权重的检测头语义不同，不能直接把
源权重的 VisDrone mAP 当作有效“微调前基线”。上述数字是同一次训练的进展证据，
不能证明 EsMoE-N 优于其他架构。项目已准备参数规模接近的 YOLO11n 对照配置，但未把
尚未完成的对照训练写成结果。

作为量级参考，上游项目公开表格在 VisDrone 上报告 YOLOv11-N 为
mAP=0.185 / mAP50=0.322、YOLO-Master-N 为 0.196 / 0.337；本项目最佳训练器
结果为 0.20263 / 0.35049，并非明显异常。但由于上游表与本项目的模型版本、数据处理
和评估细节可能不同，这只能作为外部背景，不能冒充本地受控架构对照。

参考：YOLO-Master Main Results

3. 导出与兼容性

ONNX 使用 opset 17 并通过 onnx.checker；简化模型通过 onnxsim 校验。NCNN 使用
PNNX 转换，最终 param 文件包含 561 layers / 664 blobs，未发现残留的 aten::、
prim:: 或 pnnx. 不支持层。

PNNX 20260526 会把 FP32 路由器中的冗余 .float().type_as(x) 保留为 NCNN
不支持的 aten::to。本项目在 FP32 导出时省略这两个恒等转换，并提供独立补丁与
回归测试。

当前 checkpoint 的 4 个 EsMoE 模块均为 top_k=3 / num_experts=3 / use_top_k=False，即 PyTorch eager 本身也是 dense。ONNX/NCNN 的 dense fallback
没有改变本模型实际计算的专家数量。

4. 548 张验证集一致性

三个后端统一使用固定 640 × 640 Letterbox（rect=False）、conf=0.10、
iou=0.55、class-aware NMS 和 max_det=1000。

后端	mAP50-95	mAP50	相对 PyTorch 的绝对差	验收
PyTorch dense	0.2054355	0.3674355	0	PASS
ONNX	0.2054349	0.3674358	0.000000649	PASS
NCNN	0.2054336	0.3674354	0.000001857	PASS

两种导出格式的差值均远低于课题要求的非量化 < 0.005。

5. 公平 CPU benchmark

早期测试直接逐图调用 YOLO.predict(path)，但审计发现三个运行时没有实际使用相同
线程数：PyTorch 初始化后重置为 8 线程，ONNX Runtime 使用自动线程，NCNN 默认 8
线程；同时计时混入逐图数据源创建和包装开销。因此早期“ONNX 比 PyTorch 慢”的结论
被废弃。

最终主性能口径如下：

• 每个“后端 × 重复轮次”在独立子进程运行；
• 三个运行时均显式固定 4 个 CPU 线程；
• 图片预先解码到内存，三个后端共享相同 Letterbox、FP32 NCHW 输入和 NMS；
• 排除模型加载、磁盘 I/O、画框和写文件；
• 预热 10 次、测量 100 张、独立重复 3 次；
• 正式计时前对 10 张图执行框、类别和置信度正确性闸门。

后端	推理 Mean (ms)	端到端 Mean (ms)	P50 (ms)	P95 (ms)	FPS	相对 PyTorch
PyTorch	57.002	64.903	64.419	72.886	15.41	1.000x
ONNX Runtime	39.297	47.308	49.538	63.892	21.14	1.372x
NCNN	76.473	84.451	83.956	92.403	11.84	0.769x

ONNX 端到端延迟相对 PyTorch 降低 27.1%，FPS 提升 37.2%，公平加速结论成立。
NCNN 在当前 Windows x86_64 Python 环境没有跑赢 PyTorch，这是一项平台相关负结果，
不外推为 ARM/移动端结论。

正确性闸门中，ONNX 的最大原图框坐标差为 0.001282 px、最大置信度差为
1.55e-5；NCNN 分别为 0.004578 px 和 5.10e-5，均通过
0.01 px / 1e-4 门槛。

6. 原生 NCNN C++ 与双平台

C++ 推理程序使用 CMake，包含 VisDrone 预处理、解码、class-aware NMS、JSON
benchmark 输出和线程数控制。

平台	线程	端到端 Mean (ms)	P50 (ms)	P95 (ms)	FPS
Windows 11 x86_64	4	89.81	89.91	96.10	11.13
Windows 11 x86_64	24	69.37	69.04	75.21	14.41
Ubuntu 24.04 / WSL 2 x86_64	8	76.23	76.03	83.67	13.12

Windows 扫描 1/2/4/8/12/16/24 线程后，24 线程相对固定 4 线程的端到端延迟
下降 22.8%、FPS 提升 29.5%。Linux/WSL 2 的最优点是 8 线程；24 线程反而
下降到 9.19 FPS，说明混合 P/E 核和不同调度器下不能照搬线程配置。

Windows 与 Linux 对同一输入均输出 122 个检测，类别完全一致，最大置信度差
2e-6，最大框坐标差 0.000305 px。

7. 复现

核心命令：

# 导出
python tools/export_models.py `
  --config configs/visdrone.yaml `
  --yolo-master-root vendor/YOLO-Master

# 548 张三后端一致性
python tools/evaluate_backends.py `
  --config configs/visdrone.yaml `
  --models `
    pytorch=artifacts/checkpoints/yolo-master-esmoe-n-visdrone.pt `
    onnx=artifacts/models/model.sim.onnx `
    ncnn=artifacts/models/model_ncnn_model

# 公平固定 4 线程 benchmark
python tools/benchmark_runtimes.py `
  --config configs/visdrone.yaml `
  --source datasets/VisDrone/images/val `
  --yolo-master-root vendor/YOLO-Master `
  --models `
    pytorch=artifacts/checkpoints/yolo-master-esmoe-n-visdrone.pt `
    onnx=artifacts/models/model.sim.onnx `
    ncnn=artifacts/models/model_ncnn_model `
  --threads 4 --warmup 10 --iterations 100 --repeats 3 --gate-images 10 `
  --output docs/results/benchmark-fair-cpu-t4.json

模型权重和数据集不提交进仓库；README 中给出下载、目录布局、导出、验证、benchmark
和 CMake 构建说明。所有主表的机器可读 JSON 已放入 docs/results/。

8. 限制与后续

1. 当前绝对精度仍有提升空间，且参数匹配的 YOLO11n 架构对照尚未完成；
2. 最佳 checkpoint 由 val 集选择，后续应在未参与选模的 test-dev 上补充泛化评估；
3. 第二平台是 WSL 2 x86_64，可验证 Linux ABI 和构建兼容，但不是独立 ARM/Jetson
   物理边缘设备，不能提供真实设备功耗、温度和峰值内存结论；
4. 当前 EsMoE checkpoint 未启用 Top-K 稀疏推理，因此本次加速来自运行时与计算图优化，
   不是稀疏专家裁剪。

完整实现、复现说明、补丁和结构化实验结果见文首部署仓库。