Mask R-CNN实例分割实战：从气球模板到自定义数据集训练

简介：基于气球数据集的Mask R-CNN实例分割实战代码包，面向目标检测与语义分割初学者、算法工程师及需要落地分割任务的项目开发者，帮助贯通模型原理与训练流程。压缩包共76个文件，涵盖30张真实场景气球jpg、14张网络结构png示意图、11个py核心源码、9个ipynb逐步演示笔记本、4个gif预测效果动图，并带md说明、cfg配置等文件，整体约73.68MB，目录按模块分层组织，便于快速定位。已有339人学习下载。包内Mask_RCNN-master工程完整实现了ResNet/FPN骨干、RPN候选框生成、检测分类与掩模预测分支，配套气球标注数据和训练脚本，可直接运行体验从数据加载、损失优化到推理可视化的全流程；ipynb演示覆盖环境配置、模型训练和效果评估，可视化输出包含边界框、掩模与置信度，方便直观校验模型性能。项目代码也可作为迁移学习基线，用于其他目标检测与实例分割项目，适合作为课程设计或竞赛项目的起步模板。

1. mask_rcnn_ballon.zip 是什么，值不值得花一个周末拆开

mask_rcnn_ballon.zip 标题指向的是一套以 Mask R-CNN 为核心的气球实例分割模板：用几十张标注好的气球图片，把“目标检测 + 像素级掩码”这条完整链路跑通。气球目标边缘清晰、背景干扰少，所以这类模板常年被当作实例分割的入门起点，也是做迁移学习时最顺手的底料。我当初接某公司一个零件表面缺陷分割的需求时，就是靠拆这类模板入的门，后来才发现真正的门槛不在网络结构，而在数据标注格式、版本兼容和训练参数。

这个方向适合两类人：一是刚接触实例分割、想用最小成本看完整链路的新手；二是手里有自定义数据集、想把检测模型升级成分割模型的老手。下面按我实际踩坑的顺序，从环境搭建写到自定义训练，再写到排查和交付，你可以直接照着复现。

2. 跑通最小推理：先把版本矩阵焊死，再看第一张气球图

拿到这类项目，第一步不是看论文，是先把环境固定住。Mask R-CNN 这套代码对版本极度敏感，差一个小版本就可能让你在 import 阶段直接放弃。

2.1 版本兼容是第一个坑：TensorFlow 1.x 世界的遗物

这套模板的代码是在 TensorFlow 1.x 时代写的，后面虽然有人放过兼容 2.x 的分支，但社区里下载量最大的还是 1.x 主线。它并不是不能在新版本上跑，而是你会花大量时间修tf.placeholder、tf.Session这类旧接口，修完还要面对 Keras 2.4 之后 API 合并带来的兼容问题。我的血泪经验是：别跟版本较劲，直接按这个项目年代的常见组合搭环境，一小时跑通，比折腾两天新版更划算。

我一般用 conda 固定一套 3.6 环境，所有依赖都装在这里面，绝不用系统 Python 去跑：

conda create -n mrcnn python=3.6 -y conda activate mrcnn pip install tensorflow==1.15.0 keras==2.2.5 pip install cython numpy scipy pillow opencv-python matplotlib

这套组合是反复踩坑后固定下来的：TensorFlow 1.15 是 1.x 最后一个稳定版，对 CUDA 10.0 的支持最成熟；Keras 必须用独立的 2.2.5，不能顺手装成 TensorFlow 自带的tf.keras，因为模板里大量from keras import layers的写法在tf.keras下行为会有差异。如果你显卡比较新，硬件上装不了 CUDA 10，常见做法是直接用官方 Docker 镜像跑，别在 pip 里硬升版本，升完只会换来更多报错。

注意：Python 3.7 也可以跑，但 3.9 以上会遇到 numpy 与 pycocotools 编译不兼容的问题，建议不要在版本上浪费时间。

环境装好后，需要从仓库发布页拿一份 COCO 预训练权重。为什么一开始就要 COCO 权重而不是从零训练？因为 Mask R-CNN 的 backbone 在 COCO 上已经学会了通用的边缘、纹理和形状特征，你的数据集哪怕只有几十张图，在这些特征上微调也能稳定收敛；从零开始训练的数据量和时间都不是模板默认配置能扛住的。这一步看起来玄学，其实是整套流程里最省事的一环。

