ESAM 配置文件解读指南：decoder、merge_head 与 test_cfg 三大模块参数完整说明-育师

ESAM 配置文件解读指南：decoder、merge_head 与 test_cfg 三大模块参数完整说明

【免费下载链接】ESAM[ICLR 2025, Oral] EmbodiedSAM: Online Segment Any 3D Thing in Real Time项目地址: https://gitcode.com/gh_mirrors/es/ESAM

ESAM（EmbodiedSAM）是一个在线、实时、细粒度的 3D 实例分割框架，被 ICLR 2025 接收为 Oral。要跑通或微调它，读懂configs/下的配置文件是第一步。这篇文章逐项拆解配置中最关键的三块：decoder（查询解码器）、merge_head（实例合并模块）和test_cfg（推理后处理阈值），帮你快速上手 3D 实例分割模型配置，避免踩坑。

如上图所示，模型依次经过Query Lift（查询提取）→ Query Refinement（查询精炼）→ Query Merging（查询合并）三个阶段，配置文件中的decoder、merge_head、test_cfg正好分别对应图中的 Query Refinement、Merge 与后处理环节。

ESAM 配置文件在哪里、怎么分

所有配置集中在 configs/ 目录，按模型变体分成三个子目录：

目录	说明
configs/ESAM/	完整版 ESAM（基于 SAM 2D 伪标签）
configs/ESAM-E/	效率版 ESAM-E（基于 FastSAM，更快）
configs/ESAM-E+FF/	进一步加特征融合的 ESAM-E+FF

每个子目录里还有两类命名：

*_sv_scannet.py：离线（supervision / 全场景）训练配置，如 ESAM_sv_scannet.py
*_online_*.py：在线流式训练/测试配置，如 ESAM_online_scannet.py

以在线版 ESAM_online_scannet.py 为例，配置开头先声明了几个全局量：

num_instance_classes = 18 # 实例类数（20 个语义类去掉 wall/floor 两个 stuff 类） num_semantic_classes = 20 # 语义类数 num_instance_classes_eval = 18 use_bbox = True # 是否启用 3D 框

后文decoder和test_cfg会直接引用这些变量，改数据集类别数时先改这里。

decoder：查询解码器参数逐项说明

decoder对应图中 "Query Decoder x 3" 的 Transformer 解码器，实现见 oneformer3d/query_decoder.py。参数按功能分组如下：

参数	默认值	含义
`type`	`ScanNetMixQueryDecoder`	解码器类型，支持"超级点 + 点级"混合注意力
`num_layers`	3	Transformer 解码层数
`cross_attn_mode`	`["", "SP", "SP", "SP"]`	每层交叉注意力作用在超级点(SP)还是点级(P)特征上，下标 0 表示第一层前的初始输出
`mask_pred_mode`	`["SP", "SP", "P", "P"]`	每层掩码预测粒度；最后一项必须是`"P"`（点级掩码）
`share_attn_mlp`/`share_mask_mlp`	False	SP 与点级特征是否共享投影 MLP，False 表示各自独立参数
`temporal_attn`	False	是否启用时序注意力（预留扩展）
`num_instance_queries`/`num_semantic_queries`	0	固定可学习 query 数；为 0 表示 query 全部来自超级点选择
`num_instance_classes`/`num_semantic_classes`	18 / 20	实例/语义类别数
`num_semantic_linears`	1	语义分类头线性层数（1 或 2）
`in_channels`	96	输入特征通道数，需与 backbone 的`out_channels=96`对齐
`d_model`	256	Transformer 隐藏维度
`num_heads`	8	多头注意力头数
`hidden_dim`	1024	FFN 中间层维度
`dropout`	0.0	Dropout 率
`activation_fn`	`gelu`	FFN 激活函数
`iter_pred`	True	迭代预测：每层都输出一次结果，前 3 次作为辅助监督
`attn_mask`	True	用上一层掩码生成本层注意力的遮挡掩膜
`fix_attention`	True	交叉注意力中固定"残差 + LayerNorm"结构
`objectness_flag`	False	是否额外预测 objectness 分数（默认用类别置信度）
`bbox_flag`	`use_bbox`	是否输出 3D 框回归头（配合`use_bbox`）

💡 实用提示：想轻量化，优先调num_layers、hidden_dim；想换数据集，重点核对num_instance_classes、num_semantic_classes和in_channels。

merge_head：实例合并模块参数说明

在线推理时，同一物体会在连续帧中被多次检出，merge_head负责为每个实例 query 提取归一化特征向量，供后续"实例合并"做相似度匹配。实现见 oneformer3d/merge_head.py：

merge_head=dict(type='MergeHead', in_channels=256, out_channels=256, norm='layer'), merge_criterion=dict(type='ScanNetMergeCriterion_Fast', tmp=True, p2s=False),

参数	默认值	含义
`in_channels`/`out_channels`	256 / 256	输入/输出特征维度，需与`decoder.d_model`一致
`norm`	`layer`	归一化方式，`batch`或`layer`；在线版推荐`layer`（避免 batch 波动）

其输出特征会做L2 归一化，再被merge_criterion（含时序一致性tmp与点-超级点对齐p2s两个辅助损失）监督。实际"合并哪些实例"的策略由test_cfg.merge_type控制，见下一节。

test_cfg：推理后处理阈值逐项说明

⚠️ 配置文件里其实有两个test_cfg，新手最容易混淆：

模型级：写在model = dict(...)内部，是真正的推理后处理参数（本节约定）
顶层：test_cfg = dict(type='TestLoop')，是 runner 的测试循环类型，不要改

模型级test_cfg在 oneformer3d/mixformer3d.py 的predict_by_feat_instance中被逐个使用，流程是：取 TopK → 置信度过滤 → Mask NMS → 点位数过滤。

参数	ESAM	ESAM-E	作用
`topk_insts`	20	20	从所有 query 中按分数取前 K 个候选实例（注释提示调大可能更好）
`inscat_topk_insts`	100	100	参与实例合并的最大实例数上限
`inst_score_thr`	0.3	0.21	实例类别置信度阈值，低于它直接丢弃（召回率敏感参数）
`pan_score_thr`	0.5	0.5	全景分割实例的分数阈值
`sp_score_thr`	0.4	0.4	超级点掩码二值化阈值（sigmoid 后 > 该值判为实例点）
`npoint_thr`	100	100	最小点数阈值，实例点数过少视为噪声剔除
`obj_normalization`	True	True	用掩码区域平均 sigmoid 值对分数做"对象置信度"归一化
`nms`	True	True	是否启用 Mask Matrix NMS 去重
`matrix_nms_kernel`	`linear`	`linear`	NMS 衰减核函数（`linear`/`gaussian`）
`stuff_classes`	`[0, 1]`	`[0, 1]`	stuff 类（wall、floor），实例分割中不作为 thing 输出
`merge_type`	`learnable_online`	`learnable_online`	在线实例合并策略，`merge_head`特征在此处生效