基本介绍#

SAM3 (Segment Anything Model 3) 是 Meta AI 研究院开发的一款强大的图像分割模型，能够在各种图像上进行高效的分割任务。

• SAM3 论文
• 代码

Okay, clone 完项目的代码后，在 README.md 中可以看到 SAM3 的基本结构图。

模型结构#

README.md 中是这样介绍 SAM3 的：

SAM 3 is a unified foundation model for promptable segmentation in images and videos. It can detect, segment, and track objects using text or visual prompts such as points, boxes, and masks. Compared to its predecessor SAM 2, SAM 3 introduces the ability to exhaustively segment all instances of an open-vocabulary concept specified by a short text phrase or exemplars. Unlike prior work, SAM 3 can handle a vastly larger set of open-vocabulary prompts. It achieves 75-80% of human performance on our new SA-CO benchmark which contains 270K unique concepts, over 50 times more than existing benchmarks.

This breakthrough is driven by an innovative data engine that has automatically annotated over 4 million unique concepts, creating the largest high-quality open-vocabulary segmentation dataset to date. In addition, SAM 3 introduces a new model architecture featuring a presence token that improves discrimination between closely related text prompts (e.g., “a player in white” vs. “a player in red”), as well as a decoupled detector–tracker design that minimizes task interference and scales efficiently with data.

相较于 SAM2，SAM3 的改进主要体现在以下几个方面：

1. 能力质变：从依赖点、框的视觉提示进化为理解开放词汇文本，能自动找出画面中所有符合描述（如“穿红衣的球员”）的实例。
2. 架构解耦：采用 Detector（负责理解语义）与Tracker（负责时序传播）分离的设计，共享主干网络以减少任务干扰并提升扩展性。
3. 判别精准：引入 Presence Token 机制，专门用于区分相似文本描述（如颜色、属性差异），显著提升了语义判别的准确率。

配置环境#

参考 README.md 中的说明，作如下配置（注意这个只适用于 Linux/macOS 系统）

conda create -n sam3 python=3.12 -y
conda activate sam3

cd sam3
pip install torch==2.10.0 torchvision --index-url https://download.pytorch.org/whl/cu128

pip install -e .

# Additional dependencies for training and evaluation

# For running example notebooks
pip install -e ".[notebooks]"

# For development
pip install -e ".[train,dev]"

# Optional dependencies for faster inference
pip install einops ninja 
pip install flash-attn-3 --no-deps --index-url https://download.pytorch.org/whl/cu128
pip install git+https://github.com/ronghanghu/cc_torch.git

Python 3.12 以上版本将弃用 pkg_resources 模块，而且在 Windows 版本的 Python 解释器中，这个模块已经被完全移除了，但是 SAM3 开发是在 Linux 上进行的，而且还使用了这个古老的模块，因此在 Windows 系统上直接安装 SAM3 的依赖会遇到兼容性问题。 对于 Windows 系统，建议使用 WSL 来配置环境。如果已经安装好了 UV，可以使用如下 pyproject.toml 来配置环境：