2.2 最小推理脚本：加载权重、检测、画掩码

拿到权重和代码后，先别急着训练，优先把推理跑通。这样能确认环境没问题、权重能加载、检测输出长什么样，之后再进训练环节，报错时也更好定位是数据问题还是模型问题。

# inference_demo.py import os import sys import cv2 import numpy as np ROOT_DIR = os.path.abspath("./") sys.path.append(ROOT_DIR) # 保证能 import 到 mrcnn 包 from mrcnn.config import Config from mrcnn import model as modellib from mrcnn import visualize class BalloonConfig(Config): NAME = "balloon" NUM_CLASSES = 1 + 1 # 背景 + 气球，共 2 类 GPU_COUNT = 1 IMAGES_PER_GPU = 1 BACKBONE = "resnet50" config = BalloonConfig() model = modellib.MaskRCNN(mode="inference", config=config, model_dir="./logs") model.load_weights("mask_rcnn_balloon.h5", by_name=True) img = cv2.imread("test.jpg") img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # 模型内部按 RGB 处理 results = model.detect([img], verbose=0)[0] visualize.display_instances( img, results["rois"], results["masks"], results["class_ids"], ["BG", "balloon"], results["scores"])

代码逻辑很直白：sys.path.append把项目根目录加进模块搜索路径，保证import mrcnn能找到包；load_weights里的by_name=True是关键，它让权重按层名逐层匹配，而不是要求整套权重结构和当前 Config 完全一致。因为你的类别数和 COCO 不一样，最后的全连接层和 mask 分支尺寸不同，只有by_name=True才能把 backbone 的权重顺利加载进来并跳过不匹配的层。

mode="inference"告诉模型只构建检测分支，不构建训练用的 loss 分支，省显存也省内存。model_dir="./logs"是模板要求必填的参数，推理时给一个空目录即可。detect接收的是图片列表，所以就算只有一张图也要写成[img]，返回的结果是一个列表，取[0]就是这张图的全部检测信息。display_instances第一个参数必须是 RGB 数组，如果用cv2.imread读出来的 BGR 直接传进去，画出来的掩码颜色会整体偏蓝，这是最容易忽略的细节。

2.3 看懂推理输出：rois、masks、scores 分别是什么

results是一个字典，包含四个字段，搞清楚它们的形状和含义，后面做评估、调试都会顺手很多：

masks的 shape 是推理时还原出来的原图尺寸，但训练时内部用的是 56x56 的 mini-mask 来压缩计算量，推理阶段会通过双线性插值还原回原图大小，所以画出来基本不会有大偏差。如果你的图片特别大，比如超过 2000 像素，还原出来的掩码边缘会有轻微锯齿，这是正常现象，不是 bug。

scores默认的过滤阈值是 0.7，也就是说置信度低于 0.7 的检测框会被直接丢弃。当你发现图上气球漏检时，第一反应不应该是怀疑模型，而是先把DETECTION_MIN_CONFIDENCE调低到 0.5 看看是不是阈值卡掉的。

3. 自己训练一个气球模型：数据格式、必调参数与 loss 曲线

推理跑通之后，才算真正进入正题。这个模板的价值在于它把“标注 → 训练 → 可视化”串成了一条完整的流水线，而你要做的第一步是搞懂它的数据格式。

3.1 VIA 标注转成训练集：JSON 里到底存了什么

气球数据集使用的标注工具是 VIA 网页标注器，导出的是一个 JSON 文件。这个 JSON 的结构和常见的 COCO 标注格式完全不同，顶层是一个以文件名为 key 的字典，每个 key 对应一张图的所有标注信息：

{ "123456.jpg": { "filename": "123456.jpg", "size": 123456, "regions": [ { "shape_attributes": { "name": "polygon", "all_points_x": [210, 235, 280, 240], "all_points_y": [340, 300, 330, 380] }, "region_attributes": {} } ] } }

每个regions数组元素就是一个实例，shape_attributes里存的是多边形顶点坐标。注意region_attributes在气球模板里通常是空的，类别是靠外面包的一层逻辑来区分的；如果换到你的自定义数据，建议在这个字段里写上类别名，比如{"class": "scratch"}，这样后面读标注时不用靠文件名猜类别。

