从零复现 UAV-DETR无人机目标检测论文复刻全流程踩坑记录本文记录了我复现 UAV-DETR 这篇无人机目标检测论文的完整过程分享了环境搭建、数据集处理、训练调参中遇到的各种问题和解决方案。最终在 VisDrone 数据集上取得了 mAP50 52.90% 的成绩超过了原论文报告的 48.8%。前言最近在做无人机相关的毕设/课题需要复现一篇目标检测论文。选来选去最终选了今年 1 月份挂在 arXiv 上的 UAV-DETR原因很简单它基于 RT-DETR端到端检测不需要 NMS 后处理部署方便它专门针对无人机图像的小目标问题做了改进代码基于 Ultralytics 框架上手相对容易但实际复现下来发现坑远比想象的多。这篇文章就是来记录这些坑的。一、论文在讲什么UAV-DETR 的核心思路是在 RT-DETR 的基础上加入频域信息来增强小目标的检测能力。无人机图像的特点是目标小、密度高。传统方法只在空间域做卷积高频信息边缘、纹理在多次下采样后会丢失。UAV-DETR 的做法是引入 FFT快速傅里叶变换在频域中对特征进行增强。它主要改了三个地方第一个改动MFFF 模块这个模块的全名是 Multi-Frequency Feature Fusion。它的核心思想是先把特征图变换到频域做一波注意力加权再变换回来。有意思的是它并不是对所有通道都做频域处理而是只处理 25% 的通道剩下 75% 直接通过。这种分组处理的设计在控制计算量的同时保持了效果。第二个改动频域感知下采样普通的下采样MaxPool、Stride Conv会丢掉高频信息。这个模块在下采样的同时通过一个并行的频域分支来保留这些细节。第三个改动语义对齐校准SAC不同尺度的特征图拼接时空间位置可能对不齐。SAC 通过可变形采样来校正这个偏移让融合更精准。理解了这三个改动后面看代码就清晰多了。二、环境搭建的坑坑 1Windows 编译问题论文代码里有一个可变形注意力模块MSDeformAttn需要编译 CUDA 算子。在 Linux 下问题不大但在 Windows 下会报各种编译错误。我折腾了半天最后发现 Ultralytics 框架里已经内置了一个纯 PyTorch 的实现在ultralytics/nn/modules/utils.py里虽然慢一点但完全能用。所以如果你也是 Windows 用户不要去编译那个 CUDA 算子直接用 Python 版本就行。坑 2Ultralytics 版本冲突我一开始习惯性地pip install ultralytics结果发现最新版的 API 跟论文代码不兼容各种报错。后来才明白论文代码里自带了一份修改过的ultralytics你得用项目目录下的那个版本不能用 pip 安装的。正确的做法是cd到项目根目录下运行这样 Python 会优先导入当前目录的ultralytics。坑 3显存不够我的 GPU 显存不大一开始用batch8直接 OOM。后来降到batch4才跑起来。如果你也遇到这个问题除了降 batch size还可以试开启混合精度训练ampTrue降低输入分辨率imgsz512清理 GPU 缓存训练前加torch.cuda.empty_cache()三、数据集处理的坑我用的是 VisDrone-2019-DET 数据集这是无人机检测领域最常用的数据集之一。坑 4标注格式转换VisDrone 的标注格式是这样的bbox_left, bbox_top, bbox_width, bbox_height, score, category, truncation, occlusion但 UAV-DETR 需要的是 YOLO 格式class_id center_x center_y width height这里有个容易忽略的细节VisDrone 的类别 ID 是从 1 开始的而且 0 表示忽略区域。如果你在转换时没有过滤掉 category0 的标注模型会学到一些错误的信号精度会明显下降。坑 5data.yaml 的类别顺序这个坑很小但很致命。data.yaml里的类别顺序必须和标注文件里的类别 ID 对应。如果顺序错了模型会把行人识别成汽车精度直接归零。建议转换完数据后随机抽几张图用 OpenCV 画一下标注框和类别名确认无误再开始训练。四、训练调参最花时间的部分我的最终配置model.train(datadata/visdrone/data.yaml,epochs400,batch4,imgsz640,optimizerAdamW,lr00.0001,patience40,mosaic1.0,mixup0.2,ampFalse)坑 6warmup_epochs 不是你想的那个配置文件里有个参数warmup_epochs: 2000我一开始以为是预热 2000 个 epoch心想这也太夸张了。后来查了源码才发现这个值其实是 warmup 的迭代步数steps不是 epoch 数。如果 batch_size4训练集有 6471 张图那每个 epoch 大约 1618 步2000 步也就 1.2 个 epoch 的样子。坑 7学习率不衰减配置里lrf: 1.0意思是最终学习率 初始学习率 × 1.0也就是不衰减。这跟我以前的习惯cosine annealing很不一样。我试过改成 cosine 衰减结果精度反而下降了。后来想想也合理AdamW 本身就有自适应学习率的能力配合固定学习率可能更适合 DETR 这类模型。坑 8Early Stopping 时机我设置了patience40也就是连续 40 个 epoch 验证集精度不提升就停止。最终在第 342 个 epoch 触发了 early stopping。从训练曲线来看mAP 在 200 epoch 之后提升非常缓慢从 51.3% 到 52.9%但确实还在涨。如果你计算资源充足建议把 patience 调大一些可能会有更好的结果。坑 9训练日志的正确读法Ultralytics 输出的results.csv里有很多列我一开始没注意看把val/cls_loss当成了训练 loss白白分析了半天。正确的关系是train/giou_losstrain/cls_losstrain/l1_loss 训练总 lossmetrics/mAP50(B) 验证集 mAP50这才是你要关注的精度指标val/*开头的是验证集上的 loss五、我的改进尝试在跑通原论文代码后我尝试了一些改进主要是为了探索有没有进一步提升的空间。改进 1加 Coordinate Attention坐标注意力CA把通道注意力分解成水平和垂直两个方向可以更好地保留位置信息。我觉得这对无人机小目标可能有帮助。实际测试下来有一点提升但不大大约 0.3-0.5 个点。改进 2用 GFNet 替换 FFMGFNetGlobal Filter Network用可学习的全局滤波器在频域处理特征比原版的 FFM 更简洁。好处是参数量更少缺点是效果略有下降。改进 3MFFF Coordinate Attention把 CA 加到 MFFF 前面让频域处理前先做一波坐标注意力。这个组合的效果还不错但需要更多实验来验证。总的来说原论文的架构已经设计得很好了简单的模块替换很难带来大的提升。如果要显著超越原论文可能需要更深入的架构创新。六、最终结果精度对比模型BackboneAPAP₅₀UAV-DETR-R50 (论文)ResNet5031.551.1UAV-DETR-R18 (论文)ResNet1829.848.8UAV-DETR-EV2 (论文)EfficientFormerV228.246.7我的复现 (R18)ResNet1832.8752.90我在 ResNet18 backbone 上取得了 mAP50 52.90%超过了原论文报告的 48.8%甚至比 R50 的 51.1% 还高。为什么能超越说实话我也没完全搞清楚可能的原因有训练更充分我跑了 342 个 epoch原论文可能没有训练这么久数据增强有效Mosaic MixUp 的组合可能比原论文用的增强更强超参数差异不同的学习率、weight decay 等都会影响最终结果不过精度对比需要谨慎看待不同的训练环境、随机种子、数据划分都可能导致差异。七、总结这次复现最大的收获不是精度数字而是对 DETR 类检测器有了更深入的理解。以前用 YOLO 只知道调参现在对 Transformer 在检测中的作用、频域特征增强的思路有了更清晰的认识。给想复现论文的同学几点建议先读论文再看代码。不要上来就跑代码先搞清楚论文在讲什么一次只改一个东西。调参时不要同时改多个参数否则你不知道哪个改动起了作用记录每次实验。用 Excel 或 Notion 记录每次的配置和结果方便回溯善用 Git。每次改动都 commit出了问题可以快速回退复现论文是个体力活但也是最好的学习方式。共勉。代码已开源GitHub如果对你有帮助欢迎 star。