SAM3 教程（Segment Everything Model 3）：构建隐私过滤器

SAM 3 是 Meta 推出的全新“segment anything” 模型，可通过简短的文本提示或示例找到某一概念的所有实例，并在图像和视频中返回像素级精度的掩码。这使其非常适合用于实用的隐私任务，例如模糊处理人脸、车牌或屏幕，而无需手动勾画选区或编写传统检测器。

在本教程中，我们将使用 SAM3 隐私过滤器，在 Colab 中借助 Gradio 界面完成构建。只需上传一张图像或一个视频，输入提示（如 faces、license plates），SAM3 就会返回实例掩码，这样我们只需对这些像素进行模糊处理。我们将逐步介绍环境搭建、掩码生成、高斯模糊应用，以及将 Gradio 应用连接以导出最终文件。

什么是 SAM3？

Segment Anything Model 3（SAM 3）是 Meta 面向图像与视频的开放词汇检测、分割与跟踪的统一模型。无需为每个类别配置独立的检测器，您可以使用简短短语或示例进行提示，SAM 3 将返回每个实例的掩码。

在底层，SAM 3 将文本编码器与图像编码器融合，并结合 DETR 风格的检测器与继承自 SAM-2 的带有记忆库的跟踪器。在每一帧中，它会根据提示检测出与概念对应的掩码，通过跟踪器向前传播掩码，并将新检测和跟踪得到的掩码合并为该帧的最终输出。

来源：SAM3 GitHub

SAM 3 随模型权重、微调代码与评估数据一同发布，其中包括用于可提示概念分割的SA-Co 基准。

根据 Meta 的报告，在图像与视频的开放词汇分割上，相较强基线方法，可实现约 2 倍提升，同时保持 SAM-2 的交互优势。

在本教程中，我们将把这些 SAM 3 掩码用于图像和视频的高斯模糊合成，并封装到 Gradio UI 中。

SAM3 示例：为图像与视频构建隐私过滤器

本节我们将基于 SAM3 在一个简单的 Gradio 界面中构建用于图像与视频的隐私过滤器。

其工作流程如下：

• 首先输入目标，例如人脸、车牌、电脑屏幕等
• SAM3 根据您的文本提示进行实例分割，并返回逐对象掩码
• 随后我们对这些掩码求并集，仅对被掩码的像素进行模糊
• 接着使用 Gradio UI 组件上传图像或视频，调整模糊强度与置信度，预览并下载结果。

我们将以小步快跑的方式走完整个实现。

步骤 1：安装依赖

在运行此演示之前，先确保所有前置条件就绪。要在 Colab 中运行 SAM3 隐私过滤器，您需要最新版本的 Transformers 库，以及用于 UI、张量运算、图像与视频 I/O 的一些运行时库。下面的代码片段一次性安装全部依赖。

import subprocess
import sys
import os
def install(package):
    subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", package])
print(" Installing latest Transformers")
install("git+https://github.com/huggingface/transformers.git")
pkgs = [
    "accelerate",
    "gradio",
    "numpy",
    "pillow",
    "torch",
    "torchvision",
    "imageio[ffmpeg]" 
]
for p in pkgs:
    install(p)技术支持

每个前置依赖的作用如下：

• git+https://github.com/huggingface/transformers.git：从源码拉取最新的 Transformers 库，以便使用 Sam3Processor 和 Sam3Model 类。
• torch 与 torchvision：张量计算与图像工具库，用于运行 SAM3 的前向计算。
• accelerate：Transformers 使用的推理辅助工具。
• gradio：轻量级 Web UI，用于上传媒体并预览模糊结果。
• numpy、pillow：用于图像数组与 PIL 图像操作（掩码/模糊合成）。
• imageio[ffmpeg]：读写视频，并为视频页签编码 MP4（FFmpeg）。

环境就绪并加载 facebook/sam3 后，演示程序即可通过简短文本提示进行分割，并在图像或视频中对得到的掩码区域进行模糊处理，所有操作均在一个简单的 Gradio 应用中完成。

