SAM 3 视频分割实战教程：用文本提示分割并跟踪视频中的目标

这篇教程是我根据近期学习 Segment Anything 3、视频分割和视觉提示分割流程的复现过程整理出来的，重点演示如何使用 SAM 3 在视频中根据文本概念提示完成目标分割，并在后续帧中传播分割结果。

SAM 3（Segment Anything Model 3）把 SAM 系列从“分割单个对象”扩展到“理解并分割图像和视频中某个概念的所有实例”。它引入了 Promptable Concept Segmentation（PCS，可提示概念分割）：用户可以通过短名词短语，例如striped cat，或者通过视觉样例指定一个概念；模型会检测、分割并跟踪所有匹配对象，同时在视频帧之间保持对象身份。

本文会重点跑通以下流程：

• 配置 HuggingFace Token 并安装 SAM 3
• 下载示例视频并切分成帧
• 启动 SAM 3 视频推理会话
• 用文本提示添加目标概念
• 将 SAM 3 输出转换成supervision检测格式
• 将分割结果传播到完整视频并导出结果视频

如果你正在系统学习图像分割、视频分割和视觉大模型，可以先收藏本文；配套 notebook、示例视频和后续同系列更新，我会整理成资料包，后面统一放到更方便获取的位置。

⚙️ 环境准备

SAM 3 需要访问 HuggingFace 上的模型权重，并依赖 GPU 运行视频推理。本节会完成 Token 配置、GPU 检查、依赖安装和示例视频下载。

🔑 配置 HuggingFace Token

拉取 SAM 3 权重需要 HuggingFace Access Token，并且需要你已经获得 SAM 3 checkpoint 的访问权限。

• 在官方 Hugging Face repo 申请 SAM 3 checkpoint 访问权限。
• 打开 HuggingFace Settings 页面，点击 Access Tokens，再点击 New Token 生成新的 token。
• 在 Colab 左侧面板点击 Secrets（🔑），将 HuggingFace Access Token 保存为HF_TOKEN。

如果你还不熟悉 HuggingFace 权重权限申请、Colab Secrets 或 SAM 3 环境配置，可以在评论区说明卡住的位置；我后续会把环境配置清单和常见报错整理到同系列资料里。

importosfromgoogle.colabimportuserdata os.environ["HF_TOKEN"]=userdata.get("HF_TOKEN")

🧪 检查 GPU 是否可用

先确认当前环境是否可以访问 GPU。可以使用nvidia-smi命令进行检查。如果在 Colab 中遇到 GPU 不可用的问题，可以进入Edit->Notebook settings->Hardware accelerator，将硬件加速器设置为T4 GPU，然后点击Save。

!nvidia-smi

importtorchimporttorchvisionprint("PyTorch version:",torch.__version__)print("Torchvision version:",torchvision.__version__)print("CUDA is available:",torch.cuda.is_available())

🔧 安装 SAM 3 和额外依赖

下面从官方 GitHub 仓库克隆 SAM 3，并安装 notebook 所需依赖。

!git clone https://github.com/facebookresearch/sam3.git%cd sam3 !pip install-e".[notebooks]"%cd/content

!pip install-q supervision jupyter_bbox_widget

下面两个扩展依赖用于 SAM 3 运行中的 CUDA / NMS 相关能力。不同 Colab GPU 架构可能需要一点编译时间。

!pip uninstall-y cc_torch;TORCH_CUDA_ARCH_LIST="8.0 9.0";pip install git+https://github.com/ronghanghu/cc_torch !pip uninstall-y torch_generic_nms;TORCH_CUDA_ARCH_LIST="8.0 9.0";pip install git+https://github.com/ronghanghu/torch_generic_nms

🎬 下载示例视频

下面下载几段示例视频。你也可以把SOURCE_VIDEO替换成自己的视频文件路径。

!wget-q https://storage.googleapis.com/com-roboflow-marketing/supervision/video-examples/jets-1280x720-1.mp4 !wget-q https://storage.googleapis.com/com-roboflow-marketing/supervision/video-examples/jets-1280x720-2.mp4 !wget-q https://storage.googleapis.com/com-roboflow-marketing/supervision/video-examples/jets-1280x720-3.mp4 !wget-q https://storage.googleapis.com/com-roboflow-marketing/supervision/video-examples/go-karts-1280x720-3.mp4