模板里读取这个 JSON 并构造训练数据集的代码大致是这样：

def load_balloon(dataset_dir, subset): dataset = Dataset() dataset.add_class("balloon", 1, "balloon") with open(os.path.join(dataset_dir, "via_region_data.json")) as f: annotations = json.load(f) for filename, anno in annotations.items(): if not filename.endswith(".jpg"): continue image_path = os.path.join(dataset_dir, filename) polygons = [r["shape_attributes"] for r in anno["regions"]] dataset.add_image("balloon", image_id=filename, path=image_path, polygons=polygons) return dataset

add_class的第一个参数是数据集来源名，通常和 Config 的NAME保持一致；add_image里的polygons会被模板内部处理成 RLE 格式的 mask，训练时会按需做缩放和裁剪。这里的subset参数在气球模板里其实没被用到，因为训练集和验证集都用同一个 JSON，靠文件名前缀或者目录区分。换到自己的数据时，我习惯把训练集和验证集分成两个 JSON，不要共用一份，否则验证集的指标会虚高。

3.2 训练参数表：哪些改了立刻影响效果

模板的参数集中在 Config 类里，绝大多数不需要动，但下面这几个改对了能立竿见影，改错了会让人莫名其妙：

NUM_CLASSES永远包含背景这一类，所以气球只有 1 个类别时它要写成 2，自定义数据有 5 个类别时它要写成 6，这个“加 1”经常被忘，导致训练时类别数对不上而报错。RPN_ANCHOR_SCALES是 COCO 数据集上针对大物体的默认值，如果你的目标在图中只占几十个像素，比如小零件缺陷，就必须把 anchor 降到 16 起步，否则小目标会被 RPN 直接过滤掉，训练半天模型什么都学不到。

3.3 训练命令与日志：正常 loss 长什么样

数据放好后，训练命令很简洁，模板的入口脚本接收train子命令：

python balloon.py train --dataset=./balloon --weights=coco

--weights=coco表示从 COCO 权重继续训练；如果哪天想从头训练，可以传--weights=imagenet或者--weights=last。训练分两个阶段是模板的默认行为：第一个阶段只训练 heads（输出头），冻结 backbone；之后从头开始训练所有层。前者学习率保持 0.001，后者建议手动降到 0.0001，否则在您的小数据集上很容易震荡。

训练日志里会打印四类 loss：rpn_bbox_loss、mrcnn_class_loss、mrcnn_bbox_loss、mrcnn_mask_loss。正常形态是前几个 epoch 总 loss 在 2.0 到 3.0 之间快速下降，然后缓慢逼近 0.5 以下；rpn_bbox_loss应该最先降下来，mrcnn_mask_loss最慢，因为它要拟合像素级的掩码。如果你看到 loss 在某个数值上完全不动，那不是正常收敛，是配置出了问题，下一章会详细说。

4. 换到自己的数据：迁移学习中最该动的三个旋钮

气球数据集跑通只是第一步，绝大多数人拆这个模板是为了处理自己的任务。把类别从“气球”换成你的目标，涉及三个核心问题：数据够不够、anchor 合不合适、增强怎么做。

4.1 数据底线：多少图、多少实例才够训练

我先给一个保守的参考线：在 COCO 预训练权重基础上微调，每个类别至少要 50 个实例，最好到 150 个以上；场景要覆盖至少 3 种背景、2 种光照、若干叠加角度。低于这个量，不是不能跑，而是模型会严重过拟合，验证集 AP 和训练集差一大截，部署到新环境几乎必然翻车。

我见过有人用 12 张图去训练一个 3 类分割模型，训练集 loss 降到 0.1，一到测试集检测框乱飞。这不是模型不行，是数据多样性和标注质量撑不起这个任务。实例分割和检测不一样，它要求每个实例的边缘都被准确标注，标注误差大于 2 个像素，掩码 loss 就会在某个值上卡住。

4.2 类别数、anchor 与 ROI 数量的改法

换到自定义数据时，Config 的改法大致是这样，适配一个 5 类小目标缺陷场景：

