企业官网建设流程全解析

MMDetection 配置文件从 2.x 迁移到 3.x：DataPreprocessor、Dataloader 与评测器改造实战指南

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

MMDetection 3.x 的配置文件相较 2.x 发生了系统性重构：data字典被train_dataloader/val_dataloader/test_dataloader取代，Normalize/Pad从 pipeline 中移入模型的DataPreprocessor，精度评测从数据集字段解耦为独立的 Evaluator。本文以 官方迁移文档 为主体，逐节给出 2.x 与 3.x 配置的对照迁移方法，并结合当前仓库的基线配置（coco_instance.py、schedule_1x.py）与源码实现，帮助你在升级模型配置、排查数据流问题时做到“改得对、跑得通”。

一、迁移总览：一张对照表先建立全局认知

开始逐节迁移前，先用下表把 2.x 的顶层配置字段与 3.x 的对应字段对齐，这是所有迁移工作的“字典”：

以下各节将逐一展开，每节都给出 2.x 原配置 → 3.x 新配置的完整对照。

二、模型配置：新增 DataPreprocessor 模块

3.x 中模型的 backbone、neck、head 以及train_cfg、test_cfg的参数与 2.x 基本保持一致，唯一的关键变化是新增了DataPreprocessor模块，配置位于model.data_preprocessor。它负责对输入数据做预处理：图像归一化、将不同大小的图片 padding 到统一尺寸以组 batch、把图像从内存搬运到显存等。这部分配置取代了原本写在train_pipeline和test_pipeline中的Normalize与Pad。

2.x 原配置：

# 图像归一化参数 img_norm_cfg = dict( mean=[123.675, 116.28, 103.53], std=[58.395, 57.12, 57.375], to_rgb=True) pipeline=[ ..., dict(type='Normalize', **img_norm_cfg), dict(type='Pad', size_divisor=32), # 图像 padding 到 32 的倍数 ... ]

3.x 新配置：

