在 MMDetection 中训练 V3Det 万类视觉检测模型：数据集准备、配置解析与源码剖析

在 MMDetection 中训练 V3Det 万类视觉检测模型：数据集准备、配置解析与源码剖析

【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection

导读

V3Det（Vast Vocabulary Visual Detection Dataset）是 ICCV 2023（Oral）提出的超大规模词汇视觉检测数据集，其类别规模高达 13,204 类，是 LVIS 等既有大规模词汇数据集的约 10 倍。本文以 configs/v3det/README.md 为骨架，结合仓库内 10 份 V3Det 官方配置与 mmdet/datasets/v3det.py、mmdet/models/layers/normed_predictor.py 等源码实现，系统讲解如何基于 MMDetection 完成 V3Det 数据准备、复现 Faster R-CNN / Cascade R-CNN / FCOS / Deformable-DETR / DINO 五类基线模型，并深入剖析面向万类检测的归一化分类头、自定义损失、类别均衡采样与重复框扰动（perm-repeat）等关键技术细节。

V3Det 数据集概述

V3Det 面向"更通用的视觉目标检测"提出，核心目标是打破现有检测数据集词汇量受限的瓶颈。根据 configs/v3det/README.md 中的 Abstract，其核心特性包括：

• 巨大词汇量（Vast Vocabulary）：在真实世界图像上为13,204 个类别标注了边界框，词汇量约为现有大规模词汇检测数据集（如 LVIS）的10 倍；
• 层次化类别组织（Hierarchical Category Organization）：全部类别由一棵类别树组织，标注了类别之间的包含关系，为大规模与开放词汇检测中的类别关系研究提供支撑；
• 丰富标注（Rich Annotations）：在243k 张图像上提供精确标注，同时由人类专家与强聊天机器人撰写每个类别的专业描述。

该数据集已收录进 MMDetection 仓库，作为官方支持的检测数据集之一，其数据集类型、标注格式、评估协议均在 mmdet/datasets/v3det.py 与配置文件中有完整实现。

数据准备与目录结构

下载与整理

V3Det 数据需从 V3Det 官方主页（v3det.openxlab.org.cn）与 V3Det 官方 GitHub 仓库下载。数据包含训练集与验证集，共13,204 个类别；其中训练集含183,354 张图像，验证集含29,821 张图像。按照 configs/v3det/README.md 给出的数据组织方式，下载后应整理为如下结构：

data/ V3Det/ images/ <category_node>/ |────<image_name>.png ... ... annotations/ |────v3det_2023_v1_category_tree.json # Category tree |────category_name_13204_v3det_2023_v1.txt # Category name |────v3det_2023_v1_train.json # Train set |────v3det_2023_v1_val.json # Validation set

其中图像按类别节点（<category_node>）分目录存放；v3det_2023_v1_category_tree.json保存层次化类别树；category_name_13204_v3det_2023_v1.txt每行一个类别名，共 13,204 行；v3det_2023_v1_train.json/v3det_2023_v1_val.json为 COCO 格式的训练/验证标注文件。

数据集根目录约定

仓库所有 V3Det 配置统一使用data_root = 'data/V3Det/'（见 configs/base/datasets/v3det.py），即默认数据放置在工作区根目录的data/V3Det/下，与上述目录结构一致。

V3Det 数据集在 MMDetection 中的实现

V3DetDataset：从 COCO 格式继承而来的万类数据集

MMDetection 通过V3DetDataset类接入该数据集，实现在 mmdet/datasets/v3det.py。它直接继承自CocoDataset（因为 V3Det 的标注文件是 COCO JSON 格式），仅在构造时额外做了一件事：

• 通过mmengine.list_from_file读取data_root下的类别名文件annotations/category_name_13204_v3det_2023_v1.txt（默认路径），得到 13,204 个类别名的元组；
• 将类别名注入metainfo['classes']，再交给父类初始化。

class V3DetDataset(CocoDataset): METAINFO = {'classes': None, 'palette': None} def __init__(self, *args, metainfo=None, data_root='', label_file='annotations/category_name_13204_v3det_2023_v1.txt', **kwargs): class_names = tuple(mmengine.list_from_file(os.path.join(data_root, label_file))) if metainfo is None: metainfo = {'classes': class_names} super().__init__(*args, data_root=data_root, metainfo=metainfo, **kwargs)

这意味着训练/验证标注文件路径（annotations/v3det_2023_v1_train.json、annotations/v3det_2023_v1_val.json）、图像前缀data_prefix=dict(img='')均遵循上文目录结构，可直接沿用 COCO 的加载、过滤（filter_cfg）与评估（CocoMetric）机制。

