简介这是一份基于MMDetection框架的完整实例分割项目压缩包面向计算机视觉研究者、开发者及对深度学习模型感兴趣的技术人员适用于物体识别、图像分析、医学影像处理、自动驾驶等场景。压缩包内包含完整的配置文件、预训练模型、数据处理脚本、训练与评估脚本以及示例数据集并配有详细文档可支撑从数据准备到模型训练再到部署的完整流程。资源共2000个文件以1722个Python脚本为核心涵盖模型构建、训练和推理逻辑242个Markdown文档用于说明环境配置与使用指南22个Shell脚本便于一键执行14个TXT记录配置说明。整个压缩包约32.02MB结构清晰便于快速定位。目前已有288人学习下载适合希望快速掌握MMDetection实例分割核心技术并加速实际项目落地的专业人士可有效提升图像分析精度与研发效率。 做实例分割尤其是想用mmdetection这套工具链跑通一个完整项目的时候很多人的第一反应是去网上找一个“mmdetection.rar 完整配置”之类的压缩包。我见过太多人把包下下来解压、按照里面的readme装环境结果不是torch版本和CUDA对不上就是mmcv编译报错最后连demo都跑不起来。原因很简单真正的“完整配置”不是一组文件能打包的而是环境、数据、配置、训练这条链路里每一个环节都能自洽。这篇东西我按自己实际跑通项目的顺序来写从为什么要选mmdetection做实例分割到环境搭建里最容易炸的版本匹配再到数据标注怎么转成COCO格式、配置文件到底要改哪几处、以及训练启动之后常见的报错怎么定位。整个过程都基于我最近一次从零配置、训练Mask R-CNN和RTMDet实例分割模型的实操记录。不管你是做大作业、毕设还是正经项目落地顺着这条链路走能少踩一大半的坑。1. 先搞清楚实例分割要解决什么问题——以及mmdetection到底方便在哪1.1 实例分割和语义分割、目标检测的本质区别实例分割Instance Segmentation这个任务很多人一开始会跟语义分割搞混。两者都是逐像素分类但语义分割是把图像里所有“人”的像素都归成一类不管有几个人实例分割则要求把每一个独立的人分开第一个人是一个mask第二个人是另一个mask。也就是说实例分割同时做了两件事定位每个实例在哪和分割每个实例精确到像素的轮廓。这个差异直接决定了模型的输出结构。目标检测输出的是框bbox实例分割输出的是“框掩膜mask”。mmdetection里跑Mask R-CNN本质上就是在Faster R-CNN的检测分支旁边多挂了一个mask分支对每个RoI区域做像素级二分类前景/背景。理解了这一点你后面改配置文件、调参的时候才知道每一行在干什么。1.2 为什么选mmdetection而不选YOLO系现在YOLO系也很火尤其是YOLOv8、YOLO11都自带了实例分割能力seg模型很多人会问为什么不直接用ultralytics的库非要折腾mmdetection。我的看法是看你的场景。YOLO系胜在开箱即用pip install ultralytics之后数据格式、训练命令、导出部署全都帮你封装好了适合快速出效果。但mmdetection的优势也很明显模型仓库极其丰富Mask R-CNN、Cascade Mask R-CNN、Mask2Former、RTMDet-ins、SOLO系列全都有现成配置而且它对训练过程的控制粒度更细各种训练策略如soft-nms、多尺度训练、ema都能通过配置文件精确控制适合做学术实验或者需要对照多种backbone效果的场景。如果你是做人工智能大作业或者论文实验我建议直接用mmdetection。它虽然配置门槛高一点但一旦跑通后面换模型、换backbone、改训练策略都非常灵活而且社区和论文引用都是基于这套框架写报告说明的时候更站得住脚。2. 环境搭建里的版本暗坑——这才是“完整配置”的真正含义2.1 torch、CUDA、mmcv三者的版本匹配逻辑我见过太多人在环境这步卡住最核心的问题就是没搞懂mmdetection的版本依赖链条。mmdetection不是独立运行的它的底层依赖是mmcvOpenMMLab的计算机视觉基础库而mmcv需要和torch、CUDA严格对应。这条链条是CUDA驱动版本 → PyTorch版本 → mmcv版本 → mmdetection版本每一层都向上兼容但向下严格约束。比如你系统里驱动是CUDA 12.1装的是torch 2.1.0cu121那对应的mmcv就必须是2.x版本里支持torch 2.1的编译版本。如果mmcv版本和torch版本不匹配最常见的结果是import mmcv直接报undefined symbol错误或者提示找不到某个CUDA算子。MMDetection 3.x还有一个重要的变化它不再使用mmcv.full而改用mmcv也就是mmcv 2.x同时新增了对mmengine的依赖。2.x时代那种pip install mmcv-full1.4.8的写法已经过时了。现在安装mmcv 2.x有两条路# 方式一直接安装预编译包推荐省时省力 pip install mmcv2.1.0 -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.1/index.html # 方式二源码编译只有需要改mmcv底层算子时才用 git clone https://github.com/open-mmlab/mmcv.git cd mmcv pip install -e .2.2 安装顺序与验证含MMDetection 3.x的变化我自己验证过的稳定组合是CUDA 11.8 torch 2.0.0 mmcv 2.0.1 mmdet 3.1.0 mmengine 0.8.4。这套组合在RTX 3090和RTX 4090上都跑过稳定。安装顺序建议严格按下面的来# 1. 创建独立的conda环境别跟别的项目混 conda create -n mmdet python3.9 -y conda activate mmdet # 2. 安装PyTorch注意去官网生成对应的CUDA版本命令 # 这里以CUDA 11.8为例 pip install torch2.0.0 torchvision0.15.0 --index-url https://download.pytorch.org/whl/cu118 # 3. 安装mmcv用官方预编译包 pip install mmcv2.0.1 -f https://download.openmmlab.com/mmcv/dist/cu118/torch2.0/index.html # 4. 安装mmengine和mmdet pip install mmengine0.8.4 git clone -b v3.1.0 https://github.com/open-mmlab/mmdetection.git cd mmdetection pip install -e .装完之后别急着跑训练先做一次完整的“冒烟测试”。这一步很多人跳过结果训练到一半才发现算子有问题。测试方法很简单import torch import mmcv import mmdet import mmengine # 重点验证CUDA算子能不能用 from mmcv.ops import RoIAlign print(全部导入成功cu版本:, torch.version.cuda)如果from mmcv.ops import RoIAlign这行能过说明mmcv的CUDA算子编译是对的。如果报错99%是mmcv版本和torch版本不匹配回头重新装对应的mmcv即可。2.3 环境不兼容的快速排查思路一旦遇到AssertionError: MMCVxxx is used but incompatible with torchxxx这类错误不要慌也别急着重装系统。先执行python -c import torch; print(torch.__version__) pip show mmcv然后去mmcv官网的版本对应表在OpenMMLab文档里有专门的“版本匹配表”页面搜索mmcv 2.x compatibility就行里核对。我常用的判断口诀是mmcv的编译版本号里有cu和torch标识比如mmcv-2.0.1-cp39-cp39-linux_x86_64.whl虽然文件名长但cu118/torch2.0这部分必须和你实际的torch一致。别凭感觉“差不多”不然就是白折腾。还有一个小坑mmdetection 3.x对Python版本有要求3.9是最稳妥的3.10部分版本也能用但3.11以下有些依赖还没完全适配建议直接用3.9省心。3. 数据准备是真正的拦路虎——从标注到COCO格式3.1 标注工具的选型环境装好了很多人觉得万事大吉结果在数据准备这一步直接劝退。跟分类任务不同实例分割的数据标注要同时画框和画轮廓。市面上免费好用的工具里我最推荐LabelMe。原因有三个开源免费、标注的JSON结构简单直观、导出格式和mmdetection需要的COCO格式转换起来最方便。LabelMe标注的时候每个对象用多边形polygon框出来保存下来的JSON文件长这样{ version: 5.2.1, flags: {}, shapes: [ { label: person, points: [[142.2, 153.1], [150.6, 160.5], ...], group_id: null, shape_type: polygon, flags: {} } ], imagePath: 0001.jpg, imageData: null }关键信息就两个label类别名称和points多边形顶点坐标。每张图的JSON里可以有很多个shapes每个shape就是一个实例。单张图片里的多个同类实例比如三个人就会被记录成三个独立的polygon这正好对应实例分割“每个实例一个mask”的需求。3.2 转成COCO格式的脚本思路mmdetection默认用COCO格式你需要把LabelMe的一堆JSON文件合并成一个annotations.json。COCO格式的组织结构是images图片信息、annotations所有实例标注的bbox、segmentation、category_id、categories类别id和名称映射。核心转换逻辑可以拆成四步遍历所有图片给每张图分配一个唯一的image_id记录文件名和宽高。遍历每张图的LabelMe JSON把每个shape的points转成COCO的segmentation格式。注意COCO的polygon格式是一个一维数组形如[x1, y1, x2, y2, ...]而LabelMe存的是[[x1, y1], [x2, y2], ...]需要展平。根据polygon的顶点坐标用最小外接矩形算出bbox记录为[x, y, width, height]。把类别名称映射成从1开始的数字id填到categories里。我贴一段核心的转换精简版代码帮大家理解流程import json import os import glob from pycocotools import mask as maskUtils def labelme_to_coco(labelme_jsons, output_json): coco { images: [], annotations: [], categories: [{id: 1, name: person}] } ann_id 1 for img_id, json_path in enumerate(labelme_jsons, start1): with open(json_path, r, encodingutf-8) as f: data json.load(f) # 图片信息 img_name os.path.basename(data[imagePath]) # 这里建议用cv2或PIL读取真实宽高LabelMe里的可能不准 coco[images].append({ id: img_id, file_name: img_name, width: 1920, height: 1080 }) # 每个shape转一个annotation for shape in data[shapes]: if shape[label] ! person: continue points shape[points] # 展平成COCO polygon格式 flatten [coord for point in points for coord in point] # 计算bbox xs [p[0] for p in points] ys [p[1] for p in points] x_min, y_min min(xs), min(ys) w, h max(xs) - x_min, max(ys) - y_min coco[annotations].append({ id: ann_id, image_id: img_id, category_id: 1, segmentation: [flatten], area: w * h, bbox: [x_min, y_min, w, h], iscrowd: 0 }) ann_id 1 with open(output_json, w, encodingutf-8) as f: json.dump(coco, f, ensure_asciiFalse) labelme_jsons glob.glob(./labelme_jsons/*.json) labelme_to_coco(labelme_jsons, ./annotations/train.json)这段代码只是一个最简版本实际项目中你还需要处理iscrowd重叠多的大群体标注实例分割里一般置0避免训练时冲突、验证标注和图片是否对得上、以及把数据按比例切分为train.json和val.json。切分我一般按8:2或9:1切分逻辑注意随机种子固定别每次跑都不一样。3.3 数据集目录结构数据准备完MMDetection对目录结构有一定要求虽然可以用配置文件自由指定但按下面的惯例来是最不容易出错的data/ └── my_dataset/ ├── train/ │ ├── 0001.jpg │ └── 0002.jpg ├── val/ │ ├── 0003.jpg │ └── 0004.jpg └── annotations/ ├── train.json └── val.json这里有个小技巧图片文件名不要带特殊字符和中文用纯数字加下划线最稳。我之前踩过文件名带空格导致训练时找不到图片的坑排查半天最后是日志里的路径多了一个%20才反应过来。4. 训练一个实例分割模型要改哪些配置4.1 学会读配置文件而不是从零写mmdetection的配置文件是它最强大也最劝退新手的地方。很多人打开一个配置文件看到几十个嵌套字典直接懵了。我的经验是永远不要从零写配置文件永远基于官方提供的现成配置去改。拿Mask R-CNN为例官方配置文件在configs/mask_rcnn/下有一个mask-rcnn_r50_fpn_1x_coco.py。这个文件里没有完整写出所有参数而是大量使用了_base_继承机制。打开一看里面可能只有几行_base_ [ ../_base_/models/mask-rcnn_r50_fpn.py, ../_base_/datasets/coco_instance.py, ../_base_/schedules/schedule_1x.py, ../_base_/default_runtime.py ]这四行分别是模型结构、数据集配置、训练策略、运行参数。理解这个继承结构非常重要你改自己的项目时大部分情况下只需要新建一个配置文件继承这三个基础配置然后覆盖其中一小部分参数即可。4.2 最小修改的三件套基于官方配置做自己的数据集最少要改三处数据集路径、类别数、类别名称。# my_mask_rcnn.py _base_ [ ../_base_/models/mask-rcnn_r50_fpn.py, ../_base_/datasets/coco_instance.py, ../_base_/schedules/schedule_1x.py, ../_base_/default_runtime.py ] # 1. 改数据路径 data_root data/my_dataset/ # 2. 改类别数和名称MMDetection 3.x用metainfo metainfo { classes: (person,), # 只有1个类别注意后面必须带逗号 palette: [(220, 20, 60)] # 可视化时用的颜色 } train_dataloader dict( datasetdict( data_rootdata_root, metainfometainfo, ann_fileannotations/train.json, data_prefixdict(imgtrain/) ) ) val_dataloader dict( datasetdict( data_rootdata_root, metainfometainfo, ann_fileannotations/val.json, data_prefixdict(imgval/) ) ) val_evaluator dict(ann_filedata_root annotations/val.json) # 3. 改模型头部的num_classes model dict( roi_headdict( bbox_headdict(num_classes1), mask_headdict(num_classes1) ) )注意3.x版本的写法跟2.x不一样2.x是classes(person,)写在data里3.x改成了metainfo。网上搜到的很多老教程还在用2.x的写法直接抄会报KeyError: metainfo之类的错。所以每当你搜到一篇博客先看一眼它代码里是data dict(...)还是train_dataloader dict(...)后者才是3.x。4.3 预训练模型权重怎么用训练时用预训练权重做迁移学习效果比随机初始化好一个量级尤其是数据量不大的时候。在配置文件里加一行load_from https://download.openmmlab.com/mmdetection/v2.0/mask_rcnn/mask_rcnn_r50_fpn_1x_coco/mask_rcnn_r50_fpn_1x_coco_20200205-d4b0c5d6.pth如果你网络不好也可以手动下载下来放在本地再把load_from指向本地路径。这里有个概念要区分load_from和resume不是一回事。load_from是加载预训练权重只加载网络层不加载优化器状态resume是从中断的checkpoint恢复整个训练状态包括epoch、优化器、学习率。新手经常把两者混用导致训练断点恢复后学习率异常。如果你想尝试RTMDet实例分割就是热词里那个rtmdet配置文件在configs/rtmdet/下名字一般是rtmdet-ins_s_8xb32-300e_coco.py。RTMDet-ins是anchor-free结构训练速度快很多在单卡上比Mask R-CNN快约30%精度也很能打我个人的建议是如果你的场景不要求必须用Mask R-CNNRTMDet-ins性价比更高。4.4 训练启动命令与显存处理配置改完启动训练就一行命令# 在mmdetection目录下执行 python tools/train.py my_configs/my_mask_rcnn.py --work-dir ./work_dirs/my_mask_rcnn单卡跑没问题但如果你显存只有8G或12GMask R-CNN默认的batch_size2和img_scale(1333, 800)很可能直接OOMout of memory。这时候有几种调整思路按优先级排序减小batch_size在配置里加train_dataloader dict(batch_size1)显存不够时这是最直接的。减小输入图像尺寸把train_pipeline里的img_scale从(1333, 800)改成(1000, 600)显存占用会明显下降代价是精度轻微下降。开启梯度累积如果必须用batch_size1但希望等效batch_size8的效果可以配置optim_wrapper dict(accumulative_counts8)模拟大batch训练。这些参数在官方配置里都有注释逐个覆盖即可。我自己的RTX 3090 24G跑RTMDet-ins_s小模型可以开到batch_size8但跑Mask R-CNN r50只能开到batch_size4这都正常不用焦虑。5. 启动训练之后躲不开的报错与调试5.1 最常见的两类启动失败我把训练启动阶段的报错分为两类一类是环境/算子问题另一类是数据格式问题。环境类问题最典型的就是前文提到的undefined symbol或者ModuleNotFoundError: No module named mmcv.ops这通常是mmcv没装好或者装了不带CUDA算子的纯CPU版。数据格式类问题最典型的错误长这样KeyError: gt_masks出现这个错误基本上是数据集格式不对模型在拿gt_masks真实mask标签的时候没拿到。常见原因有两个一是COCO的annotation里segmentation为空数组二是你在配置里指定的ann_file路径没对准导致加载到的是一个空的annotation。排查方法很粗暴也有效from mmdet.datasets import CocoDataset import mmengine # 直接加载数据集看第一条样本 dataset CocoDataset( data_rootdata/my_dataset/, ann_fileannotations/train.json, metainfo{classes: (person,)}, data_prefixdict(imgtrain/) ) print(len(dataset)) # 看长度是否为0 print(dataset[0].keys()) # 看有没有gt_masks、gt_bboxes等字段如果长度是0检查annotation里images、annotations字段有没有正确写入如果想看单条样本上面这段代码能帮你省下无数时间。5.2 训练过程的监测与断点恢复训练正常启动后你以为就万事大吉了还有一个高频问题训练到一半停了断电、显存炸了、手动ctrlc之前的进度全没了。这时候resume就派上用场了# 从最后一次checkpoint自动恢复 python tools/train.py my_configs/my_mask_rcnn.py --work-dir ./work_dirs/my_mask_rcnn --resume3.x版本里--resume参数会自动从work_dir里最新的epoch_x.pth加载同时恢复优化器状态和学习率。这个是官方推荐的恢复方式比自己手动指定load_from靠谱得多。训练过程中的监测我习惯在配置里打开TensorBoard日志default_hooks dict( loggerdict(typeLoggerHook, interval50), checkpointdict(typeCheckpointHook, interval1, save_bestcoco/segm_mAP) )然后启动命令加一行--vis-backend或者在训练完用TensorBoard看曲线tensorboard --logdir ./work_dirs/my_mask_rcnn重点关注两类曲线loss_cls、loss_mask是否持续下降coco/segm_mAP是否上升。如果loss降了但mAP纹丝不动大概率是数据标注有问题比如category_id和类别对应错了如果loss直接震荡发散大概率是学习率太大了把optim_wrapper里的lr从0.02调小一个量级试试。5.3 用单epoch验证全流程最后分享一个我自己踩过很多次坑后养成的习惯不管配置看起来多完美永远先跑一个epoch验证全流程再丢进去跑完整训练。一个epoch也就几分钟到十几分钟但能帮你提前发现数据路径错误、类别数不匹配、显存不足等问题避免辛辛苦苦训练10个小时后才发现loss没降、模型根本没学到东西。# 先用1个epoch跑通流程 python tools/train.py my_configs/my_mask_rcnn.py --work-dir ./work_dirs/test_run --epochs 1注意3.x里是--epochs不是--max_epochs。跑通之后再看训练日志里的lr、loss、data_time三个字段是否正常。data_time如果异常高比如超过0.5秒说明数据加载管道是瓶颈检查是不是图片太大、磁盘IO慢如果loss从第一步开始就是nan优先检查标注里有没有空的segmentation或异常的坐标值。整个流程走下来从环境搭建到模型跑通关键就一句话先统一版本再规范数据最后小步快跑验证。mmdetection这套工具链确实有上手门槛但一旦你理解了它的配置继承机制和版本依赖逻辑后面换数据集、换模型基本都是半小时内的事。我现在每次开新项目直接复用之前验证过的配置模板改改路径和类别数就能开训省下来的时间都用来调模型本身了。本文还有配套的精品资源点击获取