注意：如果您计划在 Colab 中使用 GPU，请在安装前将运行时设置为 GPU（T4/A100）。我在 Colab 上使用了 A100 GPU，以获得更快的体验。

步骤 2：导入库

环境设置完成后，导入用于 UI、模型推理、图像/视频处理与计时的库。这些就是实现 SAM3 隐私过滤器所需的全部模块。

import gradio as gr
import torch
import numpy as np
import imageio
from PIL import Image, ImageFilter
from transformers import Sam3Processor, Sam3Model
import time技术支持

此时，Gradio 提供 Web 界面，transformers 负责运行 SAM3，PyTorch 在 GPU 或 CPU 上执行推理。PIL 用于加载与编辑图像（包括高斯模糊），NumPy 管理掩码数组，imageio 读写视频文件。

接下来，我们将加载模型并构建一个小型引擎，将文本提示转换为可用于模糊处理的掩码。

步骤 3：加载 SAM3 并预测掩码

环境就绪后，让我们将 SAM3 封装进一个小型引擎：一次加载模型，按需运行基于文本提示的实例分割，并返回用于模糊处理的二值掩码。

class Sam3PrivacyEngine:
    def __init__(self):
        self.device = "cuda" if torch.cuda.is_available() else "cpu"
        self.model = None
        self.processor = None
        print(f"Initializing SAM3 on {self.device}")
        try:
            self.model = Sam3Model.from_pretrained("facebook/sam3").to(self.device)
            self.processor = Sam3Processor.from_pretrained("facebook/sam3")
            print("SAM3 Loaded Successfully!")
        except Exception as e:
            print(f"Error loading SAM3: {e}")
    def predict_masks(self, image_pil, text_prompt, threshold=0.4):
        if self.model is None: return []
        inputs = self.processor(
            images=image_pil,
            text=text_prompt,
            return_tensors="pt"
        ).to(self.device)
        with torch.no_grad():
            outputs = self.model(**inputs)
        results = self.processor.post_process_instance_segmentation(
            outputs, 
            threshold=threshold, 
            mask_threshold=0.5, 
            target_sizes=inputs["original_sizes"].tolist()
        )[0]
        masks = []
        if "masks" in results:
            for i, mask_tensor in enumerate(results["masks"]):
                mask_np = (mask_tensor.cpu().numpy() * 255).astype(np.uint8)
                mask_pil = Image.fromarray(mask_np)
                masks.append(mask_pil)
        return masks
engine = Sam3PrivacyEngine()技术支持

看看此引擎如何融入整个流程：

• Sam3PrivacyEngine.init()：初始化器会选择最佳设备（若可用则为 CUDA，否则为 CPU），加载 facebook/sam3 权重及配套的 Sam3Processor，并将模型移动到所选设备，以便高效推理。
• Sam3PrivacyEngine.predict_masks()：该方法基于 PIL 图像与文本提示构建模型输入，在 torch.no_grad() 下进行前向推理以避免梯度开销，并使用 post_process_instance_segmentation 按给定的检测与掩码阈值以及原始目标尺寸进行正确缩放的后处理。它返回每个实例的分割掩码，从张量转换为 NumPy 数组，再转换为 PIL “L” 掩码（8 位灰度图像，模式 "L"，每个像素取值 0–255），以便进行合成。
• engine = Sam3PrivacyEngine()：该行构建一个可复用的引擎实例，使 SAM3 模型仅加载一次，并可在图像或视频帧处理时反复调用，无需反复初始化。

有了这个自包含的引擎，您可以将任意图像与文本提示转换为实例掩码。接下来，我们将使用这些掩码进行选择性模糊处理，并将所有内容嵌入 Gradio UI。

步骤 4：模糊处理逻辑

本节将基于 SAM3 的掩码实现隐私处理。它仅模糊掩码区域，并保留其他部分。我们先编写一个可复用的高斯模糊函数，然后分别将其接入图像与视频两条流水线。

步骤 4.1：高斯模糊

