SAM3 实战上手指南：从安装到图像/视频分割全流程

本文面向希望快速上手 Meta SAM 3（Segment Anything with Concepts）的开发者，涵盖环境搭建、图像分割、视频分割及 Agent 智能体的完整使用流程。所有代码均基于官方源码和示例 Notebook 整理。

术语速查

术语	通俗解释
图像分割（Segmentation）	将图像中的目标对象从背景中精确"抠"出来，定位到每一个像素
掩码（Mask）	分割的输出结果。一张与原图同尺寸的二值图，值为 1 的像素表示"这里是目标"，值为 0 表示"这里是背景"。叠加到原图上就能看到目标被高亮标出
边界框（Bounding Box）	用一个矩形框标出目标对象的大致位置，比掩码粗糙但计算更快
MLLM	Multimodal Large Language Model，多模态大语言模型，既能理解文字又能理解图片的 AI 模型

1. SAM3 是什么

SAM 3（Segment Anything with Concepts）是 Meta 于 2025 年 11 月发布的新一代通用分割模型，2026 年 3 月更新至 SAM 3.1 版本。相较于前代 SAM 2，SAM 3 的核心进步包括：

• 开放词汇分割：支持通过自然语言文本描述来分割目标对象，可处理 27 万种以上的概念类别
• 图像 + 视频统一架构：同一模型同时支持图像分割和视频目标跟踪
• Presence Token 机制：能够区分语义相近的文本提示词（如 "白衣球员" 与 "红衣球员"）
• SAM 3.1 Object Multiplex：共享内存多目标跟踪方案，128 个目标场景下推理速度提升约 7 倍

许可证方面，SAM3 采用 Meta SAM License，允许商业使用，但需在分发时附带许可证副本，发表研究时需注明使用了 SAM Materials。

2. 环境搭建

2.1 硬件与软件要求

• Python ≥ 3.12
• PyTorch ≥ 2.7
• CUDA ≥ 12.6
• 支持 CUDA 的 GPU（推荐 Ampere 架构及以上）

2.2 安装步骤

# 1. 创建 Conda 环境
conda create -n sam3 python=3.12
conda activate sam3

# 2. 安装 PyTorch（CUDA 12.8）
pip install torch==2.10.0 torchvision --index-url https://download.pytorch.org/whl/cu128

# 3. 克隆仓库并安装
git clone https://github.com/facebookresearch/sam3.git
cd sam3
pip install -e .

# 4. 安装 Notebook 依赖（如需运行示例）
pip install -e ".[notebooks]"

2.3 可选加速依赖

# FlashAttention 3 + 编译优化（推荐）
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

2.4 模型权重获取

ModelScope（国内镜像，推荐国内用户）

国内网络环境可以从 ModelScope 魔搭社区下载：

1. 访问 ModelScope 搜索 SAM3 对应的模型页面
2. 手动下载权重文件（如 sam3.pt 或 sam3.1_multiplex.pt）

两种方式下载的权重文件相同，下载后均可通过 checkpoint_path 参数指定本地路径加载。

3. 图像分割实战

3.1 基本流程

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

# 开启 TF32 加速（Ampere GPU）
torch.backends.cuda.matmul.allow_tf32 = True
torch.backends.cudnn.allow_tf32 = True

# 使用 bfloat16 精度
torch.autocast("cuda", dtype=torch.bfloat16).__enter__()
torch.inference_mode().__enter__()

# 构建模型（首次运行会自动下载权重）
model = build_sam3_image_model()
processor = Sam3Processor(model, confidence_threshold=0.5)

# 加载图像
image = Image.open("your_image.jpg")
inference_state = processor.set_image(image)

# 文本 prompt 分割
output = processor.set_text_prompt(state=inference_state, prompt="person")

# 获取结果
masks = output["masks"]    # 分割掩码（每个元素是一张二值图，标记目标像素）
boxes = output["boxes"]    # 边界框（每个目标的矩形框坐标）
scores = output["scores"]  # 置信度分数（模型对每个检测结果的把握程度，0~1）

print(f"检测到 {len(scores)} 个对象")

3.2 使用本地权重

如果已手动下载权重文件，可通过以下方式加载：

import sam3

sam3_root = os.path.dirname(sam3.__file__)
# BPE 词表文件，用于将文本 prompt 转换为模型可处理的数字序列
# 该文件已随仓库代码提供在 sam3/assets/ 目录下，无需额外下载
bpe_path = f"{sam3_root}/assets/bpe_simple_vocab_16e6.txt.gz"

model = build_sam3_image_model(
    bpe_path=bpe_path,
    checkpoint_path="/path/to/sam3.pt",  # 本地权重路径
    load_from_HF=False,
)

3.3 结果可视化

import matplotlib.pyplot as plt
from sam3.visualization_utils import plot_results

# 使用内置可视化工具
plot_results(image, masks, boxes, scores)
plt.show()

4. 视频分割实战

SAM3 的视频分割采用会话式（Session-based）API，支持有状态的交互式推理。

4.1 构建视频预测器

import torch
from sam3.model_builder import build_sam3_video_predictor

# 使用所有可用 GPU
gpus_to_use = range(torch.cuda.device_count())
# 或仅使用单个 GPU
# gpus_to_use = [torch.cuda.current_device()]

predictor = build_sam3_video_predictor(gpus_to_use=gpus_to_use)

4.2 开启推理会话

# video_path 可以是 JPEG 帧文件夹或 MP4 视频文件
video_path = "assets/videos/0001"

response = predictor.handle_request(
    request=dict(
        type="start_session",
        resource_path=video_path,
    )
)
session_id = response["session_id"]

