[Issue #49] VisDrone baseline: v0.1-N vs EsMoE-N (5 epochs each)

[OldPigxjk]

Related to #49

YOLO-Master Issue #49 — 垂类数据集基线训练与 MoE 对比

任务说明

在垂类目标检测数据集 VisDrone2019-DET（无人机航拍，小目标密集）上，
分别训练两种混合专家(MoE)模型 YOLO-Master-v0.1-N 与 YOLO-Master-EsMoE-N，
对比其检测精度(mAP)与专家路由损失(moe_loss)，验证 MoE 在垂类场景下的表现。

实验配置

• 数据集: VisDrone2019-DET（train 6471 / val 548，已转 YOLO 格式）
• 训练: 从零训练(pretrained=False)，imgsz=640, batch=8, workers=0, CPU(torch 2.3.1+cpu)
• 每模型 5 epochs（受 deadline 与算力限制，两模型配置完全一致以保证公平对比）
• EsMoE-N 采用 dense evaluation（train==eval），避免 sparse eval 导致的 mAP 塌陷

指标对比

模型	参数量	epochs	mAP50	mAP50-95	train/moe_loss	train/box_loss
v0.1-N (ModularRouter)	7,516,742	5	0.08116	0.03719	0.00849	2.32631
EsMoE-N (ES_MOE)	2,690,000	5	0.07454	0.03282	0.00234	2.32700

逐 epoch mAP50

epoch	v0.1-N	EsMoE-N
1	0.01614	0.01740
2	0.04271	0.04180
3	0.06327	0.06215
4	0.07160	0.06843
5	0.08116	0.07454

前 3 个 epoch 两者几乎持平（epoch1 EsMoE-N 反超），第 4-5 epoch 起 v0.1-N 凭更大容量逐渐拉开差距。

结论

• 精度：5 epoch 的极早期阶段，v0.1-N 的 mAP50 (0.08116) 略高于 EsMoE-N (0.07454)，
  差距约 8%；两者收敛趋势一致，均处于快速上升期，尚未收敛。
• 参数效率：EsMoE-N 仅用 2.69M 参数（约为 v0.1-N 的 1/2.8） 即达到 v0.1-N 约 92% 的 mAP50，
  单位参数的检测效率明显更优。
• 路由损失：EsMoE-N 的 train/moe_loss (0.00234) 比 v0.1-N (0.00849) 低约 3.6 倍，
  其多尺度深度可分离卷积专家（kernel 3/5/7）的路由分配更"自信"、专家分工更清晰。
• 训练全程记录 moe_loss 并稳定下降，验证了两种 MoE 路由模块均可端到端训练、无梯度异常。

复现指引

仓库自带脚本（使用 ultralytics 内置 VisDrone.yaml，首次运行会自动下载数据集）：

cd /path/to/YOLO-Master

# CPU 复现（与本 PR 结果一致的配置）
PYTHONPATH=. python scripts/reproduce/reproduce_visdrone.py \
  --model both --epochs 5 --batch 8 --imgsz 640 \
  --device cpu --no-amp --no-sparse-eval --no-wandb

# GPU 复现（推荐，可跑完整 epoch 数）
PYTHONPATH=. python scripts/reproduce/reproduce_visdrone.py \
  --model both --epochs 300 --batch 64 --device 0 --no-sparse-eval

若本地已有 VisDrone 数据集，可参考本 PR 提供的 scripts/reproduce/VisDrone_local.yaml
（绝对路径配置）替换内置 yaml，避免重复下载。

交付物

• scripts/reproduce/README_issue49.md — 完整实验报告与已知问题
• scripts/reproduce/comparison_results.json — 结构化对比结果
• scripts/reproduce/visdrone_v01_results.csv / visdrone_esmoe_results.csv — 逐 epoch 原始日志
• scripts/reproduce/visdrone_v01_train.log / visdrone_esmoe_train.log — 训练原始输出
• scripts/reproduce/issue49_results_fig.png — 指标对比图
• scripts/reproduce/issue49_training_curves.png — 逐 epoch 训练曲线

已知限制（如实说明）

1. 训练轮数有限：受 CPU 算力与 issue 截止时间限制，仅训练 5 epochs，两模型尚未收敛。
   此处结论仅反映早期训练阶段的相对表现，不代表最终收敛精度。完整 300 epoch 的对比
   需要 GPU 环境，命令已在上方给出。
2. EsMoE-N 第 2 epoch 指标为补测值：该轮训练因进程中断，results.csv 的对应行未落盘。
   由于每轮权重(epoch*.pt)完整保留，已用 epoch2.pt 在 val 集(548 张)上重新做 dense-eval，
   得到真实的 mAP50=0.04180 / mAP50-95=0.01770 / P=0.180 / R=0.107；该行的 train/* 损失列
   由相邻 epoch 线性插值补齐（仅用于曲线连续性，不参与结论）。其余 4 轮均为原始训练日志。
3. SKU-110K 未纳入对比：因本机网络流量限制（单会话累计约 2GB 后限速至 10KB/s），
   13.6GB 数据集无法下载完成，故本次对比聚焦 VisDrone 单数据集。
4. CPU 环境：本机 torch 为 CPU 版本，未使用 CUDA；GPU 结果待更好网络条件下补充。

精度影响因素分析

本报告中的 mAP50（0.074~0.081）处于极低水平，并非模型能力上限，而主要由以下受控因素决定，请结合此背景解读数字：

• 训练未收敛（仅 5 epochs）：VisDrone 为小目标密集的航拍数据集，检测难度大，目标检测模型通常需 100–300 epochs 才进入收敛区。逐 epoch 曲线显示 mAP 仍处于线性上升早期（epoch5 较 epoch1 增长约 4–5 倍），远未触顶。因此本对比反映的是"早期训练阶段的相对表现"，不代表最终精度。
• sparse-eval 塌陷（EsMoE-N 特有）：ES_MOE 默认 use_sparse_inference=True，推理时仅激活约 1 个未归一化专家，而训练时融合全部专家，前向不一致导致验证 mAP 暴跌（接近 0）。本次对比统一加 --no-sparse-eval 切换稠密评测（train==eval），得到的 0.07454 才与 v0.1-N 可比；不带该 flag 时两模型指标不可直接比较。
• 算力限制放大了上述缺口：CPU 单 epoch 需 1–3.6 小时，5 epochs 已是截止时间内能跑完的上限。GPU 环境下相同配置可在数小时跑满 300 epochs，mAP 预计大幅提升，届时两模型的最终精度差与参数效率结论需重新评估。

[OldPigxjk]

@gatilin Hi mentor, the deliverables for Issue #49 are now complete and ready for review.

Final update (this push):

• Backfilled the EsMoE-N epoch-2 metrics by re-running dense evaluation on the saved epoch2.pt checkpoint (mAP50=0.04180). All 5 epochs of both models now have per-epoch records.
• Corrected the reproduction commands in the PR description (the previous ones referenced a non-existent script and default GPU/AMP flags).
• Regenerated both comparison figures with the complete 1-5 epoch series.

Summary: v0.1-N reaches mAP50=0.08116 with 7.52M params; EsMoE-N reaches mAP50=0.07454 with only 2.69M params (~92% of the accuracy at ~1/2.8 the parameters), and its moe_loss is ~3.6x lower. Both routers train end-to-end without gradient issues.

All known limitations (5-epoch budget on CPU, the interpolated loss columns for the backfilled epoch, and SKU-110K being skipped due to bandwidth limits) are documented honestly in the PR description and README_issue49.md. Happy to extend the training or add another dataset if needed.