mmdetection 实战：基于Mask R-CNN与自定义COCO数据集的目标检测全流程解析

1. 环境准备与框架搭建第一次接触mmdetection时我被它繁杂的依赖项折腾得够呛。这里分享一个已验证可用的环境配置方案建议使用Python 3.8和PyTorch 1.9的组合这个版本区间对CUDA的支持最稳定。我的实际测试环境是Ubuntu 20.04 RTX 3090以下是具体步骤conda create -n mmdet python3.8 -y conda activate mmdet pip install torch1.9.0cu111 torchvision0.10.0cu111 -f https://download.pytorch.org/whl/torch_stable.html安装mmcv-full时要特别注意版本匹配问题。有次我直接pip install mmcv-full导致训练时出现诡异的张量维度错误后来发现必须指定与mmdetection兼容的版本pip install mmcv-full1.4.0 -f https://download.openmmlab.com/mmcv/dist/cu111/torch1.9.0/index.html克隆mmdetection仓库后别急着安装。先修改requirements/build.txt把里面的pycocotools替换为pycocotools-windowsWindows用户或直接注释掉Linux用户可通过apt-get install python3-dev解决依赖。这个细节让我当初浪费了两小时排查导入错误。验证安装是否成功时不要只看官方文档里的简单测试。我建议运行以下完整检查脚本from mmdet.apis import init_detector config configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py model init_detector(config, devicecuda:0) print(model.CLASSES) # 应该输出COCO的80个类别2. 自定义COCO数据集处理很多教程只告诉你要把数据放到data/coco目录但没说明目录结构的魔鬼细节。正确的COCO格式目录应该长这样data └── coco ├── annotations │ ├── instances_train2017.json │ └── instances_val2017.json ├── train2017 │ └── *.jpg └── val2017 └── *.jpg遇到过最坑的问题是标注文件里的image_id和id字段混淆。有次训练时loss不下降最后发现是标注文件中annotations数组里的image_id与images数组里的id没对应上。建议用这个脚本验证JSON文件from pycocotools.coco import COCO coco COCO(data/coco/annotations/instances_train2017.json) print(f有效标注数量{len(coco.anns)}) print(f图像与标注对应关系示例{next(iter(coco.imgToAnns.items()))})当你的类别和COCO原始80类不同时需要特别注意三个地方的同步修改标注文件中的categories数组配置文件中的classes元组模型head中的num_classes参数我习惯用这个Python字典模板生成自定义类别的标注文件categories [{ id: 1, # 从1开始 name: 你的类别名, supercategory: none }]3. 配置文件深度定制直接修改官方配置文件是新手常犯的错误。我推荐继承式配置法就像搭积木一样层层覆盖。以Mask R-CNN为例新建configs/my_config/mask_rcnn_custom.py_base_ [ ../mask_rcnn/mask_rcnn_r50_fpn_1x_coco.py, ../_base_/datasets/coco_detection.py, # 注意用detection而非instance ] # 只修改需要变化的部分 model dict( roi_headdict( bbox_headdict(num_classes5), # 你的类别数 mask_headNone # 禁用分割头 ))数据增强的配置最容易出错。有次我发现验证集准确率异常高原来是训练和验证的Resize参数不一致。推荐这样配置pipelinetrain_pipeline [ dict(typeLoadImageFromFile), dict(typeLoadAnnotations, with_bboxTrue, with_maskFalse), dict( typeResize, img_scale[(1333, 800), (1333, 640)], # 多尺度训练 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]) ]4. 训练技巧与参数调优学习率设置是门艺术。我发现对于自定义小数据集从预训练模型微调时要用更小的学习率optimizer dict( typeAdamW, # 比SGD更稳定 lr0.0001, # 初始学习率 weight_decay0.05) lr_config dict( policyCosineAnnealing, # 余弦退火 warmuplinear, warmup_iters500, warmup_ratio0.001, min_lr1e-7)早停策略能节省大量时间。在配置中添加evaluation dict( interval1, metricbbox, save_bestbbox_mAP_50, # 自动保存最佳模型 rulegreater) checkpoint_config dict( interval1, max_keep_ckpts3) # 只保留最近3个检查点遇到显存不足时可以尝试这些技巧使用fp16训练在配置中添加fp16 dict(loss_scale512.)调整samples_per_gpu和workers_per_gpu启用梯度累积optimizer_config dict(typeGradientCumulativeOptimizerHook, cumulative_iters2)5. 结果可视化与性能分析官方提供的分析工具非常强大但少有人用透。这个命令可以生成训练过程的热力图python tools/analysis_tools/analyze_logs.py plot_curve \ work_dirs/your_exp/xxx.log.json \ --keys loss_cls loss_bbox \ --out losses.jpg测试时想要保存带置信度的预测结果可以这样修改测试命令python tools/test.py \ configs/my_config/mask_rcnn_custom.py \ work_dirs/your_exp/latest.pth \ --show-dir results/ \ --show-score-thr 0.3 \ --cfg-options model.test_cfg.rcnn.score_thr0.3对于bad case分析我开发了个小工具可视化特定类别的错误from mmdet.core.visualization import imshow_det_bboxes imshow_det_bboxes( img, # numpy数组 bboxes, # 预测框 labels, # 预测标签 class_names(cat,dog), # 你的类别名 showFalse, out_fileerror_analysis.jpg)6. 模型部署实战训练好的模型想要部署到生产环境需要经过以下步骤转换模型为TorchScript格式torch_model init_detector(config, checkpoint) input_tensor torch.rand(1, 3, 800, 1333).cuda() traced_model torch.jit.trace(torch_model, (input_tensor,)) traced_model.save(deploy_model.pt)使用ONNX Runtime加速推理python tools/deployment/pytorch2onnx.py \ configs/my_config/mask_rcnn_custom.py \ work_dirs/your_exp/latest.pth \ --output-file model.onnx \ --shape 800 1333对于TensorRT优化我建议使用mmdeploy工具链python tools/deploy.py \ configs/mmdet/detection/detection_tensorrt_dynamic.py \ configs/my_config/mask_rcnn_custom.py \ work_dirs/your_exp/latest.pth \ demo/demo.jpg \ --work-dir trt_model \ --device cuda:07. 常见问题排坑指南问题1训练时出现KeyError: acc原因在检测任务中误用了分类任务的评估指标解决确保配置中是metricbbox而非metricaccuracy问题2验证集AP异常高(0.99)原因数据泄露通常是训练集和验证集有重叠检查python tools/analysis_tools/analyze_logs.py cal_train_time xxx.log.json问题3GPU利用率波动大优化方案data dict( samples_per_gpu4, # 适当增大 workers_per_gpu2, # 根据CPU核心数调整 persistent_workersTrue) # 避免重复加载数据问题4出现NaN loss可能原因学习率过大标注框坐标超出图像范围数据归一化参数错误排查命令python tools/analysis_tools/dataset_analysis.py \ configs/my_config/mask_rcnn_custom.py \ --out-dir analysis