基于 PaddleDetection 的 Group DETR 系列实战指南：分组一对多匹配与编码器-解码器预训练

基于 PaddleDetection 的 Group DETR 系列实战指南：分组一对多匹配与编码器-解码器预训练

【免费下载链接】PaddleDetectionObject Detection toolkit based on PaddlePaddle. It supports object detection, instance segmentation, multiple object tracking and real-time multi-person keypoint detection.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleDetection

Group DETR / Group DETR v2 是两代以"分组一对一/多匹配"和"编码器-解码器预训练"为核心的 DETR 系列检测模型，本指南基于当前仓库 configs/group_detr 目录下的官方复现配置，完整讲解其原理、模型库、配置文件结构与多卡训练方法。读完本文，你将掌握如何在 PaddleDetection 中配置并训练 R-50 与 ViT-Huge 两个 Group DETR 变体，并理解dual_queries/dual_groups在源码中的底层实现。

一、Group DETR 与 Group DETR v2 技术背景

Group DETR 的目标是解决 DETR 系列模型训练收敛慢的痛点。传统 DETR 使用一对一匹配（one-to-one assignment），每个 ground-truth 目标只匹配一个 query，导致监督信号稀疏、训练需要更多轮次。Group DETR 引入分组一对多匹配（group-wise one-to-many assignment）：将一组 query 按组划分，每组中的多个 query 可以共同负责匹配同一个目标，从而在不改变推理时 query 数量的前提下，为训练提供更密集的监督信号，显著加快收敛速度。

Group DETR v2 则进一步提出**编码器-解码器预训练（encoder-decoder pretraining）**范式：先对检测模型的编码器与解码器进行预训练，再在目标检测数据上微调。根据当前仓库 configs/group_detr/README.md 的说明：

• Group DETR（论文 arXiv:2207.13085）是基于 DETR 的目标检测模型，仓库按论文完整复现。
• Group DETR v2（论文 arXiv:2211.03594）是基于 DINO 与 Group DETR 的强目标检测模型，仓库同样按论文完整复现。

说明：上文中论文链接来自仓库 README 原文，供读者理解技术出处；本仓库内的复现与配置以 PaddlePaddle 实现为准。

二、Model Zoo：已复现模型与精度

当前仓库在configs/group_detr下提供了两个可直接使用的模型配置，官方复现在 COCO 数据集上的检测精度（Box AP，即mAP(IoU=0.5:0.95)）如下表所示：

使用说明与注意事项（原文 Notes）：

• 两个模型均使用 COCO train2017 训练，并在 val2017 上以mAP(IoU=0.5:0.95)评估。
• Group DETR v2（ViT-Huge 变体）的训练流程更复杂：需要先在 ImageNet-1K 上以自监督方式预训练并微调 ViT-Huge 编码器，再在 Object365 上预训练检测器，最后在 trainCOCO 上微调；评估同样在 val2017 上进行。
• Group DETR 与 Group DETR v2 均使用4 张 GPU训练。

上述精度与下载链接均来自仓库 configs/group_detr/README.md 的 Model Zoo 表格，其中权重链接指向官方 BOS 存储，可直接用于评估或推理。

三、配置文件逐层解析

configs/group_detr目录采用 PaddleDetection 标准的_BASE_继承机制组织配置：

configs/group_detr/ ├── README.md ├── group_dino_r50_4scale_1x_coco.yml ├── group_dino_vit_huge_4scale_1x_coco.yml └── _base_/ ├── group_dino_r50.yml ├── group_dino_vit_huge.yml ├── dino_reader.yml ├── dino_2000_reader.yml └── optimizer_1x.yml

3.1 顶层入口配置

以 R-50 变体为例，group_dino_r50_4scale_1x_coco.yml 内容如下：