class DefectConfig(Config): NAME = "defect" NUM_CLASSES = 1 + 5 # 背景 + 5 类缺陷 IMAGES_PER_GPU = 2 # 显存允许就开 2，稳定 BN 统计量 STEPS_PER_EPOCH = 300 VALIDATION_STEPS = 50 RPN_ANCHOR_SCALES = (16, 32, 64, 128, 256) # 小目标关键改动 TRAIN_ROIS_PER_IMAGE = 200 # 训练时每张图采样的 ROI 数 DETECTION_MIN_CONFIDENCE = 0.7

RPN_ANCHOR_SCALES从默认的 32 起跳改成 16 起跳，是为了让 RPN 能产生覆盖小目标的候选框；如果你的目标只占图像面积的 1% 以下，甚至可以考虑在 16 前面再加一个 8。TRAIN_ROIS_PER_IMAGE控制每张图采样多少个 ROI 参与 loss 计算，目标密集时就调高，目标稀疏时可以降到 128 省一点显存。还有一个容易忽略的IMAGE_MIN_DIM/IMAGE_MAX_DIM，默认把输入缩放到 1024 以内，如果你的图本来就是 512x512，记得把IMAGE_MAX_DIM改成 512，否则小目标被缩得更小，等于白标。

4.3 数据增强与过拟合：别让模型背题

模板默认自带一部分增强，主要是随机左右翻转和亮度扰动，但对小数据集来说远远不够。我一般会引入 imgaug 做轻度增强：水平翻转、正负 10 度旋转、0.9 到 1.1 倍缩放、亮度对比度扰动。增强逻辑要保守，旋转角度超过 15 度对很多工业场景是不合理的，会造出物理上不可能出现的样本。

from imgaug import augmenters as iaa augmentation = iaa.Sequential([ iaa.Fliplr(0.5), iaa.Affine(rotate=(-10, 10), scale=(0.9, 1.1)), iaa.MultiplyBrightness((0.9, 1.1)) ]) # 传入模板的 train 函数，训练时对每个 batch 动态增强 model.train(dataset_train, dataset_val, learning_rate=0.0001, epochs=30, layers="all", augmentation=augmentation)

模板的train函数原生支持augmentation参数，所以不需要改模型代码。过拟合的早停信号是mrcnn_mask_loss在训练集上持续下降、验证集上却回升，出现这种情况就先降低学习率、增加增强强度，而不是无脑增加 epoch 数。

5. 避坑排查：这套模板最高频的 5 个翻车现场

以下 5 个问题，是我看到和经历过的最高频现场，按出现概率排序。每条都按“现象 → 原因 → 解决”给出，直接对照你的报错信息。

5.1 import 报错与 Keras 版本打架

现象：import mrcnn时抛出AttributeError: module 'tensorflow' has no attribute 'placeholder'，或者'Model' object has no attribute '...'。 原因：在当前环境里跑的是 TensorFlow 2.x，旧代码还在调用 1.x 的 API；或者是 keras 被装成了 2.4 及以上，和 templates 里的from keras import ...发生混用。 解决：用conda activate mrcnn进固定环境，执行pip list确认tensorflow==1.15.0、keras==2.2.5。如果不想重建环境，在脚本最前面加import tensorflow.compat.v1 as tf; tf.disable_v2_behavior()可以缓解一部分报错，但 run 起来还会有其他问题，不推荐。

5.2 训练 loss 卡住不动

现象：训练 10 个 epoch 后总 loss 停在 1.8 左右不再下降，或者mrcnn_mask_loss从头到尾几乎是一条直线。 原因：最常见的是没有加载 COCO 权重直接从头训练，backbone 需要从头学特征，小数据集根本推不动；其次是学习率设得过大导致 loss 在震荡区间里出不来。 解决：先确认训练命令里--weights=coco；如果把训练切分成 heads 阶段和 all 阶段，all 阶段的学习率降到 0.0001；再检查标注里是否有很多面积小于 2x2 像素的多边形，这种极端小目标会让 mask loss 失去学习信号，直接过滤掉即可。

5.3 推理掩码重叠、边缘毛刺

现象：一张图上多个检测框叠在一起，同一个气球被切成两半，掩码边缘明显锯齿。 原因：DETECTION_MIN_CONFIDENCE设得太低，低质量检测框没有被过滤；或者训练数据里大量实例相互重叠，模型学到的是把重叠区域分给多个实例。 解决：把DETECTION_MIN_CONFIDENCE从 0.7 提到 0.85 试试，先排除阈值问题；标注时把重叠的实例分别完整标出来，不要只标露出来的部分；DETECTION_NMS_THRESHOLD保持默认 0.3 别乱调，调高会让重叠框更多。

