PaddleSeg 中的 MaskFormer：基于 Set Prediction 的语义分割实现与 ADE20k 训练实战

人工智能计算机视觉预训练【免费下载链接】PaddleSegEasy-to-use image segmentation library with awesome pre-trained model zoo, supporting wide-range of practical tasks in Semantic Segmentation, Interactive Segmentation, Panoptic Segmentation, Image Matting, 3D Segmentation, etc.项目地址https://gitcode.com/gh_mirrors/pa/PaddleSeg点击查看免费下载本文围绕 PaddleSeg 仓库configs/maskformer/目录下的模型文档与配套配置展开系统讲解 MaskFormer 在 PaddlePaddle 上的完整落地形态如何从 4 份 ADE20k 训练配置出发理解其数据增广、Swin Transformer 专用 backbone、Pixel Decoder Transformer Predictor 的解码结构、匈牙利匹配损失以及预训练权重的性能表现与使用注意事项。读完本文你可以直接复刻tools/train.py训练流程并准确解读每个配置项与源码模块之间的对应关系。1. 模型背景为什么逐像素分类不够configs/maskformer/README.md引用的原始论文为Cheng, Bowen, Alex Schwing, and Alexander Kirillov. Per-pixel classification is not all you need for semantic segmentation. Advances in Neural Information Processing Systems 34 (2021): 17864-17875.传统语义分割采用逐像素dense分类范式而 MaskFormer 将分割重构为**集合预测set prediction**问题网络输出一组可学习的 queries每个 query 预测一个类别 二值 mask的三元组通过集合间无重复、无遗漏的预测天然处理多实例重叠区域从而获得更精确的边界与区域划分。PaddleSeg 对这一范式的实现在 paddleseg/models/maskformer.py损失函数实现在 paddleseg/models/losses/maskformer_loss.py两者文件头部均注明参考了原始 MaskFormer 仓库的modeling与criterion.py实现。2. 配置体系四档规模的 ADE20k 训练配方configs/maskformer/目录提供 4 份训练配置全部面向 ADE20k150 类数据集、512×512 训练分辨率、160k 迭代| 配置文件 | Backbone | 输入窗口 | 说明 | |:-:|:-:|:-:|:-| | maskformer_swin_tiny_ade20k_512x512_160k.yml | SwinTransformer_tiny_patch4_window7_224_maskformer | 7×7 | 基准配方其余配置以它为_base_| | maskformer_swin_small_ade20k_512x512_160k.yml | SwinTransformer_small_patch4_window7_224_maskformer | 7×7 | 仅替换 backbone 与预训练权重 | | maskformer_swin_base_ade20k_512x512_160k.yml | SwinTransformer_base_patch4_window7_384_maskformer | 7×7 | 以 large 配置为 base | | maskformer_swin_large_ade20k_512x512_160k.yml | SwinTransformer_large_patch4_window7_384_maskformer | 7×7 | 覆盖训练增广为 640×640 裁剪 |从配置继承关系看tiny 是完整的基准配方small 与 tiny 仅差异在backbone.type和pretrained两个字段large 额外覆盖了训练集ResizeByShort的短边采样范围320~1344max_size: 2560和RandomPaddingCrop的裁剪尺寸640×640因为更大的 backbone 使用 384 预训练尺寸、更高分辨率的训练输入base 则直接继承 large 的数据配置只替换 backbone 为 base 变体。3. 基准配置逐项解析tiny 配方下面以 maskformer_swin_tiny_ade20k_512x512_160k.yml 为蓝本逐段说明其参数含义与源码支撑。3.1 数据集与训练增广batch_size: 4 iters: 160000 train_dataset: type: ADE20K dataset_root: data/ADEChallengeData2016/ transforms: - type: ResizeByShort short_size: [256, 307, 358, 409, 460, 512, 563, 614, 665, 716, 768, 819, 870, 921, 972, 1024] max_size: 2048 - type: RandomPaddingCrop crop_size: [512, 512] - type: RandomDistort brightness_range: 0.125 brightness_prob: 1.0 contrast_range: 0.5 contrast_prob: 1.0 saturation_range: 0.5 saturation_prob: 1.0 hue_range: 18 hue_prob: 1.0 - type: RandomHorizontalFlip - type: GenerateInstanceTargets num_classes: 150 ignore_index: 255 - type: Normalize mean: [0.485, 0.456, 0.406] std: [0.229, 0.224, 0.225]几个关键点多尺度随机短边采样ResizeByShort的short_size是一个离散列表训练时逐图随机取一个短边尺寸并等比缩放max_size: 2048用于限制长边上限。这是 Mask 系列 Transformer 分割模型常用的分辨率增广策略。512×512 随机填充裁剪RandomPaddingCrop将缩放后的图裁剪到统一尺寸保证 batch 内张量形状一致。GenerateInstanceTargets是 MaskFormer 数据流的关键一环。它把稠密语义标注转换为集合预测所需的实例化目标实现见 paddleseg/transforms/transforms.py对当前图像中出现的每个类别生成一个二值 masksem_seg_gt cid并输出gt_classes不足 150 个类别时用ignore_index255补齐与gt_masks形状[num_classes, H, W]未出现的类别对应全 0 mask。这份data[instances]最终被送入损失函数做匈牙利匹配。验证集ResizeByShort: short_size: 512短边缩放到 512 后同样做 ImageNet 均值/方差归一化mode: val表示该数据集用于验证。3.2 模型定义model: type: MaskFormer num_classes: 150 backbone: type: SwinTransformer_tiny_patch4_window7_224_maskformer pretrained: https://bj.bcebos.com/paddleseg/paddleseg/dygraph/ade20k/maskformer_ade20k_swin_tiny/pretrain/model.pdparamsmodel.type: MaskFormer对应 paddleseg/models/maskformer.py 中通过manager.MODELS.add_component注册的MaskFormer类其构造参数与配置字段一一对应num_classes分类头输出维度ADE20k 为 150backbone以嵌套配置动态构建 backbonepretrained若指定init_weight()会调用utils.load_entire_model加载 ImageNet 预训练权重见 maskformer.pysem_seg_postprocess_before_inference默认False控制推理阶段后处理发生在 mask 插值之前还是语义 logits 之后。3.3 优化器与学习率optimizer: type: AdamW weight_decay: 0.01 custom_cfg: - name: backbone lr_mult: 1.0 - name: norm weight_decay_mult: 0.0 - name: relative_position_bias_table weight_decay_mult: 0.0 grad_clip_cfg: name: ClipGradByNorm clip_norm: 0.01 lr_scheduler: type: PolynomialDecay warmup_iters: 1500 warmup_start_lr: 6.0e-11 learning_rate: 6.0e-05 end_lr: 0 power: 0.9这些取值是 Transformer 分割模型的典型超参组合源码层面值得注意的有两点custom_cfg中对norm与relative_position_bias_table关闭权重衰减weight_decay_mult: 0.0。从 maskformer.py 中可以看到 Swin backbone 的相对位置偏置表relative_position_bias_table确实是显式参数对这类偏置/归一化参数不加衰减是社区通行做法clip_norm: 0.01的梯度裁剪非常激进数值很小配合warmup_start_lr: 6.0e-11的近零起点用于抑制 Transformer 训练早期的梯度爆炸这与 Mask 系列 Transformer 分割模型的训练惯例一致。3.4 损失函数loss: types: - type: MaskFormerLoss num_classes: 150 eos_coef: 0.1 coef: [1]MaskFormerLoss的完整语义在第 5 节展开。配置中eos_coef: 0.1是空 queryno-object类的交叉熵权重注意MaskFormer模型的loss_computation会将coef[i]乘到损失上见 maskformer.py此处置 1 表示不做额外缩放。4. 模型结构纵深解析4.1 专用 Swin backbone输出多尺度特征字典配置中的 backbone 类型如SwinTransformer_tiny_patch4_window7_224_maskformer在 paddleseg/models/backbones/swin_transformer.py 中定义。与普通 Swin 配置如SwinTransformer_tiny_patch4_window7_224只输出单个 tensor不同*_maskformer版本的forward将四个阶段的输出组织为字典self._out_features [res2, res3, res4, res5] self._out_feature_strides {res2: 4, res3: 8, res4: 16, res5: 32}并配套output_shape()方法返回{name: {channels, stride}}字典——这正是MaskFormer构造MaskFormerHead时传入backbone.output_shape()的接口。以 tiny 为例embed_dim96通道数依次为 96/192/384/768window_size7且使用patch_normTrue。large 变体base/large 配置则使用pretrain_img_size384的对应实现。4.2 MaskFormerHeadPixel Decoder Transformer PredictorMaskFormerHead 由两部分组成self.pixel_decoder BasePixelDecoder(input_shape) self.predictor TransformerPredictor( input_shape[transformer_in_feature][channels], # 默认 res5 mask_classificationTrue, num_classesnum_classes)BasePixelDecodermaskformer.py是一个 FPN 风格的像素解码器输入按 stride 排序后从深到浅逐层上采样融合每级先经lateral_convs1×1 卷积 GroupNorm把通道数压到 256再与上采样的浅层特征相加过output_convs3×3 卷积 GroupNorm ReLU最深层res5没有 lateral 分支lateral_convs置None直接过 output conv最终经mask_features3×3 卷积256→256输出mask_features供后续线性组合生成 mask。TransformerPredictormaskformer.py是集合预测的核心PositionEmbeddingSinenum_pos_feats128normalizeTrue为像素特征生成正弦位置编码内部Transformer采用d_model256、nhead8、enc_layers0、dec_layers6、dim_feedforward2048的默认结构——注意encoder 层数为 0即 backbone 特征投影后直接进入 6 层 decoder这是语义分割版 MaskFormer 的典型设定nn.Embedding(num_queries100, hidden_dim256)提供 100 个可学习 querydecoder 开启return_intermediate_decTrue深度监督每一层 decoder 的输出都会被收集用于aux_outputs若res5通道数与 256 不一致input_proj1×1 卷积负责投影到hidden_dim分类头class_embed输出num_classes 1 151维多出的最后一维即 no-object/空 querymask 头mask_embed是 3 层 MLP256→256→256最后用paddle.einsum(lbqc,bchw-lbqhw, mask_embed, mask_features)把 query 与像素特征线性组合成每层 decoder 的预测 mask。4.3 推理阶段从 query 到稠密语义图训练时模型直接返回[{pred_logits:..., pred_masks:..., aux_outputs:...}]交给损失函数推理路径maskformer.py则把集合预测还原为逐像素语义 logitsdef semantic_inference(self, mask_cls, mask_pred): mask_cls F.softmax(mask_cls)[..., :-1] # 去掉 no-object 类 mask_pred F.sigmoid(mask_pred) semseg paddle.einsum(qc,qhw-chw, mask_cls, mask_pred) return semseg即对每个 query 先 softmax 取前 150 类概率、sigmoid 激活 mask再以类别概率为权重对所有 query 的 mask 加权求和得到C×H×W的软预测最后经sem_seg_postprocess双线性插值回原图尺寸含去除 padding 区域的裁切。源码注释中标注了典型形状pred_logits为[B, 100, 151]pred_masks为[B, 100, 512, 512]。5. 损失函数匈牙利匹配 三项代价MaskFormerLossmaskformer_loss.py的核心流程目标整理forward把data[instances]中的gt_classes/gt_masks按图拆分过滤掉ignore_index255的补齐项得到每张图的{labels, masks}。匈牙利匹配HungarianMatchermaskformer_loss.py对每个 batch 样本计算num_queries × num_targets的代价矩阵分类代价cost_class -paddle.gather(out_prob, indextgt_ids, axis1)目标类别的负似然概率掩码代价为批量的batch_sigmoid_focal_loss与batch_dice_loss最终代价C cost_mask*C cost_class*C cost_dice*C其中权重来自HungarianMatcher(cost_class1, cost_mask20, cost_dice1)再交给scipy.optimize.linear_sum_assignment求解 1-1 指派。三项损失loss_ce被匹配 query 的交叉熵未匹配 query 的目标类别置为num_classes即 no-object 类且通过empty_weight把最后一类的权重压到eos_coef0.1抑制空 query 被过度惩罚/奖励loss_masksigmoid focal lossalpha0.25, gamma2loss_dicedice loss权重字典固定为{loss_ce: 1, loss_mask: 20, loss_dice: 1}且 6 层 decoder 的前 5 层aux_outputs各自做一遍匹配与计算键名带_i后缀权重与主损失相同深度监督。分布式归一化num_masks会all_reduce汇总各卡目标数再除以 world size下限为 1保证多卡下损失按真实 mask 数平均。这套匹配-计算-深度监督的实现与 PyTorch 原版criterion.py的结构一致文件头注释已声明参考来源差异点在于目标来源是GenerateInstanceTargets从稠密标注派生的伪实例集合因此无需额外的实例标注。6. 训练、验证与推理命令PaddleSeg 的通用入口位于 tools/ 目录。以 tiny 配方为例# 单卡训练 python tools/train.py --config configs/maskformer/maskformer_swin_tiny_ade20k_512x512_160k.yml # 验证指定训练产出的权重目录 python tools/val.py --config configs/maskformer/maskformer_swin_tiny_ade20k_512x512_160k.yml \ --slim_model output_dir/model_final.pdparams # 推理并可视化 python tools/predict.py --config configs/maskformer/maskformer_swin_tiny_ade20k_512x512_160k.yml \ --slim_model output_dir/model_final.pdparams --save_dir output --visual True注意事项dataset_root指向data/ADEChallengeData2016/训练前需按 PaddleSeg 数据规范组织好 ADE20k 的图片与标注文件多卡训练使用tools/train.py的--gpus参数如--gpus 0,1,2,3损失中的num_masks会跨卡归约无需手动换算 batch 语义推理输出为sem_seg软预测 logitssemantic_inference已把 no-object 类去掉softmax/argmax 即可得到 150 类稠密预测。7. 预训练权重性能与官方注意事项configs/maskformer/README.md给出的 ADE20k 验证集结果512×512160k 迭代ModelBackboneResolutionTraining ItersmIoUmIoU (flip)mIoU (msflip)Maskformer-tinySwinTransformer512x51216000047.93--Maskformer-smallSwinTransformer512x51216000050.4--官方 README 同时给出三条重要说明MaskFormer 支持 tiny/small/base/large 四种规格仓库提供了全部四份配置与tiny/small 的预训练权重及训练日志base 和 large 的训练结果未提供官方表述为应当与论文一致should be consistent with the paper即这两档的数值以原论文为准仓库内不给出实测 mIoUbase 与 large 的评测方式与原始代码库一致采用多尺度ms 水平翻转flip的组合评测而 tiny/small 表中给出的是单尺度数字横向对比时需注意评测协议差异环境要求请使用 CUDA 11.2 而非 CUDA 10.2以避免计算 bug。这是该文档明确的适用前提复现训练前应确认 PaddlePaddle 对应 CUDA 版本的安装。预训练权重下载链接以https://bj.bcebos.com/paddleseg/dygraph/ade20k/maskformer_ade20k_swin_{tiny,small}为前缀分别提供model.pdparams微调后权重可直接--slim_model加载与train.logbackbone 的 ImageNet 预训练权重则内嵌在各 yml 的pretrained字段中训练时自动拉取。8. 小结与延伸阅读PaddleSeg 中 MaskFormer 的完整链路可以概括为ADE20k 稠密标注 → GenerateInstanceTargets派生 gt_classes / gt_masks → SwinTransformer_xxx_maskformerres2~res5 多尺度字典特征 → BasePixelDecoderFPN 融合出 mask_features → TransformerPredictor100 queries × 6 层 decoder深度监督 → MaskFormerLoss匈牙利匹配 CE(eos_coef0.1) focal×20 dice×1 → 推理时 semantic_inference 还原为稠密语义 logits若需要进一步深入建议按以下路径阅读源码模型主干 paddleseg/models/maskformer.py、匹配与损失 paddleseg/models/losses/maskformer_loss.py、maskformer 变体 backbone paddleseg/models/backbones/swin_transformer.py、实例目标构造 paddleseg/transforms/transforms.py以及四份 ADE20k 配置 configs/maskformer/ 中 tiny 与 large 在数据增广上的差异。赞分享人工智能计算机视觉预训练【免费下载链接】PaddleSegEasy-to-use image segmentation library with awesome pre-trained model zoo, supporting wide-range of practical tasks in Semantic Segmentation, Interactive Segmentation, Panoptic Segmentation, Image Matting, 3D Segmentation, etc.项目地址https://gitcode.com/gh_mirrors/pa/PaddleSeg点击查看免费下载相关推荐RTFormer基于 Transformer 的实时语义分割网络 —— PaddleSeg 配置、训练与源码解析RTFormer基于 Transformer 的实时语义分割网络 —— PaddleSeg 配置、训练与源码解析 RTFormerReal Time Tra人工智能计算机视觉预训练PaddleSeg PanopticDeepLab 全景分割实战指南基于 PaddlePaddle 的 Bottom-Up 全景分割实现与 Cityscapes 训练部署PaddleSeg PanopticDeepLab 全景分割实战指南基于 PaddlePaddle 的 Bottom Up 全景分割实现与 Cityscape人工智能计算机视觉预训练基于UNET的图像语义分割训练实现解析基于UNET的图像语义分割训练实现解析 项目背景与概述 本文解析的是一个使用PyTorch实现UNET架构进行图像语义分割的训练脚本。UNET是一种经典的编码器示例工程机器学习深度学习教程上一篇Redux Thunk测试驱动开发TDD构建异步逻辑下一篇haipproxy安全防护终极指南如何彻底防止代理池被滥用和攻击创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考