_BASE_: [ '../datasets/coco_detection.yml', '../runtime.yml', '_base_/optimizer_1x.yml', '_base_/group_dino_r50.yml', '_base_/dino_reader.yml', ] weights: output/group_dino_r50_4scale_1x_coco/model_final find_unused_parameters: True log_iter: 100

其继承了五份基础配置：

顶层三个自有字段含义：

• weights：保存最终权重的前缀路径，训练结束后会产出model_final.pdparams等文件。
• find_unused_parameters: True：在 DDP 分布式训练中允许存在未参与反向传播的参数，Group DETR 的分组去噪分支在部分情况下会产生未用参数，因此需要开启。
• log_iter: 100：每 100 个 iter 打印一次训练日志。

ViT-Huge 变体的 group_dino_vit_huge_4scale_1x_coco.yml 结构完全一致，仅将模型配置替换为_base_/group_dino_vit_huge.yml、数据读取替换为_base_/dino_2000_reader.yml，权重前缀为output/group_dino_vit_huge_4scale_1x_coco/model_final。

3.2 模型结构配置：_base_/group_dino_r50.yml

group_dino_r50.yml 定义了完整的模型组装：

architecture: DETR pretrain_weights: https://paddledet.bj.bcebos.com/models/pretrained/ResNet50_cos_pretrained.pdparams hidden_dim: 256 use_focal_loss: True DETR: backbone: ResNet transformer: GroupDINOTransformer detr_head: DINOHead post_process: DETRPostProcess ResNet: depth: 50 norm_type: bn freeze_at: 0 return_idx: [1, 2, 3] lr_mult_list: [0.0, 0.1, 0.1, 0.1] num_stages: 4 GroupDINOTransformer: num_queries: 900 position_embed_type: sine num_levels: 4 nhead: 8 num_encoder_layers: 6 num_decoder_layers: 6 dim_feedforward: 2048 dropout: 0.0 activation: relu pe_temperature: 20 pe_offset: 0.0 num_denoising: 100 label_noise_ratio: 0.5 box_noise_scale: 1.0 learnt_init_query: True dual_queries: True dual_groups: 10 DINOHead: loss: name: DINOLoss loss_coeff: {class: 1, bbox: 5, giou: 2} aux_loss: True matcher: name: HungarianMatcher matcher_coeff: {class: 2, bbox: 5, giou: 2} DETRPostProcess: num_top_queries: 300 dual_queries: True dual_groups: 10

关键参数说明：

• architecture: DETR：以 DETR 为总装架构，内部由 backbone、transformer、head、post_process 四部分组成。
• pretrain_weights：骨干网络预训练权重（ResNet50 cosine 预训练权重），训练启动时会自动下载。
• use_focal_loss: True：分类分支使用 Focal Loss，这是 DINO 系列（含 Group DETR）相比原始 DETR 的重要改进。
• GroupDINOTransformer：这是 Group DETR 的核心模块，其中：
  • num_queries: 900：decoder 使用 900 个 query。在dual_queries开启后，这 900 个 query 会被划分为主 query 与分组 query 两类（见下文源码解析）。
  • num_levels: 4：使用 4 尺度多尺度特征（4-scale），对应多尺度可变形注意力。
  • num_encoder_layers / num_decoder_layers: 6 / 6：6 层编码器 + 6 层解码器。
  • num_denoising: 100：每组去噪 query 数量为 100，用于 DINO 风格的对比去噪训练。
  • label_noise_ratio: 0.5/box_noise_scale: 1.0：去噪训练中标签噪声比例与框噪声尺度。
  • dual_queries: True+dual_groups: 10：开启双查询（dual queries）机制，并将查询分为 10 组，这是 Group DETR "分组一对多匹配"的直接体现。
• DINOHead：损失函数为DINOLoss，分类/框/giou 损失系数为{class: 1, bbox: 5, giou: 2}，匹配器为匈牙利匹配器HungarianMatcher（系数{class: 2, bbox: 5, giou: 2}），并开启aux_loss辅助解码层损失。
• DETRPostProcess：推理后处理保留num_top_queries: 300个 top 结果，并同样传入dual_queries: True、dual_groups: 10，与训练阶段的分组设置保持一致，确保推理时能从分组 query 中正确聚合输出。

