1. 从零吃透 MMDetection为什么它值得你花时间如果你正在做目标检测相关的项目或者刚接触深度学习框架大概率会听到“MMDetection”这个名字。它不是一个新出的模型而是一个基于 PyTorch 的目标检测开源工具箱由国内一个活跃的开源算法团队维护。我第一次接触它是在一个工业质检的项目里当时需要快速对比 Faster R-CNN、YOLO 和 DETR 系列在缺陷检测上的表现。如果每个模型都单独搭一套训练和推理代码光是环境配置和数据接口对齐就能耗掉一周。MMDetection 把主流检测模型、骨干网络、数据集接口和训练流程全部统一到了一套配置体系里换模型就像换配置文件一样简单。这篇文章是“MMDetection 入门”系列的第二篇。第一篇我们聊了环境搭建和跑通第一个 Demo这一篇要解决的是从“能跑”到“能改”的跨越。具体来说我会带你拆解 MMDetection 的配置系统、注册机制、数据管道和训练流程让你能自己改模型结构、接自定义数据集、调训练策略。适合已经装好环境、跑过官方 Demo但面对一堆配置文件和模块不知道从哪下手的读者。如果你还没装好环境建议先看第一篇把基础环境跑通再回来。MMDetection 的核心价值在于“模块化”和“配置驱动”。它把目标检测拆成了骨干网络、颈部、检测头、损失函数、数据增强、训练调度等独立组件每个组件都通过注册器管理配置文件里只需要写类型和参数就能组装出一个完整的检测器。这种设计的好处是复用性极强坏处是初学者容易被层层嵌套的配置搞晕。我见过不少人在configs目录里翻了几十个文件还是没找到改学习率的地方。所以这篇的重点不是罗列 API而是帮你建立一套“看到配置文件就知道去哪改”的直觉。2. 配置文件体系深度拆解别被继承关系绕晕2.1 配置文件的基本结构长什么样MMDetection 的配置文件本质上是一个 Python 字典里面定义了模型、数据集、训练策略、运行时设置等所有信息。一个最基础的配置文件通常包含以下几个顶层字段model、dataset_type、data_root、train_dataloader、val_dataloader、test_dataloader、val_evaluator、test_evaluator、train_cfg、val_cfg、test_cfg、optim_wrapper、param_scheduler、default_hooks、custom_hooks、launcher、env_cfg、vis_backends、visualizer、work_dir、load_from、resume、randomness、experiment_name等等。看起来很多但实际项目中你经常改的也就那么几个。我拿一个典型的 Faster R-CNN 配置来举例。model字段下面有type、backbone、neck、rpn_head、roi_head、train_cfg、test_cfg。backbone里面又有type、depth、init_cfg等。这种嵌套结构的好处是清晰坏处是层级太深改一个参数要顺着路径找半天。我的经验是先记住几个关键路径改骨干网络看model.backbone改检测头看model.roi_head或model.bbox_head改数据增强看train_pipeline改学习率看optim_wrapper.optimizer.lr和param_scheduler。2.2 继承机制为什么你的配置里只有几行代码MMDetection 的配置文件支持继承这是它最实用也最容易让人困惑的设计。你打开configs/faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py可能只看到几行代码比如_base_ [../_base_/models/faster-rcnn_r50_fpn.py, ../_base_/datasets/coco_detection.py, ...]。真正的模型定义在_base_指向的基础配置文件里。这种设计的好处是避免重复比如所有 Faster R-CNN 的模型结构都放在models/faster-rcnn_r50_fpn.py里不同数据集和训练策略只需要继承这个基础配置再改数据部分。继承的规则是“后覆盖前”。如果子配置和父配置有同名字段子配置会覆盖父配置。如果字段是字典会递归合并如果是列表会直接替换。这个规则听起来简单但实际用的时候经常踩坑。比如你在子配置里写model dict(roi_headdict(bbox_headdict(num_classes10)))你以为只改了num_classes但实际上整个bbox_head会被替换成只有num_classes的字典其他参数全丢了。正确的做法是用_delete_True或者写完整的字典结构。我个人的习惯是改嵌套参数时尽量用dict()完整写出要改的那一层避免意外的覆盖。2.3 配置文件里的变量与占位符MMDetection 的配置系统支持变量引用比如data_root data/coco/然后在train_dataloader里用ann_filedata_root annotations/instances_train2017.json。这个特性在切换数据集路径时特别方便改一个地方就行。另外还有{{_base_.xxx}}这种占位符语法可以在不继承的情况下引用其他配置的值。我一般用变量来管理数据集路径和类别数因为这两个在迁移到自定义数据集时最常改。还有一个容易忽略的点是metainfo。在 MMDetection 3.x 版本里类别信息从classes字段移到了metainfo里格式是metainfodict(classes(cat, dog))。如果你从 2.x 升级上来这里不改会直接报错。我当初迁移一个旧项目时就是因为没注意这个变化训练时类别标签全乱了排查了半天才发现是metainfo没配对。3. 注册机制与模块替换想换什么就换什么3.1 注册器到底在做什么MMDetection 的模块化靠的是注册器机制。简单说每个组件骨干网络、检测头、损失函数等都有一个对应的注册器比如BACKBONES、HEADS、LOSSES。你在配置文件里写typeResNet框架就会去BACKBONES注册器里找名字叫ResNet的类来实例化。这种设计让框架可以动态组装模块也让你能方便地插入自定义组件。注册器的实现原理不复杂就是一个字典映射名字到类的映射。但它的价值在于解耦。模型代码不需要知道具体用哪个骨干网络只需要从注册器里取。你新增一个骨干网络只要用BACKBONES.register_module()装饰一下就能在配置里用type你的类名来调用。我当初给一个项目加自定义的注意力模块就是靠这个机制不用改框架源码只在自己的代码里注册一下就行。3.2 替换骨干网络的完整流程假设你想把默认的 ResNet-50 换成 ResNet-101最直接的方法是改配置里的model.backbone.depth101。但如果你想换成一个不在 MMDetection 内置列表里的骨干网络比如某个轻量级网络就需要自己注册。步骤是这样的先在你的代码里定义网络类继承BaseBackbone或torch.nn.Module实现forward方法然后用BACKBONES.register_module()装饰最后在配置里写type你的类名和对应的参数。这里有个细节要注意MMDetection 的骨干网络通常要求输出多尺度特征图因为 FPN 需要多层特征。如果你的自定义骨干只输出最后一层需要加一个适配层或者改颈部结构。我见过有人直接把分类网络拿过来当骨干结果 FPN 报错就是因为输出尺度不匹配。另外预训练权重的加载也要注意init_cfg里的checkpoint路径要指向你的权重文件否则会随机初始化训练效果差很多。3.3 替换检测头和损失函数的注意事项换检测头比换骨干简单一些因为检测头的输入输出接口更统一。比如你想把Shared2FCBBoxHead换成ConvFCBBoxHead只需要改model.roi_head.bbox_head.type。但要注意不同检测头的参数不一样比如ConvFCBBoxHead有num_shared_convs和num_shared_fcs而Shared2FCBBoxHead没有。改的时候要对照文档或源码把参数补全。损失函数也是同理。MMDetection 把分类损失、回归损失都做成了可配置的。比如你想把CrossEntropyLoss换成FocalLoss改model.roi_head.bbox_head.loss_cls就行。但 FocalLoss 有use_sigmoid、gamma、alpha等参数需要根据你的任务调。我做过一个类别极不平衡的缺陷检测项目把分类损失换成 FocalLoss 后小类别的召回率提升了将近 15 个百分点。但gamma和alpha不能乱设我试过gamma5导致训练不稳定最后用gamma2、alpha0.25才稳住。4. 数据管道与自定义数据集接入4.1 数据管道的组成与执行顺序MMDetection 的数据管道是一系列数据处理步骤的列表每个步骤是一个字典包含type和参数。典型的训练管道包括LoadImageFromFile、LoadAnnotations、Resize、RandomFlip、PackDetInputs。这些步骤按顺序执行前一步的输出是后一步的输入。理解这个顺序很重要因为有些操作有依赖关系。比如RandomFlip必须在Resize之后因为翻转后的图像尺寸会变PackDetInputs必须在最后因为它要把所有数据打包成模型需要的格式。数据管道的配置在train_pipeline、val_pipeline、test_pipeline里。训练管道通常有数据增强验证和测试管道一般只有Resize和PackDetInputs。我建议在改管道时先用小批量数据跑一遍打印每个步骤的输出形状和类型确认没问题再上全量数据。我当初加了一个自定义的RandomCrop结果因为没处理好边界框的裁剪训练时框的坐标全乱了loss 直接飙到 nan。4.2 接入自定义数据集的完整步骤接入自定义数据集是 MMDetection 入门后必须掌握的技能。步骤分三步第一把数据整理成 MMDetection 支持的格式通常是 COCO 格式或 VOC 格式第二写一个继承BaseDetDataset的数据集类实现load_data_list方法第三在配置里指定dataset_type和ann_file。COCO 格式是最省事的因为 MMDetection 内置了CocoDataset你只需要把标注文件转成 COCO 的 JSON 格式就行。转换脚本网上很多但要注意几个坑category_id必须从 1 开始不能从 0 开始bbox格式是[x, y, width, height]不是[x1, y1, x2, y2]iscrowd字段要设对否则评估时会出问题。我当初转一个数据集时因为category_id从 0 开始训练时类别全错位了排查了好久才发现。如果数据格式比较特殊比如标注是 XML 或者 CSV就需要自己写数据集类。核心是实现load_data_list返回一个列表每个元素是一个字典包含img_path、img_id、instances等信息。instances里要有bbox、bbox_label、ignore_flag等字段。写完后用DATASETS.register_module()注册然后在配置里用type你的类名。4.3 数据增强的配置与调参经验数据增强是提升检测性能的关键。MMDetection 内置了很多增强方法比如RandomFlip、Resize、RandomCrop、PhotoMetricDistortion、Expand、MinIoURandomCrop等。配置的时候要注意增强方法有prob参数控制应用概率不是所有增强都适合你的任务。比如PhotoMetricDistortion对颜色敏感的缺陷检测可能不合适因为颜色变化会改变缺陷特征。我一般会先用默认增强跑一个基线然后根据验证集表现逐步加增强。加的时候一次只加一个观察效果。比如先加RandomFlip如果 mAP 有提升就保留再加PhotoMetricDistortion如果掉了就调低prob或者去掉。另外Resize的scale参数很关键它决定了输入图像的尺寸。太小会丢小目标太大会爆显存。我通常从(1333, 800)开始试根据显存和目标大小调整。5. 训练流程与关键参数调优5.1 训练循环的组成与钩子机制MMDetection 的训练循环由Runner驱动里面注册了一系列钩子Hook在训练的不同阶段执行特定操作。常用的钩子包括IterTimerHook计时、LoggerHook日志、CheckpointHook保存权重、EvalHook验证、LrUpdaterHook学习率调整等。这些钩子在default_hooks里配置你可以改它们的参数也可以注册自定义钩子。钩子机制的好处是灵活。比如你想每 1000 次迭代保存一次权重改CheckpointHook的interval就行你想在训练前做一些初始化操作可以写一个自定义钩子实现before_run方法。我用自定义钩子做过训练过程中的可视化每 500 次迭代把验证集的预测结果画出来方便观察模型有没有跑偏。5.2 学习率与优化器的选择逻辑学习率是训练中最难调的参数之一。MMDetection 默认用 SGD学习率通常是0.028 卡或0.01单卡。如果你用 AdamW学习率要降到0.0001左右。学习率调度器param_scheduler控制学习率的变化常用的是MultiStepLR和CosineAnnealingLR。MultiStepLR在指定的 epoch 把学习率乘以gamma比如[8, 11]表示第 8 和第 11 个 epoch 各降一次。我的经验是先用默认学习率跑一个短周期比如 12 epoch看 loss 曲线。如果 loss 下降太慢学习率调大如果 loss 震荡或者 nan学习率调小。另外warmup对稳定训练很有帮助特别是用大 batch size 的时候。MMDetection 支持LinearWarmup配置在param_scheduler里通常 warmup 500 到 1000 次迭代。5.3 批次大小与显存优化的实操技巧批次大小受显存限制但也不是越大越好。大 batch 训练更稳定但可能需要调学习率小 batch 训练更快但噪声大。我一般从单卡 batch size 2 开始试如果显存够就往上加。MMDetection 支持梯度累积可以在optim_wrapper里设accumulative_counts模拟大 batch 的效果。比如你想用 batch size 8 但显存只够 2就设accumulative_counts4。显存优化还有几个技巧用fp16混合精度训练能省将近一半显存但要注意有些操作不支持 fp16可能会报错用torch.utils.checkpoint做梯度检查点用时间换显存减小输入图像尺寸这是最直接的方法。我做过一个项目输入从(1333, 800)降到(1000, 600)显存占用从 11G 降到 7GmAP 只掉了 0.5 个点性价比很高。6. 常见问题与排查技巧实录6.1 配置继承导致的参数覆盖问题这是新手最容易踩的坑。前面说过子配置的字典会递归合并但列表会直接替换。如果你在子配置里写train_pipeline [dict(typeLoadImageFromFile)]父配置里的其他管道步骤全没了。正确的做法是用_delete_True删除父配置的字段或者写完整的列表。我建议改管道时先把父配置的管道复制过来再在上面改避免遗漏。另一个坑是num_classes的继承。如果你继承了一个 COCO 配置80 类但你的数据集只有 10 类必须在子配置里改model.roi_head.bbox_head.num_classes10和model.rpn_head相关的类别数。如果只改了一处训练时可能会报维度不匹配的错误。我当初就是因为只改了bbox_head没改rpn_head训练直接崩了。6.2 数据管道报错的排查思路数据管道报错通常有几种文件路径不对、标注格式不对、图像损坏、增强操作参数不合法。排查的时候先看报错信息里的文件名和行号定位到具体的管道步骤。然后单独跑那个步骤打印输入输出。比如Resize报错可能是scale设成了(0, 0)或者图像通道数不对。我常用的排查方法是写一个小脚本手动构建数据集和管道取前几个样本跑一遍打印每个步骤的输出形状和类型。这样能快速定位是哪一步出了问题。另外PackDetInputs报错通常是前面的步骤输出的数据格式不对比如instances里缺了bbox_label字段。6.3 训练不收敛或 mAP 异常的常见原因训练不收敛的原因很多我按出现频率排个序学习率太大或太小、数据标注有问题、损失函数配置错误、预训练权重没加载、批次大小太小。排查的时候先看 loss 曲线。如果 loss 一直是 nan检查学习率和损失函数如果 loss 下降但 mAP 很低检查数据标注和评估配置如果 loss 震荡调小学习率或加大 batch size。mAP 异常低还有一个常见原因是评估时的ann_file和训练时不一致或者metainfo里的类别顺序和标注文件不一致。我遇到过一次训练时类别是(cat, dog)评估时标注文件里是(dog, cat)结果 mAP 只有 0.1改了顺序就正常了。所以每次换数据集一定要核对类别顺序。6.4 常见问题速查表问题现象可能原因排查方法解决方案训练 loss 为 nan学习率过大、损失函数参数错误检查学习率和损失配置降低学习率检查 FocalLoss 的 gammamAP 异常低类别顺序不一致、标注格式错误核对 metainfo 和标注文件统一类别顺序检查 bbox 格式显存不足batch size 过大、输入尺寸过大查看显存占用减小 batch size 或输入尺寸开 fp16数据管道报错路径错误、格式不匹配单独跑管道步骤检查路径和标注字段配置不生效继承覆盖问题打印最终配置用delete或写完整字段预训练权重没加载init_cfg 路径错误查看日志检查 checkpoint 路径7. 从入门到进阶的实操建议7.1 如何高效阅读 MMDetection 源码MMDetection 的源码结构很清晰核心代码在mmdet/models、mmdet/datasets、mmdet/engine里。读源码的时候不要从头读到尾而是带着问题读。比如你想知道ResNet是怎么实现的就去mmdet/models/backbones/resnet.py看你想知道FocalLoss怎么算的就去mmdet/models/losses/focal_loss.py看。读的时候重点关注__init__和forward方法其他辅助方法可以跳过。我建议先从配置文件入手找到对应的模块类然后去源码里看这个类的实现。这样读起来有目标不会迷失在代码海里。另外MMDetection 的文档写得不错但有些细节还是得看源码。比如某个参数的默认值文档里可能没写源码里一看就知道。7.2 自定义模块的开发与调试流程开发自定义模块的流程是先写一个最简单的版本能跑通就行然后逐步加功能每加一个功能就测试一次最后优化性能和代码质量。调试的时候用pdb或者print大法把中间变量的形状和值打出来。我习惯在forward里加断言检查输入输出的形状是否符合预期这样能早发现问题。注册自定义模块后记得在配置里引用。如果报KeyError说明注册没生效检查装饰器有没有写对或者模块有没有被导入。MMDetection 的注册是懒加载的如果你的模块文件没被导入注册器里就没有这个类。解决方法是在__init__.py里导入你的模块或者在配置里用custom_imports导入。7.3 模型部署前的检查清单训练完模型部署前要做几件事第一导出模型权重确认load_from能正确加载第二用测试集跑一遍评估确认 mAP 和训练时一致第三测试推理速度看是否满足实时性要求第四检查输入输出的格式确保和部署环境兼容。我一般会写一个推理脚本加载权重对几张测试图跑一遍可视化结果确认没问题再部署。部署时还要注意MMDetection 的模型默认输出是DetDataSample对象包含pred_instances里的bboxes、scores、labels。如果你要转成 ONNX 或者其他格式需要把后处理比如 NMS也导出或者单独实现。我做过一次 ONNX 导出因为 NMS 没导出推理结果和 PyTorch 不一致后来把 NMS 也写进了导出图里才解决。7.4 持续学习与社区资源利用MMDetection 更新挺快的新版本会加新模型和功能。建议关注官方仓库的 release notes了解新特性。另外社区里有很多实战分享和问题讨论遇到问题可以先搜一下大概率有人遇到过。我遇到过一个比较偏的 bug搜了半天没找到最后在 issue 里翻到了是版本兼容问题升级一下就解决了。学习路径上我建议先跑通官方 Demo然后改配置跑自己的数据再尝试换模型和改结构最后做自定义模块和部署。每一步都动手做一遍比只看文档强得多。我当初就是光看文档觉得懂了一上手发现全是坑还是得实操。8. 一些踩坑后的个人体会MMDetection 的学习曲线确实有点陡但一旦理解了它的配置体系和注册机制后面就顺了。我最大的体会是不要怕改配置改之前先备份改之后用print_config打印最终配置确认改对了。另外训练日志一定要仔细看loss 曲线、学习率变化、评估指标这些都能帮你判断训练是否正常。还有一个经验是遇到报错先看报错信息的最后几行通常是具体的错误原因。如果看不懂就把报错信息复制去搜或者去官方 issue 里搜。大部分问题都有人遇到过解决方案现成的。最后别急着上大模型先用小模型和小数据跑通流程确认没问题再放大。我见过不少人一上来就用大模型结果显存不够、训练太慢还没看到结果就放弃了。