基类数据集配置

configs/base/datasets/v3det.py 是各 V3Det 实验共用的基类数据集配置，关键点包括：

• 训练管线：LoadImageFromFile→LoadAnnotations(with_bbox=True)→RandomChoiceResize（短边从 640/672/704/736/768/800 中随机选择、长边 1333，keep_ratio=True）→RandomFlip(prob=0.5)→PackDetInputs；
• 测试管线：Resize(scale=(1333, 800), keep_ratio=True)固定尺度，并建议无 GT 时删除LoadAnnotations；
• 训练数据：外层用ClassBalancedDataset(oversample_thr=1e-3)包裹V3DetDataset，并设置filter_cfg=dict(filter_empty_gt=True, min_size=4)过滤空图与过小框；
• 验证/测试：test_mode=True，评估器为CocoMetric，关键参数use_mp_eval=True（多进程评估）与proposal_nums=[300]。

模型结果与基线复现

configs/v3det/README.md 给出了官方在 V3Det 验证集上的评测结果，覆盖 ResNet-50 与 Swin-B 两种骨干、五种检测范式：

其中sample1e-3指训练时使用ClassBalancedDataset且oversample_thr=1e-3。Swin-B 系列配置均在对应 R-50 配置基础上，通过_delete_=True替换骨干为SwinTransformer（embed_dims=128、depths=[2,2,18,2]、num_heads=[4,8,16,32]、window_size=7、drop_path_rate=0.3），并相应调整neck的in_channels（两阶段模型为[128,256,512,1024]，DINO 为[256,512,1024]），例如 cascade_rcnn_swinb_fpn_8x4_sample1e-3_mstrain_v3det_2x.py 与 dino-4scale_swin_16xb1_sample1e-3_v3det_36e.py。

运行训练与测试

按照 MMDetection 标准流程，训练与测试的命令如下（以 Faster R-CNN 为例）：

# 单卡训练 python tools/train.py configs/v3det/faster_rcnn_r50_fpn_8x4_sample1e-3_mstrain_v3det_2x.py # 多卡训练（8 卡） bash tools/dist_train.sh configs/v3det/faster_rcnn_r50_fpn_8x4_sample1e-3_mstrain_v3det_2x.py 8 # 测试 python tools/test.py configs/v3det/faster_rcnn_r50_fpn_8x4_sample1e-3_mstrain_v3det_2x.py <checkpoint路径>

注意：仓库只提供训练/测试入口，预训练权重需按 configs/v3det/README.md 的下载链接从 V3Det 官方模型仓库获取后，将<checkpoint路径>替换为实际权重文件位置。

面向万类检测的模型设计要点

归一化线性分类头 NormedLinear

万类分类头（13,204 类）直接使用普通nn.Linear容易导致权重与特征尺度失配。MMDetection 为此提供了归一化线性层NormedLinear，实现位于 mmdet/models/layers/normed_predictor.py，其前向过程为：

weight_ = self.weight / (self.weight.norm(dim=1, keepdim=True).pow(self.power) + self.eps) x_ = x / (x.norm(dim=1, keepdim=True).pow(self.power) + self.eps) x_ = x_ * self.tempearture return F.linear(x_, weight_, self.bias)

即同时对分类权重与输入特征做 L2 归一化，并乘以温度系数temperature控制 logits 的锐利程度；权重初始化采用均值 0、标准差 0.01 的正态分布，偏置初始化为 0。V3Det 各两阶段与单阶段配置统一使用cls_predictor_cfg=dict(type='NormedLinear', tempearture=50, bias=True)（注意源码中参数名拼写为tempearture，配置需保持一致）。

自定义分类损失：CrossEntropyCustomLoss 与 FocalCustomLoss

由于类别数高达 13,204，MMDetection 专门实现了两类"自定义"分类损失，它们通过设置custom_cls_channels、custom_activation、custom_accuracy三个标志，接管分类头输出通道数、激活函数与精度计算的默认逻辑：

• 两阶段模型（Faster R-CNN / Cascade R-CNN）使用CrossEntropyCustomLoss，实现于 mmdet/models/losses/cross_entropy_loss.py 的CrossEntropyCustomLoss类。配置为use_sigmoid=True、num_classes=13204：
  • get_cls_channels返回num_classes（sigmoid 模式不需要额外的背景通道）；
  • get_activation对前num_classes维做 sigmoid，并额外构造一个"无目标（背景）得分"通道score_neg = 1 - score_classes.sum(dim=1)（clamp 到 [0,1]）后拼接，用于统一的概率分布表示；
  • get_accuracy仅在labels < num_classes的正样本上统计acc_classes。