3.3 ViT-Huge 变体配置：_base_/group_dino_vit_huge.yml

group_dino_vit_huge.yml 将骨干替换为 Vision Transformer：

architecture: DETR pretrain_weights: https://bj.bcebos.com/v1/paddledet/models/pretrained/vit_huge_mae_patch14_dec512d8b_pretrained.pdparams hidden_dim: 256 use_focal_loss: True DETR: backbone: VisionTransformer2D neck: SimpleFeaturePyramid transformer: GroupDINOTransformer detr_head: DINOHead post_process: DETRPostProcess VisionTransformer2D: patch_size: 16 embed_dim: 1280 depth: 32 num_heads: 16 mlp_ratio: 4 attn_bias: True drop_rate: 0.0 drop_path_rate: 0.1 lr_decay_rate: 0.7 global_attn_indexes: [7, 15, 23, 31] use_abs_pos: False use_rel_pos: True rel_pos_zero_init: True window_size: 14 out_indices: [ 31, ] SimpleFeaturePyramid: out_channels: 256 num_levels: 4 GroupDINOTransformer: num_queries: 900 position_embed_type: sine pe_temperature: 20 pe_offset: 0.0 num_levels: 4 nhead: 8 num_encoder_layers: 6 num_decoder_layers: 6 dim_feedforward: 2048 use_input_proj: False dropout: 0.0 activation: relu num_denoising: 100 label_noise_ratio: 0.5 box_noise_scale: 1.0 learnt_init_query: True dual_queries: True dual_groups: 10 DETRPostProcess: num_top_queries: 300 dual_queries: True dual_groups: 10

与 R-50 变体的差异集中在骨干部分：

• VisionTransformer2D：ViT-Huge 结构，patch 16、embed_dim 1280、32 层、16 头、MLP 比例 4。预训练权重为ViT-Huge MAE（masked autoencoder）自监督预训练权重，lr_decay_rate: 0.7表示对浅层使用更低学习率的分层衰减策略。
• SimpleFeaturePyramid：由于 ViT 输出为单尺度特征，通过简单的特征金字塔（4 个 level，输出通道 256）构造多尺度特征，供 4-scale 可变形注意力使用。
• use_input_proj: False：因为已经通过SimpleFeaturePyramid将特征投影到统一通道，Transformer 内部不再重复构建输入投影层（对应源码中_build_input_proj_layer的开关，见下文）。
• DINOHead配置与 R-50 一致（DINOLoss+HungarianMatcher，系数相同），两变体共享相同的损失与匹配策略。

3.4 数据读取与增广：dino_reader.yml与dino_2000_reader.yml

两份 reader 配置分别服务于 (800, 1333) 与 (1184, 2000) 两种输入分辨率，训练阶段均采用 DINO 风格的随机多尺度增广。

dino_reader.yml 的训练流水线：

worker_num: 2 TrainReader: sample_transforms: - Decode: {} - RandomFlip: {prob: 0.5} - RandomSelect: { transforms1: [ RandomShortSideResize: { short_side_sizes: [ 480, 512, 544, 576, 608, 640, 672, 704, 736, 768, 800 ], max_size: 1333 } ], transforms2: [ RandomShortSideResize: { short_side_sizes: [ 400, 500, 600 ] }, RandomSizeCrop: { min_size: 384, max_size: 600 }, RandomShortSideResize: { short_side_sizes: [ 480, 512, 544, 576, 608, 640, 672, 704, 736, 768, 800 ], max_size: 1333 } ] } - NormalizeImage: {is_scale: true, mean: [0.485,0.456,0.406], std: [0.229, 0.224,0.225]} - NormalizeBox: {} - BboxXYXY2XYWH: {} - Permute: {} batch_transforms: - PadMaskBatch: {pad_to_stride: -1, return_pad_mask: true} batch_size: 2 shuffle: true drop_last: true collate_batch: false use_shared_memory: false

