Mask R-CNN实战：从mask_rcnn_ballon.zip到实例分割训练与推理

简介：面向计算机视觉与深度学习学习者，这份压缩包是Mask R-CNN实例分割的完整实践代码包，帮助掌握从模型原理到气球目标分割的落地方法。压缩包共76个文件，包括11个Python脚本、9个Jupyter交互式笔记、30张JPG图片、14张PNG图片、4个GIF演示动画，另有3个Markdown文档、配置文件与说明文本，总大小约73.68MB，目录结构清晰。已有338人学习下载。内容包含完整的Mask_RCNN-master工程，涵盖核心网络模块、模型构建与训练脚本，并配有多组可视化示例，能够直观理解特征金字塔网络、区域提议网络、掩模分支等关键结构，可直接基于数据包训练和推理，生成气球实例分割结果，覆盖从数据准备、模型训练到结果可视化的完整流程。对于希望深入实例分割技术、动手复现经典模型的读者，具有很高的学习价值。 拿到mask_rcnn_ballon.zip这个压缩包的时候，大概率是两种情况：要么你正在跟着某个目标分割教程走，刚把项目代码下载下来；要么是从朋友、同事或者某个网盘链接里拿到了这份仓库备份。不管哪种，这个文件名本身就包含三个关键信息——mask_rcnn是模型架构，ballon是它配套的小型气球数据集，.zip则是大多数人第一次接触这个项目时会忽略、却又最容易卡住的压缩包格式。

这篇就顺着mask_rcnn_ballon.zip这个文件本身，从解压验证、项目结构解析、环境搭建到训练推理，一步步把整个流程跑通，顺便把我自己踩过的坑和排查思路也一并写出来。无论你是刚入门目标分割的新手，还是已经跑过不少模型、只是想快速验证 Mask R-CNN 效果的老手，这篇都能帮你少走至少半天弯路。

1. 从一个小小 zip 开始——解压、检查与项目来源确认

1.1 解压前的第一道坎：损坏的 zip 包和 EOCD 错误

先问一个问题：你下载完.zip之后，是不是直接右键解压？如果是，那我强烈建议你先换一个思路。.zip是一种极常见的压缩格式，但它有一个非常脆弱的结尾标记——EOCD（End of Central Directory Record）。这个记录位于压缩包末尾，用来告诉解压工具“文件索引在哪里、压缩包目录从哪开始、总共分几段”。一旦 EOCD 损坏或者丢失，解压工具就会抛出一句让人摸不着头脑的报错：

导入资源包失败 caused by: invalid zip archive: could not find eocd

或者是命令行下直接提示“End of central directory record not found”。

出现这个错误，90% 的原因不是文件真的坏了，而是传输不完整。尤其是从网盘、聊天软件、邮件附件里拿到的 zip，经常会有几 KB 的数据被截断。解决办法也很简单：重新下载，或者让发送方重新打包一份。如果文件比较大，建议让对方打包时选“存储模式”再二次传输，减少网络中断导致的损坏概率。

还有一种特殊情况：下载到的 zip 被加密了，解压时提示输入密码。如果密码是你自己设置的却忘了，可以试试百事牛 zip 密码恢复工具这类合法的找回工具；如果是从别人那里拿到的加密包，直接找对方要密码更省事。网上有些号称“无视密码直接解压”的方案，实际成功率很低，而且容易把包解出乱码，不建议浪费时间。

1.2 解压之后先别急着跑：确认项目来源和完整性

解压完成后，第一件事不是打开代码，而是确认这个项目的来源。mask_rcnn_ballon.zip这个名字在 GitHub 上对应的其实是 Matterport 出品的Mask_RCNN仓库，配合balloon数据集做演示。这个仓库年份比较早了（2017 年开源的），代码风格还是典型的 TensorFlow 1.x + Keras 2.x 写法，和现在主流的 PyTorch 生态差别很大。

所以解压之后，先看三样东西：

• 有没有readme.md或者README.md，读一下作者给的说明；
• 有没有requirements.txt，确认依赖版本；
• 有没有samples/balloon目录，这是气球数据集训练脚本所在的位置。

如果这三样都在，说明这个 zip 大概率是完整的。如果缺了samples目录或者mrcnn目录，那不是下载损坏，就是发给你的人只打包了部分文件，这时候直接去 GitHub 搜Mask_RCNN重新下载才是正路。

1.3 GitHub 下载的 zip 包和 git 仓库之间的“关联”问题

这里多讲一句：很多人从 GitHub 页面直接点“Download ZIP”下载Mask_RCNN的压缩包，下来之后发现本地项目没有.git目录，后续想git pull拉取更新，或者想 push 回自己的远程仓库，就会遇到一个经典问题——“GitHub 上下载的 zip 项目与 git 项目关联后，变基到远程仓库失败”。

