# DAB-DETR

这是我们ICLR 2022论文“DAB-DETR”的官方PyTorch实现。

作者：刘士龙、李峰、张浩、杨晓、齐先标、苏航、朱俊、张磊

最新动态

[2022年9月22日]：我们发布了一个工具箱detrex，其中包含了最先进的基于Transformer的目标检测算法。该工具箱包括性能更优的DINO模型。欢迎大家使用！
[2022年7月12日]：DINO的代码现已开放！[DINO代码链接]。
[2022年6月]：我们发布了一种统一的目标检测与分割模型Mask DINO，在三大分割任务上均取得了最佳成绩（COCO实例分割排行榜AP为54.5，COCO全景分割排行榜PQ为59.4，ADE20K语义分割排行榜mIoU为60.8）！代码将在此处提供：MaskDINO代码链接。
[2022年5月28日]：DN-DETR的代码已在此处开放：DN-DETR代码链接！
[2022年5月22日]：我们发布了用于可视化推理结果的Notebook文件inference_and_visualize.ipynb。
[2022年4月14日]：我们发布了用于绘制类似DETR模型对比图的.pptx文件，供需要在论文中绘制模型架构图的研究者参考。
[2022年4月12日]：我们修复了文件datasets/coco_eval.py中的一个错误。CocoEvaluator类的参数useCats默认应设置为True。
[2022年4月9日]：我们的代码正式开源！
[2022年3月9日]：我们创建了一个仓库Awesome Detection Transformer，用于整理和展示关于目标检测与分割领域Transformer相关的工作。欢迎关注！
[2022年3月8日]：我们的新工作DINO在MS-COCO榜单上创造了新的记录，AP达到63.3%。[DINO代码链接]。
[2022年3月8日]：我们的新工作DN-DETR已被CVPR 2022接收！[DN-DETR代码链接]。
[2022年1月21日]：我们的工作已被ICLR 2022接收。

摘要

本文提出了一种新颖的查询表示方法，即在DETR（DEtection TRansformer）中使用动态锚框，并深入探讨了查询在DETR中的作用。该方法直接将边界框坐标作为Transformer解码器的输入查询，并逐层动态更新这些坐标。采用边界框坐标不仅能够利用显式的先验位置信息来提升查询与特征之间的相似性，从而缓解DETR训练收敛缓慢的问题，还允许我们通过边界框的宽高信息来调节位置注意力图。这种设计清晰地表明，DETR中的查询可以被理解为以级联方式逐层执行软ROI池化操作。因此，在相同实验设置下，我们的方法在类似DETR的目标检测模型中取得了MS-COCO基准测试的最佳性能，例如使用ResNet50-DC5作为骨干网络并在50个epoch内训练时，AP可达45.7%。此外，我们还进行了大量实验来验证上述分析及所提方法的有效性。

模型

模型 zoo

我们提供了基于 R50 主干网络的模型，包括 DAB-DETR 和 DAB-Deformable-DETR（更多细节请参阅我们论文 附录 C）。

	名称	主干网络	边界框 AP	日志/配置文件/检查点	在 我们的论文中的位置
0	DAB-DETR-R50	R50	42.2	Google Drive | 清华云	表 2
1	DAB-DETR-R50(3 pat)1	R50	42.6	Google Drive | 清华云	表 2
2	DAB-DETR-R50-DC5	R50	44.5	Google Drive | 清华云	表 2
3	DAB-DETR-R50-DC5-fixxy2	R50	44.7	Google Drive | 清华云	表 8、附录 H。
4	DAB-DETR-R50-DC5(3 pat)	R50	45.7	Google Drive | 清华云	表 2
5	DAB-Deformbale-DETR (仅可变形编码器)3	R50	46.9		作为 DN-DETR 的基线
6	DAB-Deformable-DETR-R50-v24	R50	48.7	Google Drive | 清华云	扩展了表 5 和附录 C 中的结果。

注释：

• ¹：带有 (3 pat) 标记的模型使用了多模式嵌入进行训练（详情请参阅 Anchor DETR 或我们的论文 https://arxiv.org/abs/2201.12329）。
• ²：“fixxy” 表示我们在训练过程中使用随机初始化的锚点，并且不更新其参数（更多细节请参阅我们论文 附录 H）。
• ³：DAB-Deformbale-DETR（仅可变形编码器）是我们 DAB-DETR 的多尺度版本。更多细节请参阅 DN-DETR。
• ⁴：此处的结果优于我们论文中的数值，因为我们训练时使用了不同的损失系数。具体细节请参考我们的配置文件。

使用方法

安装

我们以优秀的 DETR 项目作为代码库，因此对于 DAB-DETR 不需要额外的依赖。而对于 DAB-Deformable-DETR，则需要手动编译可变形注意力算子。