• 单阶段模型（FCOS）使用FocalCustomLoss，实现于 mmdet/models/losses/focal_loss.py 的FocalCustomLoss类。配置为use_sigmoid=True、num_classes=13204、gamma=2.0、alpha=0.25，其get_activation直接对前num_classes维做 sigmoid 作为类别得分，契合 focal loss 的多标签二分类建模。

重复 GT 框扰动：perm_repeat_gt_cfg

V3Det 数据中存在大量完全相同的重复标注框（同一张图中多个物体共用同一坐标的 GT 框）。这些完全一致的框会干扰 MaxIoUAssigner 对 anchor/proposal 的唯一性匹配。V3Det 系列配置在 assigner 中加入perm_repeat_gt_cfg=dict(iou_thr=0.7, perm_range=0.01)，其实现位于 mmdet/models/task_modules/assigners/max_iou_assigner.py：

• perm_repeat_bboxes（第 53 行起）找出所有完全重复的 GT 框，对每一组重复框调用_perm_box做微扰；
• _perm_box（第 14 行起）为每个框的坐标乘以uniform_(1-perm_range, 1+perm_range)的随机扰动因子，并校验扰动后宽高仍为正、且与原框 IoU 高于iou_thr（默认 0.97）；若不满足则缩小扰动范围（每轮perm_range -= counter * 0.001）递归重试，最多max_iter=5次；
• 扰动的唯一框随后进入overlaps = self.iou_calculator(gt_bboxes_unique, priors)参与 IoU 匹配，从而将重复框转化为语义一致但坐标略异的多个正样本。

这是 V3Det 训练中一个关键的"隐性"设置，直接影响分配器行为的正确性。

类别均衡采样：ClassBalancedDataset 与 oversample_thr

V3Det 的 13,204 类呈极端长尾分布。为解决该问题，所有训练配置均采用ClassBalancedDataset（来自 mmengine）包裹 V3Det 数据集，并设置oversample_thr=1e-3：该包装器根据每个类别的样本频率，对稀有类别的图像进行重复采样（repeat 次数基于oversample_thr与类别频率之比计算），使低频类别在训练过程中被更频繁地看到。这也解释了配置文件名中的sample1e-3语义——例如 configs/v3det/deformable-detr-refine-twostage_r50_8xb4_sample1e-3_v3det_50e.py 与 configs/v3det/dino-4scale_r50_8xb2_sample1e-3_v3det_36e.py 均以ClassBalancedDataset(oversample_thr=1e-3)作为外层包装。

训练策略与超参数解读

V3Det 配置全部采用基于迭代（iter-based）的训练循环，与 COCO 常规的 epoch 式训练不同，这是由数据集规模决定的（单轮遍历 18 万+ 训练图耗时巨大）。

两阶段模型（2x）训练策略

以 faster_rcnn_r50_fpn_8x4_sample1e-3_mstrain_v3det_2x.py 为例，其核心设置包括：

• 模型头：bbox_head.num_classes=13204，reg_class_agnostic=True（类别无关回归，万类下共享同一回归分支），loss_cls用CrossEntropyCustomLoss（sigmoid + 13204 类），loss_bbox用L1Loss；
• 分配/采样：rpn_proposal=dict(nms_pre=4000, max_per_img=2000)（更多候选框），rcnn 分支的 assigner 加入perm_repeat_gt_cfg=dict(iou_thr=0.7, perm_range=0.01)；
• 推理设置：test_cfg.rcnn中score_thr=0.0001（超低阈值，保证长尾类别不被误滤）、nms(iou_threshold=0.6)、max_per_img=300（每图最多输出 300 个框）；
• 训练循环：max_iter = 68760 * 2（即 2x），val_interval=max_iter（仅训练结束时验证一次）；
• 学习率：先LinearLR(start_factor=1/2048, end=5000)做 warmup，再MultiStepLR(milestones=[45840*2, 63030*2], gamma=0.1)衰减；
• 优化器：AdamW(lr=1e-4, weight_decay=0.1)，配合clip_grad(max_norm=35, norm_type=2)梯度裁剪；
• 自动学习率缩放：auto_scale_lr=dict(enable=False, base_batch_size=32)（8 GPU × 4 样本，当前默认关闭）；
• 保存/日志：CheckpointHook(by_epoch=False, interval=5730*2)，LogProcessor(window_size=50, by_epoch=False)。

