1. 项目概述：从零上手MMDetection v2.22.0

如果你刚拿到一批标注好的图片，想用MMDetection这个强大的目标检测工具箱来训练自己的模型，但面对官方文档和繁杂的配置文件感到无从下手，那你来对地方了。我最近刚用MMDetection v2.22.0完整跑通了一个自定义数据集的训练流程，从环境搭建、数据准备、配置修改到模型训练和测试，中间踩了不少坑，也总结了一套行之有效的“流水线”操作。这篇文章就是我的实战笔记，目标很明确：让你能避开我走过的弯路，用最清晰的步骤，在MMDetection v2.22.0上成功训练出第一个属于你自己的目标检测模型。无论你是做学术研究、工业质检，还是个人兴趣项目，这套流程都能直接套用。我们会聚焦于最常用的Faster R-CNN模型和COCO数据格式，因为这是最通用、社区支持最好的路径，掌握了它，再探索其他模型和格式就会容易得多。

2. 环境搭建与MMDetection安装

2.1 基础环境准备：CUDA、PyTorch与MMCV

MMDetection的稳定运行严重依赖底层环境，尤其是PyTorch和MMCV（OpenMMLab的计算机视觉基础库）的版本匹配。v2.22.0版本发布于一段时间，其版本依赖相对固定，盲目使用最新版PyTorch很可能导致兼容性问题。

我的建议是，严格按照 MMDetection官方安装文档 中推荐的版本来。以我使用的环境为例：

• 操作系统：Ubuntu 20.04 LTS 或 Windows 10/11（WSL2环境下）。纯Windows原生安装会遇到更多编译问题，强烈推荐WSL2。
• CUDA Toolkit：11.3。这是经过广泛测试的版本。确保nvidia-smi显示的CUDA版本不低于此。
• PyTorch：1.11.0。使用以下命令安装：

  pip install torch==1.11.0+cu113 torchvision==0.12.0+cu113 torchaudio==0.11.0 --extra-index-url https://download.pytorch.org/whl/cu113

• MMCV：这是关键。MMDetection v2.22.0需要mmcv-full，而非轻量版的mmcv。我们必须安装与CUDA、PyTorch版本完全匹配的预编译包。

  pip install mmcv-full==1.5.3 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.11.0/index.html

  请将URL中的cu113和torch1.11.0替换成你的CUDA和PyTorch版本。安装成功后，在Python中运行import mmcv; print(mmcv.__version__)应能正确输出版本号。

注意：切勿直接pip install mmcv-full，这大概率会触发从源码编译，过程漫长且极易失败。一定要使用-f指定预编译包的索引地址。

2.2 MMDetection安装与验证

基础环境就绪后，安装MMDetection本身反而很简单。推荐从GitHub克隆特定版本，以保证代码一致性。

git clone -b v2.22.0 https://github.com/openmmlab/mmdetection.git cd mmdetection pip install -v -e . # “-e”代表可编辑模式安装，方便修改源码 # 或者使用requirements文件安装依赖 # pip install -r requirements/build.txt # pip install -r requirements/optional.txt

安装完成后，进行一个快速的完整性验证。创建一个简单的Python脚本test_install.py：

from mmdet.apis import init_detector, inference_detector import mmcv config_file = 'configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py' checkpoint_file = 'checkpoints/faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth' # 下载预训练模型（如果尚未下载） # from mmdet.apis import init_detector # 模型会在首次运行时自动下载，也可以手动下载到checkpoints目录 model = init_detector(config_file, checkpoint_file, device='cpu') # 先用CPU测试 print('MMDetection安装及模型加载测试通过！')

如果运行没有报错，说明核心安装成功。接下来，我们需要准备最重要的燃料——你自己的数据集。

3. 自定义数据集准备：COCO格式详解与制作

MMDetection支持多种数据集格式（PASCAL VOC、COCO等），但COCO格式是社区生态最完善、文档示例最全的格式，强烈建议将你的数据转为COCO格式，能省去大量适配工作。

3.1 COCO数据集格式深度解析

COCO格式的核心是一个JSON文件，通常命名为annotations.json。它包含以下几个顶级字段：

