BlendMask 代码级剖析:blendmask.py 前向推理路径逐行详解
BlendMask 代码级剖析:blendmask.py 前向推理路径逐行详解
BlendMask 是 AdelaiDet 框架下的一款经典实例分割模型,其核心文件 adet/modeling/blendmask/blendmask.py 用不到 150 行代码串联起"骨干网络 → 基底生成 → 候选框预测 → 注意力混合掩码"的完整前向推理路径。本文面向新手,逐行拆解 forward() 中每一步在做什么、数据如何流动,帮你快速读懂这套实例分割源码。
一分钟看懂 BlendMask 前向推理整体架构
在逐行分析前,先建立整体认知。BlendMask 的 forward() 由 4 个关键部件协作完成:
| 部件 | 构建函数 | 作用 |
|---|---|---|
backbone |
build_backbone | 提取 ResNet + FPN 多尺度特征 |
basis_module(ProtoNet) |
build_basis_module | 生成一组全局 mask 基底 |
proposal_generator(FCOS) |
adet/modeling/fcos/fcos.py | 预测候选框 + 注意力系数 |
blender |
adet/modeling/blendmask/blender.py | 用注意力系数加权混合基底,得到每个实例的 mask |
💡 核心思想一句话:不直接回归掩码,而是让模型学一组"通用基底形状",每个实例再用注意力系数去加权组合基底,大幅降低了掩码预测的难度。
入口:forward() 的前 4 步——从图像到骨干特征
forward(batched_inputs) 接收的是 DatasetMapper 输出的 batch 数据(每张图片一个 dict,含 image、instances 等键)。前 4 行完成了输入准备(blendmask.py#L86-L89):
images = [x["image"].to(self.device) for x in batched_inputs]
images = [self.normalizer(x) for x in images]
images = ImageList.from_tensors(images, self.backbone.size_divisibility)
features = self.backbone(images.tensor)
逐行说明:
- 搬运到计算设备:把每张图片 tensor 移到
self.device(GPU/NPU),保证前向计算设备一致; - 像素归一化:
self.normalizer是__init__中定义的闭包,用配置的PIXEL_MEAN/PIXEL_STD做(x - mean) / std,与 ImageNet 预训练权重对齐(blendmask.py#L58-L60); - 批量打包:
ImageList.from_tensors把不同尺寸的图片 zero-pad 到同一尺寸并记录原始image_sizes,供推理后处理时恢复尺寸; - 特征提取:
self.backbone(images.tensor)一次前向得到res3/res4/res5经 FPN 融合后的多尺度特征 dict,后续所有模块都消费这份features。
分支一:basis_module 生成全局 mask 基底
代码第 101~107 行(blendmask.py#L101-L107):
basis_sem = [x["basis_sem"].to(self.device) for x in batched_inputs] if ...
basis_out, basis_losses = self.basis_module(features, basis_sem)
- 输入:骨干特征
features;训练时还附带basis_sem(thing 语义分割目标,用于辅助监督); - 实现:默认的
ProtoNet(basis_module.py#L26-L104)对 FPN 各层特征做卷积精修并逐层相加,再经一个"上采样 + 卷积塔"输出NUM_BASES个通道的全局基底图; - 输出:
basis_out["bases"]是形状为[B, num_bases, H, W]的张量,可理解为"万能形状库";basis_losses是可选的辅助语义损失。
注意:基底是全图共享的,与具体实例无关,这正是 BlendMask 高效的原因。
分支二:FCOS 生成候选框 + top_layer 产出注意力系数
第 109~114 行(blendmask.py#L109-L114):
proposals, proposal_losses = self.proposal_generator(
images, features, gt_instances, self.top_layer)
这里有两个容易被忽略的要点:
- top_layer 是什么:
__init__中定义的nn.Conv2d(blendmask.py#L48-L56),输出通道数为num_bases × attn_size × attn_size。它挂在 FCOS 检测塔的bbox_tower输出上(见 fcos.py#L233-L234),把每个候选位置的特征编码成每基底一组 attn_size×attn_size 的注意力系数; - FCOS 做了什么:分类/回归/centerness 塔前向 → 解码出逐像素得分 →
predict_proposals完成阈值过滤、NMS 选框(fcos_outputs.py#L405-L455),最终返回每张图的proposals(含pred_boxes、pred_scores、top_feat等字段)。
核心一步:Blender 注意力混合得到实例掩码
第 115~116 行把球交给 Blender(blendmask.py#L115-L116):
detector_results, detector_losses = self.blender(
basis_out["bases"], proposals, gt_instances)
blender.py#L34-L103 内部推理路径只有三步:
- ROI 采样:
self.pooler(ROIPooler)在每个预测框内从基底图上切出BOTTOM_RESOLUTION(默认 14×14)的小块; - 注意力 softmax:把候选的
top_featreshape 成[N, num_bases, attn_size, attn_size],插值到 14×14 后做softmax(跨基底维度归一化),保证每个位置是"从哪些基底取形状"的权重分布; - 加权求和:
masks = (rois * coeffs).sum(dim=1),即每个实例掩码 = 各基底在框内区域的软组合,再过sigmoid得到pred_masks,回填到proposals的box.pred_masks中。
训练时(gt_instances 非空)则换用 GT 框采样、按中心性加权计算 BCE mask 损失并返回 loss_mask。
训练/推理双分支:loss 汇总与后处理
forward() 末尾(blendmask.py#L118-L154)按 self.training 分流:
训练分支(L118-L125):把 basis_losses、detector_losses(乘以 instance_loss_weight)、proposal_losses 合并成一个 dict 直接返回,交给优化器统一反传。
推理分支(L127-L154):逐图做后处理——
detector_postprocess把pred_masks从 14×14 插值回原图尺寸,并按输入中的height/width恢复原始分辨率;- 若开启
PANOPTIC_FPN.COMBINE.ENABLED,还会跑语义分割头并用combine_semantic_and_instance_outputs合并出全景分割结果; - 若配置开启
BASIS_MODULE.LOSS_ON,还会输出seg_thing_out供 thing 语义可视化。
最终返回 list[dict],每个 dict 至少含 "instances" 键,这就是你在 demo/predictor.py 里看到检测框 + 掩码的来源。
配置与扩展入口速查
| 想改什么 | 去哪里 |
|---|---|
| 模型超参(基底数、注意力尺寸) | configs/BlendMask/Base-BlendMask.yaml |
| 具体训练配置(学习率、迭代数) | configs/BlendMask/R_50_3x.yaml |
| 换骨干 / 检测器 | adet/modeling/backbone/、adet/modeling/fcos/ |
| 单图演示推理 | demo/demo.py、demo/predictor.py |
| 模型结构文档 | docs/modules/modeling.rst |
常见疑问速查表
Q1:为什么推理时 mask 是 14×14 再放大的?
BOTTOM_RESOLUTION 控制 Blender 池化分辨率,小尺寸计算快、显存省,detector_postprocess 负责放大回原图。
Q2:top_layer 和 blender 的 attn_len 为什么要一致?
两者都等于 NUM_BASES × ATTN_SIZE × ATTN_SIZE,前者产出系数、后者消费系数,配置中改动 BASIS_MODULE.NUM_BASES 时必须同步。
Q3:forward() 返回值在训练和推理时不同,容易出错吗?
这是 Detectron2 的通用约定:训练返回 loss dict,推理返回结果 list。写自定义 meta-arch 时遵循同样契约即可。
总结:blendmask.py 的前向路径可以浓缩为一条流水线——归一化 → 骨干特征 → 全局基底 + FCOS 候选 → 注意力混合掩码 → 双分支输出。读懂这 150 行,你就掌握了 BlendMask "基底 + 注意力"这一实例分割范式的完整脉络,也具备了扩展自定义头部(如全景分割、语义辅助)的能力。