原因很简单：zip 只是代码文件的快照，不带任何版本历史。你本地git init之后，生成的提交历史和远程完全对不上，变基（rebase）自然失败。

比较顺滑的做法是：

git clone https://github.com/matterport/Mask_RCNN.git

如果实在已经下载了 zip，想关联远程仓库，也别用 rebase，直接：

git init git remote add origin https://github.com/你自己的仓库地址.git git branch -M main git add . git commit -m "initial commit" git push -u origin main --force

--force会覆盖远程历史，适合确定要把本地这份代码作为新起点的场景。不过我的建议依然是：能用git clone就尽量 clone，别去折腾 zip + rebase 的组合。

2. mask_rcnn_ballon 到底是什么——项目结构与算法原理

2.1 一看目录结构，就知道作者想让你怎么用

解压之后，目录结构大概是这样的：

mask_rcnn_ballon/ ├── mrcnn/ │ ├── __init__.py │ ├── config.py │ ├── model.py │ ├── utils.py │ └── visualize.py ├── samples/ │ └── balloon/ │ ├── balloon.py │ ├── inspect_balloon_model.ipynb │ ├── inspect_balloon_data.ipynb │ └── dataset/ │ ├── train/ │ └── val/ ├── assets/ ├── images/ ├── requirements.txt └── setup.py

mrcnn是核心代码库，model.py里是 Mask R-CNN 的完整实现，config.py定义训练和推理的配置项。samples/balloon下的balloon.py是训练脚本入口，inspect_balloon_model.ipynb和inspect_balloon_data.ipynb是两个 Jupyter notebook，分别用来可视化模型效果和数据集情况。

dataset/train和dataset/val下面就是气球数据集了。这个数据集很小，train 大概有 61 张图片，val 有 13 张左右，每张图都有对应的 JSON 标注文件（VIA 格式），标记出气球的多边形轮廓。

2.2 Mask R-CNN 到底做了什么：从检测到分割

Mask R-CNN 这个名字，拆开来看就是“Mask + R-CNN”，在目标检测的基础上多了“实例分割”的功能。普通的目标检测算法（比如 Faster R-CNN）会给你一个边界框，告诉你“这里有一个人”；而 Mask R-CNN 不仅告诉你“这里有一个人”，还会把人像轮廓精确地抠出来，生成一个像素级的掩膜（Mask）。

它的整体流程可以分成四步：

1. 用骨干网络（ResNet50 或 ResNet101）提取图像特征，配合 FPN（Feature Pyramid Network，特征金字塔）在不同尺度上检测物体；
2. 通过 RPN（Region Proposal Network，区域提议网络）生成候选区域，也就是“这张图里大概哪些地方有东西”；
3. 对每个候选区域做 RoIAlign 操作，把不同大小的特征图统一成固定尺寸，这一步比老旧的 RoIPooling 更精确，能保留像素级的位置信息；
4. 在每个候选区域上并行跑三个分支：分类分支预测物体类别、回归分支修正边界框、掩膜分支输出目标的像素掩膜。

用生活化的比喻来说：RPN 就像是“你先扫一眼房间，发现有几个人形轮廓”，RoIAlign 相当于“把每个人形区域裁剪出来，缩放到统一尺寸方便细看”，掩膜分支就像是“沿着每个人的边缘，一笔一笔画出轮廓线”。

2.3 为什么选气球数据集：小数据集跑通全流程

balloon数据集在 Mask R-CNN 社区里几乎成了“Hello World”级别的存在。因为它的数据量小到可以用 CPU 都能完成一次完整的训练（虽然慢），标注格式简单，类别也只有气球一个，非常适合用来验证代码能不能跑通、理解整条训练管线的每个环节。

对新手来说，拿这个数据集练手，意义在于：你不需要像训练 COCO 那样准备几百 GB 的数据，也不用等几天几夜，几个小时内就能看到模型从随机权重逐步学会识别气球的完整过程。对老手来说，这个小项目则是快速测试环境兼容性、验证自定义数据集标注格式的绝佳模板。

3. 环境搭建与依赖安装——最容易劝退新手的环节

3.1 用 conda 隔离环境，别让包互相打架

Mask R-CNN 的requirements.txt里写的依赖基本是 TensorFlow 1.x、Keras 2.x、OpenCV、scikit-image、imgaug 这些老版本。如果你机器上已经装了 TensorFlow 2.x，直接装这个项目会用不了，因为 API 变化太大，model.py里大量调用都会直接报错。

我的建议是老老实实用 conda 建一个独立环境：

conda create -n mask_rcnn python=3.6 conda activate mask_rcnn pip install -r requirements.txt

Python 版本我推荐 3.6。为什么不用 3.7 或更高？因为这个项目依赖的某些旧库（比如scikit-image==0.13.1、imgaug），在更高版本上容易出现编译错误。Windows 上尤其如此，比如pycocotools在 Windows 下需要 Microsoft C++ Build Tools 才能装得起来，缺少编译环境时会报一堆红色错误。

3.2 requirements.txt 里面的版本玄机

打开requirements.txt，你看到的不是一堆版本号，而是一堆“历史包袱”：

numpy scipy Pillow cython matplotlib scikit-image tensorflow>=1.3.0 keras>=2.0.8 opencv-python h5py imgaug IPython[all]

这些都没锁死版本。但实际跑起来你就会发现，numpy 版本太高可能和旧版 TensorFlow 冲突，opencv-python版本太新可能报依赖问题。实测下来比较稳的组合是：

• tensorflow==1.14.0或tensorflow-gpu==1.14.0
• keras==2.2.4（TensorFlow 1.x 配套版本）
• numpy==1.16.4
• scikit-image==0.13.1（更高版本会报circle参数变更之类的错误）
• opencv-python==4.1.0.25

装的时候建议分批装：

pip install numpy==1.16.4 scipy==1.2.1 Pillow==6.0.0 cython matplotlib==3.0.3 pip install scikit-image==0.13.1 opencv-python==4.1.0.25 pip install tensorflow==1.14.0 keras==2.2.4 pip install h5py==2.10.0 imgaug IPython[all]

这里特别说一下h5py。如果你之后要用model.load_weights(filepath, by_name=True)加载预训练权重，h5py 版本太新（比如 3.x）会报AttributeError: 'str' object has no attribute 'decode'，这是很经典的一个坑，解决办法就是不升级到 h5py 3.0。

3.3 实测的安装顺序和加速技巧

安装顺序上有个小技巧：先装 numpy、scipy、matplotlib 这类基础库，再装 scikit-image 和 opencv，最后装 Tenso rFlow 和 Keras。因为 TensorFlow 1.x 对 numpy 版本很敏感，后装可以避免 pip 自动升级 numpy 导致环境破坏。

如果下载速度慢，可以切到国内镜像源：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tensorflow==1.14.0

有 GPU 的同学，tensorflow-gpu==1.14.0对应的 CUDA 版本是 10.0，cuDNN 是 7.4。版本不匹配的话，import tensorflow时会报找不到cudart64_100.dll（Windows）或libcudnn.so.7（Linux）。我当时从 CUDA 9.0 切到 10.0 之后，才终于把这关过了。如果没有 GPU，CPU 版本跑这份数据也是没问题的，就是把训练时间拉长，具体效果下面会讲到。

4. 训练与推理实操——把代码真正跑起来

4.1 下载预训练权重，准备数据集标注

balloon.py里默认会从 COCO 预训练权重开始加载：

COCO_MODEL_PATH = os.path.join(ROOT_DIR, "mask_rcnn_coco.h5")

这个mask_rcnn_coco.h5大约 240 多 MB，在项目仓库的 releases 页面可以直接下载。为什么需要它？因为气球数据集只有 61 张训练图，从头开始训练几乎不可能收敛。用 COCO 上预训练好的权重做初始化，相当于让模型先把“识别物体边缘、提取特征”这些通用能力学会，再针对“气球”做小幅调整。

数据集部分，samples/balloon/dataset下自带 train 和 val 目录，里面每张图片对应一个.json标注文件。如果你想加入自己的图片，注意看一下标注格式，这个项目用的是 VIA 工具导出的 JSON，格式和 COCO 的 JSON 有些差别，不要混用。

4.2 训练前要改的 3 个关键参数

在balloon.py里，BalloonConfig这个类中有几个参数是需要根据自己机器情况调整的：

class BalloonConfig(Config): NAME = "balloon" IMAGES_PER_GPU = 1 STEPS_PER_EPOCH = 100 num_classes = 2

第一，IMAGES_PER_GPU默认是 1，如果你的显卡显存小于 8GB，建议保持这个值，调高会直接 OOM（显存溢出）。第二，STEPS_PER_EPOCH是每个 epoch 的训练步数，默认 100，小数据集可以改成 50，节省时间。第三，num_classes = 2表示背景 + 气球两个类别，如果你换了自己的数据集，这个数要改成“你的类别数 + 1”。

训练命令行是：

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

实测在没有 GPU 的纯 CPU 机器上，每个 epoch 大概需要 10~20 分钟，训练 10 个 epoch 就能看到明显效果。有 GPU（比如 RTX 3060 及以上的）的话，每个 epoch 可以压缩到一两分钟。

4.3 训练过程中的监控与中断恢复

训练开始后，你会看到类似下面的日志：

Epoch 1/10 100/100 [==============================] - 356s 4s/step - loss: 0.6543 - rpn_class_loss: 0.0236 - rpn_bbox_loss: 0.1341 - mrcnn_class_loss: 0.0874 - mrcnn_bbox_loss: 0.2355 - mrcnn_mask_loss: 0.1737

这里的loss是总体损失，后面几个是分项损失。关注rpn_bbox_loss和mrcnn_mask_loss两个值即可，这两个分别负责“目标框位置”和“分割掩膜”的学习，如果它们一直不降，大概率是学习率不合适或标注数据有问题。实际训练时，我发现第 1 个 epoch 的 loss 下降最快，后面逐渐变慢，这是正常的。

训练中断了怎么办？Mask R-CNN 的 checkpoint 会自动保存在logs目录下，每个 epoch 结束都会保存一个.h5文件。想接着训练，只需要把--weights参数指向最新的 checkpoint 文件即可：

python samples/balloon/balloon.py train --dataset=samples/balloon/dataset --weights=logs/balloon20250101T1234/mask_rcnn_balloon_0005.h5

这样会从第 6 个 epoch 继续，不会白白浪费之前的时间。

4.4 用训练好的模型对新图片做推理

训练结束后，预测脚本会写在inspect_balloon_model.ipynb里。核心代码其实不复杂，提取出来就是：

import numpy as np import skimage.io import mrcnn.model as modellib from samples.balloon.balloon import BalloonConfig config = BalloonConfig() model = modellib.MaskRCNN(mode="inference", config=config, model_dir="logs") model.load_weights("logs/mask_rcnn_balloon_0010.h5", by_name=True) image = skimage.io.imread("你自己的图片.jpg") results = model.detect([image], verbose=1) r = results[0] for i, score in enumerate(r["scores"]): if score > 0.7: print(f"检测到目标，置信度: {score:.2f}")

得到r["rois"]可以画出边界框，r["masks"]就是逐像素的掩膜，用plt.imshow叠加到原图上就能看到分割效果。

如果你只训练了 10 个 epoch，效果可能不太完美——气球边缘会有锯齿感，部分小气球会漏检。这是正常的，把训练 epoch 加到 30，或者增加训练图片数量，效果会明显提升。我当时只用了 61 张训练图训练 20 个 epoch，对新增的完全不同背景的气球图片，置信度大概在 0.85 上下，分割边缘总体不错，但部分被遮挡的边界还是不够干净。

5. 实操中高频踩坑清单与处理建议

5.1 几个能提前避开的坑

第一，tensorflow调用 GPU 内存不够时有两个变化：显存不足会崩，显存恰好够但空间被其它程序占用时会非常慢。建议训练前关掉浏览器、Jupyter 之外的占用程序，或者设置：

config.GPU_COUNT = 1 config.IMAGES_PER_GPU = 1

第二，load_weights过程中报HDF5相关错误，多半是 h5py 版本问题。这个上面标题已经说过了，降级到 2.10.0，基本可以解决。

第三，Windows 下运行balloon.py容易因为路径分隔符问题报找不到文件。建议在项目根目录新建一个train.bat：

conda activate mask_rcnn python samples/balloon/balloon.py train --dataset=samples\balloon\dataset --weights=coco pause

5.2 5 个常见问题速查表

5.3 换用自己的数据集时，要注意什么

从气球换到自己的数据集，需要三步改动：准备图片和标注文件，改成 VIA 或 COCO 格式；修改BalloonConfig里的NAME和num_classes；修改balloon.py里的load_mask函数，让它读取你自己的标注格式。

特别提醒一点：标注文件里的多边形坐标要与图片分辨率严格对应。如果图片被缩放或裁剪过，标注坐标却没跟着改，训练出来的模型会异常，损失值波动极大。我试过一次把标注好的 1920×1080 图片缩放到 1024×1024 用于推理，结果掩膜偏移了将近 1/5 的图幅，排查了很久才发现是坐标没有映射回去。

写在最后

以我的经验来看，mask_rcnn_ballon.zip这份资源最适合走一遍“理解实例分割全流程”的路线：下载、解压、建环境、跑训练、看推理结果，一气呵成。整个过程会碰到若干坑，但每个坑背后都对应一个实操知识点——比如 EOCD 错误让你学会检查文件完整性，h5py 版本冲突让你理解深度学习环境对依赖版本有多敏感，git rebase失败让你意识到 zip 快照和 git 仓库的区别。

最后再分享一个小技巧：如果你手头有多台机器，建议在 GitHub 上先 fork 一份 Mask R-CNN 仓库，再 clone 到自己每个工作环境里。这样任何一次代码改动（比如改了自己的数据集路径），你都能通过git diff清楚看到改了哪些地方，回退也方便。别像我当年那样，反复下载 zip、反复覆盖本地文件，最后连自己改了什么都找不回来。

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