Ultralytics SAM3 模型构建源码深度解析从视觉骨干到交互式跟踪器的组装管线【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读build_sam3.py是 Ultralytics 仓库中负责组装SAM3Segment Anything Model 3完整模型的唯一入口模块位于 ultralytics/models/sam/build_sam3.py。它把分布于 ultralytics/models/sam/sam3/ 与 ultralytics/models/sam/modules/ 下的视觉骨干、多模态 Transformer、几何编码器、分割头与视频记忆解码器等众多子模块粘合成两类可运行的模型——用于 Promptable Concept SegmentationPCS的SAM3SemanticModel与用于交互式/视频分割PVS的SAM3Model。读完本文你将掌握该模块五个核心函数各自组装了什么组件、每个关键超参的默认值与作用、checkpoint 如何被加载与重映射以及这些函数在SAM3SemanticPredictor、SAM3VideoPredictor等推理入口中的实际调用关系从而能够独立解读与调试 SAM3 相关代码。模块定位一个函数集两类模型SAM3 架构本身由detector检测器与tracker跟踪器组成检测器面向图像级的概念分割输入文本短语或示例框输出所有匹配实例跟踪器继承 SAM2 的记忆机制完成视频级分割。build_sam3.py通过一组工厂函数把这两个子系统的组件分别装配为两个顶层模型类顶层模型类适用场景对应构建函数SAM3SemanticModelsam3_image.py图像概念分割文本/exemplar 提示build_sam3_image_model()SAM3Modelmodules/sam.py交互式单目标分割与视频跟踪build_interactive_sam3()从源码头部注释Copyright (c) Meta Platforms, Inc.可以看出该文件系对 Meta 官方 SAM3 实现的移植整体在 AGPL-3.0 许可下发布。该模块内部可细分为五个函数本文逐一定位它们的作用、默认参数与底层证据。_create_vision_backbone()构建视觉骨干与特征金字塔定义于 build_sam3.py#L26-L69。它创建可学习的正弦位置编码 ViT 骨干 多尺度 FPN 颈部返回Sam3DualViTDetNeck对象是图像侧唯一真正的特征提取器。位置编码position_encoding PositionEmbeddingSine( num_pos_feats256, # 每个维度的正弦/余弦特征数 normalizeTrue, # 归一化到 [0, 1] 范围 scaleNone, # 使用默认缩放 temperature10000, # 正弦频率温度系数 )该类定义在 ultralytics/models/sam/modules/blocks.py用于给特征图补充位置信息。ViT 骨干_create_vision_backbone内部实例化 sam3/vitdet.py 的ViTvit_backbone ViT( img_size1008, # 推理输入分辨率 pretrain_img_size336, # 预训练时图像尺寸 patch_size14, # patch 边长1008/14 72×72 网格 embed_dim1024, # 隐藏维度 depth32, # Transformer 层数 num_heads16, # 注意力头数 mlp_ratio4.625, # MLP 扩展比约 4736 drop_path_rate0.1, qkv_biasTrue, use_abs_posTrue, # 使用可学习绝对位置嵌入 tile_abs_posTrue, # 大图推理时按 tile 插值绝对位置 global_att_blocks(7, 15, 23, 31), # 使用全局注意力的层 rel_pos_blocks(), # 不使用相对位置改用 RoPE use_ropeTrue, # 启用旋转位置编码 RoPE use_interp_ropeTrue, # 大图场景对 RoPE 做插值 window_size24, # 局部注意力窗口大小 pretrain_use_cls_tokenTrue, retain_cls_tokenFalse, # 前向时不保留 CLS token ln_preTrue, ln_postFalse, return_interm_layersFalse, # 只在最后一层输出 bias_patch_embedFalse, compile_modecompile_mode, # torch.compile 模式 )值得注意的几点输入尺寸为 1008patch 大小为 14因此骨干输出的 token 网格为 72×72除第 7、15、23、31 层执行全局注意力外其余层均采用 windowed attention 以控制计算量位置信息完全交给 RoPErel_pos_blocks()并通过use_interp_rope支持高分辨率推理。多尺度颈部return Sam3DualViTDetNeck( position_encodingposition_encoding, d_model256, scale_factors[4.0, 2.0, 1.0, 0.5], # 4 个 FPN 级别的上/下采样因子 trunkvit_backbone, add_sam2_neckenable_inst_interactivity, # 是否追加 SAM2 风格颈部 )Sam3DualViTDetNecksam3/necks.py#L15把 72×72 的 ViT 输出展开为 4 个尺度特征scale_factors 对应 4.0/2.0/1.0/0.5即分别上采样/下采样到 288、144、72、36 分辨率级别输出通道统一为d_model256。当需要交互式实例分割SAM2 风格点/框提示时add_sam2_neckTrue会追加第二个用于 SAM2 头部的特征金字塔——这正是参数名为Dual的含义。该参数由build_sam3_image_model调用时固定传入enable_inst_interactivityTrue。_create_sam3_transformer()概念检测器的编码器与解码器定义于 build_sam3.py#L72-L132返回一个TransformerWrappersam3/model_misc.py内部封装融合编码器与 DETR 风格解码器。融合编码器encoder TransformerEncoderFusion( layerTransformerEncoderLayer( d_model256, dim_feedforward2048, dropout0.1, pos_enc_at_attnTrue, pos_enc_at_cross_attn_keysFalse, pos_enc_at_cross_attn_queriesFalse, pre_normTrue, # Pre-LN 结构 self_attentionnn.MultiheadAttention( # 自注意力 8 头 num_heads8, dropout0.1, embed_dim256, batch_firstTrue), cross_attentionnn.MultiheadAttention( # 文本交叉注意力 num_heads8, dropout0.1, embed_dim256, batch_firstTrue), ), num_layers6, d_model256, num_feature_levels1, frozenFalse, use_act_checkpointTrue, # 激活检查点省显存 add_pooled_text_to_img_featFalse, pool_text_with_maskTrue, # 文本特征按 mask 做池化 )TransformerEncoderFusionsam3/encoder.py的 forward 同时接收图像特征src与文本 prompt 特征在每层内做自注意力并通过cross_attention让图像 token 吸收文本 token 的信息实现以概念条件化图像特征。6 层、隐藏 256、FFN 2048 与 8 头是该检测器编码器的基础配置。解码器decoder TransformerDecoder( layerTransformerDecoderLayer( d_model256, dim_feedforward2048, dropout0.1, cross_attentionnn.MultiheadAttention(num_heads8, dropout0.1, embed_dim256), n_heads8, use_text_cross_attentionTrue, # 额外对文本做交叉注意力 ), num_layers6, num_queries200, # 每图 200 个目标查询 return_intermediateTrue, # 输出每层中间结果用于深度监督 box_refineTrue, # 逐层迭代式框回归 num_o2m_queries0, # 不使用 one-to-many 查询 dacTrue, # 动态锚框查询Dynamic Anchor Queries boxRPBlog, # 参考框对数空间旋转位置编码 d_model256, frozenFalse, interaction_layerNone, dac_use_selfatt_lnTrue, use_act_checkpointTrue, presence_tokenTrue, # 启用 presence token概念是否出现 )解码器sam3/decoder.py面向图像概念分割输出200 个可学习查询逐层 refine 边界框box_refineTrue并且presence_tokenTrue会额外维护一个学习到的全局 token用来在整图层面预测该概念是否出现——这正是 SAM3 论文中解耦识别what与定位where的 presence head 在解码器层面的实现载体。返回的TransformerWrapper(encoder, decoder, d_model256)统一了二者的前向接口。build_sam3_image_model()概念分割模型的完整装配定义于 build_sam3.py#L135-L255是PCS 检测器SAM3SemanticModel的唯一构建入口。def build_sam3_image_model(checkpoint_path: str, enable_segmentation: bool True, compile: bool False):参数默认值含义checkpoint_path必填权重文件路径如sam3.ptenable_segmentationTrue是否挂载 mask 分割头置False时只做检测级输出compileFalse为True时以default模式编译视觉骨干可提速但会增加首次编译开销该函数的装配步骤对应源码中清晰的注释段拆解如下。1) 文本编码器依赖注入CLIP tokenizertry: import clip except ImportError: from ultralytics.utils.checks import check_requirements check_requirements(githttps://github.com/ultralytics/CLIP.git) import clipSAM3 文本侧依赖 Ultralytics 维护的clip包提供 tokenizer。若环境未安装这里会调用 ultralytics/utils/checks.py 的check_requirements自动安装其 GitHub fork 版本。这也与 docs/en/models/sam-3.md 中提示的TypeError: SimpleTokenizer object is not callable问题一致——只要装了 PyPI 上错误的clip包代码内文本编码就会报错需按文档卸载并用该 fork 重装。2) 视觉 语言双塔拼接为 VL 骨干vision_encoder _create_vision_backbone(compile_modecompile_mode, enable_inst_interactivityTrue) text_encoder VETextEncoder( tokenizerclip.simple_tokenizer.SimpleTokenizer(), d_model256, width1024, heads16, layers24, # 24 层、16 头、宽 1024 的 CLIP 文本编码器 ) backbone SAM3VLBackbone(visualvision_encoder, texttext_encoder, scalp1)VETextEncodersam3/text_encoder_ve.py是一套 24 层 Transformer 的 CLIP 风格文本编码器输出投影到 256 维与视觉特征对齐。SAM3VLBackbonesam3/vl_combiner.py负责把两个塔缝合成一个统一前向接口并提供forward_image/forward_text/forward_image_sam2等方法。3) 点积打分器与 prompt MLPdot_prod_scoring DotProductScoring( d_model256, d_proj256, prompt_mlpMLP(input_dim256, hidden_dim2048, output_dim256, num_layers2, residualTrue, out_normnn.LayerNorm(256)), )DotProductScoringsam3/model_misc.py在对象查询与 prompt 嵌入之间计算相似度用于对该查询是否匹配当前概念打分prompt 先经两层 MLP含残差与 LayerNorm投影。4) 通用分割头 像素解码器segmentation_head UniversalSegmentationHead( hidden_dim256, upsampling_stages3, # 上采样 3 级直至全分辨率 aux_masksFalse, # 不输出辅助 mask presence_headFalse, # presence 判断交给解码器 dot_product_scorerNone, act_ckptTrue, cross_attend_promptnn.MultiheadAttention(num_heads8, dropout0, embed_dim256), pixel_decoderPixelDecoder( num_upsampling_stages3, interpolation_modenearest, # 逐级最近邻插值 hidden_dim256, compile_modecompile_mode, ), ) if enable_segmentation else NoneUniversalSegmentationHead与PixelDecoder都定义于 sam3/maskformer_segmentation.py。该头沿用 Mask2Former 式的查询 → 像素嵌入点积出 mask范式像素解码器把多尺度骨干特征逐级上采样融合分割头再把对象查询转化为每个对象的 mask logits。当enable_segmentationFalse时整个分割头被置为None模型只做检测级预测。5) 几何提示编码器exemplar 框/点的注入input_geometry_encoder SequenceGeometryEncoder( pos_encPositionEmbeddingSine(num_pos_feats256, normalizeTrue, ...), encode_boxes_as_pointsFalse, boxes_direct_projectTrue, # 框区域直接投影为 token boxes_poolTrue, # 聚合框内视觉特征 boxes_pos_encTrue, # 为框补充位置编码 d_model256, num_layers3, layerTransformerEncoderLayer(d_model256, dim_feedforward2048, dropout0.1, ...), use_act_ckptTrue, add_clsTrue, add_post_encode_projTrue, )SequenceGeometryEncodersam3/geometry_encoders.py把图像 exemplar 框/点等几何提示编码为与文本同空间的特征序列使一张示例框图 一段视觉 token 序列从而让 PCS 既能吃文本也能吃示例图像甚至二者组合。它默认把框区域内容投影boxes_direct_project并做池化与位置编码后送入 3 层 Transformer。6) 组装SAM3SemanticModel并装载权重model SAM3SemanticModel( backbonebackbone, transformertransformer, input_geometry_encoderinput_geometry_encoder, segmentation_headsegmentation_head, num_feature_levels1, # 单尺度特征级 o2m_mask_predictTrue, dot_prod_scoringdot_prod_scoring, use_instance_queryFalse, # 不使用单实例查询面向概念而非单个物体 multimask_outputTrue, ) model _load_checkpoint(model, checkpoint_path) model.eval()SAM3SemanticModelsam3/sam3_image.py串起整条推理链VL 骨干提取图像与文本特征 → 融合编码器吸收文本条件 → 解码器产出边界框与 presence 判断 → 几何编码器处理 exemplar → 分割头生成 mask。装配完成后立即eval()返回推理就绪的模型。build_interactive_sam3()SAM2 兼容的交互/视频跟踪模型定义于 build_sam3.py#L258-L348装配tracker 侧的SAM3Model支持点/框交互式分割与视频多目标跟踪PVS 任务。def build_interactive_sam3(checkpoint_path: str, compileNone, with_backboneTrue) - SAM3Model:记忆编码器与记忆注意力memory_encoder MemoryEncoder(out_dim64, interpol_size[1152, 1152]) memory_attention MemoryAttention( batch_firstTrue, d_model256, pos_enc_at_inputTrue, layerMemoryAttentionLayer( dim_feedforward2048, dropout0.1, self_attnRoPEAttention(embedding_dim256, num_heads1, rope_theta10000.0, feat_sizes[72, 72]), d_model256, cross_attnRoPEAttention(embedding_dim256, num_heads1, kv_in_dim64, rope_theta10000.0, feat_sizes[72, 72], rope_k_repeatTrue), ), num_layers4, )这部分对应 SAM2/SAM3 的视频记忆机制MemoryEncodermodules/encoders.py把历史预测 mask 压缩成 64 维记忆特征MemoryAttentionmodules/memory_attention.py通过 4 层、带 RoPE 的跨帧注意力self/cross attention 均为num_heads1、feat_sizes[72,72]把历史记忆融入当前帧特征。interpol_size[1152,1152]提示记忆特征会被上采样到 1152×1152 参与前向。可选骨干与跟踪器模型backbone (SAM3VLBackbone(scalp1, visual_create_vision_backbone(compile_modecompile), textNone) if with_backbone else None)与 image 模型不同交互式/跟踪模型的骨干只含视觉塔textNone并且with_backbone可关闭。SAM3VideoSemanticPredictor.setup_model在构建时显式传入with_backboneFalse见 ultralytics/models/sam/predict.py#L2598-L2606因为视频语义跟踪场景下视觉骨干已由 detectorimage 模型提供tracker 仅复用其记忆解码模块避免重复加载两份骨干。最后构造的SAM3Modelmodules/sam.py带有大量跟踪行为相关开关从源码可见其核心设置image_size1008、backbone_stride14、num_maskmem7记忆缓存帧数、pred_obj_scoresTrue、multimask_output_for_trackingTrue以及一组控制 object pointer 的选项use_obj_ptrs_in_encoderTrue、fixed_no_obj_ptrTrue等。它同时传入sam_mask_decoder_extra_args为 mask 解码器开启基于稳定性的动态多 mask 选择dynamic_multimask_via_stability等整体目标是让单目标视觉提示与多目标跟踪共享同一解码器。两种入口的汇合需要注意SAM3 的 image detector 与 interactive tracker 共享同一个视觉骨干但前向路径不同SAM3SemanticPredictor.get_im_features调用self.model.backbone.forward_image(im)取图像特征predict.py#L2234-L2237而 tracker 侧则通过_create_vision_backbone中add_sam2_neckTrue追加的 SAM2 特征层经forward_image_sam2取高分辨率特征。该设计可从上文 neck 参数推断得出。_load_checkpoint()权重装载与前缀重映射定义于 build_sam3.py#L351-L382被上述两个构建函数共用负责把官方发布的权重装进不同结构的模型。def _load_checkpoint(model, checkpoint, interactiveFalse): with open(checkpoint, rb) as f: ckpt torch_load(f) # 经 ultralytics 补丁后的安全 torch.load if model in ckpt and isinstance(ckpt[model], dict): ckpt ckpt[model] # 解包带 model 键的包装格式 # 统一剥离 detector. 前缀image 模型权重命名 sam3_image_ckpt {k.replace(detector., ): v for k, v in ckpt.items() if detector in k}torch_load来自 ultralytics/utils/patches.py是仓库为保证加载安全而对标准torch.load的封装。对 checkpoint 的装载策略为官方权重通常带有detector.、tracker.、backbone.等前缀这里一律先取包含detector前缀的键并剥掉前缀得到 image 侧权重字典随后再按interactive分支做tracker → interactive 模型的键名映射if interactive: # backbone.vision_backbone.* → image_encoder.vision_backbone.* # tracker.transformer.encoder.* → memory_attention.* # tracker.maskmem_backbone.* → memory_encoder.* # tracker.* → *剥离剩余 tracker 前缀最后统一model.load_state_dict(sam3_image_ckpt, strictFalse)——strictFalse意味着允许权重与模型结构不完全一一对应这是 SAM3 这样一个由 image 模型 interactive 模型共享部分权重尤其视觉骨干的框架得以复用单一sam3.pt文件的基础。可以推断官方发布的一个 checkpoint 同时承载了detector.概念检测与tracker.视频跟踪/交互分割两部分权重通过该函数按需提取。在推理链路中的真实调用关系虽然build_sam3.py不被用户直接调用但它是所有 SAM3 推理类的模型工厂调用点集中在 ultralytics/models/sam/predict.py调用方调用的构建函数说明SAM3SemanticPredictor.get_model()predict.py#L2228-L2232build_sam3_image_model(self.args.model, compileself.args.compile)概念分割文本/exemplar 提示SAM3Predictor.get_model()predict.py#L2218-L2222build_interactive_sam3(self.args.model, compileself.args.compile)SAM2 风格的交互式分割SAM3VideoSemanticPredictor.setup_model()predict.py#L2598-L2606build_interactive_sam3(self.args.model, with_backboneFalse)视频语义跟踪复用 detector 骨干SAM._load()ultralytics/models/sam/model.py#L76-L79build_interactive_sam3(weights)SAM(sam3.pt)走 SAM2 兼容视觉提示路径各调用方普遍对导入做**延迟slow import**处理——把build_sam3及其牵涉的大量模块放到get_model/setup_model阶段才导入避免用户仅加载其他模型时承担 SAM3 庞大的依赖与初始化开销这一点从 predict.py#L2220 等处的注释与结构可以确认。使用前提与实践约束把模块源码与仓库文档结合使用前需要满足两个前提权重需单独获取。与其它自动下载的 Ultralytics 模型不同sam3.pt权重并不会在首次运行时自动下载build_sam3_image_model与build_interactive_sam3都要求传入真实存在的checkpoint_path。权重获取流程与前置准备见 docs/en/models/sam-3.md。clip依赖必须来自 Ultralytics fork。image 模型构建会用到clip.simple_tokenizer.SimpleTokenizer若环境中安装的是 PyPI 同名但接口不同的clip包运行会出现SimpleTokenizer object is not callable。build_sam3_image_model虽在ImportError时会自动调用check_requirements(githttps://github.com/ultralytics/CLIP.git)尝试修复但更稳妥的做法是按文档预先安装正确依赖。总结build_sam3.py 是整个 SAM3 功能的装配车间_create_vision_backbone与_create_sam3_transformer是基础件工厂build_sam3_image_model面向概念分割PCS组装含文本编码器、presence token、分割头与几何编码器的SAM3SemanticModelbuild_interactive_sam3面向视觉提示与视频跟踪PVS组装带记忆机制的SAM3Model而_load_checkpoint以非严格方式完成官方权重的前缀重映射与装载。理解这五个函数及其在SAM3SemanticPredictor/SAM3VideoPredictor/SAM中的接线方式就等于掌握了在 Ultralytics 生态中实例化、扩展与调试 SAM3 的钥匙。【免费下载链接】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 模型构建源码深度解析从视觉骨干到交互式跟踪器的组装管线【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读build_sam3.py是 Ultralytics 仓库中负责组装SAM3Segment Anything Model 3完整模型的唯一入口模块位于 ultralytics/models/sam/build_sam3.py。它把分布于 ultralytics/models/sam/sam3/ 与 ultralytics/models/sam/modules/ 下的视觉骨干、多模态 Transformer、几何编码器、分割头与视频记忆解码器等众多子模块粘合成两类可运行的模型——用于 Promptable Concept SegmentationPCS的SAM3SemanticModel与用于交互式/视频分割PVS的SAM3Model。读完本文你将掌握该模块五个核心函数各自组装了什么组件、每个关键超参的默认值与作用、checkpoint 如何被加载与重映射以及这些函数在SAM3SemanticPredictor、SAM3VideoPredictor等推理入口中的实际调用关系从而能够独立解读与调试 SAM3 相关代码。模块定位一个函数集两类模型SAM3 架构本身由detector检测器与tracker跟踪器组成检测器面向图像级的概念分割输入文本短语或示例框输出所有匹配实例跟踪器继承 SAM2 的记忆机制完成视频级分割。build_sam3.py通过一组工厂函数把这两个子系统的组件分别装配为两个顶层模型类顶层模型类适用场景对应构建函数SAM3SemanticModelsam3_image.py图像概念分割文本/exemplar 提示build_sam3_image_model()SAM3Modelmodules/sam.py交互式单目标分割与视频跟踪build_interactive_sam3()从源码头部注释Copyright (c) Meta Platforms, Inc.可以看出该文件系对 Meta 官方 SAM3 实现的移植整体在 AGPL-3.0 许可下发布。该模块内部可细分为五个函数本文逐一定位它们的作用、默认参数与底层证据。_create_vision_backbone()构建视觉骨干与特征金字塔定义于 build_sam3.py#L26-L69。它创建可学习的正弦位置编码 ViT 骨干 多尺度 FPN 颈部返回Sam3DualViTDetNeck对象是图像侧唯一真正的特征提取器。位置编码position_encoding PositionEmbeddingSine( num_pos_feats256, # 每个维度的正弦/余弦特征数 normalizeTrue, # 归一化到 [0, 1] 范围 scaleNone, # 使用默认缩放 temperature10000, # 正弦频率温度系数 )该类定义在 ultralytics/models/sam/modules/blocks.py用于给特征图补充位置信息。ViT 骨干_create_vision_backbone内部实例化 sam3/vitdet.py 的ViTvit_backbone ViT( img_size1008, # 推理输入分辨率 pretrain_img_size336, # 预训练时图像尺寸 patch_size14, # patch 边长1008/14 72×72 网格 embed_dim1024, # 隐藏维度 depth32, # Transformer 层数 num_heads16, # 注意力头数 mlp_ratio4.625, # MLP 扩展比约 4736 drop_path_rate0.1, qkv_biasTrue, use_abs_posTrue, # 使用可学习绝对位置嵌入 tile_abs_posTrue, # 大图推理时按 tile 插值绝对位置 global_att_blocks(7, 15, 23, 31), # 使用全局注意力的层 rel_pos_blocks(), # 不使用相对位置改用 RoPE use_ropeTrue, # 启用旋转位置编码 RoPE use_interp_ropeTrue, # 大图场景对 RoPE 做插值 window_size24, # 局部注意力窗口大小 pretrain_use_cls_tokenTrue, retain_cls_tokenFalse, # 前向时不保留 CLS token ln_preTrue, ln_postFalse, return_interm_layersFalse, # 只在最后一层输出 bias_patch_embedFalse, compile_modecompile_mode, # torch.compile 模式 )值得注意的几点输入尺寸为 1008patch 大小为 14因此骨干输出的 token 网格为 72×72除第 7、15、23、31 层执行全局注意力外其余层均采用 windowed attention 以控制计算量位置信息完全交给 RoPErel_pos_blocks()并通过use_interp_rope支持高分辨率推理。多尺度颈部return Sam3DualViTDetNeck( position_encodingposition_encoding, d_model256, scale_factors[4.0, 2.0, 1.0, 0.5], # 4 个 FPN 级别的上/下采样因子 trunkvit_backbone, add_sam2_neckenable_inst_interactivity, # 是否追加 SAM2 风格颈部 )Sam3DualViTDetNecksam3/necks.py#L15把 72×72 的 ViT 输出展开为 4 个尺度特征scale_factors 对应 4.0/2.0/1.0/0.5即分别上采样/下采样到 288、144、72、36 分辨率级别输出通道统一为d_model256。当需要交互式实例分割SAM2 风格点/框提示时add_sam2_neckTrue会追加第二个用于 SAM2 头部的特征金字塔——这正是参数名为Dual的含义。该参数由build_sam3_image_model调用时固定传入enable_inst_interactivityTrue。_create_sam3_transformer()概念检测器的编码器与解码器定义于 build_sam3.py#L72-L132返回一个TransformerWrappersam3/model_misc.py内部封装融合编码器与 DETR 风格解码器。融合编码器encoder TransformerEncoderFusion( layerTransformerEncoderLayer( d_model256, dim_feedforward2048, dropout0.1, pos_enc_at_attnTrue, pos_enc_at_cross_attn_keysFalse, pos_enc_at_cross_attn_queriesFalse, pre_normTrue, # Pre-LN 结构 self_attentionnn.MultiheadAttention( # 自注意力 8 头 num_heads8, dropout0.1, embed_dim256, batch_firstTrue), cross_attentionnn.MultiheadAttention( # 文本交叉注意力 num_heads8, dropout0.1, embed_dim256, batch_firstTrue), ), num_layers6, d_model256, num_feature_levels1, frozenFalse, use_act_checkpointTrue, # 激活检查点省显存 add_pooled_text_to_img_featFalse, pool_text_with_maskTrue, # 文本特征按 mask 做池化 )TransformerEncoderFusionsam3/encoder.py的 forward 同时接收图像特征src与文本 prompt 特征在每层内做自注意力并通过cross_attention让图像 token 吸收文本 token 的信息实现以概念条件化图像特征。6 层、隐藏 256、FFN 2048 与 8 头是该检测器编码器的基础配置。解码器decoder TransformerDecoder( layerTransformerDecoderLayer( d_model256, dim_feedforward2048, dropout0.1, cross_attentionnn.MultiheadAttention(num_heads8, dropout0.1, embed_dim256), n_heads8, use_text_cross_attentionTrue, # 额外对文本做交叉注意力 ), num_layers6, num_queries200, # 每图 200 个目标查询 return_intermediateTrue, # 输出每层中间结果用于深度监督 box_refineTrue, # 逐层迭代式框回归 num_o2m_queries0, # 不使用 one-to-many 查询 dacTrue, # 动态锚框查询Dynamic Anchor Queries boxRPBlog, # 参考框对数空间旋转位置编码 d_model256, frozenFalse, interaction_layerNone, dac_use_selfatt_lnTrue, use_act_checkpointTrue, presence_tokenTrue, # 启用 presence token概念是否出现 )解码器sam3/decoder.py面向图像概念分割输出200 个可学习查询逐层 refine 边界框box_refineTrue并且presence_tokenTrue会额外维护一个学习到的全局 token用来在整图层面预测该概念是否出现——这正是 SAM3 论文中解耦识别what与定位where的 presence head 在解码器层面的实现载体。返回的TransformerWrapper(encoder, decoder, d_model256)统一了二者的前向接口。build_sam3_image_model()概念分割模型的完整装配定义于 build_sam3.py#L135-L255是PCS 检测器SAM3SemanticModel的唯一构建入口。def build_sam3_image_model(checkpoint_path: str, enable_segmentation: bool True, compile: bool False):参数默认值含义checkpoint_path必填权重文件路径如sam3.ptenable_segmentationTrue是否挂载 mask 分割头置False时只做检测级输出compileFalse为True时以default模式编译视觉骨干可提速但会增加首次编译开销该函数的装配步骤对应源码中清晰的注释段拆解如下。1) 文本编码器依赖注入CLIP tokenizertry: import clip except ImportError: from ultralytics.utils.checks import check_requirements check_requirements(githttps://github.com/ultralytics/CLIP.git) import clipSAM3 文本侧依赖 Ultralytics 维护的clip包提供 tokenizer。若环境未安装这里会调用 ultralytics/utils/checks.py 的check_requirements自动安装其 GitHub fork 版本。这也与 docs/en/models/sam-3.md 中提示的TypeError: SimpleTokenizer object is not callable问题一致——只要装了 PyPI 上错误的clip包代码内文本编码就会报错需按文档卸载并用该 fork 重装。2) 视觉 语言双塔拼接为 VL 骨干vision_encoder _create_vision_backbone(compile_modecompile_mode, enable_inst_interactivityTrue) text_encoder VETextEncoder( tokenizerclip.simple_tokenizer.SimpleTokenizer(), d_model256, width1024, heads16, layers24, # 24 层、16 头、宽 1024 的 CLIP 文本编码器 ) backbone SAM3VLBackbone(visualvision_encoder, texttext_encoder, scalp1)VETextEncodersam3/text_encoder_ve.py是一套 24 层 Transformer 的 CLIP 风格文本编码器输出投影到 256 维与视觉特征对齐。SAM3VLBackbonesam3/vl_combiner.py负责把两个塔缝合成一个统一前向接口并提供forward_image/forward_text/forward_image_sam2等方法。3) 点积打分器与 prompt MLPdot_prod_scoring DotProductScoring( d_model256, d_proj256, prompt_mlpMLP(input_dim256, hidden_dim2048, output_dim256, num_layers2, residualTrue, out_normnn.LayerNorm(256)), )DotProductScoringsam3/model_misc.py在对象查询与 prompt 嵌入之间计算相似度用于对该查询是否匹配当前概念打分prompt 先经两层 MLP含残差与 LayerNorm投影。4) 通用分割头 像素解码器segmentation_head UniversalSegmentationHead( hidden_dim256, upsampling_stages3, # 上采样 3 级直至全分辨率 aux_masksFalse, # 不输出辅助 mask presence_headFalse, # presence 判断交给解码器 dot_product_scorerNone, act_ckptTrue, cross_attend_promptnn.MultiheadAttention(num_heads8, dropout0, embed_dim256), pixel_decoderPixelDecoder( num_upsampling_stages3, interpolation_modenearest, # 逐级最近邻插值 hidden_dim256, compile_modecompile_mode, ), ) if enable_segmentation else NoneUniversalSegmentationHead与PixelDecoder都定义于 sam3/maskformer_segmentation.py。该头沿用 Mask2Former 式的查询 → 像素嵌入点积出 mask范式像素解码器把多尺度骨干特征逐级上采样融合分割头再把对象查询转化为每个对象的 mask logits。当enable_segmentationFalse时整个分割头被置为None模型只做检测级预测。5) 几何提示编码器exemplar 框/点的注入input_geometry_encoder SequenceGeometryEncoder( pos_encPositionEmbeddingSine(num_pos_feats256, normalizeTrue, ...), encode_boxes_as_pointsFalse, boxes_direct_projectTrue, # 框区域直接投影为 token boxes_poolTrue, # 聚合框内视觉特征 boxes_pos_encTrue, # 为框补充位置编码 d_model256, num_layers3, layerTransformerEncoderLayer(d_model256, dim_feedforward2048, dropout0.1, ...), use_act_ckptTrue, add_clsTrue, add_post_encode_projTrue, )SequenceGeometryEncodersam3/geometry_encoders.py把图像 exemplar 框/点等几何提示编码为与文本同空间的特征序列使一张示例框图 一段视觉 token 序列从而让 PCS 既能吃文本也能吃示例图像甚至二者组合。它默认把框区域内容投影boxes_direct_project并做池化与位置编码后送入 3 层 Transformer。6) 组装SAM3SemanticModel并装载权重model SAM3SemanticModel( backbonebackbone, transformertransformer, input_geometry_encoderinput_geometry_encoder, segmentation_headsegmentation_head, num_feature_levels1, # 单尺度特征级 o2m_mask_predictTrue, dot_prod_scoringdot_prod_scoring, use_instance_queryFalse, # 不使用单实例查询面向概念而非单个物体 multimask_outputTrue, ) model _load_checkpoint(model, checkpoint_path) model.eval()SAM3SemanticModelsam3/sam3_image.py串起整条推理链VL 骨干提取图像与文本特征 → 融合编码器吸收文本条件 → 解码器产出边界框与 presence 判断 → 几何编码器处理 exemplar → 分割头生成 mask。装配完成后立即eval()返回推理就绪的模型。build_interactive_sam3()SAM2 兼容的交互/视频跟踪模型定义于 build_sam3.py#L258-L348装配tracker 侧的SAM3Model支持点/框交互式分割与视频多目标跟踪PVS 任务。def build_interactive_sam3(checkpoint_path: str, compileNone, with_backboneTrue) - SAM3Model:记忆编码器与记忆注意力memory_encoder MemoryEncoder(out_dim64, interpol_size[1152, 1152]) memory_attention MemoryAttention( batch_firstTrue, d_model256, pos_enc_at_inputTrue, layerMemoryAttentionLayer( dim_feedforward2048, dropout0.1, self_attnRoPEAttention(embedding_dim256, num_heads1, rope_theta10000.0, feat_sizes[72, 72]), d_model256, cross_attnRoPEAttention(embedding_dim256, num_heads1, kv_in_dim64, rope_theta10000.0, feat_sizes[72, 72], rope_k_repeatTrue), ), num_layers4, )这部分对应 SAM2/SAM3 的视频记忆机制MemoryEncodermodules/encoders.py把历史预测 mask 压缩成 64 维记忆特征MemoryAttentionmodules/memory_attention.py通过 4 层、带 RoPE 的跨帧注意力self/cross attention 均为num_heads1、feat_sizes[72,72]把历史记忆融入当前帧特征。interpol_size[1152,1152]提示记忆特征会被上采样到 1152×1152 参与前向。可选骨干与跟踪器模型backbone (SAM3VLBackbone(scalp1, visual_create_vision_backbone(compile_modecompile), textNone) if with_backbone else None)与 image 模型不同交互式/跟踪模型的骨干只含视觉塔textNone并且with_backbone可关闭。SAM3VideoSemanticPredictor.setup_model在构建时显式传入with_backboneFalse见 ultralytics/models/sam/predict.py#L2598-L2606因为视频语义跟踪场景下视觉骨干已由 detectorimage 模型提供tracker 仅复用其记忆解码模块避免重复加载两份骨干。最后构造的SAM3Modelmodules/sam.py带有大量跟踪行为相关开关从源码可见其核心设置image_size1008、backbone_stride14、num_maskmem7记忆缓存帧数、pred_obj_scoresTrue、multimask_output_for_trackingTrue以及一组控制 object pointer 的选项use_obj_ptrs_in_encoderTrue、fixed_no_obj_ptrTrue等。它同时传入sam_mask_decoder_extra_args为 mask 解码器开启基于稳定性的动态多 mask 选择dynamic_multimask_via_stability等整体目标是让单目标视觉提示与多目标跟踪共享同一解码器。两种入口的汇合需要注意SAM3 的 image detector 与 interactive tracker 共享同一个视觉骨干但前向路径不同SAM3SemanticPredictor.get_im_features调用self.model.backbone.forward_image(im)取图像特征predict.py#L2234-L2237而 tracker 侧则通过_create_vision_backbone中add_sam2_neckTrue追加的 SAM2 特征层经forward_image_sam2取高分辨率特征。该设计可从上文 neck 参数推断得出。_load_checkpoint()权重装载与前缀重映射定义于 build_sam3.py#L351-L382被上述两个构建函数共用负责把官方发布的权重装进不同结构的模型。def _load_checkpoint(model, checkpoint, interactiveFalse): with open(checkpoint, rb) as f: ckpt torch_load(f) # 经 ultralytics 补丁后的安全 torch.load if model in ckpt and isinstance(ckpt[model], dict): ckpt ckpt[model] # 解包带 model 键的包装格式 # 统一剥离 detector. 前缀image 模型权重命名 sam3_image_ckpt {k.replace(detector., ): v for k, v in ckpt.items() if detector in k}torch_load来自 ultralytics/utils/patches.py是仓库为保证加载安全而对标准torch.load的封装。对 checkpoint 的装载策略为官方权重通常带有detector.、tracker.、backbone.等前缀这里一律先取包含detector前缀的键并剥掉前缀得到 image 侧权重字典随后再按interactive分支做tracker → interactive 模型的键名映射if interactive: # backbone.vision_backbone.* → image_encoder.vision_backbone.* # tracker.transformer.encoder.* → memory_attention.* # tracker.maskmem_backbone.* → memory_encoder.* # tracker.* → *剥离剩余 tracker 前缀最后统一model.load_state_dict(sam3_image_ckpt, strictFalse)——strictFalse意味着允许权重与模型结构不完全一一对应这是 SAM3 这样一个由 image 模型 interactive 模型共享部分权重尤其视觉骨干的框架得以复用单一sam3.pt文件的基础。可以推断官方发布的一个 checkpoint 同时承载了detector.概念检测与tracker.视频跟踪/交互分割两部分权重通过该函数按需提取。在推理链路中的真实调用关系虽然build_sam3.py不被用户直接调用但它是所有 SAM3 推理类的模型工厂调用点集中在 ultralytics/models/sam/predict.py调用方调用的构建函数说明SAM3SemanticPredictor.get_model()predict.py#L2228-L2232build_sam3_image_model(self.args.model, compileself.args.compile)概念分割文本/exemplar 提示SAM3Predictor.get_model()predict.py#L2218-L2222build_interactive_sam3(self.args.model, compileself.args.compile)SAM2 风格的交互式分割SAM3VideoSemanticPredictor.setup_model()predict.py#L2598-L2606build_interactive_sam3(self.args.model, with_backboneFalse)视频语义跟踪复用 detector 骨干SAM._load()ultralytics/models/sam/model.py#L76-L79build_interactive_sam3(weights)SAM(sam3.pt)走 SAM2 兼容视觉提示路径各调用方普遍对导入做**延迟slow import**处理——把build_sam3及其牵涉的大量模块放到get_model/setup_model阶段才导入避免用户仅加载其他模型时承担 SAM3 庞大的依赖与初始化开销这一点从 predict.py#L2220 等处的注释与结构可以确认。使用前提与实践约束把模块源码与仓库文档结合使用前需要满足两个前提权重需单独获取。与其它自动下载的 Ultralytics 模型不同sam3.pt权重并不会在首次运行时自动下载build_sam3_image_model与build_interactive_sam3都要求传入真实存在的checkpoint_path。权重获取流程与前置准备见 docs/en/models/sam-3.md。clip依赖必须来自 Ultralytics fork。image 模型构建会用到clip.simple_tokenizer.SimpleTokenizer若环境中安装的是 PyPI 同名但接口不同的clip包运行会出现SimpleTokenizer object is not callable。build_sam3_image_model虽在ImportError时会自动调用check_requirements(githttps://github.com/ultralytics/CLIP.git)尝试修复但更稳妥的做法是按文档预先安装正确依赖。总结build_sam3.py 是整个 SAM3 功能的装配车间_create_vision_backbone与_create_sam3_transformer是基础件工厂build_sam3_image_model面向概念分割PCS组装含文本编码器、presence token、分割头与几何编码器的SAM3SemanticModelbuild_interactive_sam3面向视觉提示与视频跟踪PVS组装带记忆机制的SAM3Model而_load_checkpoint以非严格方式完成官方权重的前缀重映射与装载。理解这五个函数及其在SAM3SemanticPredictor/SAM3VideoPredictor/SAM中的接线方式就等于掌握了在 Ultralytics 生态中实例化、扩展与调试 SAM3 的钥匙。【免费下载链接】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），仅供参考