5.4 显存不足

现象：训练刚开始就报ResourceExhaustedError: OOM when allocating tensor。 原因：IMAGES_PER_GPU偏大，或者 backbone 用了 resnet101，在 8GB 以下的显卡上很容易超显存。 解决：把IMAGES_PER_GPU改成 1，BACKBONE改成resnet50；如果还不行，把IMAGE_MAX_DIM从 1024 降到 768 或 640，分割任务对分辨率有一定敏感性，但小数据集上 768 和 1024 的差距通常可以接受。

5.5 图片读取失败与数据集加载报错

现象：cv2.imread返回None、JSON 解析时KeyError，或者训练到一半说某个图片路径不存在。 原因：图片路径或文件名包含中文，cv2.imread在大多数版本下对中文路径返回空；或者 VIA 导出时有些图片没有任何标注，regions为空数组。 解决：所有图片名改成英文字母，目录也不要放中文；读图用cv2.imdecode(np.fromfile(path, dtype=np.uint8), cv2.IMREAD_COLOR)替代imread；在数据加载时跳过regions为空或长度为 0 的条目。

6. 从跑通到交付：mAP 评估与导出单文件推理

模型训练好了，下一步是验证它到底能不能用。很多人只看训练 loss 就拍板上线，这是把模型当黑匣子的做法，实际效果要用评估指标说话。

6.1 用 COCO 评估口径算 mAP

模板自带 COCO 风格的评估代码，但使用门槛有点高。我一般用一个更轻量的脚本，直接遍历验证集，逐张图计算 AP 再取平均：

import numpy as np from mrcnn import utils def evaluate_simple(dataset, model, config): aps = [] for image_id in dataset.image_ids: image, gt_mask, gt_class, gt_bbox = dataset.load_image_gt( image_id, config, use_mini_mask=False) pred = model.detect([image], verbose=0)[0] ap, _, _, _ = utils.compute_ap( gt_bbox, gt_class, gt_mask, pred["rois"], pred["class_ids"], pred["scores"], pred["masks"]) aps.append(ap) return np.mean(aps)

compute_ap返回四个值，第一个是 AP，内部按 COCO 的 IoU 阈值从 0.5 到 0.95 取平均，所以这个数字会比只看 IoU=0.5 的 AP 低不少，属于正常现象。如果你想看每个类别的表现，把aps按gt_class分组再分别求平均，能定位到哪个类拖了后腿。评估时注意use_mini_mask=False，否则 gt mask 是 56x56 的，和原图尺寸的预测 mask 算 IoU 会对不上。

6.2 导出单文件推理与命名习惯：给未来的自己留后悔药

模板里的训练脚本和推理脚本耦合得比较紧，我一般会在项目收尾时单独整理一个predictor.py，把 Config 读取、权重加载和detect封装成一个类，输入输出都用 numpy 数组，不依赖 matplotlib，方便接到服务里。因为 Mask R-CNN 的模型体积不小，单次推理在 GPU 上处理一张 1024 图大概要 1 到 2 秒，如果对延迟敏感，可以先把输入图像按比例缩到 768 再推理，速度能快 40% 左右，AP 损失通常在 1 到 2 个点以内。

部署阶段要特别留意一个习惯：模型文件名里带上数据集版本和训练轮数，例如mask_rcnn_defect_20240401_30ep.h5，旁边放一份config.json记录当时的 Config 参数。这个习惯救过我很多次——半年后数据更新重训模型，新旧模型对比效果时，没有命名和参数记录的你，会完全分不清哪个模型对应哪份数据，那才是真后悔药都找不着的时刻。

我现在的习惯是每训完一版模型，先在验证集上跑一遍evaluate_simple，AP 过线再谈部署；AP 不过线就回去看是数据标注问题还是 anchor 配置问题，而不是盲目加 epoch。这套模板的价值就在于它能让你快速建立起这个迭代循环，跑通一次，后续换数据、换场景就都有章可循了。希望帮到你。

本文还有配套的精品资源，点击获取