Cascade R-CNN 配置（cascade_rcnn_r50_fpn_8x4_sample1e-3_mstrain_v3det_2x.py）在此基础上把roi_head.bbox_head扩展为三个级联Shared2FCBBoxHead，级联阈值依次为 IoU 0.5 / 0.6 / 0.7，每级都带reg_class_agnostic=True、NormedLinear分类头与CrossEntropyCustomLoss，每级 sampler 采样 512 个样本、正样本比例 0.25，并将 RPN 回归损失替换为L1Loss。

Transformer 检测器（50e / 36e）训练策略

Deformable-DETR 与 DINO 系列配置直接继承 COCO 版本（_base_指向configs/deformable_detr/与configs/dino/），仅覆盖必要字段：

• 模型：bbox_head.num_classes=13204，test_cfg.max_per_img=300；
• 训练管线（RFS，Random Resize + Random Crop）：以RandomChoice二选一——要么直接在 11 档尺度[(480,1333)…(800,1333)]中随机选一缩放；要么先在大图尺度[(400,4200),(500,4200),(600,4200)]缩放后做RandomCrop(crop_size=(384,600), allow_negative_crop=True)再按上述尺度缩放（注释说明：训练集全部图像长宽比 < 7，与官方实现保持一致）；
• 数据加载：ClassBalancedDataset(oversample_thr=1e-3)+filter_cfg=dict(filter_empty_gt=False)（Transformer 检测器不丢弃空图）；
• 训练循环：DINO 配置max_iter=412560（bs16 下每 epoch 约 11460 iter，对应 36e），val_interval=max_iter/5；Deformable-DETR 配置max_iter=286500（bs32 下每 epoch 约 5730 iter，对应 50e）；
• 学习率：MultiStepLR，DINO 在 343800 iter（30e）处衰减 0.1，Deformable-DETR 在 229200 iter（40e）处衰减 0.1；
• Checkpoint：interval按各自每 epoch 迭代数设置，max_keep_ckpts=3控制磁盘占用；
• 评估：use_mp_eval=True、proposal_nums=[300]（配合测试端max_per_img=300）。

FCOS 的差异点

fcos_r50_fpn_8x4_sample1e-3_mstrain_v3det_2x.py 完全展开定义模型（不依赖模型基类），使用 FPN +FCOSHead(num_classes=13204)，strides=[8,16,32,64,128]，loss_cls为FocalCustomLoss(gamma=2.0, alpha=0.25)，loss_bbox为IoULoss，loss_centerness为 sigmoidCrossEntropyLoss；训练 2x 时max_iter = 68760*2*2（FCOS 的迭代数是两阶段模型的 2 倍），学习率为1e-4*0.25，并设置find_unused_parameters=True。

评估协议细节

V3Det 验证评估统一通过CocoMetric（metric='bbox'）完成，基类配置见 configs/base/datasets/v3det.py：

• ann_file指向annotations/v3det_2023_v1_val.json；
• use_mp_eval=True：启用多进程评估（13,204 类 + 近 3 万张验证图的 IoU 计算量极大，多进程评估可显著加速）；
• proposal_nums=[300]：只统计每图前 300 个检测框的指标，与test_cfg.max_per_img=300对齐。

Transformer 类配置（DINO / Deformable-DETR）在各自文件中覆盖了val_evaluator/test_evaluator，但参数语义一致。

引用

如果 V3Det 数据集的实验成果被用于研究工作，请按 configs/v3det/README.md 提供的 BibTeX 引用论文：

@inproceedings{wang2023v3det, title = {V3Det: Vast Vocabulary Visual Detection Dataset}, author = {Wang, Jiaqi and Zhang, Pan and Chu, Tao and Cao, Yuhang and Zhou, Yujie and Wu, Tong and Wang, Bin and He, Conghui and Lin, Dahua}, booktitle = {The IEEE International Conference on Computer Vision (ICCV)}, month = {October}, year = {2023} }

小结

本文围绕 configs/v3det/README.md 完整梳理了在 MMDetection 中开展 V3Det 万类检测实验的全链路：从数据集下载与目录组织（数据准备），到V3DetDataset的实现细节（mmdet/datasets/v3det.py），再到五类官方基线的配置与复现命令；同时结合源码剖析了万类场景下的三项关键技术——NormedLinear归一化分类头（normed_predictor.py）、CrossEntropyCustomLoss/FocalCustomLoss自定义损失（cross_entropy_loss.py、focal_loss.py）、以及perm_repeat_gt_cfg重复框扰动（max_iou_assigner.py），并解释了ClassBalancedDataset长尾采样与 iter-based 训练调参逻辑。这些配置与实现可作为大规模词汇、开放词汇检测研究的直接实验基线，读者可在此基础上进一步探索类别关系建模、层次化检测等方向。

【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection