【Bug已解决】Single-scale image input support for SAM3 Mask Decoder 解决方案一、现象长什么样SAM3 的 Mask Decoder 在官方示例里总是配合多尺度图像特征image encoder 输出的多层特征金字塔。但当你只想用单尺度图像特征比如一个已经提好的单层特征图或想省显存不走多尺度喂给 Mask Decoder 时会报这类错# 现象 A特征层数不够索引越界 IndexError: tuple index out of range File .../models/sam3/mask_decoder.py, line 88, in forward high_res image_features[-1] # 期望多尺度但只给了 1 层 # 现象 B形状对不上 RuntimeError: The size of tensor a (64) must match the size of tensor b (256) # 单尺度特征被当成某一层去和另一层做逐元素操作通道数不一致 # 现象 C字典 vs 列表约定混乱 TypeError: list indices must be integers or slices, not str # 代码里有时按 list 索引image_features[i]有时按 dictimage_features[low]最典型的触发代码你直接拿 backbone 的最后一层特征single-scale传给mask_decoder(image_featuresfeat, ...)而不是传[feat1, feat2, feat3]这种多尺度列表。二、背景SAM 系列含 SAM3的 Mask Decoder 设计上是消费多尺度图像嵌入的image encoder 通常输出若干个不同 stride 的特征图例如 1/4、1/8、1/16、1/32Mask Decoder 内部用neck/fpn把高低层特征融合再做 mask 预测。代码多处直接假设image_features是长度2 的序列并用image_features[-1]、按固定下标取层。问题在于很多实际场景只需要单尺度。比如下游只关心最终分辨率 mask不需要高层语义融合用轻量 backbone 只产出单层特征做 ablation 想验证单尺度是否够用。此时 Mask Decoder 没有单尺度兜底路径于是上面的索引/形状/类型错误就出现了。三、根因根因有三类硬性下标假设多尺度。mask_decoder里写死了low_res image_features[0]、high_res image_features[-1]并对不同层做通道对齐。当image_features只有 1 个元素要么索引越界[-1]其实 OK但image_features[1]之类越界要么两个不同层其实是同一个张量、通道数相同却被当成需要融合的不同层 → 形状断言失败。缺少num_scales自适应。 Mask Decoder 的neck上采样/卷积融合按固定层数构造没有根据输入实际层数动态调整。单尺度输入时应当跳过融合、直接把单层特征送进 mask 预测头。list / dict 约定不统一。 部分实现把多尺度存成 dict{low:..., high:...}另一部分按 list 索引。单尺度输入时用户不知道该传[feat]还是{single: feat}类型错配直接TypeError。四、最小可运行复现下面用纯 Python 模拟Mask Decoder 按固定下标取多尺度、单尺度输入越界/形状错的逻辑from dataclasses import dataclass from typing import List dataclass class FakeFeat: channels: int scale: int # 下采样倍率如 4/8/16/32 def mask_decoder_forward_multi_scale(image_features: List[FakeFeat]): # 真实代码假设至少两层并融合 low(最小 scale) 与 high(最大 scale) low image_features[0] # scale 最小的如 4 high image_features[-1] # scale 最大的如 32 if low.channels ! high.channels: # 需要 1x1 对齐通道 return ffusion {low.channels}-{high.channels} return same channel, concat # 多尺度正常 multi [FakeFeat(256, 4), FakeFeat(256, 8), FakeFeat(256, 16), FakeFeat(256, 32)] print(多尺度:, mask_decoder_forward_multi_scale(multi)) # 单尺度复现问题 single [FakeFeat(256, 16)] try: # 这里虽然 image_features[-1] 不越界但真实逻辑常取 image_features[1] 做中层 mid single[1] # IndexError print(mid) except IndexError as e: print(复现成功(越界):, e) # 复现形状单层被当成两层融合通道不匹配时误判 mixed [FakeFeat(64, 16), FakeFeat(256, 32)] # 用户把单尺度拆成两份但通道不同 print(单尺度误用:, mask_decoder_forward_multi_scale(mixed))运行后对单尺度列表取single[1]会IndexError而把单层复制成两份但通道不同会触发通道对齐逻辑被错误激活正是现象 A/B 的来源。五、解决方案第一层最小直接修复最快的止血在调用 Mask Decoder 前把单尺度特征包装成它期望的多尺度结构复制/上采样成若干层或在 decoder 入口加一个单尺度兜底分支import torch import torch.nn.functional as F def prepare_image_features_for_sam3(image_features, expected_scales4): 第一层修复把单尺度特征适配成 Mask Decoder 期望的多尺度列表。 if isinstance(image_features, torch.Tensor): # 只有一个张量 - 复制成 expected_scales 份单尺度降级方案 return [image_features for _ in range(expected_scales)] if isinstance(image_features, (list, tuple)): if len(image_features) 1: return [image_features[0] for _ in range(expected_scales)] return list(image_features) if isinstance(image_features, dict): # dict 约定按 low/high 取单尺度时两键指向同一张量 if single in image_features: t image_features[single] return [t for _ in range(expected_scales)] return [image_features[low], image_features.get(high, image_features[low])] raise TypeError(f不支持的 image_features 类型: {type(image_features)}) # 使用 single_feat torch.randn(1, 256, 64, 64) # 单尺度 multi prepare_image_features_for_sam3(single_feat, expected_scales4) masks mask_decoder(image_featuresmulti, sparse_prompt_embeddings..., dense_prompt_embeddings...)第一层让用户立刻能用单尺度特征跑通 Mask Decoder无需改动模型权重。六、解决方案第二层结构性改进更彻底的做法是让 Mask Decoder 自身支持num_scales自适应用MaskDecoderFeatureAdapter在 forward 入口统一归一化输入from dataclasses import dataclass from typing import List, Union import torch dataclass class MaskDecoderFeatureAdapter: 把任意尺度的 image_features 归一化为 decoder 内部统一格式。 min_scales: int 1 upsample_single: bool True def normalize(self, image_features): # 统一成 list[Tensor] if isinstance(image_features, torch.Tensor): feats [image_features] elif isinstance(image_features, dict): feats [image_features[k] for k in sorted(image_features.keys())] else: feats list(image_features) if len(feats) 2: # 单尺度通过 1x1 卷积生成一份高层特征避免融合越界 only feats[0] if self.upsample_single: high F.interpolate(only, scale_factor0.5, modenearest) # 通道对齐 if high.shape[1] ! only.shape[1]: conv torch.nn.Conv2d(high.shape[1], only.shape[1], 1) high conv(high) feats [only, high] return feats def forward_decoder(self, decoder, feats, *args, **kwargs): # decoder 内部按 list 索引现在 feats 至少 2 层安全 return decoder(feats, *args, **kwargs) # 使用 adapter MaskDecoderFeatureAdapter() feats adapter.normalize(single_feat) # 单尺度 - [low, high] 至少两层 out adapter.forward_decoder(mask_decoder, feats, sparse_prompt_embeddings, dense_prompt_embeddings)MaskDecoderFeatureAdapter的语义是无论输入是单尺度、多尺度、还是 dict都归一成 decoder 内部安全的list[Tensor]至少 2 层从而根治索引越界与形状错。七、解决方案第三层断言 / CI 守护用 pytest 固化单尺度输入必须被接受且输出形状正确import pytest import torch def test_single_scale_tensor_accepted(): from adapter import MaskDecoderFeatureAdapter adapter MaskDecoderFeatureAdapter() feat torch.randn(1, 256, 64, 64) out adapter.normalize(feat) assert isinstance(out, list) and len(out) 2, \ 单尺度张量必须被归一化为至少 2 层避免 decoder 索引越界 # 两层通道应一致融合不会形状错 assert out[0].shape[1] out[1].shape[1] def test_dict_single_scale_accepted(): from adapter import MaskDecoderFeatureAdapter adapter MaskDecoderFeatureAdapter() feat torch.randn(1, 256, 64, 64) out adapter.normalize({single: feat}) assert len(out) 2 def test_multi_scale_passthrough(): from adapter import MaskDecoderFeatureAdapter adapter MaskDecoderFeatureAdapter() feats [torch.randn(1, 256, 256, 256), torch.randn(1, 256, 64, 64)] out adapter.normalize(feats) assert len(out) 2 # 多尺度不应被改动CI 跑pytest tests/test_sam3_mask_decoder.py以后只要有人又把 decoder 写死成只认多尺度 list测试立刻红灯。八、排查清单当 SAM3 Mask Decoder 喂单尺度特征报错按顺序查报错是IndexError→ decoder 按固定下标取层单尺度层数不够用prepare_image_features_for_sam3包装。报错是形状不匹配通道/分辨率→ 单层被当成两层融合需要通道对齐或生成高层特征。报错是TypeError: list indices ... not str→ list/dict 约定混乱统一成 list 输入。显存允许时直接用官方多尺度输出最稳若必须单尺度确保 adapter 生成至少 2 层且通道一致。改 decoder 内部时永远不要写死image_features[1]改成按实际长度自适应。九、小结Single-scale image input support for SAM3 Mask Decoder 的根因是Mask Decoder 写死了多尺度假设固定下标、固定层数融合、list/dict 约定不统一单尺度输入就索引越界或形状错。第一层调用前用prepare_image_features_for_sam3把单尺度张量包装成期望的多尺度列表立即跑通。第二层用MaskDecoderFeatureAdapter让 decoder 入口自适应任意尺度单尺度自动生成高层特征根治越界与形状错。第三层pytest 断言单尺度张量/字典都被接受、输出至少 2 层且通道一致、多尺度原样透传防止回归。记住视觉 decoder 不要写死特征层数输入归一化层adapter应当把任意尺度统一成内部安全格式而不是让调用方去猜约定。