⚠️ 安装完成后建议重启 session。

📦 导入依赖

重启后，导入视频处理、图像处理、SAM 3 构建器和supervision等依赖。

importcv2importtorchimportnumpyasnpimportsupervisionassvfrompathlibimportPathfromPILimportImagefromtypingimportOptionalfromIPython.displayimportVideofromsam3.model_builderimportbuild_sam3_video_predictor

HOME=Path.cwd()print("HOME:",HOME)

🧠 Promptable Concept Segmentation（PCS）

PCS 是 SAM 3 的关键能力：我们不再只给一个点或一个框，而是可以给一个文本概念，让模型在视频中找出所有匹配对象，并持续跟踪它们。

🤖 加载 SAM 3 模型

这里选择使用当前可用 GPU。代码中也保留了多 GPU 的写法，如果你在多卡机器上运行，可以按需调整。

# use all available GPUs on the machine# DEVICES = range(torch.cuda.device_count())# # use only a single GPUDEVICES=[torch.cuda.current_device()]

predictor=build_sam3_video_predictor(bpe_path="/content/sam3/sam3/assets/bpe_simple_vocab_16e6.txt.gz",gpus_to_use=DEVICES)

🎞️ 处理视频帧

SAM 3 假设视频以 JPEG 帧列表的形式存储，文件名类似<frame_index>.jpg。这里先选择一段示例视频，把它切分成单帧图片并保存到磁盘。后续你可以把SOURCE_VIDEO替换成自己的视频。

SOURCE_VIDEO=HOME/"jets-1280x720-3.mp4"SOURCE_FRAMES=HOME/SOURCE_VIDEO.stem SOURCE_FRAMES.mkdir(parents=True,exist_ok=True)!ffmpeg-i{SOURCE_VIDEO}-q:v2-start_number0{SOURCE_FRAMES}/'%05d.jpg'

下面定义一个读取指定帧的工具函数。这里保留了完整异常检查，方便在文件不存在或读取失败时快速定位问题。

defload_frame(directory:str,index:int):""" 从指定目录中加载某一帧图像，目录中的帧文件需要使用 '%05d.jpg' 命名格式，例如 00000.jpg、00001.jpg、00002.jpg。 Args: directory (str): 存放图像帧的目录路径。 index (int): 帧索引，从 0 开始。 Returns: numpy.ndarray: 以 BGR 格式加载的图像帧。 Raises: FileNotFoundError: 如果帧文件不存在或无法读取。 """directory_path=Path(directory)frame_path=directory_path/f"{index:05d}.jpg"ifnotframe_path.exists():raiseFileNotFoundError(f"Frame not found:{frame_path}")frame=cv2.imread(str(frame_path))ifframeisNone:raiseFileNotFoundError(f"Failed to load frame:{frame_path}")returnframe

🧵 打开视频推理会话

SAM 3 的视频分割是有状态推理，需要先为当前视频初始化一个 inference session。初始化时，模型会加载视频目录中的 JPEG 帧，并把特征存入会话状态中。

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

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

✍️ 添加文本提示

这里使用文本提示jet，让 SAM 3 检测视频中的所有喷气式飞机。SAM 3 会自动识别多个实例，并为每个实例分配唯一的对象 ID。

frame_idx=0frame=load_frame(SOURCE_FRAMES,frame_idx)sv.plot_image(frame)

text="jet"response=predictor.handle_request(request=dict(type="add_prompt",session_id=session_id,frame_index=frame_idx,text=text,))result=response["outputs"]

🎨 可视化当前帧结果

先把 SAM 3 的输出转换成supervision.Detections，便于后续统一绘制 mask、标签和跟踪 ID。

deffrom_sam(result:dict)->sv.Detections:returnsv.Detections(xyxy=sv.mask_to_xyxy(result["out_binary_masks"]),mask=result["out_binary_masks"],confidence=result["out_probs"],tracker_id=result["out_obj_ids"],)

下面定义可视化函数，使用不同颜色绘制不同目标的 mask，并可选显示目标 ID 和文本概念。