model = dict( data_preprocessor=dict( type='DetDataPreprocessor', # 图像归一化参数 mean=[123.675, 116.28, 103.53], std=[58.395, 57.12, 57.375], bgr_to_rgb=True, # 图像 padding 参数 pad_mask=True, # 在实例分割中，需要将 mask 也进行 padding pad_size_divisor=32) # 图像 padding 到 32 的倍数 )

源码视角：DetDataPreprocessor 还做了什么

从 data_preprocessor.py 的实现可以看到，DetDataPreprocessor继承自 MMEngine 的ImgDataPreprocessor，在标准能力（collate 并搬运数据、按pad_valuepadding、stack 成 batch、bgr_to_rgb转换、按mean/std归一化）之外，还针对检测任务做了两处扩展：

1. 支持 batch 级数据增强（batch_augments参数，按nn.ModuleList构建）；
2. 额外向 data sample 中追加batch_input_shape和pad_shape元信息，供后续 NMS、结果解码等环节使用。

此外它还有几个检测场景常用、但官方迁移对照中未全部列出的参数：pad_value（默认 0，图像 padding 填充值）、mask_pad_value（mask padding 填充值，默认 0）、pad_seg/seg_pad_value（语义分割图 padding，默认值 255）、boxtype2tensor（是否把BaseBoxes类型的 bbox 转成 Tensor，默认 True）。当前仓库 mask-rcnn_r50_fpn.py 中的基线配置即为该模块的标准写法。

迁移要点：把img_norm_cfg中的to_rgb对应改为bgr_to_rgb；实例分割模型务必保留pad_mask=True，否则 batch 内 mask 尺寸不一致会导致 padding 行为不正确。

三、数据集与评测器配置

这是变化最大的一节，需要从 Dataloader/Dataset、数据变换 pipeline、评测器三个层面分别迁移。

3.1 Dataloader 和 Dataset 配置

3.x 将数据加载设置与 PyTorch 官方DataLoader的接口对齐：训练、验证、测试的数据加载分别放在train_dataloader、val_dataloader、test_dataloader中，输入参数与 PyTorch DataLoader 基本一致。2.x 中不可配置的sampler、batch_sampler、persistent_workers等参数，现在全部开放到配置文件里。数据集配置则通过train_dataloader.dataset、val_dataloader.dataset、test_dataloader.dataset分别对应 2.x 的data.train、data.val、data.test。

2.x 原配置：

data = dict( samples_per_gpu=2, workers_per_gpu=2, train=dict( type=dataset_type, ann_file=data_root + 'annotations/instances_train2017.json', img_prefix=data_root + 'train2017/', pipeline=train_pipeline), val=dict( type=dataset_type, ann_file=data_root + 'annotations/instances_val2017.json', img_prefix=data_root + 'val2017/', pipeline=test_pipeline), test=dict( type=dataset_type, ann_file=data_root + 'annotations/instances_val2017.json', img_prefix=data_root + 'val2017/', pipeline=test_pipeline))

3.x 新配置：

train_dataloader = dict( batch_size=2, num_workers=2, persistent_workers=True, # 避免每次迭代后 dataloader 重新创建子进程 sampler=dict(type='DefaultSampler', shuffle=True), # 默认的 sampler，同时支持分布式训练和非分布式训练 batch_sampler=dict(type='AspectRatioBatchSampler'), # 默认的 batch_sampler，用于保证 batch 中的图片具有相似的长宽比，从而可以更好地利用显存 dataset=dict( type=dataset_type, data_root=data_root, ann_file='annotations/instances_train2017.json', data_prefix=dict(img='train2017/'), filter_cfg=dict(filter_empty_gt=True, min_size=32), pipeline=train_pipeline)) # 在 3.x 版本中可以独立配置验证和测试的 dataloader val_dataloader = dict( batch_size=1, num_workers=2, persistent_workers=True, drop_last=False, sampler=dict(type='DefaultSampler', shuffle=False), dataset=dict( type=dataset_type, data_root=data_root, ann_file='annotations/instances_val2017.json', data_prefix=dict(img='val2017/'), test_mode=True, pipeline=test_pipeline)) test_dataloader = val_dataloader # 测试 dataloader 的配置与验证 dataloader 的配置相同，这里省略

字段级迁移要点：

• samples_per_gpu→batch_size，workers_per_gpu→num_workers（注意 3.x 是全局 batch，不再是“每卡 batch”）；
• img_prefix→data_prefix=dict(img=...)，标注文件路径相对data_root书写；
• 2.x 隐式按test_mode区分的数据集，3.x 中在 val/test 数据集中显式声明test_mode=True；
• AspectRatioBatchSampler的实现位于 batch_sampler.py，它通过随机选取一个“主导比例”把长宽比相近的样本聚到同一 batch，配合 padding 可以减少显存浪费。

当前仓库的 coco_instance.py 完整展示了上述三个 dataloader 加评测器的落地写法，可直接作为迁移模板。

3.2 Data transform pipeline 配置

既然归一化与 padding 已移入model.data_preprocessor，3.x 的 pipeline 中就不再需要Normalize和Pad。同时，负责数据格式打包的Collect与DefaultFormatBundle两个 transform 被合并为PackDetInputs，它负责把 data pipeline 中的数据打包成模型输入格式（其实现位于 formatting.py；关于输入格式的完整转换过程，可继续阅读 数据流文档）。

以 Mask R-CNN 1x 的train_pipeline为例：

2.x 原配置：

img_norm_cfg = dict( mean=[123.675, 116.28, 103.53], std=[58.395, 57.12, 57.375], to_rgb=True) train_pipeline = [ dict(type='LoadImageFromFile'), dict(type='LoadAnnotations', with_bbox=True), dict(type='Resize', img_scale=(1333, 800), keep_ratio=True), dict(type='RandomFlip', flip_ratio=0.5), dict(type='Normalize', **img_norm_cfg), dict(type='Pad', size_divisor=32), dict(type='DefaultFormatBundle'), dict(type='Collect', keys=['img', 'gt_bboxes', 'gt_labels']), ]

3.x 新配置：

train_pipeline = [ dict(type='LoadImageFromFile'), dict(type='LoadAnnotations', with_bbox=True), dict(type='Resize', scale=(1333, 800), keep_ratio=True), dict(type='RandomFlip', prob=0.5), dict(type='PackDetInputs') ]

test_pipeline除了同样去掉Normalize与Pad外，还有一个重要变化：3.x 将测试时的数据增强（TTA）与普通测试流程分离，移除了 2.x 的MultiScaleFlipAug包装器，TTA 需要单独配置使用。

2.x 原配置：

test_pipeline = [ dict(type='LoadImageFromFile'), dict( type='MultiScaleFlipAug', img_scale=(1333, 800), flip=False, transforms=[ dict(type='Resize', keep_ratio=True), dict(type='RandomFlip'), dict(type='Normalize', **img_norm_cfg), dict(type='Pad', size_divisor=32), dict(type='ImageToTensor', keys=['img']), dict(type='Collect', keys=['img']), ]) ]

3.x 新配置：

test_pipeline = [ dict(type='LoadImageFromFile'), dict(type='Resize', scale=(1333, 800), keep_ratio=True), dict( type='PackDetInputs', meta_keys=('img_id', 'img_path', 'ori_shape', 'img_shape', 'scale_factor')) ]

注意PackDetInputs的meta_keys参数：它决定哪些元信息会进入模型的输入。上述五个 key 是 3.x 的默认值（见 formatting.py），若你自定义了数据管线并需要透传额外元信息（如视频帧序号），应在这里显式扩展。

3.3 数据增强 transform 的参数改名

部分 transform 在 3.x 中被拆分或改名，参数名同步调整。2.x → 3.x 的对应关系如下：

Resize（单尺度缩放，参数img_scale改名为scale）：

# 2.x dict(type='Resize', img_scale=(1333, 800), keep_ratio=True) # 3.x dict(type='Resize', scale=(1333, 800), keep_ratio=True)

RandomResize（多尺度范围内随机缩放，从 Resize 的 multiscale_mode='range' 拆分为独立 transform）：

# 2.x dict(type='Resize', img_scale=[(1333, 640), (1333, 800)], multiscale_mode='range', keep_ratio=True) # 3.x dict(type='RandomResize', scale=[(1333, 640), (1333, 800)], keep_ratio=True)

RandomChoiceResize（多尺度中随机选一，对应 multiscale_mode='value'）：

# 2.x dict(type='Resize', img_scale=[(1333, 640), (1333, 672), (1333, 704), (1333, 736), (1333, 768), (1333, 800)], multiscale_mode='value', keep_ratio=True) # 3.x dict(type='RandomChoiceResize', scales=[(1333, 640), (1333, 672), (1333, 704), (1333, 736), (1333, 768), (1333, 800)], keep_ratio=True)

RandomFlip（参数flip_ratio改名为prob）：

# 2.x dict(type='RandomFlip', flip_ratio=0.5) # 3.x dict(type='RandomFlip', prob=0.5)

这些 transform 均实现在 mmdet/datasets/transforms/ 目录下（transforms.py、geometric.py等），迁移后如需核对具体参数行为，可直接查阅对应实现。

3.4 评测器（Evaluator）配置

3.x 中模型精度评测不再与数据集绑定，而是通过独立的评测器完成：val_evaluator用于验证集评测，test_evaluator用于测试集评测，两者对应 2.x 的evaluation字段。常见数据集的迁移对照如下。

COCO：

# 2.x data = dict( val=dict( type='CocoDataset', ann_file=data_root + 'annotations/instances_val2017.json')) evaluation = dict(metric=['bbox', 'segm']) # 3.x val_evaluator = dict( type='CocoMetric', ann_file=data_root + 'annotations/instances_val2017.json', metric=['bbox', 'segm'], format_only=False)

Pascal VOC：

# 2.x data = dict( val=dict( type=dataset_type, ann_file=data_root + 'VOC2007/ImageSets/Main/test.txt')) evaluation = dict(metric='mAP') # 3.x val_evaluator = dict( type='VOCMetric', metric='mAP', eval_mode='11points')

OpenImages：

# 2.x data = dict( val=dict( type='OpenImagesDataset', ann_file=data_root + 'annotations/validation-annotations-bbox.csv', img_prefix=data_root + 'OpenImages/validation/', label_file=data_root + 'annotations/class-descriptions-boxable.csv', hierarchy_file=data_root + 'annotations/bbox_labels_600_hierarchy.json', meta_file=data_root + 'annotations/validation-image-metas.pkl', image_level_ann_file=data_root + 'annotations/validation-annotations-human-imagelabels-boxable.csv')) evaluation = dict(interval=1, metric='mAP') # 3.x val_evaluator = dict( type='OpenImagesMetric', iou_thrs=0.5, ioa_thrs=0.5, use_group_of=True, get_supercategory=True)

CityScapes（一个数据集挂多个评测器）：

# 2.x data = dict( val=dict( type='CityScapesDataset', ann_file=data_root + 'annotations/instancesonly_filtered_gtFine_val.json', img_prefix=data_root + 'leftImg8bit/val/', pipeline=test_pipeline)) evaluation = dict(metric=['bbox', 'segm']) # 3.x val_evaluator = [ dict( type='CocoMetric', ann_file=data_root + 'annotations/instancesonly_filtered_gtFine_val.json', metric=['bbox', 'segm']), dict( type='CityScapesMetric', ann_file=data_root + 'annotations/instancesonly_filtered_gtFine_val.json', seg_prefix=data_root + '/gtFine/val', outfile_prefix='./work_dirs/cityscapes_metric/instance') ]

CityScapes 的示例展示了 3.x 评测器的灵活性：val_evaluator可以是列表，同一份数据可同时挂CocoMetric与CityScapesMetric两套指标。所有评测器实现集中在 mmdet/evaluation/metrics/ 目录（coco_metric.py、voc_metric.py、openimages_metric.py、cityscapes_metric.py等），迁移时可按type名检索对应实现确认参数。另外注意CocoMetric的format_only=True模式：在 COCO 官方 test-dev 集上只做结果格式提交而不计算指标（官方基线配置中给出了被注释的示例，见 coco_instance.py）。

四、训练与测试循环的配置

2.x 用runner描述训练循环，验证间隔则藏在evaluation字段里；3.x 显式拆分为train_cfg、val_cfg、test_cfg三个字段：

2.x 原配置：

runner = dict( type='EpochBasedRunner', # 训练循环的类型 max_epochs=12) # 最大训练轮次 evaluation = dict(interval=2) # 验证间隔。每 2 个 epoch 验证一次

3.x 新配置：

train_cfg = dict( type='EpochBasedTrainLoop', # 训练循环的类型 max_epochs=12, # 最大训练轮次 val_interval=2) # 验证间隔。每 2 个 epoch 验证一次 val_cfg = dict(type='ValLoop') # 验证循环的类型 test_cfg = dict(type='TestLoop') # 测试循环的类型

仓库基线 schedule_1x.py 即为该写法的实例（1x 调度中val_interval=1，即每个 epoch 验证一次）。从源码结构看，循环类型（EpochBasedTrainLoop、ValLoop、TestLoop）由 MMEngine 的 Runner 统一构建，type字段决定了按 epoch 还是按 iteration 推进。

五、优化器与学习率配置

5.1 优化器：optimizer 与 optimizer_config 合并为 optim_wrapper

3.x 将优化器及梯度裁剪配置统一移入optim_wrapper字段：

2.x 原配置：

optimizer = dict( type='SGD', # 随机梯度下降优化器 lr=0.02, # 基础学习率 momentum=0.9, # 带动量的随机梯度下降 weight_decay=0.0001) # 权重衰减 optimizer_config = dict(grad_clip=None) # 梯度裁剪的配置，设置为 None 关闭梯度裁剪

3.x 新配置：

optim_wrapper = dict( # 优化器封装的配置 type='OptimWrapper', # 优化器封装的类型。可以切换至 AmpOptimWrapper 来启用混合精度训练 optimizer=dict( # 优化器配置。支持 PyTorch 的各种优化器 type='SGD', # 随机梯度下降优化器 lr=0.02, # 基础学习率 momentum=0.9, # 带动量的随机梯度下降 weight_decay=0.0001), # 权重衰减 clip_grad=None, # 梯度裁剪的配置，设置为 None 关闭梯度裁剪 )

两个实用提示：其一，type从OptimWrapper切换为AmpOptimWrapper即可启用混合精度训练（仓库中带amp的配置，如 faster-rcnn_r50_fpn_amp-1x_coco.py，都采用该方式）；其二，clip_grad的None表示关闭裁剪，配置裁剪时可传入max_norm等 MMEngine 支持的参数字典。基线 schedule_1x.py 中展示了不带裁剪参数的最简写法。

5.2 学习率：lr_config 拆分为 param_scheduler 列表

学习率配置从lr_config移至param_scheduler，改为“调度器列表”的形式，更贴近 PyTorch 的 LR 调整策略，一个策略拆成多个独立的 scheduler 按序生效：

2.x 原配置：

lr_config = dict( policy='step', # 在训练过程中使用 multi step 学习率策略 warmup='linear', # 使用线性学习率预热 warmup_iters=500, # 到第 500 个 iteration 结束预热 warmup_ratio=0.001, # 学习率预热的系数 step=[8, 11], # 在哪几个 epoch 进行学习率衰减 gamma=0.1) # 学习率衰减系数

3.x 新配置：

param_scheduler = [ dict( type='LinearLR', # 使用线性学习率预热 start_factor=0.001, # 学习率预热的系数 by_epoch=False, # 按 iteration 更新预热学习率 begin=0, # 从第一个 iteration 开始 end=500), # 到第 500 个 iteration 结束 dict( type='MultiStepLR', # 在训练过程中使用 multi step 学习率策略 by_epoch=True, # 按 epoch 更新学习率 begin=0, # 从第一个 epoch 开始 end=12, # 到第 12 个 epoch 结束 milestones=[8, 11], # 在哪几个 epoch 进行学习率衰减 gamma=0.1) # 学习率衰减系数 ]

迁移要点：warmup='linear'对应LinearLR（warmup_iters→end，warmup_ratio→start_factor，注意预热按 iteration 更新需设by_epoch=False）；policy='step'对应MultiStepLR（step列表 →milestones）。end字段应覆盖训练总轮次（本例 12），保证 MultiStepLR 在整个训练期持续生效。仓库中 schedule_1x.py 与 schedule_2x.py 等基线调度都遵循这一模式。其他更复杂的调度策略（如余弦退火、Cosine 混合调度）可按 MMEngine 的参数调度器文档逐一对应迁移。

六、其他配置的迁移

6.1 保存 checkpoint 的配置

checkpoint 相关设置从checkpoint_config、evaluation.save_best统一收敛到default_hooks.checkpoint：

注意 3.x 中save_best='auto'与interval同属CheckpointHook的参数，可以写在同一处，而不像 2.x 那样分散在两个字段。仓库 default_runtime.py 给出了默认 hook 全集：timer、logger、param_scheduler、checkpoint、sampler_seed、visualization七个 hook 一次性声明。

6.2 日志的配置

3.x 中日志打印与可视化由 MMEngine 的 logger 与 visualizer 分工完成，涉及default_hooks.logger、log_processor和vis_backends三组字段：

迁移要点：2.x 的MMDetWandbHook、TensorboardLoggerHook等“日志 hook”在 3.x 中统一抽象为vis_backends列表中的可视化后端，visualizer负责把后端挂载到可视化器上；log_processor的window_size控制日志数值的平滑窗口，仓库默认值为 50（见 default_runtime.py）。可视化相关的完整用法可参考 可视化教程。

6.3 Runtime 配置

环境相关的零散变量在 3.x 中归拢进env_cfg：

2.x 原配置：

cudnn_benchmark = False opencv_num_threads = 0 mp_start_method = 'fork' dist_params = dict(backend='nccl') log_level = 'INFO' load_from = None resume_from = None

3.x 新配置：

env_cfg = dict( cudnn_benchmark=False, mp_cfg=dict(mp_start_method='fork', opencv_num_threads=0), dist_cfg=dict(backend='nccl')) log_level = 'INFO' load_from = None resume = False

对照要点：dist_params→env_cfg.dist_cfg，mp_start_method/opencv_num_threads→env_cfg.mp_cfg；resume_from（字符串路径）简化为resume（布尔值），断点恢复路径由命令行--resume传入。default_runtime.py 中还包括default_scope = 'mmdet'与load_from字段，前者用于注册表作用域管理，迁移自定义组件时不要遗漏。

七、迁移完成后的核对清单

完成上述各节替换后，可按下述清单快速自检（每一项都能在仓库中找到参照实现）：

1. model：data_preprocessor已声明且参数正确（检测type='DetDataPreprocessor'，分割任务pad_mask=True）→ 参照 mask-rcnn_r50_fpn.py；
2. pipeline：train_pipeline/test_pipeline中已无Normalize、Pad、DefaultFormatBundle、Collect、MultiScaleFlipAug，末尾以PackDetInputs收尾；Resize使用scale、RandomFlip使用prob→ 参照 coco_instance.py；
3. dataloader：train_dataloader/val_dataloader/test_dataloader齐全，batch_size、num_workers已按 3.x 语义换算（全局而非每卡）；val/test 数据集显式test_mode=True；
4. 评测器：val_evaluator/test_evaluator已配置，type 与指标对应关系正确（COCO →CocoMetric，VOC →VOCMetric）；
5. 训练循环：train_cfg/val_cfg/test_cfg三个字段齐全，验证间隔写在train_cfg.val_interval；
6. 优化与调度：optim_wrapper（含clip_grad）与param_scheduler列表（预热 + 主策略两个 scheduler）无optimizer/lr_config残留；
7. 运行时：default_hooks、env_cfg、log_processor、vis_backends声明完整，resume_from已改为resume。

对照仓库中任意一个基线配置（推荐从 mask-rcnn_r50_fpn_1x_coco.py 及其_base_组合入手），即可确认你的迁移配置与官方写法一致。

八、适用范围与限制

• 本文基于当前仓库（MMDetection 3.x）的文档与配置实际内容整理，示例参数以 docs/zh_cn/migration/config_migration.md 与configs/_base_/目录下的基线文件为准；
• 3.x 依赖 MMEngine 的 Runner、Hook、调度器体系，循环类型、优化器封装、参数调度器等字段的具体语义以 MMEngine 版本为准；
• 文中 pipeline、dataloader 示例以 COCO 实例分割（Mask R-CNN 1x）为基准，纯检测、全景分割或跟踪任务在pad_seg、评测器类型、数据格式上会有所不同，迁移时请参照对应_base_配置调整。

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