BlendMask 代码级剖析:blendmask.py 前向推理路径逐行详解

原创2026-11-03 14:39:421,979 阅读
文章标签:深度学习计算机视觉

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)

逐行说明:

  1. 搬运到计算设备:把每张图片 tensor 移到 self.device(GPU/NPU),保证前向计算设备一致;
  2. 像素归一化:self.normalizer 是 __init__ 中定义的闭包,用配置的 PIXEL_MEAN/PIXEL_STD 做 (x - mean) / std,与 ImageNet 预训练权重对齐(blendmask.py#L58-L60);
  3. 批量打包:ImageList.from_tensors 把不同尺寸的图片 zero-pad 到同一尺寸并记录原始 image_sizes,供推理后处理时恢复尺寸;
  4. 特征提取: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)

这里有两个容易被忽略的要点:

  1. 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 的注意力系数;
  2. 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 内部推理路径只有三步:

  1. ROI 采样:self.pooler(ROIPooler)在每个预测框内从基底图上切出 BOTTOM_RESOLUTION(默认 14×14)的小块;
  2. 注意力 softmax:把候选的 top_feat reshape 成 [N, num_bases, attn_size, attn_size],插值到 14×14 后做 softmax(跨基底维度归一化),保证每个位置是"从哪些基底取形状"的权重分布;
  3. 加权求和: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 "基底 + 注意力"这一实例分割范式的完整脉络,也具备了扩展自定义头部(如全景分割、语义辅助)的能力。

登录后查看全文
blendmask