该辅助函数接收一张图像和一个或多个 PIL “L” 掩码，将它们混合为单一复合掩码，并仅在掩码为白色（255）的区域粘贴图像的模糊副本。

def apply_blur_pure(image_pil, masks, blur_strength):
    if not masks:
        return image_pil
    radius = blur_strength
    blurred_image = image_pil.filter(ImageFilter.GaussianBlur(radius=radius))
    composite_mask = Image.new("L", image_pil.size, 0)
    for mask in masks:
        composite_mask.paste(255, (0, 0), mask=mask)
    final_image = image_pil.copy()
    final_image.paste(blurred_image, (0, 0), mask=composite_mask)
    return final_image技术支持

函数的工作原理如下：

• GaussianBlur() 首先创建整张图像的完全模糊版本。而 composite_mask 是一个初始化为黑色（0 = 保留原图）的 “L”（灰度）掩码。
• 对每个 SAM3 掩码，将其粘贴到复合掩码上，使需要模糊的白色像素（255）叠加累积。
• 最后，将模糊图像按 composite_mask 覆盖到原图上，因此只有白色区域会被模糊。
• final_image.paste() 仅替换被掩码的像素，最大限度保留其余区域的视觉保真度。

只需一次调用，您就能模糊任意一组区域（如人脸、屏幕、车牌），同时保持背景不变。

步骤 4.2：图像流水线

此子步骤覆盖端到端的图像流程：从输入规范化，到使用 SAM3 获取掩码，再到对掩码像素进行模糊处理，最后返回结果。

def process_image(input_img, text_prompt, blur_strength, confidence):
    if input_img is None: return None, None
    if isinstance(input_img, np.ndarray):
        image_pil = Image.fromarray(input_img).convert("RGB")
    else:
        image_pil = input_img.convert("RGB")
    masks = engine.predict_masks(image_pil, text_prompt, confidence)
    result_pil = apply_blur_pure(image_pil, masks, blur_strength)
    output_path = "privacy_image.png"
    result_pil.save(output_path)
    return np.array(result_pil), output_path技术支持

图像处理按如下步骤进行：

• 首先将任意来自 Gradio 的 NumPy 数组转换为 PIL RGB 图像，确保处理一致性。
• 然后调用 engine.predict_masks()，基于提供的 text_prompt 获取 SAM3 实例掩码。
• 接着以所选 blur_strength 调用 apply_blur_pure()，仅对被掩码的区域进行模糊。
• 处理完成后，将结果保存为 png，并返回 NumPy 数组与可下载文件。

完成图像流程后，我们继续视频流水线。

步骤 4.3：视频流水线

视频流程与图像类似，但通过 imageio 按帧流式处理。对于每一帧，我们进行分割、模糊掩码区域，并写入 H.264 编码的 MP4 文件。

def process_video(video_path, text_prompt, blur_strength, confidence, max_frames):
    if not video_path: return None, None
    try:
        reader = imageio.get_reader(video_path)
        meta = reader.get_meta_data()
        fps = meta.get('fps', 24)  
        output_path = "privacy_video.mp4"
        writer = imageio.get_writer(
            output_path, 
            fps=fps, 
            codec='libx264', 
            pixelformat='yuv420p',
            macro_block_size=1
        )  
        print("Starting video processing...")
        for i, frame in enumerate(reader):
            if i >= max_frames:
                break  
            frame_pil = Image.fromarray(frame).convert("RGB")
            masks = engine.predict_masks(frame_pil, text_prompt, confidence)
            processed_pil = apply_blur_pure(frame_pil, masks, blur_strength)
            writer.append_data(np.array(processed_pil))
            if i % 10 == 0:
                print(f"Processed frame {i}...")
        writer.close()
        reader.close()
        print("Video processing complete.")
        return output_path, output_path
    except Exception as e:
        print(f"Error: {e}")
        return None, None技术支持

我们按如下流程处理视频：

• 首先使用 imageio.get_reader() 打开文件，逐帧迭代，并从元数据读取 FPS（若缺失则默认 24）。
• 然后对每一帧，转换为 PIL 图像，通过 engine.predict_masks() 预测 SAM3 掩码，并使用 apply_blur_pure() 对掩码区域进行模糊。
• 将每帧处理结果追加到 MP4 写入器中，配置 pixelformat='yuv420p' 以获得更广泛的兼容性，并设置 macro_block_size=1 以避免对齐伪影。
• 处理完成后，我们有意通过在特定帧数后停止来裁剪输出，默认处理 60 帧（约 2 秒），以加快 Colab 测试并避免超时。

借助该视频流程，您可以通过简单的文本提示，模糊会议录屏、行车记录仪片段或屏幕录制中的敏感区域。

步骤 5：Gradio 推理

在完成掩码与模糊处理后，我们将其封装到一个轻量级的 Gradio UI 中，便于任何人上传图像或视频、输入文本提示并下载输出结果。

with gr.Blocks(title="SAM3 Privacy Filter", theme=gr.themes.Soft()) as demo:
    gr.Markdown("# SAM3 Privacy Filter")
    gr.Markdown("Auto-detect and blur faces/objects.")
    with gr.Tabs():
        with gr.Tab("Image"):
            with gr.Row():
                with gr.Column():
                    im_input = gr.Image(label="Input Image", type="numpy")
                    im_prompt = gr.Textbox(label="Text Prompt", value="faces")
                    im_blur = gr.Slider(5, 100, value=30, label="Blur Strength")
                    im_conf = gr.Slider(0.1, 1.0, value=0.4, label="Confidence")
                    im_btn = gr.Button("Blur Image", variant="primary")
                with gr.Column():
                    im_output = gr.Image(label="Preview")
                    im_dl = gr.File(label="Download Image")   
            im_btn.click(process_image, [im_input, im_prompt, im_blur, im_conf], [im_output, im_dl])
        with gr.Tab("Video"):
            with gr.Row():
                with gr.Column():
                    vid_input = gr.Video(label="Input Video")
                    vid_prompt = gr.Textbox(label="Text Prompt", value="faces")
                    vid_blur = gr.Slider(5, 100, value=30, label="Blur Strength")
                    vid_conf = gr.Slider(0.1, 1.0, value=0.4, label="Confidence")
                    vid_limit = gr.Slider(10, 300, value=60, step=10, label="Max Frames")
                    vid_btn = gr.Button("Blur Video", variant="primary")
                with gr.Column():
                    vid_output = gr.Video(label="Preview")
                    vid_dl = gr.File(label="Download Video")
            vid_btn.click(process_video, [vid_input, vid_prompt, vid_blur, vid_conf, vid_limit], [vid_output, vid_dl])
demo.launch(share=True, debug=True)技术支持

该 Gradio 应用通过以下方式将 SAM3 的掩码与模糊流水线嵌入到一个简单的 Web UI 中：

• 应用外壳（gr.Blocks）：创建单页 Gradio 应用，包含标题与两个页签（图像与视频），用户可在不离开页面的情况下切换模式。
• 图像页签：输入包括图像上传器、文本提示输入框，以及模糊强度与置信度滑块。输出字段显示处理后的预览与可下载 PNG；Blur Image 按钮将流程路由至 process_image，调用 SAM3 获取掩码，并仅对掩码像素应用高斯模糊。
• 视频页签：用于视频模糊处理，输入包括视频上传器、文本提示输入框、模糊强度与置信度滑块，以及用于快速演示的最大帧数上限。输出提供内联预览与可下载 MP4；Blur Video 按钮调用 process_video，逐帧预测掩码、模糊掩码区域，并编码为 H.264 视频。
• 启动：demo.launch() 方法启动应用，生成可共享链接，并在启用调试时提供详细堆栈跟踪。

现在，我们的 SAM3 隐私过滤器 已可上传媒体（图像/视频）、设置提示与阈值，并导出模糊后的输出。

注意：本演示中的所有图像与视频均来自 Pexels.com，可免费使用。