可变形DETR

作者：朱锡洲、苏伟杰、卢乐威、李斌、王小刚、戴继峰。

本仓库是论文《可变形DETR：用于端到端目标检测的可变形Transformer》（arXiv:2010.04159）的官方实现。

简介

TL;DR。 可变形DETR是一种高效且收敛速度快的端到端目标检测器。它通过一种基于采样的高效注意力机制，有效缓解了DETR计算复杂度高、收敛慢的问题。

摘要。 DETR最近被提出，旨在消除目标检测中大量手工设计的组件，同时展现出良好的性能。然而，由于Transformer注意力模块在处理图像特征图时的局限性，DETR存在收敛缓慢和特征空间分辨率有限的问题。为了解决这些问题，我们提出了可变形DETR，其注意力模块仅关注参考点周围的一小部分关键采样点。与DETR相比，可变形DETR在训练轮数减少10倍的情况下，仍能取得更好的性能（尤其是在小目标检测上）。我们在COCO基准数据集上的大量实验验证了我们方法的有效性。

许可证

本项目采用Apache 2.0许可证发布。

更改日志

有关主要更改的详细记录，请参阅changelog.md。

引用可变形DETR

如果您在研究中使用了可变形DETR，请考虑引用以下文献：

@article{zhu2020deformable,
  title={Deformable DETR: Deformable Transformers for End-to-End Object Detection},
  author={Zhu, Xizhou and Su, Weijie and Lu, Lewei and Li, Bin and Wang, Xiaogang and Dai, Jifeng},
  journal={arXiv preprint arXiv:2010.04159},
  year={2020}
}

主要结果

方法	Epochs	AP	APS	APM	APL	params (M)	FLOPs (G)	Total Train Time (GPU hours)	Train Speed (GPU hours /epoch)	Infer Speed (FPS)	Batch Infer Speed (FPS)	URL
Faster R-CNN + FPN	109	42.0	26.6	45.4	53.4	42	180	380	3.5	25.6	28.0	-
DETR	500	42.0	20.5	45.8	61.1	41	86	2000	4.0	27.0	38.3	-
DETR-DC5	500	43.3	22.5	47.3	61.1	41	187	7000	14.0	11.4	12.4	-
DETR-DC5	50	35.3	15.2	37.5	53.6	41	187	700	14.0	11.4	12.4	-
DETR-DC5+	50	36.2	16.3	39.2	53.9	41	187	700	14.0	11.4	12.4	-
Deformable DETR (single scale)	50	39.4	20.6	43.0	55.5	34	78	160	3.2	27.0	42.4	config log model
Deformable DETR (single scale, DC5)	50	41.5	24.1	45.3	56.0	34	128	215	4.3	22.1	29.4	config log model
Deformable DETR	50	44.5	27.1	47.6	59.6	40	173	325	6.5	15.0	19.4	config log model
+ iterative bounding box refinement	50	46.2	28.3	49.2	61.5	41	173	325	6.5	15.0	19.4	config log model
++ two-stage Deformable DETR	50	46.9	29.6	50.1	61.6	41	173	340	6.8	14.5	18.8	config log model

注释：

1. 所有Deformable DETR模型均使用总批量大小为32进行训练。
2. 训练和推理速度均在NVIDIA Tesla V100 GPU上测量。
3. “Deformable DETR (single scale)”表示仅使用res5特征图（步幅为32）作为可变形Transformer编码器的输入特征图。
4. “DC5”表示移除ResNet C5阶段的步幅，并改为使用2倍膨胀率。
5. “DETR-DC5+”表示对DETR-DC5进行了一些修改，包括使用焦点损失进行边界框分类，并将对象查询数量增加到300。
6. “Batch Infer Speed”指以批量大小为4进行推理，以最大化GPU利用率。
7. 原始实现基于我们的内部代码库。由于平台切换中的诸多细节差异，最终的准确性和运行时间可能存在细微差别。

安装

要求

• Linux系统，CUDA≥9.2，GCC≥5.4

• Python≥3.7

  我们建议您使用Anaconda创建一个conda环境：

  conda create -n deformable_detr python=3.7 pip
  

  然后激活该环境：

  conda activate deformable_detr
  

• PyTorch≥1.5.1，torchvision≥0.6.1（请按照此处的说明进行安装）

  例如，如果您使用的CUDA版本是9.2，可以按如下方式安装PyTorch和torchvision：

  conda install pytorch=1.5.1 torchvision=0.6.1 cudatoolkit=9.2 -c pytorch
  

• 其他依赖项

  pip install -r requirements.txt
  

编译CUDA算子

cd ./models/ops
sh ./make.sh
# 单元测试（应显示所有检查均为True）
python test.py

使用

数据集准备

请下载COCO 2017数据集，并按以下方式组织：