我们已在 python=3.7.3, pytorch=1.9.0, cuda=11.1 环境下测试过这些模型，其他版本也可能适用。

1. 克隆本仓库

git clone https://github.com/IDEA-opensource/DAB-DETR.git
cd DAB-DETR

2. 安装 PyTorch 和 torchvision

请按照 https://pytorch.org/get-started/locally/ 上的说明进行安装。

# 示例：
conda install -c pytorch pytorch torchvision

3. 安装其他所需包

pip install -r requirements.txt

4. 编译 CUDA 算子

cd models/dab_deformable_detr/ops
python setup.py build install
# 运行单元测试（应显示所有检查均为 True）
python test.py
cd ../../..

数据

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

COCODIR/
  ├── train2017/
  ├── val2017/
  └── annotations/
  	├── instances_train2017.json
  	└── instances_val2017.json

运行

我们以标准的 DAB-DETR-R50 和 DAB-Deformable-DETR-R50 为例，演示如何进行训练和评估。

使用我们的预训练模型进行推理

请参阅 inference_and_visualize.ipynb。

评估我们的预训练模型

从 此链接 下载我们的 DAB-DETR-R50 模型检查点，并执行以下命令。您预计最终的 AP 大约为 42.2。

对于我们的 DAB-Deformable-DETR（下载地址），预期的最终 AP 为 48.7。

# 对于 dab_detr：AP 为 42.2
python main.py -m dab_detr \
  --output_dir logs/DABDETR/R50 \
  --batch_size 1 \
  --coco_path /path/to/your/COCODIR \ # 替换为您自己的 COCO 路径
  --resume /path/to/our/checkpoint \ # 替换为您自己的检查点路径
  --eval

# 对于 dab_deformable_detr：AP 为 48.7
python main.py -m dab_deformable_detr \
  --output_dir logs/dab_deformable_detr/R50 \
  --batch_size 2 \
  --coco_path /path/to/your/COCODIR \ # 替换为您自己的 COCO 路径
  --resume /path/to/our/checkpoint \ # 替换为您自己的检查点路径
  --transformer_activation relu \
  --eval

训练自己的模型

同样，你也可以在单个进程中训练我们的模型：

# 对于dab_detr
python main.py -m dab_detr \
  --output_dir logs/DABDETR/R50 \
  --batch_size 1 \
  --epochs 50 \
  --lr_drop 40 \
  --coco_path /path/to/your/COCODIR  # 将参数替换为你自己的COCO数据集路径

分布式运行

然而，由于训练耗时较长，我们建议在多设备上进行训练。

如果你计划在使用Slurm调度的集群上训练模型，以下是一个示例命令：

# 对于dab_detr：42.2 AP
python run_with_submitit.py \
  --timeout 3000 \
  --job_name DABDETR \
  --coco_path /path/to/your/COCODIR \
  -m dab_detr \
  --job_dir logs/DABDETR/R50_%j \
  --batch_size 2 \
  --ngpus 8 \
  --nodes 1 \
  --epochs 50 \
  --lr_drop 40 

# 对于dab_deformable_detr：48.7 AP
python run_with_submitit.py \
  --timeout 3000 \
  --job_name dab_deformable_detr \
  --coco_path /path/to/your/COCODIR \
  -m dab_deformable_detr \
  --transformer_activation relu \
  --job_dir logs/dab_deformable_detr/R50_%j \
  --batch_size 2 \
  --ngpus 8 \
  --nodes 1 \
  --epochs 50 \
  --lr_drop 40 

最终的AP值应与我们的结果相近。（DAB-DETR为42.2，DAB-Deformable-DETR为48.7）。我们的配置文件和日志（参见model_zoo）也可作为参考。

注意：

• 结果对批量大小较为敏感。我们默认使用16（每张GPU 2张图像 × 8张GPU）。

或者在单节点上使用多进程运行：

# 对于dab_detr：42.2 AP
python -m torch.distributed.launch --nproc_per_node=8 \
  main.py -m dab_detr \
  --output_dir logs/DABDETR/R50 \
  --batch_size 2 \
  --epochs 50 \
  --lr_drop 40 \
  --coco_path /path/to/your/COCODIR

# 对于dab_deformable_detr：48.7 AP
python -m torch.distributed.launch --nproc_per_node=8 \
  main.py -m dab_deformable_detr \
  --output_dir logs/dab_deformable_detr/R50 \
  --batch_size 2 \
  --epochs 50 \
  --lr_drop 40 \
  --transformer_activation relu \
  --coco_path /path/to/your/COCODIR

模型详解

类DETR模型对比

源文件可在这里找到。