COLOR=sv.ColorPalette.from_hex(["#ffff00","#ff9b00","#ff8080","#ff66b2","#ff66ff","#b266ff","#9999ff","#3399ff","#66ffff","#33ff99","#66ff66","#99ff00"])defannotate(image:np.ndarray,detections:sv.Detections,text=None)->np.ndarray:h,w,_=image.shape text_scale=sv.calculate_optimal_text_scale(resolution_wh=(w,h))mask_annotator=sv.MaskAnnotator(color=COLOR,color_lookup=sv.ColorLookup.TRACK,opacity=0.6)annotated_image=image.copy()annotated_image=mask_annotator.annotate(annotated_image,detections)iftext:label_annotator=sv.LabelAnnotator(color=COLOR,color_lookup=sv.ColorLookup.TRACK,text_scale=text_scale,text_color=sv.Color.BLACK,text_position=sv.Position.TOP_CENTER,text_offset=(0,-30))labels=[f"#{tracker_id}{text}"fortracker_idindetections.tracker_id]annotated_image=label_annotator.annotate(annotated_image,detections,labels)returnannotated_image

detections=from_sam(result)annotated_frame=annotate(frame,detections,text)sv.plot_image(annotated_frame)

🔁 在视频中传播分割结果

添加文本提示后，SAM 3 可以将当前帧的目标概念传播到后续视频帧中，从而得到完整视频的分割结果。

defpropagate_in_video(predictor,session_id):frame_outputs={}forresponseinpredictor.handle_stream_request(request=dict(type="propagate_in_video",session_id=session_id,)):frame_outputs[response["frame_index"]]=response["outputs"]returnframe_outputs

frame_outputs=propagate_in_video(predictor=predictor,session_id=session_id)

下面用supervision.process_video逐帧处理原始视频，并把分割 mask 绘制到每一帧，最后用ffmpeg压缩输出视频。

TARGET_VIDEO=HOME/f"{SOURCE_VIDEO.stem}-result{SOURCE_VIDEO.suffix}"TARGET_VIDEO_COMPRESSED=HOME/f"{TARGET_VIDEO.stem}-compressed{TARGET_VIDEO.suffix}"defcallback(frame:np.ndarray,index:int)->np.ndarray:annotated_frame=frame.copy()output=frame_outputs[index]detections=from_sam(output)returnannotate(frame,detections,text)sv.process_video(source_path=SOURCE_VIDEO,target_path=TARGET_VIDEO,callback=callback)!ffmpeg-y-loglevel error-i{TARGET_VIDEO}-vcodec libx264-crf28{TARGET_VIDEO_COMPRESSED}

Video(TARGET_VIDEO_COMPRESSED,embed=True,width=1080)

视频- sample

📌 小结

这篇教程完整跑通了 SAM 3 视频分割的核心流程：

• 配置 HuggingFace Token 并安装 SAM 3
• 下载视频并切分成 JPEG 帧
• 初始化 SAM 3 视频推理 session
• 使用文本提示jet指定要分割的概念
• 将 SAM 3 输出转换成supervision.Detections
• 在单帧上绘制 mask 和目标 ID
• 将分割结果传播到完整视频并导出结果视频

对于刚入门视频分割的同学，建议重点理解两点：第一，SAM 3 不只是单帧分割，而是可以围绕“概念”在视频中持续分割和跟踪；第二，视频分割通常需要会话状态，因为模型需要在帧与帧之间维护对象身份。

后续我会继续把类似的图像分割、视频分割、目标检测和 OCR 项目整理成系列教程。配套 notebook、示例视频和运行环境说明也会按主题逐步整理出来，适合刚入门计算机视觉和多模态模型的同学跟着实践。

📚 同系列教程汇总

• Google Gemini 3.5 Flash 零样本目标检测教程：从提示词到可视化结果

• GLM-OCR 文档识别实战教程：从验证码、公式到车牌 OCR

• RF-DETR + ByteTrack 多目标跟踪实战教程：从命令行到 Python 视频轨迹可视化

• SAM 3 图像分割实战教程：文本、框和点提示的多种分割方式

• SAM 3 视频分割实战教程：用文本提示分割并跟踪视频中的目标