MMDetection 配置文件从 2.x 迁移到 3.xDataPreprocessor、Dataloader 与评测器改造实战指南【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetectionMMDetection 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 配置说明img_norm_cfg pipeline 中的Normalizemodel.data_preprocessor归一化等预处理移入模型pipeline 中的Padmodel.data_preprocessor.pad_size_divisorpadding 移入模型pipeline中的DefaultFormatBundleCollectpipeline 末尾的PackDetInputs数据打包 transform 合并data.samples_per_gpu/workers_per_gpu*_dataloader.batch_size/num_workers与 PyTorch DataLoader 对齐data.train/val/testtrain_dataloader.dataset等三个 dataloader 独立配置evaluation字段val_evaluator/test_evaluator评测器与数据集解耦runnerevaluation(interval...)train_cfg/val_cfg/test_cfg训练循环显式配置optimizeroptimizer_configoptim_wrapper优化器封装 梯度裁剪lr_configparam_scheduler更贴近 PyTorch 的 LR 策略checkpoint_configdefault_hooks.checkpointcheckpoint 管理移入 Hooklog_configdefault_hooks.loggerlog_processorvis_backends日志与可视化分离dist_params/cudnn_benchmark等env_cfg运行环境配置归拢以下各节将逐一展开每节都给出 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_rgbTrue) pipeline[ ..., dict(typeNormalize, **img_norm_cfg), dict(typePad, size_divisor32), # 图像 padding 到 32 的倍数 ... ]3.x 新配置model dict( data_preprocessordict( typeDetDataPreprocessor, # 图像归一化参数 mean[123.675, 116.28, 103.53], std[58.395, 57.12, 57.375], bgr_to_rgbTrue, # 图像 padding 参数 pad_maskTrue, # 在实例分割中需要将 mask 也进行 padding pad_size_divisor32) # 图像 padding 到 32 的倍数 )源码视角DetDataPreprocessor 还做了什么从 data_preprocessor.py 的实现可以看到DetDataPreprocessor继承自 MMEngine 的ImgDataPreprocessor在标准能力collate 并搬运数据、按pad_valuepadding、stack 成 batch、bgr_to_rgb转换、按mean/std归一化之外还针对检测任务做了两处扩展支持 batch 级数据增强batch_augments参数按nn.ModuleList构建额外向 data sample 中追加batch_input_shape和pad_shape元信息供后续 NMS、结果解码等环节使用。此外它还有几个检测场景常用、但官方迁移对照中未全部列出的参数pad_value默认 0图像 padding 填充值、mask_pad_valuemask 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_maskTrue否则 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_gpu2, workers_per_gpu2, traindict( typedataset_type, ann_filedata_root annotations/instances_train2017.json, img_prefixdata_root train2017/, pipelinetrain_pipeline), valdict( typedataset_type, ann_filedata_root annotations/instances_val2017.json, img_prefixdata_root val2017/, pipelinetest_pipeline), testdict( typedataset_type, ann_filedata_root annotations/instances_val2017.json, img_prefixdata_root val2017/, pipelinetest_pipeline))3.x 新配置train_dataloader dict( batch_size2, num_workers2, persistent_workersTrue, # 避免每次迭代后 dataloader 重新创建子进程 samplerdict(typeDefaultSampler, shuffleTrue), # 默认的 sampler同时支持分布式训练和非分布式训练 batch_samplerdict(typeAspectRatioBatchSampler), # 默认的 batch_sampler用于保证 batch 中的图片具有相似的长宽比从而可以更好地利用显存 datasetdict( typedataset_type, data_rootdata_root, ann_fileannotations/instances_train2017.json, data_prefixdict(imgtrain2017/), filter_cfgdict(filter_empty_gtTrue, min_size32), pipelinetrain_pipeline)) # 在 3.x 版本中可以独立配置验证和测试的 dataloader val_dataloader dict( batch_size1, num_workers2, persistent_workersTrue, drop_lastFalse, samplerdict(typeDefaultSampler, shuffleFalse), datasetdict( typedataset_type, data_rootdata_root, ann_fileannotations/instances_val2017.json, data_prefixdict(imgval2017/), test_modeTrue, pipelinetest_pipeline)) test_dataloader val_dataloader # 测试 dataloader 的配置与验证 dataloader 的配置相同这里省略字段级迁移要点samples_per_gpu→batch_sizeworkers_per_gpu→num_workers注意 3.x 是全局 batch不再是“每卡 batch”img_prefix→data_prefixdict(img...)标注文件路径相对data_root书写2.x 隐式按test_mode区分的数据集3.x 中在 val/test 数据集中显式声明test_modeTrueAspectRatioBatchSampler的实现位于 batch_sampler.py它通过随机选取一个“主导比例”把长宽比相近的样本聚到同一 batch配合 padding 可以减少显存浪费。当前仓库的 coco_instance.py 完整展示了上述三个 dataloader 加评测器的落地写法可直接作为迁移模板。3.2 Data transform pipeline 配置既然归一化与 padding 已移入model.data_preprocessor3.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_rgbTrue) train_pipeline [ dict(typeLoadImageFromFile), dict(typeLoadAnnotations, with_bboxTrue), dict(typeResize, img_scale(1333, 800), keep_ratioTrue), dict(typeRandomFlip, flip_ratio0.5), dict(typeNormalize, **img_norm_cfg), dict(typePad, size_divisor32), dict(typeDefaultFormatBundle), dict(typeCollect, keys[img, gt_bboxes, gt_labels]), ]3.x 新配置train_pipeline [ dict(typeLoadImageFromFile), dict(typeLoadAnnotations, with_bboxTrue), dict(typeResize, scale(1333, 800), keep_ratioTrue), dict(typeRandomFlip, prob0.5), dict(typePackDetInputs) ]test_pipeline除了同样去掉Normalize与Pad外还有一个重要变化3.x 将测试时的数据增强TTA与普通测试流程分离移除了 2.x 的MultiScaleFlipAug包装器TTA 需要单独配置使用。2.x 原配置test_pipeline [ dict(typeLoadImageFromFile), dict( typeMultiScaleFlipAug, img_scale(1333, 800), flipFalse, transforms[ dict(typeResize, keep_ratioTrue), dict(typeRandomFlip), dict(typeNormalize, **img_norm_cfg), dict(typePad, size_divisor32), dict(typeImageToTensor, keys[img]), dict(typeCollect, keys[img]), ]) ]3.x 新配置test_pipeline [ dict(typeLoadImageFromFile), dict(typeResize, scale(1333, 800), keep_ratioTrue), dict( typePackDetInputs, 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(typeResize, img_scale(1333, 800), keep_ratioTrue) # 3.x dict(typeResize, scale(1333, 800), keep_ratioTrue)RandomResize多尺度范围内随机缩放从 Resize 的 multiscale_moderange 拆分为独立 transform# 2.x dict(typeResize, img_scale[(1333, 640), (1333, 800)], multiscale_moderange, keep_ratioTrue) # 3.x dict(typeRandomResize, scale[(1333, 640), (1333, 800)], keep_ratioTrue)RandomChoiceResize多尺度中随机选一对应 multiscale_modevalue# 2.x dict(typeResize, img_scale[(1333, 640), (1333, 672), (1333, 704), (1333, 736), (1333, 768), (1333, 800)], multiscale_modevalue, keep_ratioTrue) # 3.x dict(typeRandomChoiceResize, scales[(1333, 640), (1333, 672), (1333, 704), (1333, 736), (1333, 768), (1333, 800)], keep_ratioTrue)RandomFlip参数flip_ratio改名为prob# 2.x dict(typeRandomFlip, flip_ratio0.5) # 3.x dict(typeRandomFlip, prob0.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( valdict( typeCocoDataset, ann_filedata_root annotations/instances_val2017.json)) evaluation dict(metric[bbox, segm]) # 3.x val_evaluator dict( typeCocoMetric, ann_filedata_root annotations/instances_val2017.json, metric[bbox, segm], format_onlyFalse)Pascal VOC# 2.x data dict( valdict( typedataset_type, ann_filedata_root VOC2007/ImageSets/Main/test.txt)) evaluation dict(metricmAP) # 3.x val_evaluator dict( typeVOCMetric, metricmAP, eval_mode11points)OpenImages# 2.x data dict( valdict( typeOpenImagesDataset, ann_filedata_root annotations/validation-annotations-bbox.csv, img_prefixdata_root OpenImages/validation/, label_filedata_root annotations/class-descriptions-boxable.csv, hierarchy_filedata_root annotations/bbox_labels_600_hierarchy.json, meta_filedata_root annotations/validation-image-metas.pkl, image_level_ann_filedata_root annotations/validation-annotations-human-imagelabels-boxable.csv)) evaluation dict(interval1, metricmAP) # 3.x val_evaluator dict( typeOpenImagesMetric, iou_thrs0.5, ioa_thrs0.5, use_group_ofTrue, get_supercategoryTrue)CityScapes一个数据集挂多个评测器# 2.x data dict( valdict( typeCityScapesDataset, ann_filedata_root annotations/instancesonly_filtered_gtFine_val.json, img_prefixdata_root leftImg8bit/val/, pipelinetest_pipeline)) evaluation dict(metric[bbox, segm]) # 3.x val_evaluator [ dict( typeCocoMetric, ann_filedata_root annotations/instancesonly_filtered_gtFine_val.json, metric[bbox, segm]), dict( typeCityScapesMetric, ann_filedata_root annotations/instancesonly_filtered_gtFine_val.json, seg_prefixdata_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_onlyTrue模式在 COCO 官方 test-dev 集上只做结果格式提交而不计算指标官方基线配置中给出了被注释的示例见 coco_instance.py。四、训练与测试循环的配置2.x 用runner描述训练循环验证间隔则藏在evaluation字段里3.x 显式拆分为train_cfg、val_cfg、test_cfg三个字段2.x 原配置runner dict( typeEpochBasedRunner, # 训练循环的类型 max_epochs12) # 最大训练轮次 evaluation dict(interval2) # 验证间隔。每 2 个 epoch 验证一次3.x 新配置train_cfg dict( typeEpochBasedTrainLoop, # 训练循环的类型 max_epochs12, # 最大训练轮次 val_interval2) # 验证间隔。每 2 个 epoch 验证一次 val_cfg dict(typeValLoop) # 验证循环的类型 test_cfg dict(typeTestLoop) # 测试循环的类型仓库基线 schedule_1x.py 即为该写法的实例1x 调度中val_interval1即每个 epoch 验证一次。从源码结构看循环类型EpochBasedTrainLoop、ValLoop、TestLoop由 MMEngine 的 Runner 统一构建type字段决定了按 epoch 还是按 iteration 推进。五、优化器与学习率配置5.1 优化器optimizer 与 optimizer_config 合并为 optim_wrapper3.x 将优化器及梯度裁剪配置统一移入optim_wrapper字段2.x 原配置optimizer dict( typeSGD, # 随机梯度下降优化器 lr0.02, # 基础学习率 momentum0.9, # 带动量的随机梯度下降 weight_decay0.0001) # 权重衰减 optimizer_config dict(grad_clipNone) # 梯度裁剪的配置设置为 None 关闭梯度裁剪3.x 新配置optim_wrapper dict( # 优化器封装的配置 typeOptimWrapper, # 优化器封装的类型。可以切换至 AmpOptimWrapper 来启用混合精度训练 optimizerdict( # 优化器配置。支持 PyTorch 的各种优化器 typeSGD, # 随机梯度下降优化器 lr0.02, # 基础学习率 momentum0.9, # 带动量的随机梯度下降 weight_decay0.0001), # 权重衰减 clip_gradNone, # 梯度裁剪的配置设置为 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( policystep, # 在训练过程中使用 multi step 学习率策略 warmuplinear, # 使用线性学习率预热 warmup_iters500, # 到第 500 个 iteration 结束预热 warmup_ratio0.001, # 学习率预热的系数 step[8, 11], # 在哪几个 epoch 进行学习率衰减 gamma0.1) # 学习率衰减系数3.x 新配置param_scheduler [ dict( typeLinearLR, # 使用线性学习率预热 start_factor0.001, # 学习率预热的系数 by_epochFalse, # 按 iteration 更新预热学习率 begin0, # 从第一个 iteration 开始 end500), # 到第 500 个 iteration 结束 dict( typeMultiStepLR, # 在训练过程中使用 multi step 学习率策略 by_epochTrue, # 按 epoch 更新学习率 begin0, # 从第一个 epoch 开始 end12, # 到第 12 个 epoch 结束 milestones[8, 11], # 在哪几个 epoch 进行学习率衰减 gamma0.1) # 学习率衰减系数 ]迁移要点warmuplinear对应LinearLRwarmup_iters→endwarmup_ratio→start_factor注意预热按 iteration 更新需设by_epochFalsepolicystep对应MultiStepLRstep列表 →milestones。end字段应覆盖训练总轮次本例 12保证 MultiStepLR 在整个训练期持续生效。仓库中 schedule_1x.py 与 schedule_2x.py 等基线调度都遵循这一模式。其他更复杂的调度策略如余弦退火、Cosine 混合调度可按 MMEngine 的参数调度器文档逐一对应迁移。六、其他配置的迁移6.1 保存 checkpoint 的配置checkpoint 相关设置从checkpoint_config、evaluation.save_best统一收敛到default_hooks.checkpoint功能2.x 原配置3.x 新配置设置保存间隔checkpoint_config dict(interval1)default_hooks dict(checkpointdict(typeCheckpointHook, interval1))保存最佳模型evaluation dict(save_bestauto)default_hooks dict(checkpointdict(typeCheckpointHook, save_bestauto))只保留最新几个模型checkpoint_config dict(max_keep_ckpts3)default_hooks dict(checkpointdict(typeCheckpointHook, max_keep_ckpts3))注意 3.x 中save_bestauto与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 原配置3.x 新配置设置日志打印间隔log_config dict(interval50)default_hooks dict(loggerdict(typeLoggerHook, interval50))可选log_processor dict(typeLogProcessor, window_size50)配置数值平滑窗口TensorBoard / WandB 可视化log_config dict(interval50, hooks[dict(typeTextLoggerHook), dict(typeTensorboardLoggerHook), dict(typeMMDetWandbHook, init_kwargs{project: mmdetection, group: maskrcnn-r50-fpn-1x-coco}, interval50, log_checkpointTrue, log_checkpoint_metadataTrue, num_eval_images100)])vis_backends [dict(typeLocalVisBackend), dict(typeTensorboardVisBackend), dict(typeWandbVisBackend, init_kwargs{project: mmdetection, group: maskrcnn-r50-r50-fpn-1x-coco})]配合visualizer dict(typeDetLocalVisualizer, vis_backendsvis_backends, namevisualizer)迁移要点2.x 的MMDetWandbHook、TensorboardLoggerHook等“日志 hook”在 3.x 中统一抽象为vis_backends列表中的可视化后端visualizer负责把后端挂载到可视化器上log_processor的window_size控制日志数值的平滑窗口仓库默认值为 50见 default_runtime.py。可视化相关的完整用法可参考 可视化教程。6.3 Runtime 配置环境相关的零散变量在 3.x 中归拢进env_cfg2.x 原配置cudnn_benchmark False opencv_num_threads 0 mp_start_method fork dist_params dict(backendnccl) log_level INFO load_from None resume_from None3.x 新配置env_cfg dict( cudnn_benchmarkFalse, mp_cfgdict(mp_start_methodfork, opencv_num_threads0), dist_cfgdict(backendnccl)) log_level INFO load_from None resume False对照要点dist_params→env_cfg.dist_cfgmp_start_method/opencv_num_threads→env_cfg.mp_cfgresume_from字符串路径简化为resume布尔值断点恢复路径由命令行--resume传入。default_runtime.py 中还包括default_scope mmdet与load_from字段前者用于注册表作用域管理迁移自定义组件时不要遗漏。七、迁移完成后的核对清单完成上述各节替换后可按下述清单快速自检每一项都能在仓库中找到参照实现modeldata_preprocessor已声明且参数正确检测typeDetDataPreprocessor分割任务pad_maskTrue→ 参照 mask-rcnn_r50_fpn.pypipelinetrain_pipeline/test_pipeline中已无Normalize、Pad、DefaultFormatBundle、Collect、MultiScaleFlipAug末尾以PackDetInputs收尾Resize使用scale、RandomFlip使用prob→ 参照 coco_instance.pydataloadertrain_dataloader/val_dataloader/test_dataloader齐全batch_size、num_workers已按 3.x 语义换算全局而非每卡val/test 数据集显式test_modeTrue评测器val_evaluator/test_evaluator已配置type 与指标对应关系正确COCO →CocoMetricVOC →VOCMetric训练循环train_cfg/val_cfg/test_cfg三个字段齐全验证间隔写在train_cfg.val_interval优化与调度optim_wrapper含clip_grad与param_scheduler列表预热 主策略两个 scheduler无optimizer/lr_config残留运行时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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考