链接

DINO：具有改进去噪锚框的DETR，用于端到端目标检测。
Hao Zhang*, Feng Li*, Shilong Liu*, Lei Zhang, Hang Su, Jun Zhu, Lionel M. Ni, Heung-Yeung Shum
arXiv 2022。
[论文] [代码]

DN-DETR：通过引入查询去噪加速DETR训练。
Feng Li*, Hao Zhang*, Shilong Liu, Jian Guo, Lionel M. Ni, Lei Zhang。
IEEE计算机视觉与模式识别会议（CVPR）2022。
[论文] [代码]

许可证

DAB-DETR采用Apache 2.0许可证发布。更多信息请参阅LICENSE文件。

版权所有 © IDEA。保留所有权利。

根据Apache许可证第2.0版（“许可证”）授权；除非符合许可证规定，否则不得使用这些文件。您可以在http://www.apache.org/licenses/LICENSE-2.0获取许可证副本。

除非适用法律要求或书面协议另有约定，否则根据“AS IS”基础分发的软件不提供任何形式的保证或条件，无论是明示还是暗示。有关特定语言的权限和限制，请参阅许可证条款。

引用

@inproceedings{
  liu2022dabdetr,
  title={{DAB}-{DETR}: Dynamic Anchor Boxes are Better Queries for {DETR}},
  author={Shilong Liu and Feng Li and Hao Zhang and Xiao Yang and Xianbiao Qi and Hang Su and Jun Zhu and Lei Zhang},
  booktitle={International Conference on Learning Representations},
  year={2022},
  url={https://openreview.net/forum?id=oMI9PjOb9Jl}
}

DAB-DETR 快速上手指南

DAB-DETR 是 ICLR 2022 收录的目标检测模型，通过动态锚框（Dynamic Anchor Boxes）作为 Transformer 的查询向量，显著提升了 DETR 类模型的收敛速度和检测精度。本指南基于官方 PyTorch 实现整理。

环境准备

• 操作系统: Linux (推荐)
• Python: 3.7.3 (其他版本可能兼容，但官方测试为此版本)
• PyTorch: 1.9.0
• CUDA: 11.1
• 数据集: COCO 2017 (需自行下载并整理目录结构)

COCO 数据集目录结构要求：

COCODIR/
  ├── train2017/
  ├── val2017/
  └── annotations/
      ├── instances_train2017.json
      └── instances_val2017.json

安装步骤

1. 克隆代码库

git clone https://github.com/IDEA-opensource/DAB-DETR.git
cd DAB-DETR

2. 安装 PyTorch 和 torchvision

建议根据本地 CUDA 版本前往 PyTorch 官网 获取安装命令。以下为官方测试环境的示例：

conda install -c pytorch pytorch torchvision

提示：国内用户可使用清华源加速安装： conda install -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch pytorch torchvision

3. 安装依赖包

pip install -r requirements.txt

提示：国内用户可使用 pip 国内镜像： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 编译 CUDA 算子 (仅 DAB-Deformable-DETR 需要)

如果你计划使用 DAB-Deformable-DETR 模型，必须手动编译可变形注意力算子。基础版 DAB-DETR 可跳过此步。

cd models/dab_deformable_detr/ops
python setup.py build install
# 单元测试（应输出所有 checking is True）
python test.py
cd ../../..

基本使用

以下示例展示如何使用预训练模型进行评估（Evaluation）。请确保已下载对应的权重文件并替换命令中的路径。

1. 评估基础版 DAB-DETR (ResNet50)

预期 AP 约为 42.2。

python main.py -m dab_detr \
  --output_dir logs/DABDETR/R50 \
  --batch_size 1 \
  --coco_path /path/to/your/COCODIR \
  --resume /path/to/your/checkpoint.pth \
  --eval

2. 评估可变形版 DAB-Deformable-DETR (ResNet50)

预期 AP 约为 48.7。

python main.py -m dab_deformable_detr \
  --output_dir logs/dab_deformable_detr/R50 \
  --batch_size 2 \
  --coco_path /path/to/your/COCODIR \
  --resume /path/to/your/checkpoint.pth \
  --transformer_activation relu \
  --eval

3. 训练自己的模型 (单卡示例)

以基础版 DAB-DETR 为例，训练 50 个 epoch：

python main.py -m dab_detr \
  --output_dir logs/DABDETR/R50 \
  --batch_size 1 \
  --epochs 50 \
  --lr_drop 40 \
  --coco_path /path/to/your/COCODIR

注意：由于训练耗时较长，生产环境建议使用多卡分布式训练（需配置 Slurm 或使用 torch.distributed），具体命令可参考官方 README 中的 "Distributed Run" 部分。