4.3 添加文本 prompt 并传播

# 在第 0 帧添加文本 prompt
response = predictor.handle_request(
    request=dict(
        type="add_prompt",
        session_id=session_id,
        frame_index=0,
        text="person",
    )
)

# 将分割结果传播到整个视频
outputs_per_frame = {}
for response in predictor.handle_stream_request(
    request=dict(
        type="propagate_in_video",
        session_id=session_id,
    )
):
    outputs_per_frame[response["frame_index"]] = response["outputs"]

4.4 使用点 prompt 进行交互式分割

除文本 prompt 外，SAM3 视频模式还支持点击式交互：

# 在指定帧添加正向点击（label=1）和负向点击（label=0）
response = predictor.handle_request(
    request=dict(
        type="add_prompt",
        session_id=session_id,
        frame_index=0,
        points=[[0.5, 0.3]],   # 归一化坐标 [x, y]
        labels=[1],             # 1=正向, 0=负向
    )
)

4.5 重置会话

切换 prompt 前需要重置会话：

predictor.handle_request(
    request=dict(
        type="reset_session",
        session_id=session_id,
    )
)

5. SAM3 Agent 快速体验

SAM3 Agent 将 MLLM（多模态大语言模型，既能看图又能理解文字的 AI）与 SAM3 分割模型结合，可处理复杂的自然语言查询，如 "the leftmost child wearing blue vest"（最左边穿蓝色背心的小孩）。

5.1 准备 MLLM 服务

Agent 需要一个 MLLM 后端作为"大脑"来理解用户意图并指挥 SAM3 工作。最简单的方式是使用阿里云 DashScope API（Qwen-VL 系列）：

LLM_CONFIGS = {
    "qwen-vl-max": {
        "provider": "dashscope",
        "model": "qwen-vl-max",
        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    },
}

llm_config = LLM_CONFIGS["qwen-vl-max"]
llm_config["api_key"] = "your-dashscope-api-key"  # 替换为实际 API Key
llm_config["name"] = "qwen-vl-max"
LLM_SERVER_URL = llm_config["base_url"]

也可以使用 vLLM 本地部署开源模型：

# 在独立的 Conda 环境中安装 vLLM
conda create -n vllm python=3.12
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

# 启动 vLLM 服务
vllm serve Qwen/Qwen3-VL-8B-Thinking \
    --tensor-parallel-size 4 \
    --allowed-local-media-path / \
    --enforce-eager \
    --port 8001

5.2 运行 Agent 推理

from functools import partial
from sam3.agent.client_llm import send_generate_request as send_generate_request_orig
from sam3.agent.client_sam3 import call_sam_service as call_sam_service_orig
from sam3.agent.inference import run_single_image_inference

# 构建 SAM3 模型和处理器（参考第 3 节）
model = build_sam3_image_model()
processor = Sam3Processor(model, confidence_threshold=0.5)

# 绑定参数
send_generate_request = partial(
    send_generate_request_orig,
    server_url=LLM_SERVER_URL,
    model=llm_config["model"],
    api_key=llm_config["api_key"],
)
call_sam_service = partial(call_sam_service_orig, sam3_processor=processor)

# 执行推理
image_path = "assets/images/test_image.jpg"
prompt = "the leftmost child wearing blue vest"

run_single_image_inference(
    image_path,
    prompt,
    llm_config,
    send_generate_request,
    call_sam_service,
    output_dir="agent_output",
    debug=True,
)

运行后，agent_output 目录下会生成：

• *_pred.json：预测结果的结构化数据（包含掩码、边界框坐标、置信度分数）
• *_pred.png：可视化结果图（目标对象被高亮标出的图片）
• *_history.json：Agent 与 MLLM 的完整对话历史（debug 模式下生成，便于排查问题）

6. SAM 3 vs SAM 3.1

SAM 3.1 于 2026 年 3 月发布，主要改进在视频推理效率方面：

特性	SAM 3	SAM 3.1
多目标跟踪	逐对象独立处理	Object Multiplex 联合处理
128 目标推理速度	基准	~7x 加速
torch.compile 支持	基础	增强融合优化
后处理	逐个处理	批量处理

使用 SAM 3.1 模型：

from sam3.model_builder import build_sam3_multiplex_video_model

# 构建 SAM 3.1 Multiplex 视频模型
model = build_sam3_multiplex_video_model()

7. 常见问题

Q: 显存不足怎么办？

• 确保使用 bfloat16 或 float16 精度
• 视频模式下减少同时跟踪的目标数量
• 使用单 GPU 模式而非多 GPU

Q: 首次推理很慢？

• 首次运行需要下载模型权重和编译内核，后续运行会显著加快
• 安装 FlashAttention 3 和 cc_torch 可进一步提升速度

Q: Agent 推理报 JSON 解析错误？

• 检查 MLLM 服务是否正常运行
• 确认 API Key 有效
• 部分 MLLM 可能不严格遵循工具调用格式，建议使用 Qwen-VL-Max 或更大参数的模型

8. 参考资料

• SAM 3 GitHub 仓库：https://github.com/facebookresearch/sam3
• SAM 3 论文：https://arxiv.org/abs/2511.16719
• SAM 3 项目主页：https://ai.meta.com/sam3
• SAM 3.1 发布说明：仓库内 RELEASE_SAM3p1.md

---

本文基于 SAM3 开源代码及官方示例 Notebook 整理，代码版本为 SAM 3.1（2026 年 3 月）。实际运行效果可能因硬件环境和模型版本而异。