最近在做一个工业场景的缺陷检测项目，需要识别几种很偏门的瑕疵类型，这类需求没有现成的预训练模型可以直接抄答案，只能自己标注一批图片，再用 mmdetection 训练一个自定义数据集的目标检测模型。前后折腾了两周，踩了大大小小一堆坑，最后总算跑通了。这篇文章就把整个流程重新梳理一遍，从数据集制作、格式转换到训练评估、报错排查，尽量覆盖你在实战中最可能遇到的每一个环节。
mmdetection 是目前目标检测领域覆盖面最广的开源工具库之一，Faster R-CNN、RetinaNet、YOLOv3、SSD、Cascade R-CNN 这类经典算法都能开箱即用，而且配置文件设计得很统一，替换数据集和网络结构基本就是改改字典的事。也正因为它管的算法多，版本依赖特别复杂，新手最容易被卡住的就是环境问题。这篇博文适合三类人：第一次接触 mmdetection 想做自定义数据集的新手；数据已经标好但不知道怎么组织成 COCO 格式的开发者；以及训练中途老是报错、连日志都看不懂的同学。
1. 项目整体思路拆解：动手之前先想明白这四件事
1.1 为什么选 mmdetection 而不是自己搭网络或换其他框架
我在选框架时其实犹豫过一阵。如果用现成的 YOLOv5，确实上手最快，数据格式也简单，但当时我需要对比 Faster R-CNN 和 Cascade R-CNN 多种算法，还想后续试试不同 backbone 的效果。mmdetection 一个库就全包了，换成不同算法直接换配置文件就行，这点比每个模型单独搭一套工程舒服太多。这也是我最终选它的核心原因：不是因为它最简单，而是因为它最能满足“算法灵活对比”的需求。
另一个原因是社区资料丰富。毕竟这个库用的人多，真遇到报错，搜一下基本能找到解决方案。对自定义数据集的训练流程，官方文档也给出了很标准的路子：把数据转成 COCO 格式，然后改配置里的类别数和路径，就能启动训练。这个思路看起来简单，但细节藏得深，后面我会把每一步拆开讲，尤其是那些不改就会突然给你罢工的坑。
1.2 自定义数据集的核心流程梳理
整个项目可以拆成四条主线：环境搭建、数据准备、训练评估、问题排查。环境搭建解决的是“代码能不能跑起来”，数据准备解决的是“模型能看到什么”，训练评估解决的是“模型学得好不好”，问题排查则是贯穿全程的兜底能力。
别小看“模型能看到什么”这半句话。目标检测模型的训练质量，不只是网络结构决定的，数据标注是否规范、类别定义是否统一、训练集和验证集划分是否合理，都会直接影响最终 mAP。我第一次训练时标注不严谨，一个类别名称在部分图片里叫 defect，另一些叫 Defect，结果模型学得稀里糊涂，loss 降不下去，最后查了半天才发现是这种低级问题。所以从头开始就规范起来，反而最省时间。
1.3 先规划再动手：数据量、目录结构和类别清单
动手标数据之前，我建议你先想清楚三件事：每个类别大概有多少样本、图片按什么比例划分训练集和验证集、类别名称怎么统一命名。举个例子，我当时的自定义类别有三类：defect、scratch、stain，所有标注文件里的名字必须严格一致，大小写、空格都不能错，否则类别映射会乱。
- 类别名称统一用英文小写，比如 defect、scratch、stain，不要混入标点或空格。
- 训练集和验证集划分比例建议 8:2，验证集图片务必和训练集没有交集，否则验证结果虚高，上线就现原形。
- 样本数量上，如果做迁移学习，每类至少要有几十到上百张标注图片才比较稳，太少的话建议先做二分类或合并相似类别，别硬上多分类。
目录结构我推荐按这种方式组织，后面配置里能直接复用：
custom_dataset/ ├── train/ │ ├── img_001.jpg │ └── ... ├── val/ │ ├── img_001.jpg │ └── ... └── annotations/ ├── instances_train.json └── instances_val.json2. 环境配置与标注工具准备：坑从这里开始
2.1 版本对应关系，mmdetection 和 mmcv 必须锁死
我在这块差点崩溃。mmdetection 2.x 系列必须搭配 mmcv 1.x 系列，mmdetection 3.x 则要配 mmcv 2.x，这两者不能随意乱配。我当时第一次装，直接 pip install mmcv 装了最新版，结果 mmdet 2.25 的代码跑起来一堆报错，后来才搞清楚版本匹配是硬约束。
我这套环境给你作参考：Python 3.7 + PyTorch 1.10.0 + CUDA 11.3 + mmcv-full 1.7.0 + mmdet 2.25.0。安装方式也比较直接，先创建虚拟环境，再装 PyTorch，然后装 mmcv-full，最后装 mmdet。需要提醒的是，mmcv-full 的安装会做编译校验，你的 CUDA 和 PyTorch 版本不匹配时，它会在安装时就报错，这时候可以先检查这两个环节。
conda create -n mmdet python=3.7 -y conda activate mmdet conda install pytorch==1.10.0 torchvision==0.11.0 cudatoolkit=11.3 -c pytorch -c conda-forge pip install mmcv-full==1.7.0 pip install mmdet==2.25.0版本匹配表在官方文档里写得很清楚，但很多人不习惯先查。我的习惯是：先确定 mmdet 大版本，再回推 mmcv 的对应版本，最后根据显卡驱动定 CUDA。多人在同一台服务器上共用环境时，建议用 conda 虚拟环境隔离，别直接在 base 环境里装，容易互相污染。
注意：如果你跟我一样用 mmdet 3.x 系列，配置文件写法会有一点变化，比如训练循环相关参数从 Runner 改成了 TrainLoop，代码 API 也略有调整。但数据准备和 COCO 格式这条主线是一样的，所以本文的核心流程照样适用。
2.2 标注工具选型：Labelme 比 LabelImg 更适合自定义数据集
标注工具有很多，我用过 LabelImg，也用过 Labelme，还试过一些带自动标注功能的新工具。最终我在这个项目里用的是 Labelme，原因是它对类别列表的管理更灵活，导出 JSON 后转 COCO 格式的脚本也容易写。
- LabelImg 导出的是 XML，VOC 格式，对矩形框标注够用，但多边形标注支持一般。
- Labelme 导出的是 JSON，支持矩形框和多边形，字段结构清晰，适合做后期二次开发。
- 如果目标物体形状不规则，建议用 Labelme 的 polygon 模式，检测效果反而更好。
标注时别急着追求数量，先保证质量。我第一次标的时候，边框画得随意，有的框比物体大了一圈，有的只框了一半，最后 mAP 卡在 0.4 左右上不去。后来重新检查一遍标注，把明显的坏框修掉，mAP 立刻涨了五六个点。标注这个环节没有捷径，一次做对，后面省一堆事。
3. 自定义数据集制作：从一堆图片到 COCO 格式 JSON
3.1 COCO 格式的核心字段，你必须弄懂
mmdetection 对 COCO 格式的原生支持最好，这也是官方示例数据集采用 COCO 的原因。COCO 格式的 JSON 整体是一个大字典，最关键的字段是 images、annotations、categories 三个。
images 数组里的每个元素，至少要包含三个字段：id、file_name、width、height。width 和 height 别搞错，后面模型会根据这个值来匹配标注坐标。annotations 数组里核心字段是 image_id、category_id、bbox、area、iscrowd。其中 bbox 的格式是 [x, y, width, height]，x、y 是左上角坐标，width 和 height 是框的宽和高。
这里有一个经典的坑：很多人习惯用 VOC 的 [x1, y1, x2, y2] 格式直接填进去，但 COCO 不认这个，它要的是 [x, y, width, height]。如果你转格式的时候不转换，训练时目标框位置会乱套，模型根本学不出来。area 字段直接填 width * height 就行，iscrowd 一般是 0，表示单个目标；如果一张图里有一堆挤在一起的小目标，可以标成 1，但新手不建议碰。
3.2 用 Labelme 标注的 JSON 转 COCO 的实操脚本
Labelme 导出的 JSON 里，shapes 字段记录了每个目标的 label 和 points。对于矩形框，points 是 [[x1, y1], [x2, y2]] 两个点。转成 COCO 时，需要把这两个点换算成 x、y、width、height。
我直接把这个脚本放出来，这是我在项目里实际用过的版本，里面加了基础的容错处理。核心逻辑就是遍历 Labelme 的 JSON 文件，读取图片尺寸，然后逐条解析标注框，最后组装成 COCO 结构。
import json import glob import os from PIL import Image def convert_labelme_to_coco(labelme_dir, output_path, categories): images = [] annotations = [] cat_id_map = {name: i + 1 for i, name in enumerate(categories)} ann_id = 1 image_id = 1 for json_path in glob.glob(os.path.join(labelme_dir, '*.json')): with open(json_path, 'r', encoding='utf-8') as f: data = json.load(f) img_path = data['imagePath'] img_name = os.path.basename(img_path) img_full_path = os.path.join(os.path.dirname(json_path), img_name) if not os.path.exists(img_full_path): continue img = Image.open(img_full_path) width, height = img.size images.append({ 'id': image_id, 'file_name': img_name, 'width': width, 'height': height }) for shape in data['shapes']: label = shape['label'] points = shape['points'] if label not in cat_id_map: continue if len(points) != 2: continue x1, y1 = points[0] x2, y2 = points[1] x = min(x1, x2) y = min(y1, y2) w = abs(x2 - x1) h = abs(y2 - y1) if w <= 0 or h <= 0: continue annotations.append({ 'id': ann_id, 'image_id': image_id, 'category_id': cat_id_map[label], 'bbox': [x, y, w, h], 'area': w * h, 'iscrowd': 0 }) ann_id += 1 image_id += 1 coco = { 'info': {'description': 'custom dataset'}, 'licenses': [], 'images': images, 'annotations': annotations, 'categories': [ {'id': i + 1, 'name': name} for i, name in enumerate(categories) ] } with open(output_path, 'w', encoding='utf-8') as f: json.dump(coco, f, ensure_ascii=False, indent=2) if __name__ == '__main__': convert_labelme_to_coco( 'custom_dataset/labelme_jsons', 'custom_dataset/annotations/instances_train.json', ['defect', 'scratch', 'stain'] )跑完脚本后，我推荐你做一次“数据体检”：写个简单脚本，统计一下 annotation 数量、各类别目标数量、图片分辨率分布。我项目里就出现过某类图片只有十几张、另一类有几百张的严重不平衡，如果不提前发现，模型会对少数类直接“放弃治疗”。
3.3 json 格式检查与常见低级错误
转换完成之后要仔细检查几点：json 文件编码是不是 utf-8、所有 image_id 是否能在 images 里找到、category_id 是否在 categories 定义范围内。我见过不少人转出来的 json，annotation 里的 image_id 是从 0 开始的，而 images 数组里的 id 是从 1 开始的，结果就是训练时一大半标注都被丢弃，mmdetection 还会报一堆 warning。
还有一个经验：图片文件名里不要带中文和空格。虽然 mmdetection 底层能处理，但 COCO API 在读取和匹配时偶尔会出问题，为了省心，前期就直接把所有图片重命名为纯数字加英文字母。如果图片已经在老项目里有固定命名规则，建议你在转格式前先批量改名，别等训练报错再回头折腾。
4. 核心配置文件修改：从改着玩到改得明白
4.1 解构训练配置文件的关键字典
mmdetection 的配置文件本质上是一个 Python 字典文件，它会定义模型结构、数据集路径、训练策略等。自定义数据集项目里，你基本不需要从零写配置，而是从已有的示例配置上改，这样少踩很多坑。
我以 Faster R-CNN 为例，核心的改动点有三个：model 里的 num_classes、data 里的 dataset_type 与 classes 和路径、schedule 里的训练轮数和学习率。
model 字段里的 roi_head.bbox_head.num_classes 必须改成你的类别数。很多新手第一个报错就是这里，num_classes 没改，一直用默认的 80，加载预训练权重后维度对不上，直接 Assertion Error。我这个项目里是 3 类，也就是 num_classes=3。如果你是单类检测，依然要写 1，不要写 0。
model = dict( type='FasterRCNN', backbone=dict(type='ResNet', depth=50), ... roi_head=dict( type='StandardRoIHead', bbox_head=dict( type='Shared2FCBBoxHead', num_classes=3, # 改成你的类别数 ... ) ) )4.2 修改数据字典，image 路径与 ann 文件缺一不可
data 字段是自定义数据集项目的重头戏。你需要显式地告诉 mmdetection，训练集和验证集的标注文件在哪里、图片前缀是什么、类别列表是什么。我在实际项目里发现一个容易遗漏的点：dataset_type 要写成 CocoDataset，同时还要在 train、val、test 三个子配置里分别加上 classes。
dataset_type = 'CocoDataset' classes = ('defect', 'scratch', 'stain') data = dict( samples_per_gpu=2, workers_per_gpu=2, train=dict( type=dataset_type, classes=classes, ann_file='custom_dataset/annotations/instances_train.json', img_prefix='custom_dataset/train/' ), val=dict( type=dataset_type, classes=classes, ann_file='custom_dataset/annotations/instances_val.json', img_prefix='custom_dataset/val/' ), test=dict( type=dataset_type, classes=classes, ann_file='custom_dataset/annotations/instances_val.json', img_prefix='custom_dataset/val/' ) )samples_per_gpu 表示每张 GPU 卡一次迭代的样本数。如果你的显卡显存只有 8G，别硬设成 4，通常会 OOM。我一般从 2 开始跑，显存有余量再加。workers_per_gpu 是数据加载线程数，一般 2 到 4 就够，开大了某些老机器 CPU 反而先顶不住。
4.3 训练策略配置：小数据集别直接 1x
mmdetection 的 schedule 配置里有 1x、2x、3x 这些概念，分别对应训练 12、24、36 个 epoch。对自定义小数据集，我个人不建议直接用 1x 配置，因为数据量少，模型容易过拟合，需要在学习率和训练轮数上做调整。
我当时用的是更保守的方案：学习率从 0.01 降到 0.001，训练轮数延长到 24 个 epoch，并配合了余弦退火学习率策略。对小数据集来说，低学习率加长训练时间，比高学习率短训练的表现稳定得多。当然这也和你的类别数量、标注质量有关，我的经验是损失函数在前 10 个 epoch 下降明显，后面趋于平缓，所以 24 个 epoch 基本是性价比最高的。
lr_config = dict( policy='CosineAnnealing', min_lr_ratio=0.001 ) runner = dict(type='EpochBasedRunner', max_epochs=24)提示：如果你用的是 mmdet 3.x，runner 配置换成了 train_cfg 里的 max_epochs，写法上略有差别，但调整思路完全一致。
5. 训练、评估与可视化：跑起来只是第一步
5.1 启动训练的命令与日志解读
环境没问题、配置改完之后，就可以启动训练了。单卡训练的命令很简单：
python tools/train.py configs/my_config/faster_rcnn_r50_fpn_1x_custom.py如果你想在后台跑，并且把日志写到文件里，就用：
nohup python tools/train.py configs/my_config/faster_rcnn_r50_fpn_1x_custom.py --work-dir work_dirs/my_custom > train.log 2>&1 &训练刚开始时，日志里会出现模型结构预览、数据集加载信息，然后是每个 iter 和 epoch 的 loss 数值。我一般会重点关注 loss_rpn_cls、loss_rpn_bbox、loss_cls、loss_bbox 这几个指标。正常情况是前几个 epoch 整体 loss 明显下降，后面缓慢下降。如果 loss 直接变成 NaN，大概率是学习率过大或者数据里有异常标注，先查这两个。
多卡训练我也提一句，mmdetection 提供了分布式训练脚本，两卡就写 2，四卡就写 4：
bash tools/dist_train.sh configs/my_config/faster_rcnn_r50_fpn_1x_custom.py 2但多卡训练有一个隐藏大坑：workers_per_gpu 的数据加载如果不同步，某些机器会把显存占满然后报共享内存错误，这时可以把 DataLoader 的 persistent_workers 和 num_workers 调低。
5.2 评估模型：用 mAP 和损失曲线说话
训练完成后，用 test 脚本评估模型在验证集上的表现：
python tools/test.py configs/my_config/faster_rcnn_r50_fpn_1x_custom.py work_dirs/my_custom/epoch_24.pth --eval bbox输出的 mAP 是综合评价指标，iou=0.5 的 AP 对实际项目最有参考价值。如果 AP 在 0.5 以下，先别急着调网络结构，优先检查数据问题，比如标注框是否准确、类别是否平衡、train 和 val 是否有交集。我那个项目里第一次评估 mAP 只有 0.42，排查之后写上一个小脚本统计每个类别的 AP，发现 scratch 类别的 AP 比其他类低了近 20 个点，原因是这个类别的样本只有二十几张，增强也不够，后续加数据和做数据增强后，AP 提到了 0.68。
评估结果会输出一个包括 mAP、mAP@0.5、mAP@0.75 的表格。如果你要部署到实际业务里，建议把重点放在 mAP@0.5 和对应类别的 AP 上，这两个指标更贴近业务真实感受。mAP@0.75 偏严格，适合对定位精度要求高的场景。
5.3 推理可视化：看一眼模型到底检测成了什么样
评估指标只是一个数字，真正确认模型效果的方式还是可视化推理。mmdetection 2.x 自带 demo 脚本，可以直接对单张图片做推理：
python demo/image_demo.py custom_dataset/val/test_img.jpg configs/my_config/faster_rcnn_r50_fpn_1x_custom.py work_dirs/my_custom/epoch_24.pth --device cuda:0 --score-thr 0.3我实际用过之后觉得，可视化环节不只是“看效果”，更是发现数据问题的机会。比如模型把很多背景误检成 defect，那可能是训练集里负样本太少，图片背景过于单一；如果漏检很多目标本身就很小的物体，可能需要提高输入图像分辨率，或者调整 anchor 的 scale。这些判断如果只看 mAP 数字，容易一头雾水。
写推理脚本也不难，核心是加载 config 和 checkpoint，构建模型，然后调用 inference_detector。这块代码网上很多，但在 mmdet 2.x 和 3.x 之间 API 有差异，建议直接翻对应版本的官方 demo 文件改，别跨版本硬套。
6. 常见问题与排查技巧实录
6.1 高频报错速查表
我整理了一份常见报错速查表，每一行都是我在实践里遇到过的真实问题，你可以直接对照排查。
| 报错/表现 | 原因 | 解决方案 |
|---|---|---|
| AssertionError: num_classes 不匹配 | 配置里忘了改 ROI head 的类别数 | 改 model.roi_head.bbox_head.num_classes |
| KeyError: 'xxx' is not in models registry | mmdet 版本和配置文件版本不一致 | 确认 mmdet 2.x 配 mmcv 1.x，3.x 配 mmcv 2.x |
| OOM / CUDA out of memory | batch size 或输入分辨率过大 | 调小 samples_per_gpu，关掉 albu 增强 |
| IndexError 或 KeyError 在加载数据集 | COCO JSON 里 image_id 或 category_id 对不上 | 写脚本校验 annotation 和 images 的对应关系 |
| loss 变 NaN | 学习率过大或标注里出现异常的框 | 调低 lr，检查标注 bbox 是否为 0 或负数 |
| 验证 mAP 太低，但在训练集很好 | 训练集验证集有交叠，或严重过拟合 | 重新划分数据集，减少 epoch，加数据增强 |
| 图片加载时报文件不存在 | img_prefix 路径不对或图片名带中文/空格 | 统一重命名图片，核对目录结构 |
6.2 训练过程中几个值得留意的细节
第一个细节是 checkpoint 的保存策略。mmdetection 默认每 1 个 epoch 存一个 checkpoint，如果训练 24 个 epoch，会占不少磁盘。我在项目里一般设置每个 3 个 epoch 间隔保存一次，同时保留 best 模型，既不影响后期挑模型，也不至于把磁盘撑爆。
第二个细节是数据增强。mmdetection 默认的增强主要是随机翻转和缩放，对小数据集来说略保守。我后来在 train_pipeline 里加了多尺度训练增强，效果提升明显。但要注意，增强不是越多越好，有些增强会把小目标直接裁掉，反而降低性能，建议逐步加，每次改动后重新评估对比。
第三个细节是预训练权重的选择。mmdetection 会自动下载在 ImageNet 上预训练的 backbone 权重，如果你的网络环境差，下载会卡住，最后训练半天还在等权重。提前把权重文件下载下来，放到对应目录下，然后配置里指定 pretrained 路径可以省很多时间。
6.3 我的独家避坑技巧：先跑通十张图再全量训练
这个方法我想推荐给所有人。正式启动全量训练前，先做一个 mini 实验：只拿 10 张训练图片和 3 张验证图片，把完整的训练、评估、推理流程跑一遍。如果这个小实验能顺利跑完，说明环境、配置、数据格式都没问题；如果这个过程里报错，你只需要盯着十张图调试，问题定位快得多。
我早期没这个习惯，直接 2000 张图开跑，结果半小时后才发现 COCO JSON 里 class 顺序写反了，白白浪费一大笔时间。后来每次新建数据集项目，我都是先跑十张图，确认流程顺畅后再切到全量数据。这个习惯帮我省下的时间，真的够写好几篇博客了。
6.4 关于“验证集效果不错但实际场景翻车”的一点思考
这个问题不是个别现象。模型在验证集 mAP 很高，一到实际拍摄的新图片上效果就很差，最常见的原因是验证集和实际测试数据分布不一致。实际拍摄的图片可能光照更复杂、角度更多变、目标更小，而这些在你的标注图片里根本没见过，模型自然泛化不掉。
我给自己的项目加了一个额外的小测试集，从真实场景里挑了一部分图片，单独做一次评估，不参与训练也不参与常规验证。每次迭代模型后，都拿这个测试集跑一遍，对比 mAP 变化。这个做法不复杂，但能帮你更早发现模型的真实短板。
我在实际项目中还有一个体会：train 和 val 的划分不能简单随机打散，尤其是同一场景拍出来的连续帧图片，几乎一样的背景，如果一部分进了训练集，另一部分进了验证集，评估结果会虚高不少。我后来改成按视频片段或者按拍摄时间切分数据，尽量保证同场景的图片不会被同时分到两边。
写在最后：一点真实感受
整条自定义数据集流程走下来，我最深的感受是：mmdetection 把模型的训练门槛降得很低，但数据工程的门槛一点没降。很多人一上来就折腾配置、折腾模型结构，其实真正决定项目成败的，往往是你有没有把数据转好、把类分对、把训练验证集切得干净。
我这几个星期踩过的坑，差不多都写在前面了。如果这个项目让你重新走一遍，我建议你直接从“十张图 mini 实验”开始，先确认环境通、数据通，再全量开跑，真的能少走很多弯路。之后再遇到自定义数据集的检测需求，就不会像我第一次那样手足无措了。