• images: 一个列表，包含所有图像的信息。
• annotations: 一个列表，包含所有目标实例的标注信息。
• categories: 一个列表，定义所有物体类别。

下面我们拆解每一个部分，并说明如何从你的原始标注（比如LabelImg生成的XML）转换过来。

1.images字段每个图像是一个字典，例如：

{ "id": 1, // 图像唯一ID，从1开始递增 "width": 800, "height": 600, "file_name": "image_001.jpg" // 相对于数据集根目录的路径 }

你需要遍历你的所有图片，为每一张生成这样一个记录。id必须唯一且连续。

2.categories字段定义你的检测类别。id通常从1开始，0保留给背景（MMDetection内部处理）。

[ {"id": 1, "name": "cat", "supercategory": "animal"}, {"id": 2, "name": "dog", "supercategory": "animal"}, {"id": 3, "name": "person", "supercategory": "human"} ]

supercategory可以用于更粗粒度的分组，非必需，但建议填写。

3.annotations字段（最关键）每个目标实例一个字典：

{ "id": 1, // 标注实例唯一ID，全局递增 "image_id": 1, // 对应 images 中的 id "category_id": 1, // 对应 categories 中的 id "bbox": [x, y, width, height], // [左上角x, 左上角y, 宽度, 高度] "area": width * height, // bbox面积，用于评估指标如AP "segmentation": [], // 实例分割多边形坐标，目标检测可留空列表 "iscrowd": 0 // 0表示单个物体，1表示一群物体（如人群） }

这里最重要的是bbox的格式。COCO使用的是[x, y, width, height]，即左上角坐标和宽高。这与某些标注工具（如YOLO使用的中心点坐标和归一化宽高）不同，转换时务必注意。

3.2 从常见格式转换到COCO格式的实操脚本

假设你的原始标注是PASCAL VOC格式（XML文件），下面是一个使用Pythonxml.etree.ElementTree进行转换的示例脚本核心逻辑：

import json import os import xml.etree.ElementTree as ET from PIL import Image def voc_to_coco(voc_annotations_dir, images_dir, output_json_path): images = [] annotations = [] categories = [] # 1. 构建 categories # 这里需要你事先知道所有类别并映射到id category_dict = {"cat": 1, "dog": 2, "person": 3} for name, cid in category_dict.items(): categories.append({"id": cid, "name": name, "supercategory": "none"}) ann_id = 1 for img_id, xml_file in enumerate(os.listdir(voc_annotations_dir), 1): if not xml_file.endswith('.xml'): continue tree = ET.parse(os.path.join(voc_annotations_dir, xml_file)) root = tree.getroot() # 2. 构建 image 信息 filename = root.find('filename').text img_path = os.path.join(images_dir, filename) with Image.open(img_path) as img: width, height = img.size images.append({ "id": img_id, "width": width, "height": height, "file_name": filename, }) # 3. 构建 annotation 信息 for obj in root.iter('object'): cls_name = obj.find('name').text if cls_name not in category_dict: continue # 或者跳过未知类别 xml_box = obj.find('bndbox') xmin = int(float(xml_box.find('xmin').text)) ymin = int(float(xml_box.find('ymin').text)) xmax = int(float(xml_box.find('xmax').text)) ymax = int(float(xml_box.find('ymax').text)) # VOC是[xmin, ymin, xmax, ymax]，需转为COCO的[x, y, width, height] coco_bbox = [xmin, ymin, xmax - xmin, ymax - ymin] area = coco_bbox[2] * coco_bbox[3] annotations.append({ "id": ann_id, "image_id": img_id, "category_id": category_dict[cls_name], "bbox": coco_bbox, "area": area, "segmentation": [], "iscrowd": 0 }) ann_id += 1 # 4. 组装成COCO JSON coco_format_json = { "images": images, "annotations": annotations, "categories": categories } with open(output_json_path, 'w') as f: json.dump(coco_format_json, f, indent=2) print(f"转换完成，共 {len(images)} 张图片，{len(annotations)} 个标注。") # 使用示例 voc_to_coco('./voc_annotations', './images', './annotations/train.json')

运行这个脚本，你就能得到标准的COCO格式标注文件。记得将图片文件放在images_dir指定的目录下。

3.3 数据集目录结构规划

一个清晰的数据集目录结构能让后续配置变得简单。我推荐如下结构：

mmdetection/ ├── data/ │ └── my_dataset/ # 你的数据集根目录 │ ├── annotations/ # 存放COCO格式的JSON文件 │ │ ├── train.json │ │ └── val.json │ └── images/ # 存放所有图片（或按train/val放子目录） │ ├── train/ │ │ ├── img1.jpg │ │ └── ... │ └── val/ │ ├── img2.jpg │ └── ...

实操心得：在制作train.json和val.json时，images列表和annotations列表只包含对应划分的数据。categories列表在两个文件中必须完全一致。你可以先用一个脚本生成完整的all.json，再根据划分列表拆分成train.json和val.json。

4. 配置文件解析与关键修改

MMDetection采用模块化、可继承的配置文件系统，这是其强大之处，也是新手最容易困惑的地方。我们不需要从头写配置，而是基于一个基准配置文件进行修改。

4.1 配置文件继承机制解读

以训练Faster R-CNN为例，我们查看configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py，会发现它的第一行是：

_base_ = [ '../_base_/models/faster_rcnn_r50_fpn.py', '../_base_/datasets/coco_detection.py', '../_base_/schedules/schedule_1x.py', '../_base_/default_runtime.py' ]

这表示它继承了四个基础配置文件，分别定义了模型结构、数据流水线、训练策略和运行时设置（如日志、钩子）。我们的修改策略是：创建一个新的配置文件，继承我们选中的基准配置，然后只覆盖需要修改的部分。这样做既保证了配置的完整性，又使修改清晰可追溯。

4.2 创建自定义配置文件

在mmdetection/configs目录下（或任何你喜欢的位置，建议在项目根目录新建一个configs文件夹），创建我们的配置文件，例如my_faster_rcnn_r50_fpn_1x_mydataset.py。

# my_faster_rcnn_r50_fpn_1x_mydataset.py _base_ = './faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py' # 相对于当前文件的路径 # 1. 修改数据集相关配置 dataset_type = 'CocoDataset' classes = ('cat', 'dog', 'person') # 务必与你的 categories 中 name 的顺序和内容一致！ data_root = 'data/my_dataset/' # 指向你的数据集根目录 # 覆盖 _base_ 中关于数据集的配置 data = dict( samples_per_gpu=2, # 批大小。根据你的GPU内存调整。如果遇到CUDA out of memory，就调小这个值。 workers_per_gpu=2, # 数据加载线程数。通常设为CPU核心数，但不宜过大。 train=dict( type=dataset_type, ann_file=data_root + 'annotations/train.json', img_prefix=data_root + 'images/train/', classes=classes # 指定类别 ), val=dict( type=dataset_type, ann_file=data_root + 'annotations/val.json', img_prefix=data_root + 'images/val/', classes=classes ), test=dict( type=dataset_type, ann_file=data_root + 'annotations/val.json', # 测试集可以用验证集代替 img_prefix=data_root + 'images/val/', classes=classes ) ) # 2. 修改模型头部类别数 # 找到 _base_ 中模型定义的路径，然后修改 roi_head 的 bbox_head model = dict( roi_head=dict( bbox_head=dict( num_classes=len(classes) # 关键！必须修改为你的类别数，这里是3 ) ) ) # 3. 修改训练策略（可选，但建议调整） # 学习率根据 batch size 线性缩放是一个经验法则。原配置 base_lr=0.02 对应 8 GPUs * 2 imgs/gpu = 16 的总batch size。 # 如果你用单卡，samples_per_gpu=2，总batch size=2，那么学习率应缩放为 0.02 * (2 / 16) = 0.0025 optimizer = dict(type='SGD', lr=0.0025, momentum=0.9, weight_decay=0.0001) lr_config = dict( policy='step', warmup='linear', warmup_iters=500, warmup_ratio=0.001, step=[8, 11]) # 学习率在第8和第11个epoch下降 runner = dict(type='EpochBasedRunner', max_epochs=12) # 总训练轮数 # 4. 修改运行时配置（如日志、检查点频率） checkpoint_config = dict(interval=1) # 每个epoch保存一次检查点 log_config = dict(interval=50, hooks=[dict(type='TextLoggerHook')]) # 每50个iteration打印一次日志 # 指定工作目录，训练日志和模型权重将保存在这里 work_dir = './work_dirs/my_faster_rcnn_exp1'

这个配置文件是核心中的核心。请逐行理解，特别是num_classes和lr的修改，这是新手最常出错的两个地方。num_classes不修改会导致维度不匹配错误；lr设置不当会导致训练不收敛。

4.3 配置文件的调试与验证

在开始漫长训练之前，先用一个极小的设置验证整个数据流和配置是否正确。我们可以创建一个“玩具”配置文件，只加载几张图片跑通前向传播。

# debug_config.py _base_ = './my_faster_rcnn_r50_fpn_1x_mydataset.py' # 覆盖数据加载部分，仅用于调试 data = dict( samples_per_gpu=1, workers_per_gpu=1, train=dict( type=_base_.dataset_type, ann_file=_base_.data_root + 'annotations/train.json', img_prefix=_base_.data_root + 'images/train/', classes=_base_.classes, # 使用更小的流水线，加速调试 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']), ] ) )

然后运行一个简单的测试脚本：

python tools/misc/browse_dataset.py debug_config.py --show

这个命令会可视化你的数据加载和增强效果，确保图片和标注能正确配对、显示。这是排查数据问题最直观的方法。

5. 模型训练、监控与测试

5.1 启动训练与分布式训练

单GPU训练命令很简单：

python tools/train.py my_faster_rcnn_r50_fpn_1x_mydataset.py

如果你有多张GPU，可以使用分布式训练以大幅加速。MMDetection基于PyTorch的DistributedDataParallel(DDP) 封装了分布式训练命令：

./tools/dist_train.sh my_faster_rcnn_r50_fpn_1x_mydataset.py 8 --work-dir ./work_dirs/my_exp

这里的8代表使用8个GPU。dist_train.sh脚本会自动处理进程启动、端口分配等繁琐细节。训练日志和模型权重会保存在--work-dir指定的目录，如果配置文件中已指定work_dir，则以配置文件为准。

5.2 训练过程监控与日志解读

训练开始后，控制台会打印日志。你需要关注以下几个关键信息：

• Loss曲线：loss_rpn_cls、loss_rpn_bbox、loss_cls、loss_bbox是Faster R-CNN的主要损失。在训练初期，这些loss应该呈现明显的下降趋势。如果loss剧烈震荡或居高不下，可能是学习率过高、数据有问题或标注错误。
• 学习率：日志会显示当前的学习率。根据lr_config的设置，你应该能看到在指定epoch学习率按比例下降。
• 内存使用：关注GPU内存占用。如果接近上限，可以尝试减小samples_per_gpu或输入图片尺寸。

更强大的监控工具是TensorBoard。MMDetection默认集成了TensorBoard日志。在训练命令后加上--tensorboard参数，或者在配置文件中添加：

log_config = dict( interval=50, hooks=[ dict(type='TextLoggerHook'), dict(type='TensorboardLoggerHook') # 添加这行 ])

训练后，在work_dir下会生成tf_logs目录，使用tensorboard --logdir ./work_dirs/my_exp/tf_logs即可在浏览器中查看丰富的可视化图表，包括Loss曲线、学习率、验证集mAP等，这对于分析训练状态至关重要。

5.3 模型测试与性能评估

训练完成后，我们使用验证集评估模型性能。使用以下命令：

# 单GPU测试 python tools/test.py my_faster_rcnn_r50_fpn_1x_mydataset.py ./work_dirs/my_exp/latest.pth --eval bbox # 多GPU测试 ./tools/dist_test.sh my_faster_rcnn_r50_fpn_1x_mydataset.py ./work_dirs/my_exp/latest.pth 8 --eval bbox

--eval bbox指定评估边界框检测的指标。MMDetection会计算COCO风格的一系列指标，其中最重要的是：

• AP (Average Precision): IoU阈值从0.5到0.95，步长0.05的平均精度。这是COCO的主要评价指标，记为AP或AP@[.5:.95]。
• AP50: IoU阈值为0.5时的AP，即PASCAL VOC的评价标准。
• AP75: IoU阈值为0.75时的AP。
• AP_s, AP_m, AP_l: 分别对应小、中、大尺寸目标的AP。

一份合格的训练结果，AP和AP50应该达到一个合理的值（取决于你的数据集难度和规模）。如果AP_s远低于AP_l，说明模型对小目标检测不好，可能需要调整FPN结构、使用更小的anchor或增加小目标的训练数据。

5.4 模型推理与可视化

训练出模型后，我们当然想看看它的实际检测效果。MMDetection提供了简单的推理API：

from mmdet.apis import init_detector, inference_detector, show_result_pyplot import mmcv # 指定配置文件和训练好的模型 config_file = 'my_faster_rcnn_r50_fpn_1x_mydataset.py' checkpoint_file = './work_dirs/my_exp/latest.pth' # 初始化模型 model = init_detector(config_file, checkpoint_file, device='cuda:0') # 对单张图片进行推理 img = 'test.jpg' # 或者 img = mmcv.imread('test.jpg') result = inference_detector(model, img) # 可视化结果 # show_result_pyplot函数会直接显示图片，适合在Jupyter Notebook中使用 # show_result_pyplot(model, img, result, score_thr=0.3) # score_thr是显示分数阈值 # 更常用的方式：将结果绘制到图片上并保存 vis_img = model.show_result(img, result, score_thr=0.3, show=False) mmcv.imwrite(vis_img, 'result.jpg') print('检测结果已保存至 result.jpg')

你可以调整score_thr来过滤低置信度的检测框，这个值需要根据你的具体应用场景来权衡召回率和精度。

6. 实战避坑指南与高级技巧

6.1 常见错误与解决方案

1. KeyError: ‘xxx’ is not in the fields或AssertionError: Thenum_classes(xx) shared by all branches must be the same

   • 问题：这是最经典的错误。根本原因是模型的num_classes没有修改，或者修改得不彻底。Faster R-CNN的num_classes需要同时在roi_head.bbox_head和rpn_head（如果RPN也有分类头的话，新版通常不需要）中修改。最稳妥的方法是像我们之前那样，在配置文件中通过model.dict()覆盖。
   • 解决：仔细检查配置文件，确保model.roi_head.bbox_head.num_classes已正确设置为你的类别数。使用print(model)打印模型结构来确认。

2. CUDA out of memory (OOM)

   • 问题：GPU内存不足。
   • 解决：
     • 减小配置中的samples_per_gpu（批大小）。
     • 减小输入图片尺寸。在train_pipeline和test_pipeline中找到Resize操作，将img_scale改小，例如从(1333, 800)改为(800, 600)。
     • 使用梯度累积（Gradient Accumulation）。这需要在优化器配置和train_cfg中设置，对新手稍复杂，但可以有效模拟大batch size训练。
     • 尝试更轻量的模型，如RetinaNet或FCOS。

3. Loss为NaN或训练不收敛

   • 问题：学习率设置不当、数据存在极端值（如坐标超出图像范围）、标注错误。
   • 解决：
     • 首要检查数据：使用browse_dataset.py脚本仔细检查标注框是否合理。确保bbox坐标非负且不超过图像宽高。
     • 调整学习率：根据你的batch size按线性缩放规则调整lr。如果loss爆炸（变成NaN），大幅降低学习率（如除以10）再试。
     • 使用预训练权重：确保你的配置中load_from指向了在COCO上预训练的模型权重（MMDetection会自动下载或你需要手动指定路径）。从随机初始化开始训练检测器非常困难。

4. 验证集mAP为0或极低，但训练loss正常下降

   • 问题：过拟合，或者训练集和验证集分布差异极大。
   • 解决：
     • 增加数据增强的多样性（如更多的随机裁剪、颜色抖动）。
     • 检查是否不小心在验证集上使用了训练时的数据增强（如RandomFlip）。验证集流水线应该只有Resize,Normalize,Pad,DefaultFormatBundle等确定性操作。
     • 使用更小的模型或添加正则化（如Dropout，但检测模型中不常用）。
     • 确保训练轮数max_epochs没有过多。

6.2 性能调优与进阶技巧

1. 数据增强策略调优：MMDetection的数据增强流水线（pipeline）非常灵活。对于小数据集，增强是防止过拟合的关键。你可以在配置文件的train_pipeline中添加或调整增强操作，例如：

   train_pipeline = [ dict(type='LoadImageFromFile'), dict(type='LoadAnnotations', with_bbox=True), dict(type='Resize', img_scale=[(1333, 800), (1600, 960)], multiscale_mode='range', keep_ratio=True), # 多尺度训练 dict(type='RandomFlip', flip_ratio=0.5), dict(type='RandomCrop', crop_size=(0.8, 0.8), crop_type='relative_range'), # 随机裁剪 dict(type='PhotoMetricDistortion', # 光度失真 brightness_delta=32, contrast_range=(0.5, 1.5), saturation_range=(0.5, 1.5), hue_delta=18), dict(type='Normalize', **img_norm_cfg), dict(type='Pad', size_divisor=32), dict(type='DefaultFormatBundle'), dict(type='Collect', keys=['img', 'gt_bboxes', 'gt_labels']), ]

   注意，增强不是越多越好，需要根据你的任务特性调整。工业质检可能不需要RandomFlip，而自然场景目标检测则需要。

2. 学习率策略与优化器选择：除了StepLR，还可以尝试CosineAnnealingLR（余弦退火），它通常能带来更好的收敛效果和最终精度。将lr_config修改为：

   lr_config = dict( policy='CosineAnnealing', warmup='linear', warmup_iters=500, warmup_ratio=0.001, min_lr_ratio=1e-5 # 最小学习率 )

   对于优化器，SGD with momentum是检测任务的主流，但也可以尝试AdamW，尤其在小数据集或训练不稳定时。

3. 模型微调与冻结骨干网络：如果你的数据集与预训练数据集（如COCO）差异很大，或者数据量很小，可以考虑冻结骨干网络（Backbone）的前几层，只训练后面的网络层，以防止过拟合和加速训练。

   # 在配置文件中修改 model = dict( backbone=dict( frozen_stages=2, # 冻结前2个stage（ResNet有4个stage） norm_cfg=dict(type='BN', requires_grad=False), # 冻结BN层的统计量 norm_eval=True), ... )

   训练初期验证集指标提升很快，但后续可能遇到瓶颈，此时可以解冻部分层继续训练。

6.3 部署与落地考量

训练出一个指标不错的模型只是第一步，要真正用起来，还需要考虑部署。

1. 模型转换：MMDetection模型通常需要转换为其他格式以便部署。常用的有：

   • ONNX: 使用tools/deployment/pytorch2onnx.py脚本转换，可以获得一个跨平台的中间表示。
   • TorchScript: 使用PyTorch自带的torch.jit.trace或torch.jit.script进行转换，适合在PyTorch生态内部署。
   • TensorRT (for NVIDIA GPUs): 通过ONNX中转或直接使用MMDeploy等工具链，可以极大提升推理速度。

2. 速度与精度权衡：在配置文件中选择不同的Backbone（如将r50换成r18或mobilenetv2）和Neck（如修改FPN的通道数）可以显著影响模型速度和精度。MMDetection的Model Zoo提供了大量预训练模型及其性能指标，可以作为选型参考。

3. 构建简易推理服务：对于原型验证，可以快速搭建一个基于Flask或FastAPI的Web服务，将上面提到的推理代码封装成API，方便其他系统调用。

走到这一步，你已经完成了从数据准备到模型训练、评估和初步部署的完整闭环。MMDetection的功能远不止于此，它支持数十种检测算法、实例分割、全景分割等高级任务。但掌握这套基于Faster R-CNN和COCO格式的标准流程，就像掌握了打开宝库的钥匙，你可以自信地去探索更复杂的模型和任务了。记住，遇到问题多查官方文档和GitHub Issues，社区里很可能已经有现成的解决方案。