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/ESAMESAMEmbodiedSAM是一个在线、实时、细粒度的 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-EFF/进一步加特征融合的 ESAM-EFF每个子目录里还有两类命名*_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。参数按功能分组如下参数默认值含义typeScanNetMixQueryDecoder解码器类型支持超级点 点级混合注意力num_layers3Transformer 解码层数cross_attn_mode[, SP, SP, SP]每层交叉注意力作用在超级点(SP)还是点级(P)特征上下标 0 表示第一层前的初始输出mask_pred_mode[SP, SP, P, P]每层掩码预测粒度最后一项必须是P点级掩码share_attn_mlp/share_mask_mlpFalseSP 与点级特征是否共享投影 MLPFalse 表示各自独立参数temporal_attnFalse是否启用时序注意力预留扩展num_instance_queries/num_semantic_queries0固定可学习 query 数为 0 表示 query 全部来自超级点选择num_instance_classes/num_semantic_classes18 / 20实例/语义类别数num_semantic_linears1语义分类头线性层数1 或 2in_channels96输入特征通道数需与 backbone 的out_channels96对齐d_model256Transformer 隐藏维度num_heads8多头注意力头数hidden_dim1024FFN 中间层维度dropout0.0Dropout 率activation_fngeluFFN 激活函数iter_predTrue迭代预测每层都输出一次结果前 3 次作为辅助监督attn_maskTrue用上一层掩码生成本层注意力的遮挡掩膜fix_attentionTrue交叉注意力中固定残差 LayerNorm结构objectness_flagFalse是否额外预测 objectness 分数默认用类别置信度bbox_flaguse_bbox是否输出 3D 框回归头配合use_bbox 实用提示想轻量化优先调num_layers、hidden_dim想换数据集重点核对num_instance_classes、num_semantic_classes和in_channels。merge_head实例合并模块参数说明在线推理时同一物体会在连续帧中被多次检出merge_head负责为每个实例 query 提取归一化特征向量供后续实例合并做相似度匹配。实现见 oneformer3d/merge_head.pymerge_headdict(typeMergeHead, in_channels256, out_channels256, normlayer), merge_criteriondict(typeScanNetMergeCriterion_Fast, tmpTrue, p2sFalse),参数默认值含义in_channels/out_channels256 / 256输入/输出特征维度需与decoder.d_model一致normlayer归一化方式batch或layer在线版推荐layer避免 batch 波动其输出特征会做L2 归一化再被merge_criterion含时序一致性tmp与点-超级点对齐p2s两个辅助损失监督。实际合并哪些实例的策略由test_cfg.merge_type控制见下一节。test_cfg推理后处理阈值逐项说明⚠️ 配置文件里其实有两个test_cfg新手最容易混淆模型级写在model dict(...)内部是真正的推理后处理参数本节约定顶层test_cfg dict(typeTestLoop)是 runner 的测试循环类型不要改模型级test_cfg在 oneformer3d/mixformer3d.py 的predict_by_feat_instance中被逐个使用流程是取 TopK → 置信度过滤 → Mask NMS → 点位数过滤。参数ESAMESAM-E作用topk_insts2020从所有 query 中按分数取前 K 个候选实例注释提示调大可能更好inscat_topk_insts100100参与实例合并的最大实例数上限inst_score_thr0.30.21实例类别置信度阈值低于它直接丢弃召回率敏感参数pan_score_thr0.50.5全景分割实例的分数阈值sp_score_thr0.40.4超级点掩码二值化阈值sigmoid 后 该值判为实例点npoint_thr100100最小点数阈值实例点数过少视为噪声剔除obj_normalizationTrueTrue用掩码区域平均 sigmoid 值对分数做对象置信度归一化nmsTrueTrue是否启用 Mask Matrix NMS 去重matrix_nms_kernellinearlinearNMS 衰减核函数linear/gaussianstuff_classes[0, 1][0, 1]stuff 类wall、floor实例分割中不作为 thing 输出merge_typelearnable_onlinelearnable_online在线实例合并策略merge_head特征在此处生效 调参经验漏检多就降低inst_score_thr并调大topk_insts重复框多就调高inst_score_thr或检查 NMS 配置。ESAM-E 把inst_score_thr调到 0.21正是为了配合 FastSAM 分数分布。相关配置与文档索引训练/测试脚本tools/train.py、tools/test.py数据集与训练教程docs/run.md、docs/dataset_preparation.md自定义数据推理docs/demo.md多数据集变体配置configs/ESAM_CA/ScanNet200-CA、configs/ESAM-E_CA/核心实现oneformer3d/mixformer3d.py模型主体、oneformer3d/instance_merge.py实例合并一句话总结decoder决定模型容量与推理粒度SP/P 模式、层数、维度merge_head决定跨帧实例合并的特征质量维度对齐 d_model在线用 layer normtest_cfg决定最终输出的召回与精度阈值 NMS 合并策略三者配合才能既保证实时性又拿到高分的 3D 实例分割结果。改任何一项前先对照本文的默认值表基本就能避免改了配置跑不起来的问题。【免费下载链接】ESAM[ICLR 2025, Oral] EmbodiedSAM: Online Segment Any 3D Thing in Real Time项目地址: https://gitcode.com/gh_mirrors/es/ESAM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考