MMDetection是目标检测领域绕不开的一个工具箱但很多初学者卡在第一步——环境装不上、数据格式搞不懂、配置文件看不懂。这篇教程会从零开始把MMDetection的完整使用链路拆开来讲包括环境搭建、数据准备、配置修改、训练推理和排错经验内容偏实战照着做就能跑通。1. 为什么是MMDetection入门之前先搞清楚框架边界目标检测的框架不少Detectron2、PaddleDetection、MMDetection三足鼎立。MMDetection之所以被用得最多主要有三个原因算法覆盖全、模块解耦彻底、社区活跃度高。截止目前它内置了超过两百个检测模型和训练配置从两阶段的Faster R-CNN、单阶段的YOLO系列、DETR这类Transformer系列到Mask R-CNN、Cascade R-CNN、ATSS、FCOS等基本学术界出现的经典算法都有官方实现。这意味着你做对比实验、复现论文、改造模型都不需要从零写网络结构。另一个核心优势是它的模块化设计。整个框架把模型拆成Backbone、Neck、Head、Loss等独立组件每个组件都可以单独替换和组合。比如你想把ResNet50换成Swin Transformer只需要在配置文件里改一行想把FPN换成PAFPN也是一行的事情。这种设计带来的不仅是代码复用更是实验灵活性的质变——你能在同一个代码框架里公平对比不同改进点的增益这是工程上和科研上都非常看重的能力。不过有一点需要注意不是所有任务都适合用MMDetection。如果你的目标是纯工业落地、追求极致推理速度可能更适合直接用TensorRT或OpenVINO做部署优化如果你是做非常规的检测任务比如不规则倾斜目标检测、全景分割虽然MMDetection有RotatedBox和Panoptic的扩展但生态成熟度不如其核心检测任务。所以入门之前先明确你的场景属于哪一类避免学了框架之后发现用不上。从学习曲线的角度看MMDetection的配置文件体系是最大的门槛但也是最大的财富。它的所有参数都通过config文件暴露高度规范化。这个框架适合的人群很广研究生复现论文、算法工程师做业务调优、开发者在项目中集成检测能力都能从中找到对应的用法。本篇教程按“环境—数据—配置—训练—推理—排错”这条主线展开接下来逐层深入。2. 环境搭建版本匹配比安装本身更考验耐心2.1 版本对应关系决定了你能不能一次装通MMDetection安装最核心的难点不在于执行pip install而在于版本之间的匹配。它依赖PyTorch和MMCV而MMCV又分为mmcv和mmcv-lite两个变体不同MMDetection版本对MMCV的版本号还有严格限制。我见过太多人在装环境时卡了一下午最后发现是版本不兼容。先明确当前主流使用的版本分支。以MMDetection 2.x系列为例它依赖的mmcv-full版本一般要求在1.4.0到1.7.x之间PyTorch要求在1.5到1.13之间Python版本则建议3.7到3.9更高版本有时会遇到编译问题。而MMDetection 3.x系列则做了比较大的架构调整将mmcv和mmdet的版本绑定方式改成了mmcv2.0.0并且和mmengine这个新的训练引擎绑定。这里给出一个核心原则先确定cuda和PyTorch再确定MMCV最后确定MMDetection。CUDA版本决定PyTorch版本PyTorch版本决定MMCV编译方式MMCV版本决定MMDetection版本上限。链路不能反着来反着装大概率会出问题。2.2 安装步骤从CUDA到MMDetection的完整命令第一步检查硬件驱动支持的最高CUDA版本nvidia-smi如果显示CUDA Version: 11.8说明驱动支持到11.8。然后查看本机是否已安装合适的CUDA toolkitnvcc --version我建议直接用conda创建一个干净的环境避免污染已有环境conda create -n mmdet python3.8 conda activate mmdet第二步安装PyTorch。以CUDA 11.8为例pip install torch1.13.1cu117 torchvision0.14.1cu117 --extra-index-url https://download.pytorch.org/whl/cu117为什么这里选择1.13.1而不是更新版本因为这是2.x系列MMDetection下兼容性最好的PyTorch版本之一。如果你对版本对应关系不够熟悉又不想花大量时间折腾直接用官方文档中推荐的组合即可。第三步安装MMCV。这里有一个关键选择装mmcv-full还是mmcv。2.x系列必须安装带编译优化的mmcv-fullpip install mmcv-full1.7.2 -f https://download.openmmlab.com/mmcv/dist/cu117/torch1.13/index.html注意这里的-f参数指定了预编译包的下载地址。使用预编译包可以跳过本地编译安装速度快很多。如果你的CUDA版本或PyTorch版本不在预编译包的列表里那就只能从源码编译git clone https://github.com/open-mmlab/mmcv.git cd mmcv MMCV_WITH_OPS1 pip install -e .预编译包能解决的尽量用预编译包本地编译耗时且容易出问题。编译过程中常见的报错是Killed内存不足或gcc: error编译器版本问题处理起来很麻烦。第四步安装MMDetection。推荐用源码安装的方式因为后续调试模型、修改源码都会用到git clone https://github.com/open-mmlab/mmdetection.git cd mmdetection pip install -r requirements/build.txt pip install -e .执行完后验证安装是否成功import mmdet print(mmdet.__version__)能正常输出版本号说明核心安装完成。这里我补充一个容易被忽略的细节MMDetection源码安装之后配置文件和预训练权重会自动放在mmdetection目录下的checkpoints文件夹里而不是放在site-packages里。这样做的意义是方便你直接查看源码结构和修改工具脚本但也意味着不要轻易移动mmdetection目录的位置否则权重路径会失效。2.3 常见环境报错与对应处理安装过程中最常见的三个报错我逐个说明处理方式。报错一ModuleNotFoundError: No module named mmcv。这个大概率是MMCV没装上或者装的版本不对。检查一下是mmcv还是mmcv-full2.x系列必须要后者。报错二ImportError: libGL.so.1: cannot open shared object file。这是缺少OpenGL依赖库常见于Ubuntu服务器环境apt-get update apt-get install -y libgl1-mesa-glx libglib2.0-0报错三RuntimeError: CUDA error: no kernel image is available for execution on the device。这说明PyTorch的CUDA版本和你的GPU驱动不兼容检查驱动版本降低CUDA版本重新安装。安装阶段的总体心态是不要期望一次成功而是按“驱动—CUDA—PyTorch—mmcv—mmdet”的顺序排查每一步都验证通过再走下一步。3. 数据准备从官方数据集到自己数据集的完整链路3.1 先跑通官方Demo用COCO子集练手数据准备的第一个阶段建议先不要碰自定义数据集而是跑通官方Demo。MMDetection官方提供了一些小型数据集的配置比如configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py。但COCO完整数据集有20多GB下载一次很耗时。这里有一个更轻量的方案使用COCO数据集的mini版本比如coco_data子集中的instances_train2017.json可以只保留前1000张图片。下载COCO数据集的命令mkdir -p data/coco cd data/coco wget http://images.cocodataset.org/zips/train2017.zip wget http://images.cocodataset.org/annotations/annotations_trainval2017.zip如果你只是想快速验证环境没问题也可以只下载annotations然后用一个小脚本来抽取子集。不过更推荐的方式是直接用MMDetection自带的demo脚本跑推理用一张测试图片比如在demo/demo.jpg中自带的图片验证模型可以正常加载和推理python demo/image_demo.py demo/demo.jpg configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py checkpoints/faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth --device cuda:0从网上下载训练好的权重跑通推理这步的意义是验证你的环境链路完整为后续自定义数据的每一步打基础。3.2 自定义数据集从标注工具到COCO格式的转换跑通Demo之后就要开始准备自己的数据了。MMDetection默认支持COCO格式的数据标注文件一个JSON文件同时也兼容VOC格式。但建议统一使用COCO格式因为它结构清晰且在实例分割、关键点检测等任务上都有统一的表示方式。整个自定义数据准备流程我按步骤拆解第一步数据采集与整理。把所有图片放到同一个目录下命名尽量规范。比如images/train/、images/val/、images/test/。图片数量建议训练集和验证集按9:1或8:2划分。第二步标注工具选择。常用的工具有LabelImg矩形框标注、Labelme多边形/矩形标注、X-AnyLabeling等。如果你做的是矩形框检测LabelImg足够用它可以直接导出Pascal VOC格式的XML文件。如果你做的是实例分割推荐Labelme它导出的是JSON格式的多边形坐标。第三步格式转换。LabelImg导出的VOC格式并不能直接交给MMDetection用需要转成COCO格式。MMDetection仓库里提供了一个通用的转换脚本tools/dataset_converters/目录下的脚本。但对于大多数人来说自己写转换脚本更灵活。整理COCO JSON的格式其实并不复杂核心包含5个keyimages、annotations、categories、info、licenses。其中images是一组字典每个字典包含id、file_name、width、height等字段annotations里每一个字典对应一个标注框包含id、image_id、category_id、bbox、area、iscrowd等字段categories则定义类别列表和对应的id。这里有一个非常关键的细节类别id必须从1开始而不是从0开始。虽然COCO数据集的原始类别是从1到80但人群习惯从0编号。如果直接用0作为第一个类别的id训练时会出现诡异的收敛问题。具体表现是训练loss下降正常但验证时AP特别低甚至为0。这个坑坑了我两天排查到最后发现就是类别id从0导致的问题。原因是MMDetection里有num_classes和categories的映射逻辑后台使用0作为背景类如果前景类和背景类id冲突整个训练逻辑就乱了。第四步检查数据标注的有效性。转换完之后一定要做一次数据可视化检查不要急着训练。方法有两种一是写脚本把标注框画在图片上随机抽查几十张二是使用MMDetection提供的tools/analysis_tools/browse_dataset.py脚本python tools/analysis_tools/browse_dataset.py configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py --output-dir vis_output这一步能帮你发现很多肉眼看不到的问题标注框坐标超出图像边界、宽高为负数、重复标注等。这些脏数据如果不处理训练时会严重影响效果。3.3 数据增强如何让模型在小数据集上不轻易过拟合数据准备阶段有一个很少在入门教程里被重视但实际很重要的环节数据增强策略。MMDetection在config里通过train_pipeline字段来控制。默认的train_pipeline一般包括LoadImageFromFile加载图片、LoadAnnotations加载标注、Resize缩放、RandomFlip随机翻转、Normalize归一化、DefaultFormatBundle格式打包和Collect收集。这些基础方案对标准baseline是够用的但如果你的数据量只有几百张、上千张很容易过拟合。这时候可以考虑加入更激进的数据增强RandomCrop随机裁剪挺适合遮挡严重的场景让模型学习局部特征。PhotoMetricDistortion调整亮度、对比度、饱和度、色相模拟不同光照条件。RandAugment或AutoAugment自动数据增强策略在大量实验中被证明能提升鲁棒性。Mosaic在最新的YOLOX和RTMDet配置中常见把四张图拼成一张显著提高小目标检测效果。值得提醒的是数据增强不是加得越多越好。增强强度过大会引入过多的分布偏移导致训练不稳定。我的经验是先从基础增强开始实验跑通后再逐个加增强项每加一项都对比验证集AP的变化效果变好就保留变差就回退。4. 配置文件真正决定训练逻辑的核心部分4.1 Config体系的工作方式继承与覆盖配置文件config是MMDetection的命脉但也是新手最容易一头雾水的地方。一个模型的完整训练配置往往由多个文件拼接而成通过继承关系来复用公共设置。这和面向对象编程里的继承非常相似——子类配置文件通过_base_字段来引用基础配置然后按需覆盖特定字段。拿经典的configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py为例它的_base_包含三个部分_base_ [ ../_base_/models/faster_rcnn_r50_fpn.py, ../_base_/datasets/coco_detection.py, ../_base_/schedules/schedule_1x.py, ../_base_/default_runtime.py ]这四个文件分别定义了模型结构、数据集配置、训练调度、运行环境。当你新建一个自己的config文件时只需要继承这些基础配置然后覆盖需要修改的字段比如num_classes、data_root、batch_size等。理解这个继承机制非常重要。很多同学在修改配置文件时直接在完整的config基础上改改完发现训练跑出来的还是原来的行为原因就是没有正确覆盖基类中的字段或者改错了层级。建议先运行python tools/analysis_tools/get_flops.py configs/xxx.py这样能看到模型最终聚合后的完整配置。4.2 关键字段逐项解析model、dataset、schedule一个配置文件的核心逻辑分为三个部分模型怎么搭、数据怎么喂、怎么训练。Model部分要看三个子字段type决定检测器类型Faster R-CNN还是RetinaNet等backbone决定主干网络ResNet、Swin等neck决定特征融合方式FPN等rpn_head和roi_head分别对应两阶段检测器中的区域提议网络和感兴趣区域分类回归网络。以num_classes为例假设你有3个类别加上背景是4个需要分别修改rpn_head和roi_head下的num_classes。为了便于后续维护建议在config文件的头部定义num_classes 3然后在整个config中引用这个变量。这样做的好处是后续调整类别数时只用改一处不需要全局查找替换。Dataset部分核心参数包括data_root数据根目录、ann_file标注文件路径、img_prefix图片路径、pipeline数据增强流程、samples_per_gpu和workers_per_gpu。这部分最容易出的问题就是路径错误。MMDetection在拼接路径时使用的规则是img_prefix train2017/这种形式如果你把图片放在data/coco/train2017/下配置里img_prefix写成了data/coco/那实际就会找data/coco/train2017/train2017/这肯定报错。Schedule部分optimizer设定优化器和初始学习率lr_config设定学习率调整策略runner设定最大训练轮次。以Faster R-CNN的标准配置为例optimizer dict(typeSGD, lr0.02, momentum0.9, weight_decay0.0001) lr_config dict( policystep, warmuplinear, warmup_iters500, warmup_ratio0.001, step[8, 11] ) runner dict(typeEpochBasedRunner, max_epochs12)这里的lr0.02对应的是batch_size168卡x2的情况。如果你的batch_size不是16学习率应该按比例缩放。推荐线性缩放规则lr_new lr_base * (batch_size_new / batch_size_base)。假设你只用单卡且batch_size2理想的学习率大约是0.02 * 2 / 16 0.0025。如果不调整学习率容易出现训练震荡或者收敛缓慢的问题。4.3 从零搭建一个新Detector的config实践示例假设你要用Mask R-CNN在自定义数据集上训练一个3类实例分割模型一个基础的config文件长这样_base_ [ ../_base_/models/mask_rcnn_r50_fpn.py, ../_base_/datasets/coco_instance.py, ../_base_/schedules/schedule_1x.py, ../_base_/default_runtime.py ] num_classes 3 model dict( roi_headdict( bbox_headdict(num_classesnum_classes), mask_headdict(num_classesnum_classes) ) ) dataset_type CocoDataset data_root data/custom/ data dict( samples_per_gpu2, workers_per_gpu2, traindict( typedataset_type, ann_fileannotations/instances_train.json, img_prefiximages/train/, classes(cat, dog, bird) ), valdict( typedataset_type, ann_fileannotations/instances_val.json, img_prefiximages/val/, classes(cat, dog, bird) ) ) optimizer dict(lr0.0025)这个配置文件体现了几个关键点第一model部分通过仅覆盖roi_head中需要修改的字段保持了基类中backbone和neck的默认设置第二dataset部分指定了自定义数据集的路径同时通过classes字段告诉数据加载器类别名称和顺序第三optimizer的学习率按batch_size做了线性缩放。有一点要特别留意classes的传入顺序必须与标注JSON中categories的顺序一致。MMDetection在构建类别映射时用的是列表的顺序来给类别编号顺序不对会导致训练出来的模型类别对应错乱。比如你把(cat, dog, bird)写成了(dog, cat, bird)训练器的loss依然会收敛但推理时把猫识别成狗看起来模型完全没法用。排查这个问题的方式是查看类别名称和概率输出不要只看AP指标。5. 训练、评估与可视化从命令行到结果解读5.1 模型训练单卡与多卡的正确打开方式训练之前先把预训练权重准备好。MMDetection在checkpoints目录下通常需要预训练好的backbone权重这对于提高收敛速度和最终精度都很有帮助尤其是在自定义数据集较小的情况下。官方provides下载脚本或直接通过curl下载mkdir -p checkpoints wget -c https://download.openmmlab.com/mmdetection/v2.0/faster_rcnn/faster_rcnn_r50_fpn_1x_coco/faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth -P checkpoints/训练的命令统一走tools/train.py脚本。单卡训练python tools/train.py configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py --work-dir work_dirs/faster_rcnn_r50_fpn_1x_coco --auto-scale-lr多卡训练使用torch.distributed.launch对应旧版本PyTorch或torchrun对应新版bash tools/dist_train.sh configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py 8 --work-dir work_dirs/xxx这里的8表示使用8张GPU。有一个细微但重要的差别--work-dir参数指定了训练日志和权重文件的保存位置。如果你不指定默认会生成在工作目录下以时间戳命名的文件夹。我建议每次实验都显式指定并统一命名为work_dirs/实验名称_日期方便后续对比。训练过程中要重点观察日志中的loss值变化。刚开始的几百个iterloss下降非常快从几下降到1左右之后逐渐变缓这是正常现象。如果loss在整个训练过程中都在0级别附近徘徊可能是学习率过大如果loss下降过慢、波动过大可能是学习率过小或数据有问题。5.2 看曲线、读日志训练过程怎么判断是否健康训练时不要只是傻等要懂得实时监控训练状态。MMDetection在work_dirs下会生成一个时间戳.log.json文件这是训练过程中的全部日志记录。你可以用脚本解析import json import matplotlib.pyplot as plt logs [] with open(work_dirs/xxx.log.json, r) as f: for line in f: logs.append(json.loads(line)) loss_values [x[loss] for x in logs if loss in x] epochs [x[epoch] for x in logs if loss in x] plt.plot(epochs, loss_values) plt.xlabel(Epoch) plt.ylabel(Loss) plt.savefig(loss_curve.png)如果不想自己写MMDetection也提供了可视化工具python tools/analysis_tools/analyze_logs.py plot_curve work_dirs/xxx.log.json --keys loss --out loss_curve.png观察曲线时有几个判断标准训练loss和验证损失差距过大比如训练loss在0.2以下验证loss在1以上说明过拟合考虑增加数据增强或正则化训练loss和验证损失都在高位下不去说明欠拟合考虑增大模型容量或增加训练轮数曲线剧烈震荡考虑降低学习率或增大batch_size。5.3 测试与可视化推理用训练好的模型跑自己的图片训练完成后首先要做定量评估。测试命令python tools/test.py configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py work_dirs/xxx/latest.pth --eval bbox如果是实例分割任务改为--eval bbox segm。评估结果会输出mAP、AR等指标。重点关注mAP0.5和mAP0.5:0.95这两个指标前者是通用的宽松指标后者更严格也更接近实际应用中的检测质量感受。接下来做定性可视化。用训练好的模型推理一张图片from mmdet.apis import init_detector, inference_detector import mmcv config_file configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py checkpoint_file work_dirs/xxx/latest.pth model init_detector(config_file, checkpoint_file, devicecuda:0) result inference_detector(model, test.jpg) model.show_result(test.jpg, result, out_fileresult.jpg)对于目标检测任务show_result会在图片上画出预测框和类别分数。这里有一个容易被忽略的点对不同尺度的图片显示的框大小可能让你误判模型效果。如果要更仔细地评估模型在特定图像上的表现可以用model.show_result加上score_thr0.3这类阈值参数来调节置信度阈值。6. 自定义模型和模块的修改思路6.1 在配置文件里调整模型结构加一个注意力模块很多人在跑通默认的Faster R-CNN之后就开始尝试改进模型。最基础的需求是在backbone后面加一个注意力模块。这里我不能直接放完整的自定义代码但可以说清楚思路使用MMDetection的注册器机制。以一个假设场景为例你想在ResNet50的layer4之后插入一个坐标注意力模块CoordAttention。做法是在mmdet/models/backbones下编写一个新模块通过BACKBONES.register_module()注册。然后在配置文件中指定model dict( backbonedict( typeMyResNet50, ... ) )注册器是MMDetection和MMEngine的精华机制它维护一个“字符串类型名到模块类”的映射。配置文件里填写typeMyResNet50时注册器会根据字符串去找对应的类。只要你正确导入了自定义模块注册器就能识别。这个机制意味着你不需要修改框架核心代码就能随时插入自己的模块。从这里可以延伸出一个重要的学习方法学会阅读已注册的模块源码比会改配置文件更重要。以FasterRCNN类为例它的前向传播逻辑、rpn_head和roi_head的交互方式都在源码里有清晰的注释。6.2 损失函数修改和后处理参数调整除模型结构外训练中还经常要调整损失函数。MMDetection把损失函数抽象成了loss_cls、loss_bbox、loss_mask等字段。如果你想给分类损失加一个focal loss的变体只需修改roi_head中的配置model dict( roi_headdict( bbox_headdict( loss_clsdict(typeFocalLoss, use_sigmoidTrue, gamma2.0, alpha0.25), loss_bboxdict(typeL1Loss, loss_weight1.0) ) ) )改动配置就能改变训练目标这是MMDetection框架对科研和调参极大友好的地方。同时test_cfg和train_cfg中还有很多后处理参数比如nms_iou_thrNMS的IoU阈值、score_thr得分阈值、max_per_img每张图最大输出框数。这些参数直接影响最终检测结果的召回率和精确度实际调优时非常有用。6.3 深度学习项目的目录组织方式当自定义代码量变大后建议不要直接修改mmdetection仓库源码而是建立自己的项目目录my_project/ ├── configs/ │ └── my_faster_rcnn_r50_fpn.py ├── mmdet_custom/ │ ├── models/ │ │ ├── backbones/ │ │ ├── necks/ │ │ └── dense_heads/ │ └── datasets/ └── tools/然后在自定义模块的__init__.py中显式导入模块这样才能保证注册器能识别到你的类。7. 常见训练问题和排错经验这一节对新手来说价值最高因为你在训练中遇到问题可能在官方文档里找不到直接答案但大概率在这个列表里。7.1 数据加载相关Dataset not found、图像格式错误报错信息FileNotFoundError: data/coco/annotations/instances_train2017.json does not exist。这通常是路径配置错误。检查conf文件中的data_root和ann_file是否拼写正确以及文件是否真的在这个目录下。报错信息AttributeError: NoneType object has no attribute shape。这通常是某张图片加载失败。常见原因包括图片损坏、扩展名大小写不一致比如.JPG和.jpg混淆、图片是RGBA四通道但未做转换。排查方法是检查数据的完整性脚本遍历图片目录并逐一尝试用OpenCV读取import cv2 import glob import os img_files glob.glob(data/custom/images/train/*.jpg) for img_file in img_files: img cv2.imread(img_file) if img is None: print(fBroken image: {img_file})7.2 显存溢出如何用梯度累积减小显存压力新手最常见的问题就是CUDA out of memory。显存不够通常的解决方案是降低batch_size但这样会影响模型收敛效果尤其是BN层的统计量会变得不稳定。更稳妥的方案是使用梯度累积gradient accumulation等效于增大batch_size但不增加显存消耗。MMDetection原生支持梯度累积。配置文件中有两个参数optimizer_config里的grad_clip和accumulative_counts。后者在MMDetection 2.x的某些版本中可能不直接暴露但可以通过自定义hook或直接修改训练脚本实现。如果不想改动代码最简单的方案是在runner配置里添加梯度累积相关的字段。在自定义数据集很小的情况下我还会建议直接调整图像缩放尺寸来减小显存压力比如从默认的(1333, 800)改成(800, 600)。这样虽然损失了一些精度但显存占用显著降低跑通流程没有问题后续再逐步增加分辨率。7.3 训练精度始终很低先检查数据还是先调参模型训练完发现mAP很低这是最让人困惑的情况。按我的经验优先级应该是先检查数据再检查配置最后再调参。数据检查要确认几个方面类别id是否从1开始标注框是否和图片中的物体对得上训练集和验证集的图片是否存在信息泄漏比如同一物体的不同裁剪同时出现在训练集和验证集是否存在大量的背景框即标注框占据了图片的大部分面积。配置检查要确认类别数量是否和数据集一致学习率是否随batch_size调整过预训练权重是否成功加载。MMDetection训练时会在日志里输出load checkpoint from ...你可以检查权重加载信息中是否出现了unexpected key或者missing key的警告。调参这个环节排在最后是因为没有前两者的保证调参有效果也是偶然的不具可解释性。8. 从入门到实战一个完整的项目案例复盘以我最近做一个安全帽佩戴检测项目为例完整梳理整个流程。这个项目的目标是在监控视频画面上检测工人是否佩戴安全帽类别只有两个helmet和head。数据集有大约2000张图片标注工作用了LabelImg导出VOC格式后自己写了转换脚本变成COCO格式。训练集1500张验证集500张。类别id从1开始1是helmet2是head。配置文件选择了faster_rcnn_r50_fpn_1x_coco.py作为基础修改了num_classes2data_root指向项目数据目录学习率从0.02调整到0.005batch_size从16降到4。训练了12个epoch验证集mAP0.5大概在91.2%。在这个项目里遇到的比较有意思的问题是硬帽子和头的遮挡关系。因为安全帽戴在头上很多标注框是重叠的。一开始模型在预测时总会出现帽子框和头框同时输出的情况业务上要求如果帽子框存在并覆盖头部就不应该再输出头框。最后通过在test_cfg中设置合适nms_iou_thr以及一套业务层面的过滤逻辑解决了这个问题。这个项目给我的体会是算法精度只是其中一环真正的业务难点往往在数据定义和后处理逻辑上。目标检测框架能帮你解决“在图片中找到物体并分类”的问题但如何定义“找到”和“分类”的规则这就是工程问题了。9. 后续学习路径建议跑通MMDetection的完整流程只是入门的开始。从这里继续深入推荐按以下三个方向进阶第一方向熟悉框架内部机制。读configs/_base_/models下的核心模型代码理解FasterRCNN的前向逻辑尝试实现一个简单的自定义head。这个阶段的目标是摆脱“只会改config”的层次能够修改模型结构。第二方向追踪新模型。MMDetection官方支持RTMDet、DINO、Mask2Former等新模型。阅读这些模型的论文和对应代码理解它们相对于baseline的改进点在哪里。在配置文件中切换到这些模型对比它们在你自己的数据集上的表现。这个习惯能让你保持对目标检测技术前沿的跟进。第三方向工程化能力。模型训练完成后部署是很多实际项目绕不开的环节。学习如何使用MMDeploy将MMDetection模型转换为ONNX或TensorRT格式并完成服务化部署。同时可以尝试MMDetection的增量训练功能在已有模型的基础上继续训练适应新的数据分布这在真实业务中非常常见。以上就是MMDetection入门到实战比较完整的经验了。工具本身在快速迭代但这些工作流和排错思路是通用的希望能帮你减少踩坑时间。