• RandomSelect：以 50% 概率选择两条增广路径之一——纯随机短边缩放，或"缩放 + 随机裁剪 + 再缩放"的组合增广（large-scale jitter 风格），提升模型尺度鲁棒性。
• short_side_sizes从 480 到 800 共 11 档，max_size: 1333限制最长边，与 Model Zoo 表中 (800, 1333) 分辨率对应。
• PadMaskBatch：对 batch 内的图做 padding，并返回 pad mask（return_pad_mask: true），供 Transformer 编码器忽略 padding 区域。
• 训练batch_size: 2，drop_last: true，collate_batch: false（由 PadMaskBatch 自定义 batch 组装）。

dino_2000_reader.yml 面向 ViT-Huge 变体，区别在于：

• 短边缩放档位扩展为 480~1184 共 24 档，max_size: 2000；随机裁剪的min_size: 384, max_size: 900。
• 评估与测试分辨率提升为(1184, 2000)，与 Model Zoo 表中 ViT-Huge 一行的 Resolution 对应。

两份配置的 EvalReader / TestReader 均采用保持长宽比的单尺度Resize（keep_ratio: True），batch_size: 1。

3.5 训练计划与优化器：optimizer_1x.yml

optimizer_1x.yml 是典型的 DETR 系列 1x 训练计划：

epoch: 12 LearningRate: base_lr: 0.0001 schedulers: - !PiecewiseDecay gamma: 0.1 milestones: [11] use_warmup: false OptimizerBuilder: clip_grad_by_norm: 0.1 regularizer: false optimizer: type: AdamW weight_decay: 0.0001

• 12 epoch 总训练时长，在第 11 epoch 处学习率乘以 0.1（PiecewiseDecay，gamma: 0.1），无 warmup。
• AdamW 优化器，基础学习率1e-4，权重衰减1e-4，不额外使用正则化（regularizer: false）。
• 梯度裁剪：clip_grad_by_norm: 0.1，限制全局梯度范数，保证 Transformer 训练稳定。

四、源码级原理：dual_queries与dual_groups的实现

Group DETR 的分组一对多匹配在源码中由 ppdet/modeling/transformers/group_detr_transformer.py 中的GroupDINOTransformer类实现。该类继承自 DINO 系列的可变形 Transformer 结构，核心新增即双查询分组机制。

从__init__签名（第 339-367 行）可见其关键入参：

class GroupDINOTransformer(nn.Layer): __shared__ = ['num_classes', 'hidden_dim'] def __init__(self, num_classes=80, hidden_dim=256, num_queries=900, ... learnt_init_query=True, use_input_proj=True, dual_queries=False, dual_groups=0, eps=1e-2):

当dual_queries=True时，源码会为每个分组创建独立的参数（第 414-474 行附近）：

• 分组去噪类别嵌入：denoising_class_embed_groups = nn.LayerList([nn.Embedding(num_classes, hidden_dim) for _ in range(self.dual_groups)])，即每个分组拥有独立的去噪类别嵌入。
• 分组 query 初始化：tgt_embed_dual = nn.LayerList([nn.Embedding(num_queries, hidden_dim) for _ in range(self.dual_groups)])，每个分组有独立的可学习 query 初始嵌入，并通过normal_初始化。
• 分组编码器输出头：enc_output被复制为dual_groups + 1份（主查询 + 10 组），同时为每组单独创建enc_bbox_head_dq与enc_score_head_dq（分组框/分类头）。

这一设计意味着：主查询（main queries）负责最终的检测输出，而 10 组（dual_groups=10）分组查询以一对多的方式分别匹配同一个 ground-truth，在训练时提供更密集的匹配监督；推理阶段分组查询的输出通过 DETRPostProcess 聚合（ppdet/modeling/post_process.py 中同样接收dual_queries与dual_groups），仅保留主查询对应的num_top_queries: 300个结果。