code_root/
└── data/
    └── coco/
        ├── train2017/
        ├── val2017/
        └── annotations/
        	├── instances_train2017.json
        	└── instances_val2017.json

训练

单节点训练

例如，在8张GPU上训练Deformable DETR的命令如下：

GPUS_PER_NODE=8 ./tools/run_dist_launch.sh 8 ./configs/r50_deformable_detr.sh

多节点训练

例如，在2个节点上分别使用8张GPU训练Deformable DETR的命令如下：

在节点1上：

MASTER_ADDR=<节点1的IP地址> NODE_RANK=0 GPUS_PER_NODE=8 ./tools/run_dist_launch.sh 16 ./configs/r50_deformable_detr.sh

在节点2上：

MASTER_ADDR=<节点1的IP地址> NODE_RANK=1 GPUS_PER_NODE=8 ./tools/run_dist_launch.sh 16 ./configs/r50_deformable_detr.sh

在Slurm集群上训练

如果你使用的是Slurm集群，可以简单地运行以下命令，在1个节点的8张GPU上进行训练：

GPUS_PER_NODE=8 ./tools/run_dist_slurm.sh <分区> deformable_detr 8 configs/r50_deformable_detr.sh

或者在2个节点上，每个节点8张GPU：

GPUS_PER_NODE=8 ./tools/run_dist_slurm.sh <分区> deformable_detr 16 configs/r50_deformable_detr.sh

加速训练的一些技巧

• 如果你的文件系统读取图像较慢，可以考虑启用--cache_mode选项，以便在训练开始时将整个数据集加载到内存中。
• 可以根据你的GPU显存情况，适当增大批大小以最大化GPU利用率，例如设置--batch_size 3或--batch_size 4。

评估

你可以获取Deformable DETR的配置文件和预训练模型（链接见“主要结果”部分），然后运行以下命令在COCO 2017验证集上对其进行评估：

<配置文件路径> --resume <预训练模型路径> --eval

你也可以使用./tools/run_dist_launch.sh或./tools/run_dist_slurm.sh来进行分布式评估。

Deformable DETR 快速上手指南

Deformable DETR 是一种高效且收敛快速的端到端目标检测模型。它通过一种新颖的基于采样的注意力机制，解决了原始 DETR 模型复杂度高和收敛慢的问题，尤其在处理小目标时表现优异，且仅需 1/10 的训练轮次即可达到更好效果。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux
• 硬件: NVIDIA GPU (CUDA >= 9.2)
• 编译器: GCC >= 5.4
• Python: >= 3.7
• 深度学习框架: PyTorch >= 1.5.1, torchvision >= 0.6.1

推荐配置： 建议使用 Anaconda 创建独立的虚拟环境。如果您在中国大陆，建议在安装依赖时使用清华或阿里镜像源以加速下载。

# 创建并激活 conda 环境
conda create -n deformable_detr python=3.7 pip
conda activate deformable_detr

# 安装 PyTorch 和 torchvision (示例：CUDA 9.2，请根据实际版本调整)
# 国内用户可添加 -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/
conda install pytorch=1.5.1 torchvision=0.6.1 cudatoolkit=9.2 -c pytorch

# 安装其他 Python 依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

Deformable DETR 包含自定义的 CUDA 算子，需要手动编译。

1. 克隆代码库（如果尚未下载）：

   git clone https://github.com/fundamentalvision/Deformable-DETR.git
   cd Deformable-DETR
   

2. 编译 CUDA 算子： 进入算子目录并执行编译脚本，随后运行单元测试确保编译成功。

   cd ./models/ops
   sh ./make.sh
   # 运行单元测试 (应输出所有 checking is True)
   python test.py
   cd ../..
   

3. 数据集准备： 下载 COCO 2017 数据集 并按以下结构组织文件：

   code_root/
   └── data/
       └── coco/
           ├── train2017/
           ├── val2017/
           └── annotations/
               ├── instances_train2017.json
               └── instances_val2017.json
   

基本使用

训练模型

以下命令演示如何在单节点 8 张 GPU 上启动训练。

# 单节点训练 (8 GPUs)
GPUS_PER_NODE=8 ./tools/run_dist_launch.sh 8 ./configs/r50_deformable_detr.sh

加速小贴士：

• 如果读取图片较慢，可添加 --cache_mode 参数将数据集一次性加载到内存。
• 可根据显存大小调整 batch size (例如 --batch_size 4) 以最大化 GPU 利用率。

评估模型

您可以从 README 的 "Main Results" 部分下载预训练模型和对应的配置文件，然后在 COCO 2017 验证集上进行评估。

# 单机评估
python main.py <path to config file> --resume <path to pre-trained model> --eval

# 分布式评估 (推荐)
GPUS_PER_NODE=8 ./tools/run_dist_launch.sh 8 <path to config file> --resume <path to pre-trained model> --eval

注：请将 <path to ...> 替换为实际的本地文件路径。