Ultralytics SAM3 视觉主干解析ViTDet Backbonevitdet.py架构与参数全解读【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文是 docs/en/reference/models/sam/sam3/vitdet.md 这一 API 参考页面的深度展开。该页面通过 mkdocstrings 索引了 ultralytics/models/sam/sam3/vitdet.py 模块中的Attention、Block、ViT三个类。本文以这些类的源码 docstring 与实际实现为主体结合 SAM3 在仓库中的真实装配方式完整解读这套 ViTDet 视觉主干的模块职责、每个构造参数的语义以及它在 SAM3 多模态分割链路中扮演的角色。一、模块定位SAM3 的纯 Transformer 视觉特征提取器SAM3 是 Ultralytics 仓库中负责视觉语言分割与视频跟踪的一族模型源码位于 ultralytics/models/sam/sam3。其图像侧编码器并不使用 CNN 金字塔而是直接采用一套纯 ViT主干——也就是 vitdet.py 中实现的ViTDet Backbone。源码文件头说明了它的来源与定位该主干改编自 Detectron2 的 ViTDet 实现原始论文题为Exploring Plain Vision Transformer Backbones for Object Detection即把普通 ViT 当作检测 / 分割骨干直接使用的路线模块内的RoPE旋转位置编码实现参考了多份公开代码文件注释列出的 3 个参考来源均为公开的 rope/rotary embedding 开源实现文件同时携带Copyright (c) Meta Platforms, Inc.的版权声明表明其上游血统。在 SAM3 中这个主干被包在Sam3DualViTDetNeck颈部结构内再与文本编码器组成SAM3VLBackbone最后接入掩码 Transformer 解码链路。因此理解vitdet.py就等于理解 SAM3 图像特征从 patch 化到多尺度特征输出的全过程。模块从内到外包含三个层次与 reference 页面索引一一对应Attention—— 带相对位置编码 2D RoPE的多头注意力单元Block—— 支持**窗口注意力window attention**的标准 Transformer BlockViT—— 由上述 Block 堆叠而成的完整主干负责输出特征图。三者均依赖同目录工具函数modules/utils.py 中的compute_axial_cis、apply_rotary_enc、window_partition、window_unpartition、concat_rel_pos、get_abs_pos并在构造时引用 sam3/model_misc.py 中的LayerScale。二、Attention融合相对位置编码与 2D RoPE 的多头注意力Attention类vitdet.py 中 L40 起是一个即插即用的多头注意力模块。它最大的特点是在标准 QKV 注意力之外提供两条正交的位置信息注入通道可学习的分解式相对位置编码rel_pos与旋转位置编码RoPE。二者互不冲突源码注释明确写到use_ropeindependent of use_rel_pos, as it can be used together。2.1 构造参数参数默认值含义dim必填输入通道数num_heads8注意力头数head_dim dim // num_headsqkv_biasTrue是否在 QKV 线性投影中加入可学习偏置use_rel_posFalse是否向注意力图加入相对位置编码rel_pos_zero_initTrue是否将相对位置参数零初始化否则用trunc_normal_std0.02input_sizeNone输入分辨率用于计算相对位置参数尺寸或 RoPE 尺寸cls_tokenFalse是否存在 cls token存在时 attention map 需相应处理use_ropeFalse是否使用 2D RoPErope_theta10000.0控制 RoPE 频率的基频rope_pt_sizeNone前一训练阶段pretrain的 RoPE 尺寸供插值/平铺使用rope_interpFalse是否把 RoPE 插值而非外推到目标输入尺寸2.2 相对位置编码的初始化_setup_rel_pos开启use_rel_pos后要求提供input_size且不允许与cls_token共存源码断言cls_token is False注册两个可学习参数rel_pos_h、rel_pos_w形状均为(2 * input_size - 1, head_dim)即对 H、W 两个轴向分别建模相对距离若rel_pos_zero_initFalse用trunc_normal_以 std0.02 初始化预计算relative_coords索引张量供前向时直接从 embedding 查表避免逐次计算。2.3 2D RoPE 频域的初始化_setup_rope_freqs开启use_rope后当rope_pt_size为None时以input_size兜底通过functools.partial固定compute_axial_cis(dimhead_dim, thetarope_theta)作为频域计算函数rope_interpTrue时以scale_pos rope_pt_size[0] / input_size[0]缩放坐标实现把预训练分辨率下学习到的频域插值到当前分辨率的目的若携带 cls token会额外拼接一个恒等旋转的极坐标项cls_freqs_cis保证 cls 位置不参与旋转。2.4 前向过程forward同时支持两种布局的输入4D 张量(B, H, W, C)特征图形式此时不允许 cls token3D 张量(B, L, C)序列形式并自动由L推导H W sqrt(L - s)s为 cls token 个数。计算流程见 vitdet.py一次qkv线性投影得到(B, L, 3, num_heads, head_dim)拆出 q、k、v对 q、k 施加 RoPE_apply_rope→apply_rotary_enc若use_rel_pos调用concat_rel_pos(..., rescaleTrue)把相对位置编码拼接进 q、k——这是一种用拼接维度代替加法偏置的等效实现并通过rescale修正缩放因子以配合F.scaled_dot_product_attention详见后文工具函数部分用 PyTorch 的F.scaled_dot_product_attention完成高效注意力计算按原布局4D/3D重组并经过proj输出。三、Block带窗口注意力与 LayerScale 的 Transformer 单元Block类vitdet.py把上面的Attention包装成标准的前置归一化pre-normTransformer Block并叠加三项 ViTDet/SAM 体系常用的工程化组件窗口注意力、Stochastic DepthDropPath、LayerScale。3.1 构造参数Block在透传Attention全部位置编码相关参数的基础上新增了参数默认值含义mlp_ratio4.0MLP 隐藏维与嵌入维之比drop_path0.0Stochastic Depth随机深度概率norm_layernn.LayerNorm归一化层构造器act_layernn.GELUMLP 激活函数window_size0窗口注意力窗口尺寸0 表示不启用窗口注意力dropout0.0残差路径与 MLP 内部 dropoutinit_valuesNoneLayerScale 初始值为None时不启用 LayerScale注意依赖关系Block 内部check_requirements(timm)并从timm.layers导入DropPath与Mlp即该模块的运行环境需要安装timm。3.2 窗口注意力机制当window_size 0时Block 在前向中先调用window_partition(x, window_size)把(B, H, W, C)特征切成互不重叠的若干window_size × window_size窗口必要时自动 padding再送入注意力注意力计算完成后用window_unpartition还原并裁掉 padding见 vitdet.py。窗口注意力的价值在于把O((H·W)²)的全局注意力复杂度降为窗口内的局部计算让深层高分辨率特征成为可行。同时Block构造Attention时若处于窗口模式会把Attention的input_size固定为(window_size, window_size)使位置编码参数大小只与窗口相关。3.3 残差结构shortcut x x norm1(x) # 前置归一化 x (window_partition) → attn → (window_unpartition) x ls1(x) # LayerScale若启用 x shortcut dropout(drop_path(x)) x x dropout(drop_path(ls2(mlp(norm2(x))))) # 第二条残差其中LayerScale来自 sam3/model_misc.py以逐通道可学习缩放系数init_values为初值作用在注意力/MLP 输出上是稳定深层 Transformer 训练的重要技巧。每个 Block 的drop_path概率由上层 ViT 按 stochastic depth 递减规则逐一分配。四、ViT由 32 层 Block 组成的完整主干ViT类vitdet.py是模块的顶层封装docstring 明确引用了 ViTDet 论文。它负责把原始图像送入 Patch Embedding逐层经过 Block 后返回多层特征图。4.1 构造参数全表参数默认值含义img_size1024输入图像尺寸仅影响相对位置/RoPE 计算patch_size16Patch 尺寸in_chans3输入通道数embed_dim768Patch 嵌入维度depth12Transformer 深度Block 数num_heads12每 Block 注意力头数mlp_ratio4.0MLP 隐藏维与嵌入维之比qkv_biasTrueQKV 投影是否带偏置drop_path_rate0.0Stochastic Depth 总速率按深度线性衰减分配norm_layerLayerNorm归一化层可为构造器或名称字符串act_layernn.GELUMLP 激活函数use_abs_posTrue是否使用绝对位置编码tile_abs_posTrue绝对位置编码尺寸不匹配时用平铺而非插值rel_pos_blocks(2, 5, 8, 11)启用相对位置编码的 Block 索引boolTrue时全部启用rel_pos_zero_initTrue相对位置参数零初始化window_size14窗口尺寸配合global_att_blocks区分全局/窗口块global_att_blocks(2, 5, 8, 11)使用全局注意力的 Block 索引其余块使用窗口注意力use_ropeFalse是否使用 2D RoPE可与 rel_pos 并存rope_pt_sizeNone预训练阶段的 RoPE 尺寸供插值/平铺use_interp_ropeFalse是否插值 RoPE 到目标尺寸pretrain_img_size224预训练输入尺寸决定绝对位置编码 patch 数pretrain_use_cls_tokenTrue预训练模型是否带 cls tokenretain_cls_tokenTrue当前模型是否保留 cls tokendropout0.0残差及 MLP 内 dropoutreturn_interm_layersFalse是否返回所有全局注意力块的中间特征init_valuesNoneLayerScale 初始值ln_preFalse是否在 Block 前施加 LayerNormln_postFalse是否在末层输出前施加 LayerNormbias_patch_embedTruePatch Embedding 卷积是否带偏置compile_modeNonetorch.compile编译模式None表示不编译use_act_checkpointTrue训练时是否启用激活检查点activation checkpointing4.2 构造逻辑要点窗口与全局块划分。window_block_indexes [i for i in range(depth) if i not in global_att_blocks]即只有落在global_att_blocks索引上的块做全局注意力其余块都使用窗口注意力。相对位置编码块的标记则按rel_pos_blockstuple 或 bool展开到depth长度的布尔列表。cls token 约束。当retain_cls_tokenTrue时要求预训练本就使用 cls token由于窗口化特征图会被展平源码断言windowing 不支持与 cls token 共存且rel pos 不支持与 cls token 共存新增class_embedding可学习参数初始缩放为embed_dim ** -0.5。Patch Embedding。复用 modules/blocks.py 中的PatchEmbed卷积实现kernel/stride 均为patch_size可通过bias_patch_embed控制偏置。绝对位置编码。若use_abs_posTrue按pretrain_img_size // patch_size计算num_patches再依pretrain_use_cls_token决定是否多留一个 cls 位置注册为pos_embed参数并trunc_normal_std0.02初始化。当前向遇到尺寸与预训练不一致的特征时get_abs_pos会依据tile_abs_pos选择平铺或双三次插值。Stochastic Depth 衰减。dpr torch.linspace(0, drop_path_rate, depth)逐 Block 分配递增的丢弃概率。LayerScale 与可选编译。每块按init_values装配 LayerScale当compile_mode非空时会把整个forward用torch.compile(..., modecompile_mode, fullgraphTrue)编译并在训练 激活检查点场景下关闭 DDP 图优化torch._dynamo.config.optimize_ddp False。4.3 前向输出与多尺度特性前向流程见 vitdet.pypatch_embed(x)得到(B, H, W, C)的 patch 序列SAM3 中通常为14×14卷积下采样若保留 cls token则把class_embedding拼接在序列头部叠加绝对位置编码经get_abs_pos按需平铺/裁剪逐 Block 前向训练模式下若use_act_checkpointTrue用torch.utils.checkpoint.checkpoint(blk, x, use_reentrantFalse)包住每个 Block 以换取显存在每个或最后一个全局注意力块后收集输出剥离 cls token 并还原为NCHW特征图。返回值为list[torch.Tensor]。若return_interm_layersFalse只在最后一个全局块处返回一层特征若为True则返回全部全局注意力块对应的中间层特征——这正是为多尺度下游neck 多层级 Transformer encoder预留的接口。4.4 动态分辨率适配set_imgszset_imgsz(imgszNone)vitdet.py允许在推理前把主干切换到新的输入分辨率默认回退到[1008, 1008]。它遍历所有 Block对非窗口块重新执行_setup_rel_pos与_setup_rope_freqs按imgsz // patch_size重建相对位置参数与 RoPE 频域。这是 SAM3 在不重新训练的前提下适配不同分辨率图像、并让 RoPE 通过插值保持平移等变性的关键机制。五、底层位置编码与窗口工具vitdet 的基础设施ViT/Attention/Block频繁调用的六个工具函数全部集中在 modules/utils.py理解它们才能真正读懂 vitdet 的数值流compute_axial_cis(dim, end_x, end_y, theta, scale_pos)L119对 H、W 两轴分别构造轴向axial旋转频率用极坐标形式torch.polar生成复数旋转因子输出(end_x*end_y, dim//2)。SAM2 系列的RoPEAttentionmodules/blocks.py 中也复用它theta10000、scale_pos为插值缩放。apply_rotary_enc(xq, xk, freqs_cis, repeat_freqs_k)L175把 q/k 视为复数按freqs_cis做旋转乘法。含对 MPS 设备不支持复数 repeat 的特殊处理。window_partition/window_unpartitionL225/L255特征图 ⇆ 不重叠窗口的互逆变换自动 padding 对齐并裁剪还原。concat_rel_pos(q, k, q_hw, k_hw, rel_pos_h, rel_pos_w, rescale, relative_coords)L454把相对位置 bias 以拼接 q、k 的扩展维度方式注入注意力——q 拼上rel_h、rel_wk 拼上单位阵。这样qkᵀ的乘积中自然出现位置偏置项rescaleTrue时按新增维度重新校准缩放因子确保与F.scaled_dot_product_attention内部缩放配合正确。get_abs_pos(abs_pos, has_cls_token, hw, retain_cls_token, tiling)L389把预训练分辨率下学习的绝对位置编码适配到当前分辨率——tiling模式下用平铺复制否则用双三次插值并正确处理 cls 位置。六、生产装配SAM3 里真实使用的 ViTDet 配置源码文件 build_sam3.py 的_create_vision_backbone给出了这套主干在 SAM3 中的真实实例化参数L37-L62与上一节的默认值有显著差异充分体现了 ViTDet 的设计意图vit_backbone ViT( img_size1008, # SAM3 工作分辨率 pretrain_img_size336, # 预训练分辨率patch 化后为 24×24 patch 网格 patch_size14, # 特征步长 14tracker 侧 backbone_stride14 与此对应 embed_dim1024, depth32, # 32 层 num_heads16, # head_dim 1024 / 16 64 mlp_ratio4.625, norm_layerLayerNorm, drop_path_rate0.1, qkv_biasTrue, use_abs_posTrue, tile_abs_posTrue, # 预训练→运行分辨率用平铺而非插值 global_att_blocks(7, 15, 23, 31), # 每 8 层做一次全局注意力 rel_pos_blocks(), # 全部块关闭 rel_pos改为纯 RoPE use_ropeTrue, use_interp_ropeTrue, # 336→1008 的 3× 分辨率迁移靠 RoPE 插值 window_size24, # 1008/147272 可被 24 整除 pretrain_use_cls_tokenTrue, retain_cls_tokenFalse, # 部署时丢弃 cls token ln_preTrue, ln_postFalse, return_interm_layersFalse, bias_patch_embedFalse, compile_modecompile_mode, )从配置可以看出几条设计链输入1008×1008经patch_size14卷积后得到72×72的 patch 网格除第 7、15、23、31 层做全局注意力外其余 28 层使用24×24窗口注意力以控制计算量预训练于 336 分辨率24×24网格后通过tile_abs_posTrue平铺绝对位置编码、use_interp_ropeTrue插值 RoPE 频域完成到 3× 更高分辨率的迁移。该主干随后被封装进 necks.py 的Sam3DualViTDetNeckSam3DualViTDetNeck( position_encodingPositionEmbeddingSine(num_pos_feats256, normalizeTrue, scaleNone, temperature10000), d_model256, # 下游统一特征维 scale_factors[4.0, 2.0, 1.0, 0.5], # 上采样/下采样尺度因子构建多尺度 level trunkvit_backbone, add_sam2_neckenable_inst_interactivity, )从构造参数可以推断neck 负责把 ViT 输出投影/缩放到 256 维并按scale_factors生成多个分辨率的特征 level供 encoder.py 中基于 Deformable-DETR 风格的多层 Transformer encoderTransformerEncoderFusionnum_feature_levels1使用。需要交互式实例/视频分割时add_sam2_neckTrue会额外附加 SAM2 风格的 neck 输出高层特征 stride 16/stride 8 等。七、结语与延伸阅读Attention→Block→ViT三层递进构成了 SAM3 视觉侧的主干答案一个把 rel_pos、RoPE、窗口注意力、Stochastic Depth、LayerScale、绝对位置平铺、激活检查点、torch.compile等多种工程手段集成于一体、且支持动态分辨率切换的纯 Transformer 检测骨干。它既承载了 ViTDetplain ViT as backbone的简洁理念也体现了 SAM 系列针对高分辨率分割 / 跟踪场景的精细化调优。想继续深入可在仓库内按如下路径追踪本模块全文ultralytics/models/sam/sam3/vitdet.py依赖的共享工具函数ultralytics/models/sam/modules/utils.pyRoPE、窗口、相对位置、绝对位置SAM3 生产装配与 ViT 实例化ultralytics/models/sam/build_sam3.py主干下游的 neck 与多尺度构造ultralytics/models/sam/sam3/necks.py特征融合 Transformer encoderultralytics/models/sam/sam3/encoder.py语义/实例模型主体ultralytics/models/sam/sam3/sam3_image.py交互式跟踪封装与 backbone 复用ultralytics/models/sam/sam3/init.pySAM3 模型使用与推理入口ultralytics/models/sam/build_sam3.py 的build_sam3_image_model/build_interactive_sam3说明本文涉及的一切参数默认值、断言约束与调用关系均以当前仓库 vitdet.py 及 build_sam3.py 的实际代码为准文中凡属推断性质的表述如 neck 的缩放行为均已使用可以推断/从构造参数看等限定语。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ultralytics SAM3 视觉主干解析：ViTDet Backbone（vitdet.py）架构与参数全解读
Ultralytics SAM3 视觉主干解析ViTDet Backbonevitdet.py架构与参数全解读【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文是 docs/en/reference/models/sam/sam3/vitdet.md 这一 API 参考页面的深度展开。该页面通过 mkdocstrings 索引了 ultralytics/models/sam/sam3/vitdet.py 模块中的Attention、Block、ViT三个类。本文以这些类的源码 docstring 与实际实现为主体结合 SAM3 在仓库中的真实装配方式完整解读这套 ViTDet 视觉主干的模块职责、每个构造参数的语义以及它在 SAM3 多模态分割链路中扮演的角色。一、模块定位SAM3 的纯 Transformer 视觉特征提取器SAM3 是 Ultralytics 仓库中负责视觉语言分割与视频跟踪的一族模型源码位于 ultralytics/models/sam/sam3。其图像侧编码器并不使用 CNN 金字塔而是直接采用一套纯 ViT主干——也就是 vitdet.py 中实现的ViTDet Backbone。源码文件头说明了它的来源与定位该主干改编自 Detectron2 的 ViTDet 实现原始论文题为Exploring Plain Vision Transformer Backbones for Object Detection即把普通 ViT 当作检测 / 分割骨干直接使用的路线模块内的RoPE旋转位置编码实现参考了多份公开代码文件注释列出的 3 个参考来源均为公开的 rope/rotary embedding 开源实现文件同时携带Copyright (c) Meta Platforms, Inc.的版权声明表明其上游血统。在 SAM3 中这个主干被包在Sam3DualViTDetNeck颈部结构内再与文本编码器组成SAM3VLBackbone最后接入掩码 Transformer 解码链路。因此理解vitdet.py就等于理解 SAM3 图像特征从 patch 化到多尺度特征输出的全过程。模块从内到外包含三个层次与 reference 页面索引一一对应Attention—— 带相对位置编码 2D RoPE的多头注意力单元Block—— 支持**窗口注意力window attention**的标准 Transformer BlockViT—— 由上述 Block 堆叠而成的完整主干负责输出特征图。三者均依赖同目录工具函数modules/utils.py 中的compute_axial_cis、apply_rotary_enc、window_partition、window_unpartition、concat_rel_pos、get_abs_pos并在构造时引用 sam3/model_misc.py 中的LayerScale。二、Attention融合相对位置编码与 2D RoPE 的多头注意力Attention类vitdet.py 中 L40 起是一个即插即用的多头注意力模块。它最大的特点是在标准 QKV 注意力之外提供两条正交的位置信息注入通道可学习的分解式相对位置编码rel_pos与旋转位置编码RoPE。二者互不冲突源码注释明确写到use_ropeindependent of use_rel_pos, as it can be used together。2.1 构造参数参数默认值含义dim必填输入通道数num_heads8注意力头数head_dim dim // num_headsqkv_biasTrue是否在 QKV 线性投影中加入可学习偏置use_rel_posFalse是否向注意力图加入相对位置编码rel_pos_zero_initTrue是否将相对位置参数零初始化否则用trunc_normal_std0.02input_sizeNone输入分辨率用于计算相对位置参数尺寸或 RoPE 尺寸cls_tokenFalse是否存在 cls token存在时 attention map 需相应处理use_ropeFalse是否使用 2D RoPErope_theta10000.0控制 RoPE 频率的基频rope_pt_sizeNone前一训练阶段pretrain的 RoPE 尺寸供插值/平铺使用rope_interpFalse是否把 RoPE 插值而非外推到目标输入尺寸2.2 相对位置编码的初始化_setup_rel_pos开启use_rel_pos后要求提供input_size且不允许与cls_token共存源码断言cls_token is False注册两个可学习参数rel_pos_h、rel_pos_w形状均为(2 * input_size - 1, head_dim)即对 H、W 两个轴向分别建模相对距离若rel_pos_zero_initFalse用trunc_normal_以 std0.02 初始化预计算relative_coords索引张量供前向时直接从 embedding 查表避免逐次计算。2.3 2D RoPE 频域的初始化_setup_rope_freqs开启use_rope后当rope_pt_size为None时以input_size兜底通过functools.partial固定compute_axial_cis(dimhead_dim, thetarope_theta)作为频域计算函数rope_interpTrue时以scale_pos rope_pt_size[0] / input_size[0]缩放坐标实现把预训练分辨率下学习到的频域插值到当前分辨率的目的若携带 cls token会额外拼接一个恒等旋转的极坐标项cls_freqs_cis保证 cls 位置不参与旋转。2.4 前向过程forward同时支持两种布局的输入4D 张量(B, H, W, C)特征图形式此时不允许 cls token3D 张量(B, L, C)序列形式并自动由L推导H W sqrt(L - s)s为 cls token 个数。计算流程见 vitdet.py一次qkv线性投影得到(B, L, 3, num_heads, head_dim)拆出 q、k、v对 q、k 施加 RoPE_apply_rope→apply_rotary_enc若use_rel_pos调用concat_rel_pos(..., rescaleTrue)把相对位置编码拼接进 q、k——这是一种用拼接维度代替加法偏置的等效实现并通过rescale修正缩放因子以配合F.scaled_dot_product_attention详见后文工具函数部分用 PyTorch 的F.scaled_dot_product_attention完成高效注意力计算按原布局4D/3D重组并经过proj输出。三、Block带窗口注意力与 LayerScale 的 Transformer 单元Block类vitdet.py把上面的Attention包装成标准的前置归一化pre-normTransformer Block并叠加三项 ViTDet/SAM 体系常用的工程化组件窗口注意力、Stochastic DepthDropPath、LayerScale。3.1 构造参数Block在透传Attention全部位置编码相关参数的基础上新增了参数默认值含义mlp_ratio4.0MLP 隐藏维与嵌入维之比drop_path0.0Stochastic Depth随机深度概率norm_layernn.LayerNorm归一化层构造器act_layernn.GELUMLP 激活函数window_size0窗口注意力窗口尺寸0 表示不启用窗口注意力dropout0.0残差路径与 MLP 内部 dropoutinit_valuesNoneLayerScale 初始值为None时不启用 LayerScale注意依赖关系Block 内部check_requirements(timm)并从timm.layers导入DropPath与Mlp即该模块的运行环境需要安装timm。3.2 窗口注意力机制当window_size 0时Block 在前向中先调用window_partition(x, window_size)把(B, H, W, C)特征切成互不重叠的若干window_size × window_size窗口必要时自动 padding再送入注意力注意力计算完成后用window_unpartition还原并裁掉 padding见 vitdet.py。窗口注意力的价值在于把O((H·W)²)的全局注意力复杂度降为窗口内的局部计算让深层高分辨率特征成为可行。同时Block构造Attention时若处于窗口模式会把Attention的input_size固定为(window_size, window_size)使位置编码参数大小只与窗口相关。3.3 残差结构shortcut x x norm1(x) # 前置归一化 x (window_partition) → attn → (window_unpartition) x ls1(x) # LayerScale若启用 x shortcut dropout(drop_path(x)) x x dropout(drop_path(ls2(mlp(norm2(x))))) # 第二条残差其中LayerScale来自 sam3/model_misc.py以逐通道可学习缩放系数init_values为初值作用在注意力/MLP 输出上是稳定深层 Transformer 训练的重要技巧。每个 Block 的drop_path概率由上层 ViT 按 stochastic depth 递减规则逐一分配。四、ViT由 32 层 Block 组成的完整主干ViT类vitdet.py是模块的顶层封装docstring 明确引用了 ViTDet 论文。它负责把原始图像送入 Patch Embedding逐层经过 Block 后返回多层特征图。4.1 构造参数全表参数默认值含义img_size1024输入图像尺寸仅影响相对位置/RoPE 计算patch_size16Patch 尺寸in_chans3输入通道数embed_dim768Patch 嵌入维度depth12Transformer 深度Block 数num_heads12每 Block 注意力头数mlp_ratio4.0MLP 隐藏维与嵌入维之比qkv_biasTrueQKV 投影是否带偏置drop_path_rate0.0Stochastic Depth 总速率按深度线性衰减分配norm_layerLayerNorm归一化层可为构造器或名称字符串act_layernn.GELUMLP 激活函数use_abs_posTrue是否使用绝对位置编码tile_abs_posTrue绝对位置编码尺寸不匹配时用平铺而非插值rel_pos_blocks(2, 5, 8, 11)启用相对位置编码的 Block 索引boolTrue时全部启用rel_pos_zero_initTrue相对位置参数零初始化window_size14窗口尺寸配合global_att_blocks区分全局/窗口块global_att_blocks(2, 5, 8, 11)使用全局注意力的 Block 索引其余块使用窗口注意力use_ropeFalse是否使用 2D RoPE可与 rel_pos 并存rope_pt_sizeNone预训练阶段的 RoPE 尺寸供插值/平铺use_interp_ropeFalse是否插值 RoPE 到目标尺寸pretrain_img_size224预训练输入尺寸决定绝对位置编码 patch 数pretrain_use_cls_tokenTrue预训练模型是否带 cls tokenretain_cls_tokenTrue当前模型是否保留 cls tokendropout0.0残差及 MLP 内 dropoutreturn_interm_layersFalse是否返回所有全局注意力块的中间特征init_valuesNoneLayerScale 初始值ln_preFalse是否在 Block 前施加 LayerNormln_postFalse是否在末层输出前施加 LayerNormbias_patch_embedTruePatch Embedding 卷积是否带偏置compile_modeNonetorch.compile编译模式None表示不编译use_act_checkpointTrue训练时是否启用激活检查点activation checkpointing4.2 构造逻辑要点窗口与全局块划分。window_block_indexes [i for i in range(depth) if i not in global_att_blocks]即只有落在global_att_blocks索引上的块做全局注意力其余块都使用窗口注意力。相对位置编码块的标记则按rel_pos_blockstuple 或 bool展开到depth长度的布尔列表。cls token 约束。当retain_cls_tokenTrue时要求预训练本就使用 cls token由于窗口化特征图会被展平源码断言windowing 不支持与 cls token 共存且rel pos 不支持与 cls token 共存新增class_embedding可学习参数初始缩放为embed_dim ** -0.5。Patch Embedding。复用 modules/blocks.py 中的PatchEmbed卷积实现kernel/stride 均为patch_size可通过bias_patch_embed控制偏置。绝对位置编码。若use_abs_posTrue按pretrain_img_size // patch_size计算num_patches再依pretrain_use_cls_token决定是否多留一个 cls 位置注册为pos_embed参数并trunc_normal_std0.02初始化。当前向遇到尺寸与预训练不一致的特征时get_abs_pos会依据tile_abs_pos选择平铺或双三次插值。Stochastic Depth 衰减。dpr torch.linspace(0, drop_path_rate, depth)逐 Block 分配递增的丢弃概率。LayerScale 与可选编译。每块按init_values装配 LayerScale当compile_mode非空时会把整个forward用torch.compile(..., modecompile_mode, fullgraphTrue)编译并在训练 激活检查点场景下关闭 DDP 图优化torch._dynamo.config.optimize_ddp False。4.3 前向输出与多尺度特性前向流程见 vitdet.pypatch_embed(x)得到(B, H, W, C)的 patch 序列SAM3 中通常为14×14卷积下采样若保留 cls token则把class_embedding拼接在序列头部叠加绝对位置编码经get_abs_pos按需平铺/裁剪逐 Block 前向训练模式下若use_act_checkpointTrue用torch.utils.checkpoint.checkpoint(blk, x, use_reentrantFalse)包住每个 Block 以换取显存在每个或最后一个全局注意力块后收集输出剥离 cls token 并还原为NCHW特征图。返回值为list[torch.Tensor]。若return_interm_layersFalse只在最后一个全局块处返回一层特征若为True则返回全部全局注意力块对应的中间层特征——这正是为多尺度下游neck 多层级 Transformer encoder预留的接口。4.4 动态分辨率适配set_imgszset_imgsz(imgszNone)vitdet.py允许在推理前把主干切换到新的输入分辨率默认回退到[1008, 1008]。它遍历所有 Block对非窗口块重新执行_setup_rel_pos与_setup_rope_freqs按imgsz // patch_size重建相对位置参数与 RoPE 频域。这是 SAM3 在不重新训练的前提下适配不同分辨率图像、并让 RoPE 通过插值保持平移等变性的关键机制。五、底层位置编码与窗口工具vitdet 的基础设施ViT/Attention/Block频繁调用的六个工具函数全部集中在 modules/utils.py理解它们才能真正读懂 vitdet 的数值流compute_axial_cis(dim, end_x, end_y, theta, scale_pos)L119对 H、W 两轴分别构造轴向axial旋转频率用极坐标形式torch.polar生成复数旋转因子输出(end_x*end_y, dim//2)。SAM2 系列的RoPEAttentionmodules/blocks.py 中也复用它theta10000、scale_pos为插值缩放。apply_rotary_enc(xq, xk, freqs_cis, repeat_freqs_k)L175把 q/k 视为复数按freqs_cis做旋转乘法。含对 MPS 设备不支持复数 repeat 的特殊处理。window_partition/window_unpartitionL225/L255特征图 ⇆ 不重叠窗口的互逆变换自动 padding 对齐并裁剪还原。concat_rel_pos(q, k, q_hw, k_hw, rel_pos_h, rel_pos_w, rescale, relative_coords)L454把相对位置 bias 以拼接 q、k 的扩展维度方式注入注意力——q 拼上rel_h、rel_wk 拼上单位阵。这样qkᵀ的乘积中自然出现位置偏置项rescaleTrue时按新增维度重新校准缩放因子确保与F.scaled_dot_product_attention内部缩放配合正确。get_abs_pos(abs_pos, has_cls_token, hw, retain_cls_token, tiling)L389把预训练分辨率下学习的绝对位置编码适配到当前分辨率——tiling模式下用平铺复制否则用双三次插值并正确处理 cls 位置。六、生产装配SAM3 里真实使用的 ViTDet 配置源码文件 build_sam3.py 的_create_vision_backbone给出了这套主干在 SAM3 中的真实实例化参数L37-L62与上一节的默认值有显著差异充分体现了 ViTDet 的设计意图vit_backbone ViT( img_size1008, # SAM3 工作分辨率 pretrain_img_size336, # 预训练分辨率patch 化后为 24×24 patch 网格 patch_size14, # 特征步长 14tracker 侧 backbone_stride14 与此对应 embed_dim1024, depth32, # 32 层 num_heads16, # head_dim 1024 / 16 64 mlp_ratio4.625, norm_layerLayerNorm, drop_path_rate0.1, qkv_biasTrue, use_abs_posTrue, tile_abs_posTrue, # 预训练→运行分辨率用平铺而非插值 global_att_blocks(7, 15, 23, 31), # 每 8 层做一次全局注意力 rel_pos_blocks(), # 全部块关闭 rel_pos改为纯 RoPE use_ropeTrue, use_interp_ropeTrue, # 336→1008 的 3× 分辨率迁移靠 RoPE 插值 window_size24, # 1008/147272 可被 24 整除 pretrain_use_cls_tokenTrue, retain_cls_tokenFalse, # 部署时丢弃 cls token ln_preTrue, ln_postFalse, return_interm_layersFalse, bias_patch_embedFalse, compile_modecompile_mode, )从配置可以看出几条设计链输入1008×1008经patch_size14卷积后得到72×72的 patch 网格除第 7、15、23、31 层做全局注意力外其余 28 层使用24×24窗口注意力以控制计算量预训练于 336 分辨率24×24网格后通过tile_abs_posTrue平铺绝对位置编码、use_interp_ropeTrue插值 RoPE 频域完成到 3× 更高分辨率的迁移。该主干随后被封装进 necks.py 的Sam3DualViTDetNeckSam3DualViTDetNeck( position_encodingPositionEmbeddingSine(num_pos_feats256, normalizeTrue, scaleNone, temperature10000), d_model256, # 下游统一特征维 scale_factors[4.0, 2.0, 1.0, 0.5], # 上采样/下采样尺度因子构建多尺度 level trunkvit_backbone, add_sam2_neckenable_inst_interactivity, )从构造参数可以推断neck 负责把 ViT 输出投影/缩放到 256 维并按scale_factors生成多个分辨率的特征 level供 encoder.py 中基于 Deformable-DETR 风格的多层 Transformer encoderTransformerEncoderFusionnum_feature_levels1使用。需要交互式实例/视频分割时add_sam2_neckTrue会额外附加 SAM2 风格的 neck 输出高层特征 stride 16/stride 8 等。七、结语与延伸阅读Attention→Block→ViT三层递进构成了 SAM3 视觉侧的主干答案一个把 rel_pos、RoPE、窗口注意力、Stochastic Depth、LayerScale、绝对位置平铺、激活检查点、torch.compile等多种工程手段集成于一体、且支持动态分辨率切换的纯 Transformer 检测骨干。它既承载了 ViTDetplain ViT as backbone的简洁理念也体现了 SAM 系列针对高分辨率分割 / 跟踪场景的精细化调优。想继续深入可在仓库内按如下路径追踪本模块全文ultralytics/models/sam/sam3/vitdet.py依赖的共享工具函数ultralytics/models/sam/modules/utils.pyRoPE、窗口、相对位置、绝对位置SAM3 生产装配与 ViT 实例化ultralytics/models/sam/build_sam3.py主干下游的 neck 与多尺度构造ultralytics/models/sam/sam3/necks.py特征融合 Transformer encoderultralytics/models/sam/sam3/encoder.py语义/实例模型主体ultralytics/models/sam/sam3/sam3_image.py交互式跟踪封装与 backbone 复用ultralytics/models/sam/sam3/init.pySAM3 模型使用与推理入口ultralytics/models/sam/build_sam3.py 的build_sam3_image_model/build_interactive_sam3说明本文涉及的一切参数默认值、断言约束与调用关系均以当前仓库 vitdet.py 及 build_sam3.py 的实际代码为准文中凡属推断性质的表述如 neck 的缩放行为均已使用可以推断/从构造参数看等限定语。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考