此外，use_input_proj开关对应源码第 382-384 行的if use_input_proj: self._build_input_proj_layer(backbone_feat_channels)：R-50 变体开启（对 backbone 多尺度特征做通道投影），ViT-Huge 变体关闭（特征已由SimpleFeaturePyramid统一到 256 通道，避免重复投影）。from_config（第 515-517 行）会从input_shape自动读取 backbone 各层输出通道数填充backbone_feat_channels。

上述类名、参数名与分支逻辑均可直接在 group_detr_transformer.py 中核对；配置文件中出现的GroupDINOTransformer、DINOHead、DETRPostProcess等模块名与该文件__all__ = ['GroupDINOTransformer']的注册机制一一对应。

五、训练、评估与推理

5.1 多卡训练

仓库 README 给出的官方训练命令为4 卡分布式训练（--fleet使用 Fleet 分布式训练，--eval训练中周期评估）：

python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/group_detr/group_dino_r50_4scale_1x_coco.yml --fleet --eval

python -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/group_detr/group_dino_vit_huge_4scale_1x_coco.yml --fleet --eval

单卡（或更少卡）训练时可去掉--fleet，例如：

python tools/train.py -c configs/group_detr/group_dino_r50_4scale_1x_coco.yml --eval

注意：

• 两个模型的官方精度均基于4 卡训练得到，若使用不同卡数，建议按卡数等比调整batch_size并相应缩放学习率，否则精度可能有偏差。
• ViT-Huge 变体对显存要求极高（(1184, 2000) 分辨率 + 32 层 ViT），且其完整复现流程依赖 ImageNet-1K 自监督预训练与 Object365 预训练后的权重（即配置中的pretrain_weights），直接从头训练无法复现 63.3 Box AP。

5.2 评估

使用 tools/eval.py 在 COCO val2017 上评估：

python tools/eval.py -c configs/group_detr/group_dino_r50_4scale_1x_coco.yml -o weights=output/group_dino_r50_4scale_1x_coco/model_final.pdparams

也可直接下载 Model Zoo 表格中的 BOS 权重进行评估。评估指标为 COCOmAP(IoU=0.5:0.95)，即表格中的 Box AP。

5.3 推理

使用 tools/infer.py 对单张图片推理：

python tools/infer.py -c configs/group_detr/group_dino_r50_4scale_1x_coco.yml -o weights=output/group_dino_r50_4scale_1x_coco/model_final.pdparams --infer_img=demo/000000014439.jpg

如需服务化或高性能推理，可参考 deploy/python/infer.py 与 deploy/EXPORT_MODEL.md 完成模型导出。

六、复现要点总结

七、引用

若在你的研究或工程中使用了 Group DETR / Group DETR v2，可引用以下文献（来自仓库 README）：

@article{chen2022group, title={Group DETR: Fast DETR training with group-wise one-to-many assignment}, author={Chen, Qiang and Chen, Xiaokang and Wang, Jian and Feng, Haocheng and Han, Junyu and Ding, Errui and Zeng, Gang and Wang, Jingdong}, journal={arXiv preprint arXiv:2207.13085}, volume={1}, number={2}, year={2022} } @article{chen2022group, title={Group DETR v2: Strong object detector with encoder-decoder pretraining}, author={Chen, Qiang and Wang, Jian and Han, Chuchu and Zhang, Shan and Li, Zexian and Chen, Xiaokang and Chen, Jiahui and Wang, Xiaodi and Han, Shuming and Zhang, Gang and others}, journal={arXiv preprint arXiv:2211.03594}, year={2022} }

【免费下载链接】PaddleDetectionObject Detection toolkit based on PaddlePaddle. It supports object detection, instance segmentation, multiple object tracking and real-time multi-person keypoint detection.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleDetection