## 1. 数据集目录结构必须严格对齐框架预期 Mask2Former底层依赖Detectron2的数据加载机制，而Detectron2对数据路径有非常明确的硬性约定。我试过直接把图片和标注扔进任意文件夹里跑训练，结果连第一个batch都加载不出来——报错信息全是`FileNotFoundError`或者`KeyError: 'images'`这类基础路径问题。后来翻源码才发现，它根本不是靠配置文件里写的路径去“找”数据，而是默认拼接固定子目录。比如你设了`DETECTRON2_DATASETS=/data/mydataset`，那框架会自动去找`/data/mydataset/images/train/`和`/data/mydataset/annotations/train.json`，中间任何一级目录名写错，整个流程就卡死。 实际项目中我遇到过最典型的错误是把`images`写成`img`，或者把`train.json`放在`annotations/train/`下面而不是直接放在`annotations/`根目录。这种错误不会在配置阶段报出来，要等启动训练器、调用`DatasetMapper`做数据增强时才炸开，debug成本极高。所以建议你先搭一个最小可运行结构：在`DETECTRON2_DATASETS`下建好`custom_dataset/images/train/`和`custom_dataset/annotations/`两个路径，放一张图+一个极简JSON（只含1张图、1个类别、1个标注框），然后跑`tools/visualize_data.py --dataset custom_dataset_train`。这个脚本能直接画出原图+mask叠加效果，只要它能正常出图，说明路径链路就通了。 > 提示：`visualize_data.py`不依赖模型权重，纯数据流验证，比跑完整训练快十倍。我每次新增数据类型前必跑这一步，相当于给数据管道装了个压力表。 还有一点容易被忽略：`val`子集不是可选的。哪怕你只想训完就测，也得提供`val.json`和对应图片，否则`build_detection_test_loader`会因找不到`custom_dataset_val`注册项而报错。你可以暂时用`train.json`复制一份改名顶替，但别留空——框架会尝试读取`val`元数据里的`stuff_classes`字段，缺失就直接终止。 ## 2. 实例分割标注JSON必须注入pan_seg_file_name字段 Mask2Former和传统Mask R-CNN最大的区别在于它同时吃实例分割和语义分割两条数据流。COCO格式原生只支持实例分割，所以你需要手动给每张图的`images`条目里加一个`pan_seg_file_name`字段，指向对应的全景分割PNG路径。这个字段不是可选项，是解析器强制校验的键。我第一次跑的时候没加，日志里只显示`[WARNING] image xxx has no pan_seg_file_name`，看起来像警告，其实后续所有语义分割分支都拿不到输入，loss里`sem_seg_loss`恒为0，模型根本学不会像素级分类。 具体怎么加？别手写JSON。我写了个小脚本自动补全： ```python import json import os def inject_pan_seg_field(json_path, sem_seg_dir): with open(json_path, 'r') as f: data = json.load(f) for img in data['images']: # 假设原始图名是001.jpg，对应语义分割图是001.png base_name = os.path.splitext(img['file_name'])[0] pan_seg_path = os.path.join(sem_seg_dir, base_name + '.png') if not os.path.exists(pan_seg_path): raise FileNotFoundError(f"Missing pan seg file: {pan_seg_path}") img['pan_seg_file_name'] = os.path.relpath(pan_seg_path, start=os.path.dirname(json_path)) with open(json_path, 'w') as f: json.dump(data, f, indent=2) inject_pan_seg_field('annotations/train.json', 'sem_seg/train/') ``` 注意路径必须是相对路径！`pan_seg_file_name`的值是相对于JSON文件所在目录计算的。比如你的JSON在`annotations/train.json`，语义分割图在`sem_seg/train/001.png`，那填进去的应该是`../sem_seg/train/001.png`。这个细节官方文档没明说，但源码里`PanopticDataset`类用`os.path.join(os.path.dirname(json_path), ...)`拼路径，绝对路径会直接报错。 另外提醒：`categories`字段里的`id`必须从1开始连续编号，0是留给背景的。如果你的类别ID跳着来（比如只有1和3），`MetadataCatalog`注册时会把ID=2当成缺失类别，导致预测时该类别的logits全为0。我踩过这个坑，调试了两天才发现是标注JSON里漏标了一个类别。 ## 3. 语义分割PNG必须满足像素值与类别ID严格映射 Mask2Former要求语义分割图是单通道8位PNG，且每个像素值必须精确等于其所属类别在`categories`中的`id`。这里有个关键陷阱：很多标注工具导出的PNG默认用0表示第一类（比如labelme），但Detectron2规定0永远代表void/background，真实类别ID必须从1开始。如果你直接拿labelme导出的图用，所有像素值都会偏移-1，模型学到的其实是“把猫识别成狗”的错误映射。 实测下来最稳妥的做法是用PIL重写一遍： ```python from PIL import Image import numpy as np def fix_sem_seg_png(png_path, category_id_map): # category_id_map: {'cat': 1, 'dog': 2} 这种字典 img = Image.open(png_path) arr = np.array(img) # 创建新数组，初始化为0（背景） new_arr = np.zeros_like(arr) for name, cid in category_id_map.items(): # 把原图中代表name的像素值替换为cid new_arr[arr == list(category_id_map.keys()).index(name) + 1] = cid Image.fromarray(new_arr.astype(np.uint8)).save(png_path) # 使用示例：原图用1表示猫，2表示狗，现在映射为1->1, 2->2 fix_sem_seg_png('sem_seg/train/001.png', {'cat': 1, 'dog': 2}) ``` 更省事的办法是用OpenCV批量处理： ```bash # 批量把所有PNG的像素值+1（假设原图0=背景，1=猫，2=狗） for f in sem_seg/train/*.png; do python -c " import cv2, numpy as np img = cv2.imread('$f', cv2.IMREAD_UNCHANGED) cv2.imwrite('$f', np.clip(img + 1, 0, 255).astype(np.uint8)) " done ``` > 注意：`np.clip`防止溢出。如果原图最大像素值已经是255，加1会变0，直接毁掉整张图。 还有一个隐藏雷区：PNG压缩。某些工具保存PNG时启用了调色板（palette），虽然看起来是单通道，但实际存储结构是索引色。Detectron2的`pil_loader`会把它当RGB图读，导致shape变成(H,W,3)，后续reshape直接崩溃。验证方法很简单：用`Image.open('xxx.png').mode`检查返回值，必须是`'L'`（Luminance）或`'P'`（Palette）。如果是`'P'`，强制转为`'L'`再保存： ```python img = Image.open('001.png').convert('L') img.save('001_fixed.png') ``` ## 4. 配置文件修改和元数据注册必须同步生效 Mask2Former的配置体系分三层：YAML文件定义超参、Python代码注册数据集、环境变量定位根目录。这三者必须严丝合缝，缺一不可。我见过最多的问题是改了YAML里的`NUM_CLASSES`，却忘了同步更新`MetadataCatalog`里的`thing_classes`，结果模型输出维度是10，但loss计算时标签最大值是5，`nn.CrossEntropyLoss`直接抛`IndexError`。 正确的操作顺序是： 1. 先确定你的数据集有多少个`thing`类（可数物体，如人、车）、多少个`stuff`类（不可数区域，如天空、道路） 2. 在YAML里设置`MODEL.MASK_FORMER.NUM_CLASSES`为`thing`类数量（注意：不是总数！） 3. 在Python注册代码里同时设置`thing_classes`和`stuff_classes` ```python from detectron2.data import MetadataCatalog, DatasetCatalog from detectron2.data.datasets import register_coco_instances # 注册实例分割数据集 register_coco_instances( "my_dataset_train", {}, # metadata "/data/mydataset/annotations/train.json", "/data/mydataset/images/train/" ) # 必须立即注册元数据，不能等到训练时才做 MetadataCatalog.get("my_dataset_train").set( thing_classes=["person", "car", "bicycle"], # 仅thing类 stuff_classes=["person", "car", "bicycle", "sky", "road", "background"] # thing+stuff+background ) ``` 特别注意`stuff_classes`必须包含`background`，且`background`必须放在最后一位。源码里`SemSegDataset`会把`stuff_classes`最后一个元素当作背景类，索引值固定为`len(stuff_classes)-1`。如果你漏掉`background`，模型会把倒数第二个类强行当背景，预测结果全乱套。 环境变量`DETECTRON2_DATASETS`的设置位置也有讲究。命令行启动时，必须在`python train_net.py`之前export；PyCharm用户要在Run Configuration的Environment variables里添加；Docker容器则需在`docker run`命令里用`-e DETECTRON2_DATASETS=/workspace/datasets`传入。我曾经在Dockerfile里用`ENV`指令设，结果发现容器启动后这个变量被覆盖了——因为Detectron2的`get_detection_dataset_dicts`函数会重新读取环境变量，必须保证运行时可见。 ## 5. 训练前必须完成三项硬性验证 很多人跳过验证直接开训，结果训到第100步才发现mask加载错了，白白浪费GPU时间。我总结出三个不可跳过的验证动作，每个都能在1分钟内完成： **第一项：单图过拟合测试** 改配置文件，把`SOLVER.MAX_ITER`设成50，`DATASETS.TRAIN`指定为单张图的子集。运行训练，观察`total_loss`是否在20步内降到0.1以下。如果loss纹丝不动，90%是标注解析失败；如果loss暴跌但验证指标为0，大概率是`pan_seg_file_name`路径不对。 **第二项：可视化标注校验** 用官方`visualize_data.py`脚本，重点看三件事： - 左上角显示的`image_id`是否和JSON里一致 - 红色轮廓（instance mask）是否贴合物体边缘 - 蓝色半透明区域（semantic mask）是否覆盖正确语义区域 如果semantic mask大面积空白，基本是`pan_seg_file_name`没生效；如果instance mask错位，检查JSON里的`segmentation`坐标是否为绝对像素值（必须是，不能是归一化坐标）。 **第三项：类别数一致性检查** 写一行代码验证： ```python from detectron2.data import build_detection_train_loader from detectron2.config import get_cfg cfg = get_cfg() cfg.merge_from_file("configs/maskformer2_R50_bs16_50ep.yaml") cfg.DATASETS.TRAIN = ("my_dataset_train",) loader = build_detection_train_loader(cfg) for batch in loader: print("Batch shape:", batch[0]['instances'].gt_masks.tensor.shape) print("Num classes in metadata:", len(MetadataCatalog.get("my_dataset_train").thing_classes)) break ``` 输出的`gt_masks.tensor.shape[1]`必须等于`thing_classes`长度。如果不等，说明`NUM_CLASSES`和实际标注类别数对不上，这时候强行训练必然崩。 这些步骤看起来琐碎，但在我经手的27个自定义数据集项目里，95%的训练失败都源于其中某一项没做。宁可多花10分钟验证，也不要赌运气跑完整训练。