mmdetection自定义数据集实战：从COCO标注到训练部署全流程-北京尧图网络

先把话放在这能把 mmdetection 的 Demo 跑通说明你已经摸了门能在自定义数据集上把它训起来才算是真正开始做项目。如果你是第一次接触 mmdetection 自定义数据集几天下来最可能的状态是“看着教程能跑、换成自己的数据就懵”标注格式不认、类别对不上、训练一启动就报一堆 KeyError 或者 shape mismatch。这篇文章完全围绕自定义数据集这条链路来写把我实际踩过的坑、确认过有效的步骤、以及那些文档里没写明白的细节一次性整理给你适合刚完成 mmedetection 入门、打算做自己项目数据训练的开发者参考。这里不绕圈子直接按做事的顺序来数据怎么整理、环境怎么装、代码怎么注册、配置怎么改、训练和排查怎么做。整个过程我会尽量沿着真实项目走过的路径讲包括哪些地方容易翻车、为什么翻车以及对应怎么处理。1. 先把整体思路理清自定义数据集到底在解决什么问题1.1 为什么替换数据集会变成“分水岭”很多人误以为 mmdetection 支持自定义数据集是给个开关就能自动识别实际完全不是这回事。这个库内部有一套相对严格的“数据供给”约定模型只认它定义好的 Dataset 类和对应的标注结构而不是像写脚本那样读一个文件夹就开始跑。自定义数据集的核心本质是把你的数据翻译成 mmdetection 能消费的格式并让它知道你一共有几个类别、标注以什么路径存放、训练集和验证集如何切分。这个环节没打通后面所有训练、评测、推理都无从谈起。我在实际项目里见过不少人卡在这步一到两天不是代码多难而是对整个输入输出链路没有建立清晰的认识。先把链路画清楚你的物理数据图片标注经过 Dataset 类包装变成 PyTorch 想要的 batch 数据DataLoader 把它送给模型模型输出的预测结果再回到 Dataset 定义的评估逻辑里计算 mAP 指标。任何一个环节格式不匹配都会在运行时暴露出来。1.2 最小闭环需要哪几块拼图你要让自定义数据跑通训练至少需要四块拼图缺一不可一套格式规范的数据集目录推荐 COCO 格式一个能被注册机制识别到的 Dataset 类一份针对你数据修改过的配置文件包含类别数、数据路径、训练策略一条训练和验证命令以及能看懂的训练日志。这四块都做好之后你甚至可以把自己的数据集接到很多预训练模型上做微调不需要改任何模型结构代码。下面的内容就是分别把每一块展开讲清楚每一步都给出可以直接参考的做法。2. 数据准备COCO 格式为什么是默认答案2.1 别自己发明标注格式直接用 COCO 就对了我第一次做自定义数据集时也动过“自己定义一套 JSON 格式更简单”的念头。后来发现自己定义格式意味着你要自己写解析逻辑、自己处理缺失字段、自己写评估函数而 mmdetection 里已经内置了完整的 COCO 数据类、加载器和评估代码。直接选 COCO是最省力且最不会出错的路。COCO 格式的核心是一份 JSON 标注文件。它跟图片是分离的图片按路径存放JSON 里记录图片元信息、目标框、类别信息。这种“标注外置”的做法好处很明显增删图片不需要改动标注文件只要保证 JSON 里写的file_name能找到对应图片即可。还有一个实际考量现在很多标注工具导出的默认格式就是 COCO比如一些团队内部用的标注平台或者开源标注工具一键导出就是 COCO JSON。你用 COCO 格式等于把整个工具链的兼容性问题提前解决掉了。2.2 目录结构到底怎么组织直接给一个我实测下来最舒服的目录结构data/ mydataset/ annotations/ train.json val.json images/ train/ img_001.jpg img_002.jpg val/ img_101.jpgannotations放标注文件images下按训练集和验证集分目录放图片。这样文件数量多了也不会乱而且 mmdetection 的ann_file和img_prefix可以精确指向对应位置。如果你的原始数据集中图片不多全部放在一个images/目录里、train.json和val.json都引用同一批图片文件也不是不行。但我不建议这么做因为训练过程中经常会单独抽查某张验证图片按数据集分目录存放会让排查工作直观很多。另外注意图片格式问题。mmdetection 默认用 OpenCV 读图常见扩展名都能识别但图片和标注里的文件名一定要完全一致大小写也严格区分。文件名不匹配是初学者最常踩的低级错误之一我后面排查章节会专门聊。2.3 标注 JSON 的最小可用结构COCO 标注 JSON 顶层通常有三个字段images、annotations、categories。做目标检测任务时一份最精简的标注文件长这样{ images: [ { id: 1, file_name: img_001.jpg, width: 1280, height: 720 } ], annotations: [ { id: 1, image_id: 1, category_id: 1, bbox: [100, 150, 300, 200], area: 60000, iscrowd: 0, segmentation: [] } ], categories: [ { id: 1, name: defect } ] }逐个解释关键字段尤其是容易理解错的bbox在 COCO 里永远是[x, y, width, height]的格式其中x, y是目标框左上角坐标width和height是框的宽高。不少人习惯用[x1, y1, x2, y2]表示框转 COCO 时经常忘记换算这是模型训练效果差或者评估完全报错的常见原因。area理论上只需要一个浮点数但最好等于width * height很多评估脚本会拿它做面积分档统计。iscrowd默认设为 0。如果你的数据里有挨得很近的目标不要简单地设置成 1 来逃避标注困难因为iscrowd1的实例在训练时会被特殊处理行为可能和你预期不一样。segmentation字段在做纯检测任务时可以留空数组。只有做实例分割才需要填多边形坐标点。不过留空时CocoDataset内部也会给生成一个基于 bbox 的 mask用于某些模型的 mask 分支这个自动填充不影响纯检测训练。2.4 数据校验训练前先写个自检脚本我强烈建议在踏入训练环节之前先花十分钟写一个数据自检脚本。这个习惯帮我省了无数次无意义的训练等待。脚本不需要复杂主要做三件事import json with open(data/mydataset/annotations/train.json, r, encodingutf-8) as f: ann json.load(f) image_ids set(img[id] for img in ann[images]) ann_image_ids set(a[image_id] for a in ann[annotations]) print(images:, len(image_ids)) print(annotations:, len(ann[annotations])) print(categories:, ann.get(categories)) # 检查是否有标注指向了不存在的图片 missing ann_image_ids - image_ids print(missing image ids:, missing) # 检查 bbox 是否越界 import os for a in ann[annotations]: img_info next(img for img in ann[images] if img[id] a[image_id]) x, y, w, h a[bbox] if x 0 or y 0 or x w img_info[width] or y h img_info[height]: print(bbox out of range:, a[id])这段脚本至少能帮你发现四个致命问题image_id对不上、bbox 写成xyxy导致坐标越界、类别 ID 乱跳、标注数量与预期严重不符。其中 bbox 越界问题尤其隐蔽因为很多模型训练时对越界框会做裁剪或过滤但评估时的标准和训练不完全一致最后指标往往很难看。3. 环境安装版本匹配是一切的前提3.1 先定 PyTorch 和 CUDA再选 MMCVmmdetection 的环境安装本身不复杂难在它依赖的 MMCV 和 PyTorch 版本需要严格匹配。开门见山说先确定你要用的 CUDA 版本然后安装与其匹配的 PyTorch最后安装对应版本的 MMCV顺序错了后面全是兼容性报错。一个比较稳妥的组合是 CUDA 11.7 搭配 PyTorch 1.13 或者 2.0 系列。创建虚拟环境的命令通常是conda create -n mmdet python3.8 -y conda activate mmdet pip install torch1.13.1 torchvision0.14.1 --index-url https://download.pytorch.org/whl/cu117 pip install openmim mim install mmcv-full pip install mmdet用openmim安装 MMCV 的好处是它会自动根据当前环境里的 PyTorch 和 CUDA 版本选择合适的编译版本省去手动查表的痛苦。如果你之前手动装过 MMCV 而且不断报undefined symbol多半是编译时的 CUDA 版本和运行时不匹配重装可以解决。还有一点要提醒mmdetection 3.x 和 2.x 的安装方式存在差异。3.x 里mmcv-full已经被同名的新版mmcv取代部分 API 也变了。如果你刚开始做新项目直接选 3.x 就好如果你拿到的是旧代码或者旧教程就继续用 2.x两者不要混用。3.2 安装完成后的快速验证环境装完先别急着跑训练用下面的代码验证一下关键组件能不能正常导入import torch import mmcv import mmdet print(torch:, torch.__version__) print(cuda:, torch.version.cuda) print(mmcv:, mmcv.__version__) print(mmdet:, mmdet.__version__)如果mmcv导入时报错优先检查它编译时用的是哪个 CUDA而不是怀疑安装命令有问题。另外GPU 显存不够的时候不要妄想通过调小 batch size 无限制硬撑有些模型在显存不足时会产生 CUDA OOM而且 OOM 信息不一定直观。稍后排查章节我会专门展开。4. 让 mmdetection 认识你的数据注册与配置4.1 注册机制给新数据集一个“合法身份”mmdetection 使用一个全局注册器来管理系统里的所有模块包括数据集、模型、优化器等等。它的逻辑就是任何类只要带上了注册器的装饰器并且被 import 过就能在配置文件中通过字符串名字被实例化。所以自定义数据集的本质不是“让 mmdetection 自动识别”而是“注册进去”。这一步非常关键却很容易被忽略。很多人在配置文件里写了typeMyDataset却忘了把写好的类 import 进来结果训练一启动就报找不到模块。4.2 自定义 Dataset 类的标准写法最省事的方式是继承CocoDataset只需覆盖CLASSES属性。以工业缺陷检测为例假设你只有一个类别defectfrom mmdet.registry import DATASETS from mmdet.datasets import CocoDataset DATASETS.register_module() class DefectDataset(CocoDataset): METAINFO { classes: (defect,), }如果你用的是 mmdetection 2.x写法略有不同from mmdet.datasets import CocoDataset DATASETS.register_module() class DefectDataset(CocoDataset): CLASSES (defect,)我这里强烈建议把CLASSES或者METAINFO写对不仅因为训练要拿它来构建类别映射还因为它会在训练日志和结果可视化中出现。如果你漏改这个类而配置文件的num_classes又对不上会出现各种奇怪的 shape 错误。写完这个文件后要在mmdet/datasets/__init__.py里把它导入或者更干净的做法在模型配置文件里通过custom_imports指定导入路径。直接改__init__.py对初学者最容易理解但如果你要维护多个项目用custom_imports更规整。4.3 配置文件需要修改的关键位置这里拿经典的 Faster R-CNN 作为例子。基于某个官方预训练配置做微调你只需要关注这几个关键点_base_ configs/faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py model dict( roi_headdict( bbox_headdict(num_classes1))) data dict( traindict( typeDefectDataset, data_rootdata/mydataset/, ann_fileannotations/train.json, img_prefiximages/train/), valdict( typeDefectDataset, data_rootdata/mydataset/, ann_fileannotations/val.json, img_prefiximages/val/), testdict( typeDefectDataset, data_rootdata/mydataset/, ann_fileannotations/val.json, img_prefiximages/val/))num_classes必须和你的实际类别数一致这是最容易出错的地方。它影响检测头最后的输出维度多写少写都会在训练开始时直接报 shape mismatch 错误。data_root、ann_file、img_prefix共同决定数据加载路径。注意img_prefix是相对data_root的路径最终拼接出来的完整路径要能真实访问到图片。4.4 类别数量对网络结构的影响做自定义数据集时很多人只想着改num_classes却忘了想透这个参数到底影响哪里。对于 Faster R-CNN 这类两级检测器bbox_head的num_classes直接决定分类分支的维度对于 YOLO 系列还要额外影响每个 anchor 位置的预测张量长度。这也是为什么我建议你从一开始就理解自己的模型结构而不是单纯做“填空”。类别数一旦变化整个 head 的权重都变了所以自定义数据集通常都会配合“加载预训练权重做微调”一起用而不是从头训。加载预训练能省大量时间但要记得忽略 head 层权重不匹配的问题框架一般会自动跳过。5. 训练与调优从跑通到跑好5.1 训练命令和产物当你把 Dataset 类注册好、配置文件改好训练命令就很标准了python tools/train.py configs/my_defect_config.py --work-dir work_dirs/my_defect--work-dir会存放训练日志、配置备份、每个 epoch 的 checkpoint。建议每次实验都建一个独立的 work-dir而不是复用因为 mmdetection 默认会在配置里定义的work_dir下覆盖旧文件。我习惯在命令行用--work-dir覆盖配置里的值方便实验管理。训练过程中终端会打印当前 epoch、loss 各项数值、学习率、显存占用等信息。如果 loss 一直不下降先检查是不是数据路径错了导致模型什么都没学到再看学习率设置。5.2 理解 loss 数值别被日志唬住训练日志里常见的loss_rpn_cls、loss_rpn_bbox、loss_cls、loss_bbox分别是 RPN 分支和检测头的分类与回归损失。刚开始训练时 loss 数值一般比较大随着训练逐渐降低。如果你的自定义数据集只有 1 类loss_cls通常不会降得特别低因为二分类问题交叉熵的下限不会像多分类那么明显。如果 loss 在第一个 epoch 就变成nan绝大多数情况是学习率设置过大或者数据里出现了异常值。不要在nan出现后继续硬刚先降低学习率再检查标注坐标是否包含无穷大或异常数值。5.3 关于 anchor 和训练技巧的经验之谈很多自定义数据集的目标尺寸和 COCO 差异巨大。比如工业小目标检测目标可能只有几十个像素而预训练模型预设的 anchor 尺寸都是针对 COCO 大目标调的。这种情况下直接训召回率会非常低。你需要修改配置里的anchor_generator做适配或者使用一些专门针对小目标的模型结构。还有一点自定义数据集规模通常不大几百张图、几千个目标已经算不错了。这种规模下一定要加载 COCO 预训练模型并且可以少迭代一些 epoch。不要死守 1x schedule 也就是 12 个 epoch 的设置我实际经验是 50 到 200 张图的小数据集10 个 epoch 左右就已经收敛得差不多再跑下去反而开始过拟合。5.4 评估指标怎么看训练完成后tools/test.py会输出 COCO 风格的评估结果python tools/test.py configs/my_defect_config.py work_dirs/my_defect/best_bbox_mAP_epoch_10.pth --show-dir work_dirs/my_defect/vis指标里最常用的是mAP和mAP_50。mAP是多个 IoU 阈值下的平均值数值通常会比较低mAP_50是 IoU0.5 时的准确率更接近人的感知通常也是工程交付时的验收指标。如果你的mAP_50很高但mAP很低说明检测框位置精度不够可以考虑增加回归损失权重或者做更精细的 anchor 调整。6. 推理、可视化与模型落地6.1 用训练好的权重做推理自定义数据集训练完拿到权重做推理同样简单python demo/image_demo.py images/test.jpg configs/my_defect_config.py work_dirs/my_defect/best_bbox_mAP_epoch_10.pth --out-file result.jpg如果想把推理集成到自己的 Python 项目里直接用 API 会更灵活from mmdet.apis import init_detector, inference_detector model init_detector(configs/my_defect_config.py, work_dirs/my_defect/best_bbox_mAP_epoch_10.pth, devicecuda:0) result inference_detector(model, images/test.jpg)result的结构是根据模型类型变化的Faster R-CNN 等检测模型返回的是类别列表每个类别里包含若干[x1, y1, x2, y2, score]的数组。请注意这里的坐标是xyxy格式和 COCO 标注的xywh不一样解析结果的时候别搞混。6.2 模型导出到部署流程后面做服务化部署时通常需要先把模型导出为静态图格式。mmdetection 官方提供了tools/deployment/相关工具可以把 PyTorch 模型转为 ONNX。但说实话检测模型导出时的后处理比较复杂尤其是 NMS 部分经常要额外处理。如果只是内部快速验证直接用 PyTorch 服务反而省事真正要上生产环境建议在推理框架里重写后处理逻辑。这里有一个很容易踩的坑导出的 ONNX 模型通常只包含模型主干和检测头NMS 不一定包含在内也就是说输出是一堆原始预测框和得分你要自己执行阈值过滤和非极大值抑制。转换前务必确认这一点。7. 常见问题与避坑指南7.1 高频报错速查表这部分内容是我自己一路踩坑积累下来的建议直接收藏。报错关键字常见原因处理方法FileNotFoundError图片路径或标注文件路径拼错检查data_rootann_fileimg_prefix拼接后的实际路径Can not get the file ...file_name与磁盘上的图片文件名不一致严格比对文件名及大小写KeyError: gt_labelsDataset类没正确解析标注检查 annotations 里的categories是否为空或者 category_id 是否存在AssertionError: num_classes ... mismatch配置文件里的num_classes与实际类别数不一致核对bbox_head.num_classes和CLASSES的类别数量shape mismatch预训练权重分类层维度与新模型不一致检查load_from预训练权重的类别数或者正确设置num_classesNaN in loss学习率过大或标注中含有异常坐标降低学习率检查标注坐标是否为有限数值CUDA out of memory显存不足减小samples_per_gpu或者降低输入分辨率必要时更换更小的模型7.2 独家经验如何定位数据类报错训练一启动就报错有时候报错信息很晦涩看起来跟数据没什么关系。我的排查顺序是固定的先单独加载自定义 Dataset 类看能不能拿到一条完整样本。方法是写一个小脚本在训练逻辑之外手动实例化 Datasetfrom mmdet.datasets import build_dataset cfg dict( typeDefectDataset, data_rootdata/mydataset/, ann_fileannotations/train.json, img_prefiximages/train/) dataset build_dataset(cfg) print(len(dataset)) data dataset[0] print(data.keys()) print(data[gt_bboxes], data[gt_bboxes].shape) print(data[gt_labels], data[gt_labels].shape)这一步能把 90% 的数据格式问题暴露出来。如果 Dataset 能正常返回数据但训练仍报错那问题通常出在模型结构或配置上排查范围能缩小很多。7.3 训练速度慢和数据读取瓶颈自定义数据集不大时你可能感觉不到数据读取是瓶颈。但我遇到过图片分辨率很高、磁盘 IO 又慢的情况训练时 GPU 利用率一直上不去整个训练跑得异常憋屈。解决思路是先调大workers_per_gpu默认值是 2可以适当调高到 4 或 8然后再考虑是否把图片统一缩放到一个合适的分辨率。另外不要把所有图片无序堆放在一个目录里。我见过某个项目有十几万张图全在一个目录下加载时系统需要频繁扫描目录速度非常慢。按子目录组织文件或者至少保证数据集规模在你可控范围内。7.4 多类任务类别顺序的坑如果你的自定义数据集有多个类别请把categories按固定顺序放好并且在测试阶段保持同一个顺序。COCO 格式中category_id是真正的类别 ID不要求连续但CLASSES元组里的顺序决定了模型输出的类别索引。这里有一个非常容易翻车的细节如果你的场景里类别 ID 从 0 开始比如defect0, scratch1而CocoDataset默认认为category_id从 1 开始那第一类会因为 ID0 被过滤或者被跳过。保险做法是类别 ID 全部从 1 开始并在标注转换脚本里统一处理不要在生产环境里留着这种洞。8. 一些更偏向工程落地的建议8.1 尽早固定数据版本项目做久了你会发现最大的隐患往往不是模型结构而是“数据集被篡改”。今天有人帮你加了几张正样本明天标注工具重新导出过一次类别名称忽然变了最后训练出来的模型指标变了都不知道原因。建议从一开始就给数据集做版本管理每次改动都记录是谁在什么时间改了什么。哪怕只是把标注文件复制一份存起来也比什么都没有强。8.2 小数据集先跑通再叠加技巧如果你是第一次做自定义数据集不要一上来就尝试复杂的模型尽量使用基础模型先跑通全流程。我自己经常用 Faster R-CNN 这种结构清晰的两级检测器做首次验证因为它的配置最成熟出问题相对容易排查。等数据链路完全稳定了再替换成更轻量或者更强力的模型会比较稳妥。8.3 记录每一次实验的超参数自定义数据集训练中我最后悔的就是前期没有记录超参数组合。同样是这么点数据learning_rate0.02和0.01出来的 mAP 可能差好几个点不同优化器的敏感性也完全不同。每次实验把学习率、batch size、训练轮数、数据增强配置记下来跑完了一并归档后面回看时思路会清晰很多。用已有的work_dirs里的配置文件做记录是不够的因为它只覆盖了初始化代码不会详细记录你的迭代思考。9. 写在最后的小经验根据我实际操作的体会mmdetection 自定义数据集这条链路真正的难度从来不是框架本身而是你是否愿意在训练之前把所有数据的细节整理到位。把标注格式、目录结构、类别顺序这些看似琐碎的事情做完后面所有环节都会顺起来。最后再分享一个很多教程不会强调的小技巧当你用mim install mmcv-full或者其他方式安装环境时一定把版本打印命令存到项目的 README 里等换了机器或者隔了几个月重新跑项目时这份环境记录能让你少折腾一个晚上。自定义数据集的坑无非就是环境、数据、配置三角弄清楚各自的职责边界剩下的事就是耐心调试和迭代了。

mmdetection自定义数据集实战：从COCO标注到训练部署全流程

相关推荐

ThinkPHP6+Layui企业OA系统实战：从环境搭建到二次开发全流程

AI原生硬件：从计算基石到多智能体协同的底层重塑

多层RNN从原理到实战：LSTM/GRU堆叠的表示能力与梯度陷阱

更多资讯

SSM社保系统项目从部署到源码解析：Spring+MyBatis实践指南

SpringBoot+Vue前后端分离实战：高校办公室行政事务管理系统设计与实现

手写 Tool Use 的三种方案：正则、JSON Schema 与注册表模式

Linux命令定位三件套：which、whereis、locate用法详解

180个开源Video Skill：让代码模型真正看懂视频

AI教材写作如何实现低查重？长篇教材结构化落地指南

今日更新

电商智能运营体系从0到1：架构设计、落地步骤与避坑指南

压缩空气储能与热网热惯性联合优化调度：热电联产系统建模与求解

若依框架AI代码生成不稳定？用Agent Skill三层结构+五步法搞定

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？