[build-system]
requires = ["setuptools>=61", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "sam_unified"
version = "0.1.0"
description = "Unified Segment Anything Model (SAM 2 & 3) implementation"
readme = "README.md"
requires-python = ">=3.12"
license = {text = "MIT"}
authors = [
    {name = "Meta AI Research"}
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
]
dependencies = [
    "torch>=2.7",
    "torchvision",
    "timm>=1.0.17",
    "numpy>=1.26,<2",
    "tqdm",
    "ftfy==6.1.1",
    "regex",
    "iopath>=0.1.10",
    "typing_extensions",
    "huggingface_hub",
    "pillow",
    "einops",
    "pycocotools",
    "psutil",
    "triton",
    "scipy",
    "opencv-python",
    "modelscope",
]

[project.optional-dependencies]
dev = [
    "pytest",
    "pytest-cov",
    "black==24.2.0",
    "ufmt==2.8.0",
    "ruff-api==0.1.0",
    "usort==1.0.2",
    "gitpython==3.1.31",
    "yt-dlp",
    "pandas",
    "opencv-python",
    "pycocotools",
    "numba",
    "python-rapidjson",
]
notebooks = [
    "matplotlib",
    "jupyter",
    "notebook",
    "ipywidgets",
    "ipycanvas",
    "ipympl",
    "pycocotools",
    "decord",
    "opencv-python",
    "einops",
    "scikit-image",
    "scikit-learn",
]
train = [
    "hydra-core",
    "submitit",
    "tensorboard",
    "zstandard",
    "scipy",
    "torchmetrics",
    "fvcore",
    "fairscale",
    "scikit-image",
    "scikit-learn",
]

[tool.setuptools.packages.find]
include = ["sam2*", "sam3*"]

[tool.uv]
index-url = "https://mirrors.aliyun.com/pypi/simple/"
extra-index-url = ["https://download.pytorch.org/whl/cu128"]
index-strategy = "unsafe-best-match"

预训练模型下载#

SAM3 的模型权重不像 SAM, SAM2 那样提供了 .pt 权重文件，而是必须通过 huggingface 平台获取，而且还需要提交使用申请。

• SAM3 huggingface repo
• 申请指导

考虑到申请 SAM3 的模型权重非常的容易被拒绝，这里推荐使用魔塔社区先下载模型权重，再用 huggingface 加载的方式：

# 确保已经安装了 modelscope
pip install modelscope

# 下载 SAM3 模型权重
modelscope download --model facebook/sam3

# 下载 SAM3.1 模型权重
modelscope download --model facebook/sam3.1

下载完成后，在 modelscope 的本地 repo 文件中可以直接看到 sam3.pt 和 sam3.1_multiplex.pt 的权重文件的，这个时候可以直接使用

model = build_sam3_image_model(load_from_HF=False, checkpoint_path="your/path/to/sam3.pt")

的方式来加载模型权重了，下面的接口展示也是以这个加载方式为例。需要注意的是，如果是 Windows WSL 加载模型的话，路径开头不是 Windows 格式，而是 /mnt/d (D 盘) 这样的格式。

数据类型 Debug#

由于 SAM3 的发布时间距今并不长，因此官方代码中仍然存在不少的 bugs。在运行官方接口之前，需要先修改 sam3/sam3/perflib/fused.py 中的 addmm_act() 函数:

def addmm_act(activation, linear, mat1):
    if torch.is_grad_enabled():
        raise ValueError("Expected grad to be disabled.")
    self = linear.bias.detach()
    mat2 = linear.weight.detach()
    # keep the original dtype so we can cast the result back
    out_dtype = linear.weight.dtype if hasattr(linear, "weight") else mat1.dtype
    self = self.to(torch.bfloat16)
    mat1 = mat1.to(torch.bfloat16)
    mat2 = mat2.to(torch.bfloat16)
    mat1_flat = mat1.view(-1, mat1.shape[-1])
    if activation in [torch.nn.functional.relu, torch.nn.ReLU]:
        y = addmm_act_op(self, mat1_flat, mat2.t(), beta=1, alpha=1, use_gelu=False)
        return y.view(mat1.shape[:-1] + (y.shape[-1],)).to(out_dtype)
    if activation in [torch.nn.functional.gelu, torch.nn.GELU]:
        y = addmm_act_op(self, mat1_flat, mat2.t(), beta=1, alpha=1, use_gelu=True)
        return y.view(mat1.shape[:-1] + (y.shape[-1],)).to(out_dtype)
    raise ValueError(f"Unexpected activation {activation}")

修改完成后，就可以运行下列代码了。

单张图像预测——文本提示#

import torch
from PIL import Image
from sam3.model_builder import build_sam3_image_model
from sam3.model.sam3_image_processor import Sam3Processor


# Load the model
model = build_sam3_image_model(load_from_HF=False, checkpoint_path="your/path/to/sam3.pt")
print(model.device)

processor = Sam3Processor(model)
# Load an image
image = Image.open("input.jpg")
inference_state = processor.set_image(image)
# Prompt the model with text
output = processor.set_text_prompt(state=inference_state, prompt="A man in the red.")

# Get the masks, bounding boxes, and scores
masks, boxes, scores = output["masks"], output["boxes"], output["scores"]

输出的 output 是一个字典，格式如下：

{
    "original_height": int,                 # 输入图像的原始高度 H
    "original_width": int,                  # 输入图像的原始宽度 W

    # 视觉-语言骨干网络输出（SAM3VLBackbone）
    "backbone_out": dict(                   # 主干网络的输出特征图
        "vision_features": Tensor,          # 多尺度视觉特征图 [B, 256, 72, 72]
        "vision_pos_enc": list[Tensor],     # 位置编码（多层级），len=3
        "backbone_fpn": list[Tensor],       # FPN 各层输出，len=3
        "sam2_backbone_out": dict | None,   # SAM2 兼容模式输出

        # 文本提示编码器输出
        "language_features": Tensor,        # 文本语义特征 (seq_len, B, 256)
        "language_mask": boolean Tensor,    # Attention掩码 (B, seq_len)
        "language_embeds": Tensor,          # Token级嵌入 (seq_len, B, 1024)
    ),

    # 几何提示编码器输出
    "geometric_prompt": Prompt Object,      # 编码后的点、框、掩码几何提示

    # 检测解码器最终输出
    "masks_logits": Tensor,                 # 原始logits (N, 1, H, W)
    "masks": boolean Tensor,                # 二值掩码 (N, 1, H, W)
    "boxes": Tensor,                        # 边界框 (N, 4) (x1, y1, x2, y2)
    "scores": Tensor,                       # 置信度分数 (N, )
}

视频预测器修改#

考虑到我们使用的不是 huggingface 上的模型权重，因此需要为 sam3/sam3/model/sam3_video_predictor.py 添加 load_from_HF 参数:

class Sam3VideoPredictor(Sam3BasePredictor):
    def __init__(
        self,
        checkpoint_path=None,
        load_from_HF=True,          # 新增参数，控制是否从 huggingface 加载模型权重
        bpe_path=None,
        has_presence_token=True,
        geo_encoder_use_img_cross_attn=True,
        strict_state_dict_loading=True,
        async_loading_frames=False,
        video_loader_type="cv2",
        apply_temporal_disambiguation: bool = True,
        compile: bool = False,
    ):
        super().__init__()
        self.async_loading_frames = async_loading_frames
        self.video_loader_type = video_loader_type
        from sam3.model_builder import build_sam3_video_model

        self.model = (
            build_sam3_video_model(
                checkpoint_path=checkpoint_path,
                load_from_HF=load_from_HF,              # 传递参数控制加载方式
                bpe_path=bpe_path,
                has_presence_token=has_presence_token,
                geo_encoder_use_img_cross_attn=geo_encoder_use_img_cross_attn,
                strict_state_dict_loading=strict_state_dict_loading,
                apply_temporal_disambiguation=apply_temporal_disambiguation,
                compile=compile,
            )
            .cuda()
            .eval()
        )
    
    # 其余功能函数不做修改
    ...

这是因为 build_sam3_video_model 函数中确实有 load_from_HF 的参数控制，但是在 Sam3VideoPredictor 的构造函数中并没有传递这个参数，因此默认是从 huggingface 加载模型权重的，这样就会导致我们无法使用本地下载的模型权重了。

结合文本提示的视频预测#

from sam3.model_builder import build_sam3_video_predictor

def video_predict(video_path: str, text_prompt: str, sam3_checkpoint_path: str = "your/path/to/sam3.pt"):
    # 加载模型
    video_predictor = build_sam3_video_predictor(
        load_from_HF=False, 
        checkpoint_path=sam3_checkpoint_path
    )
    
    # 开启一个 session，逐帧把视频的 RGB 像素压缩成特征图
    start_response = video_predictor.handle_request(
        request=dict(
            type="start_session",
            resource_path=video_path,
        )
    )

    # 得到 session_id，后续的所有请求都要带上这个 ID，底层才能把它们关联到同一个视频上，进行正确的时序跟踪和掩码传播
    # 模型可以同时处理不同的 sessions，每个 session 代表一个视频，互不干扰
    session_id = start_response["session_id"]
    print("Session started with ID:", session_id)

    # 为当前的 session 增加文本提示，触发给定帧的 Mask 预测
    response = video_predictor.handle_request(
        request=dict(
            type="add_prompt",
            session_id=session_id,
            frame_index=0,                      # 可以是任意的帧
            text=text_prompt,
        )
    )
    # 观察初始检测到多少个与文本提示相关的对象（Mask），这些对象都会被记录，并在整个视频中被跟踪
    output = response["outputs"]
    print(f"The number of initial predicted objects related to the prompt \"{text_prompt}\" is ", len(output.get("out_binary_masks", [])))

    print("---------- Starting Video Propagation ----------")
    outputs_per_frame = {}
    for stream_resp in video_predictor.handle_stream_request(
        request=dict(
            type="propagate_in_video",
            session_id=session_id,
        )
    ):
        f_idx = stream_resp["frame_index"]                  # 异步执行，实际上 tqdm 的进度条和帧预测的时间进度是不同的，预测帧的操作比特征提取的操作要慢好几个时间步
        outputs_per_frame[f_idx] = stream_resp["outputs"]

    return outputs_per_frame


video_path = "your/path/to/video.mp4"     # 或者 "your/path/to/image_folder" (JPG 图像文件夹或视频文件)
text_prompt = "People"
outputs_per_frame = video_predict(video_path, text_prompt)

输出的 outputs_per_frame 是一个字典套字典，键是帧索引，值是一个包含预测结果的字典。每一帧的预测结果的字典格式如下：

{
    # 对象标识
    "out_obj_ids": np.ndarray[int64],        # 形状: (N,)，跟踪对象的唯一ID
    
    # 置信度分数
    "out_probs": np.ndarray[float32],        # 形状: (N,)，每个对象的检测置信度
    
    # 边界框（归一化坐标）
    "out_boxes_xywh": np.ndarray[float32],   # 形状: (N, 4)，格式: [x_center, y_center, width, height]
                                              # ⚠️ 注意：是中心点坐标 + 宽高，且是归一化的（0-1范围）
    
    # 二值掩码
    "out_binary_masks": np.ndarray[bool],    # 形状: (N, H, W)，每个对象的像素级分割掩码，这个也是最常用的预测掩码结果
    
    # 帧统计信息
    "frame_stats": {
        "num_obj_tracked": int,               # 当前成功跟踪的对象数量
        "num_obj_dropped": int                # 丢失/被丢弃的对象数量
    }
}

1.1 Sam3BasePredictor (model/sam3_base_predictor.py)#

类作用: SAM 3 和 SAM 3.1 视频预测器的共享底层基类，提供统一的推流、请求接管与长驻内存的会话注册表（Session Manager）机制。负责会话管理（启动、重置、关闭）、请求分发（handle_request / handle_stream_request）以及通用的 add_prompt / propagate_in_video / remove_object / reset_session / close_session 方法。

属性表格:

方法表格:

1.2 Sam3MultiplexVideoPredictor (model/sam3_multiplex_video_predictor.py)#

类作用: 面向用户的 SAM 3.1 Multiplex（多路复用多目标追踪）预测容器。集成了 BF16 精度上下文和 Torch Dynamo (torch.compile) 预热机制。包装了 Sam3MultiplexTrackingWithInteractivity，提供 bf16 自动转换、预热编译、会话过期管理以及从 Sam3BasePredictor 继承的 handle_request / handle_stream_request 分发 API。

属性表格:

方法表格:

注意：此类继承自 Sam3BasePredictor，因此也拥有所有基类方法（handle_request、start_session、add_prompt 等）。

1.3 Sam3VideoPredictor (model/sam3_video_predictor.py)#

类作用: 非复用（Non-multiplex）版本的基础 SAM 3 Tracker 的对外用户封装，保持了与 SAM 2 SAM2VideoPredictor 极为相似的接口风格（以向后兼容单目标/精简模式追踪）。继承自 Sam3BasePredictor，负责加载 SAM3 视频模型，提供单 GPU 推理。同时包含多 GPU 扩展类 Sam3VideoPredictorMultiGPU 以支持分布式推理。

属性表格 (Sam3VideoPredictor):

方法表格 (Sam3VideoPredictor):

类 Sam3VideoPredictorMultiGPU (继承自 Sam3VideoPredictor):

属性表格:

方法表格:

1.4 Sam3Processor (model/sam3_image_processor.py)#

类作用: 面向单张/多张无关图像推理过程的封装调度机，自动处理 torchvision.transforms.v2 以及基础数据状态对齐。负责图像预处理、文本/几何提示添加、前向推理及结果后处理。

属性表格:

方法表格:

2.1 Sam3TrackerBase (model/sam3_tracker_base.py)#

类作用: SAM 3 视频跟踪的核心基类，整合图像主干网络、Transformer 编码器模块和过去帧记忆的 Cross-Attention 系统。负责管理时序记忆、特征融合、SAM 头推理以及帧间跟踪状态维护。继承自 torch.nn.Module，是所有跟踪器的基础架构。

属性表格:

初始化参数表格 (传递给 __init__ 的配置):

方法表格:

静态方法:

• concat_points(old_point_inputs, new_points, new_labels): 将新点和标签添加到先前的点输入中（添加到末尾）。

2.2 Sam3MultiplexTracking 等族系 (sam3_multiplex_tracking.py)#

类作用: SAM 3.1 多路复用（Multiplex）多目标跟踪的核心实现族系，继承自 Sam3MultiplexBase（进而继承 Sam3VideoBase）。承担同时跟踪数十个甚至上百个交织目标的复杂管理任务，支持多GPU分布式推理、热启动延迟（hotstart）、掩码确认（masklet confirmation）、批处理后处理等高级特性。族系包含三个主要类：Sam3MultiplexTracking（基础版本）、Sam3MultiplexTrackingProd（生产版本，支持批处理视频）和 Sam3MultiplexTrackingWithInteractivity（交互增强版本，支持用户操作历史记录与部分传播）。

2.3 Sam3VideoBase (sam3_video_base.py)#

类作用: SAM 3 视频跟踪的基础类，继承自 torch.nn.Module，整合检测器（detector）和跟踪器（tracker）两大核心组件，实现检测-跟踪匹配、热启动延迟（hotstart）、掩码确认（masklet confirmation）、非极大值抑制（NMS）、分布式推理等核心跟踪逻辑。作为预测器（Predictor）和跟踪器（Tracker）之间的中间抽象层，隔离业务逻辑与模型拓扑，提供统一的单帧推理流程 _det_track_one_frame。

属性表格:

初始化参数表格 (传递给 Sam3VideoBase.__init__ 的配置):

方法表格:

静态方法:

• _convert_to_numpy(self): 将张量转换为NumPy数组。
• _create_cpu_metadata(self, trk_obj_ids, det_masks): 创建CPU元数据。

2.4 Sam3MultiplexBase (sam3_multiplex_base.py)#

类作用: SAM 3.1 多路复用（Multiplex）跟踪的中间抽象层，继承自 Sam3VideoBase，为多路复用跟踪添加特定配置和功能。引入多路复用控制器（bucket capacity）、批处理接地（batched grounding）、生产环境标志（running_in_prod）、性能分析等特性，是多路复用跟踪族系（Sam3MultiplexTracking等）的直接父类。

继承关系: Sam3MultiplexBase → Sam3VideoBase

属性表格 (特有属性，不包括继承的属性):

初始化参数表格 (传递给 Sam3MultiplexBase.__init__ 的特有参数):

注: 此外还继承所有 Sam3VideoBase 的初始化参数（如 score_threshold_detection、hotstart_delay 等）。

方法表格 (特有方法，不包括继承的方法):

注: 此类继承所有 Sam3VideoBase 的方法（如 run_backbone_and_detection、run_tracker_propagation 等）。

3.1 Sam3Image & Sam3ImageOnVideoMultiGPU (sam3_image.py / multiplex_detector)#

类作用: SAM 3 多模态图像检测与分割模型，支持文本提示（“Find Object”）的视觉-语言联合推理。作为检测器核心，处理图像特征提取、几何提示编码、Transformer编码器-解码器推理和分割头预测，为视频跟踪提供单帧检测能力。

继承关系:

• Sam3Image → torch.nn.Module
• Sam3ImageOnVideoMultiGPU → Sam3Image

3.2 SAM3VLBackbone (vl_combiner.py / vitdet.py / necks.py)#

类作用: Visual-Language Backbone（视觉-语言骨干网络）。将视觉骨干网络（Vision Transformer，来自Hiera或VitDet，负责密集像素特征提取）与语言编码器（Text Encoder，负责理解文本提示如”红色的车”）组合在一起，但不进行特征融合。主要作为方便包装器，统一处理两个骨干网络的激活检查点和编译优化。

文件位置:

• 主类: model/vl_combiner.py
• 视觉骨干: model/necks.py (Sam3DualViTDetNeck, Sam3TriViTDetNeck)
• 文本编码器: 外部提供（如CLIP、BERT等）

3.3 Prompt 集成包装 (geometry_encoders.py)#

说明: Prompt 是一个几何提示工具类，用于操作几何提示（框、点、掩码），遵循 PyTorch 序列优先的约定。它封装了三种类型的几何提示：边界框（boxes）、点（points）和掩码（masks），并提供了统一的接口进行拼接、克隆等操作。MaskEncoder 是掩码编码器的基类，负责将输入掩码下采样并添加位置编码。FusedMaskEncoder 是 MaskEncoder 的子类，额外融合了图像特征。SequenceGeometryEncoder 是一个完整的几何提示编码器，支持将框、点、掩码编码为统一的序列表示。

类定义: class Prompt:（第83行）

属性表:

初始化参数表:

核心方法表:

类定义: class MaskEncoder(nn.Module):（第404行）

属性表:

初始化参数表:

核心方法表:

类定义: class FusedMaskEncoder(MaskEncoder):（第425行）

属性表（继承自 MaskEncoder，新增）:

初始化参数表（继承自 MaskEncoder，新增）:

核心方法表:

类定义: class SequenceGeometryEncoder(nn.Module):（第470行）

属性表:

初始化参数表:

核心方法表:

注意: SequenceGeometryEncoder 支持三种编码方式的任意组合（直接投影、特征池化、位置编码），组合时采用简单相加。若 encode_boxes_as_points=True，边界框将被转换为两个点（左上和右下）并与现有点序列拼接。

4.1 MultiplexMaskDecoder (multiplex_mask_decoder.py & maskformer_segmentation.py)#

说明: MultiplexMaskDecoder 是一个支持多路复用（multiplex）的掩码解码器，能够同时预测多个目标的掩码。它借鉴了 MaskFormer 的思想，使用 Transformer 架构和动态多掩码选择机制。maskformer_segmentation.py 提供了 SegmentationHead、PixelDecoder、UniversalSegmentationHead 等组件，用于像素级特征解码和掩码预测。

类定义: class MultiplexMaskDecoder(nn.Module):（第16行）

属性表:

初始化参数表:

核心方法表:

辅助类: class MLP(nn.Module):（第448行）—— 简单的多层感知机，用于 IoU 预测头等。

类定义: class SegmentationHead(nn.Module):（第56行）

属性表:

初始化参数表:

核心方法表:

类定义: class PixelDecoder(nn.Module):（第184行）

属性表:

初始化参数表:

核心方法表:

类定义: class UniversalSegmentationHead(SegmentationHead):（第234行）

属性表（继承自 SegmentationHead，新增）:

初始化参数表（继承自 SegmentationHead，新增）:

核心方法表:

注意: maskformer_segmentation.py 还包含 LinearPresenceHead（第16行）和 MaskPredictor（第25行）等辅助类。

4.2 MaskDecoder (sam/mask_decoder.py)#

说明: 标准的 Transformer 掩码解码器，用于根据图像嵌入和提示嵌入预测掩码。它支持多掩码输出（每个提示最多输出4个掩码：1个主掩码 + 3个辅助掩码）和动态多掩码选择机制（基于稳定性分数）。是 SAM 系列的核心解码组件。

类定义: class MaskDecoder(nn.Module):（第14行）

属性表: