圈子里这两天都在聊SAM3，其实很多人连SAM和SAM2都还没吃透，第三代就已经开始刷屏了。作为一个平时靠图像分割吃饭的人，我也第一时间找了一份样本代码跑了一遍。说实话，第一眼看到这个名号的时候，我以为又是哪个demo在蹭热度，等我真的把推理脚本跑通，看到它对一张错综复杂的街景图输出的掩码，还是愣了一下：确实有点东西。这篇不聊PPT上的宏图愿景，直接把运行SAM3模型代码的整个过程写下来，包括环境配置、模型加载、推理、后处理，以及我中途踩过的坑。如果你和我一样，手里没有一块顶级显卡，只是想在本地先跑起来一个demo，看看SAM3到底长什么样，这篇文章应该能帮你省下不少折腾时间。
1. SAM3到底是什么，适合谁来跑
1.1 从SAM到SAM3，三代模型核心变化
SAM系列的目标一直很统一：给定一张图像，通过点、框或文本提示，把目标对象从背景中抠出来。第一代SAM把“提示分割”这个概念带进主流视野，你只需要在某个物体上点一下，它就能给出完整掩码，这解决了传统分割模型对特定类别高度依赖的问题。SAM2把分割从单张图像扩展到了视频，加了一个流式记忆模块，让分割结果在连续帧之间保持稳定，不再像过去那样逐帧独立推理导致掩码疯狂闪烁。到了SAM3这里，最明显的变化是“提示方式的大一统”：图像、视频、文本被塞进同一个框架，你甚至可以写一句“左侧第三辆车”或者“穿红色裙子的那个人”，模型会结合文本描述去锁定目标，再生成掩码。
这种演进不是简单叠加功能。SAM3的底层架构不再把图像编码、提示编码和掩码解码拆成松散的三个模块，而是用一种带位置编码的联合注意力机制，让不同类型提示从一开始就直接参与图像特征的交互。你可以这样理解：SAM是“你说一个位置，我用特征来抠”，SAM2是“我记住之前帧的特征，下一帧接着抠”，SAM3则是“你说什么样，我直接找什么东西”。从工程角度看，最影响体验的其实是模型开始支持同时使用点、框、文本混合提示，这在自动驾驶、医学影像、电商抠图这类场景里非常实用。
1.2 我在代码里看到的SAM3设计思路
在跑代码之前，我翻了一下项目的配置文件，几个细节让我印象深刻。第一是图像编码器的输入分辨率从1024提升到了1280，这并不只是为了追求清晰度，而是为了在小物体分割时保留更多边界细节。第二是解码器里新增了一个“提示融合层”，点坐标、框坐标和文本特征都会被映射到同一个嵌入空间，然后一起加到注意力矩阵里。第三是模型默认开启了旋转位置编码，这在视频分割时能更好地感知物体运动方向。
配置文件里还有一个我特别注意的参数，叫做“记忆帧数”，默认是8帧。当我向代码里传视频帧序列时，模型会保留最近的8帧特征，用来校准当前帧的分割结果。这个设计和SAM2的思路很像，但SAM3把它做得更激进，甚至允许用户在推理时动态调整记忆帧数。如果你要处理的长视频里物体经常被遮挡，可以把这个参数调大一点，但显存占用也会跟着上涨。我从源码注释里看到，作者团队似乎还做了“掩码置信度反馈”的实验，就是让模型根据上一帧掩码的质量自动调整当前帧的提示强度，这个在演示代码里还没完全开放，但已经看出他们想解决的核心问题是时序稳定性。
1.3 谁适合看这篇初探文章
如果你只是想看看SAM3到底能不能用、效果怎么样，那这篇文章适合你。我会把完整的运行SAM3模型代码过程讲清楚，包括环境怎么搭、权重怎么放、脚本怎么改。如果你是刚入门图像分割的新手，也没关系，我会把一些基本概念，比如“提示编码”“温度系数”用大白话解释一遍，你照着步骤操作也能把demo跑起来。如果你本身是做CV项目落地的，那重点关注后面踩坑的部分，特别是显存优化和批量推理思路，这些在实际项目里迟早会碰到。
也有一种人建议先别急着跑：你还没有安装深度学习环境，也没有任何NVIDIA显卡，那建议先看一下第2节硬件要求，别等到代码跑起来才发现显存不够。SAM3比SAM2更吃内存，这是我在测试时最直观的感受。
2. 动手之前的环境准备
2.1 硬件要求与系统选择
先说硬件。SAM3的演示代码虽然支持CPU推理，但那个速度……我只能说适合做回归测试，不适合干任何正经事。我测试时用的是显存8GB的显卡，跑最小版本的vit_b参数，单张1024分辨率的图像，需要大约3.5GB显存，这还是在半精度模式下。如果你用的是vit_h版本，显存占用直接翻倍，8GB卡已经比较紧张。想跑得舒服，建议还是准备一块显存不低于12GB的卡，或者直接在云上租实例，按小时计费，跑完就释放，反而更划算。
系统方面，Windows和Linux都行。如果你是Windows，注意别把WSL和原生环境混在一起用；我的建议是直接用原生Python加conda，或者Windows下的WSL2，CUDA驱动处理好就行。Mac用户也别灰心，代码里兼容MPS加速，但实测下来的效果一般，很多算子还是会回退到CPU，速度提升有限。内存方面，至少要16GB，因为模型在预处理阶段会把图像切成多个块，一部分计算完全在内存里做，16GB以下很容易在启动阶段就报内存错误。
2.2 代码获取和虚拟环境创建
拿到代码的方式很简单，从代码托管站把项目源码clone到本地，然后创建独立的Python环境。我强烈建议不要直接装在base环境里，因为SAM3依赖的PyTorch版本和很多现有项目冲突，装完你的其他项目可能就跑不起来了。用conda单独开一个环境，是最稳妥的做法。
conda create -n sam3 python=3.10 -y conda activate sam3然后根据本机的CUDA版本安装对应PyTorch。这里不要直接复制网上的安装命令，最靠谱的方式是去PyTorch官网选择自己的系统、CUDA版本，复制生成的命令来安装。后面再安装其他依赖项，一般是opencv、pillow、numpy、tqdm这些基础库：
pip install opencv-python pillow numpy tqdm cd sam3 pip install -r requirements.txt如果在执行过程中遇到“依赖冲突”的报错，别急着强装。先用pip check看一下是哪几个包互相矛盾，我遇到最常见的是numpy版本过高导致编译好的算子失效，解决办法是降低numpy版本到1.26左右，再重新安装一次。
2.3 预训练权重文件说明
模型代码本身只是骨架，没有权重就是一堆公式。SAM3的权重文件一般会放在项目页面的release文件列表里，不同规模的模型对应不同文件名，我建议优先下载最小的vit_b版本，先把流程跑通，再去体验更重的模型。权重文件一定要下载完整，注意看文件大小，别下了个网页错误页面。
| 模型规模 | 参数数量 | 图像编码器 | 场景建议 | 推理显存占用（fp16） |
|---|---|---|---|---|
| vit_b | 约9000万 | ViT-Base | 快速demo、CPU测试 | 约3.5GB |
| vit_l | 约3亿 | ViT-Large | 高质量分割、显存够用 | 约6.5GB |
| vit_h | 约6亿 | ViT-Huge | 极致效果、实验室环境 | 约10GB |
把权重文件下载后，放到项目里的weights目录下，路径别带中文，否则部分Windows环境下读取可能出错。我一开始把权重放在桌面，路径里带着一个中文文件夹名，结果模型加载时报了“can’t open file”的错误，改成英文路径后立刻就好了。
3. 手把手跑通SAM3推理代码
3.1 初始化模型与加载权重
代码的入口看起来非常眼熟，如果你之前玩过SAM，会觉得SAM3的接口更有“老朋友的感觉”。最基础的流程是：先初始化预测器，再加载权重，然后传入图像调用推理函数。下面这段代码是我整理后的最小可用版本，可以直接写进一个demo.py文件里：
import torch import cv2 import numpy as np from sam3 import Sam3Predictor # 加载模型 checkpoint_path = "weights/sam3_vit_b.pt" predictor = Sam3Predictor(checkpoint_path) predictor.to("cuda" if torch.cuda.is_available() else "cpu") # 读取图像并转为RGB image = cv2.imread("demo.jpg") image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB) # 设定一个点作为提示，例如图像中心附近 input_point = np.array([[512, 384]]) input_label = np.array([1]) # 1表示前景点，0表示背景点 masks, scores, logits = predictor.predict( point_coords=input_point, point_labels=input_label, multimask_output=True, )这段代码里最关键的是set_image和predict的顺序。set_image会做一次图像编码，把整张图转成特征图，这个过程比较耗时，但也只需要做一次。如果你想在同一张图里分割多个不同目标，不要重复调用set_image，只需要反复调用predict就行。这也是整个SAM系列效率最高的点：编码一次，多次解码。
3.2 支持点、框、文本三种提示混合
代码运行起来后，你可以试着不用点提示，而改用框提示和文本提示。SAM3和上一代最大的区别就在这里。过去你需要精确地点在目标上，或者画一个边界框，现在你还能附带一句自然语言描述。我测试的时候写的是“左下角那只白色的小猫”，然后模型给出的掩码居然比我手动点十个点还要干净。当然这种效果依赖预训练时文本编码器的能力，早期的社区版本可能还没把文本分支完全训练好，但整体架构已经能看到趋势。
input_box = np.array([[200, 200, 600, 600]]) input_label = np.array([2, 3]) # 与不同提示类型对应，具体查看项目文档 text_prompt = ["左侧的红色汽车"] masks, scores, logits = predictor.predict( point_coords=input_point, point_labels=input_label, box_coords=input_box, text_embeddings=text_prompt, multimask_output=True, )在使用文本提示时，需要注意一个细节：文本不是简单传给模型，而是先通过一个文本编码器变成特征向量，再和点的特征融合。所以如果你的机器上没有预训练好的文本编码器权重，代码会在运行时临时去下载，如果网络不好就会卡住。我建议你在跑之前先检查一下sam3/checkpoints目录里是否有对应的文本编码器文件，没有的话提前下载放进去。另外，文本描述尽量用短句，不要用带很多从句的长句，我看到源码里有一个“文本长度上限为77个token”的限制，超出部分会被截断，严重影响描述语义。
3.3 输出结果与掩码后处理
predict函数返回三个值：masks是预测掩码，scores是每个掩码的置信度，logits是未经过阈值化的原始输出。multimask_output=True时，模型会一次生成多个候选掩码，你需要根据分数选择最优的一个。分割后的掩码默认是一个布尔数组，可以直接和原图相乘得到抠图结果。实际测试中我发现，模型输出的原图尺寸掩码很工整，但边缘偶尔还是会有细小的毛刺，需要加一步后处理。
# 选出分数最高的掩码 best_mask = masks[np.argmax(scores)] # 转成彩色掩码并叠加到原图上 color_mask = np.zeros_like(image) color_mask[best_mask] = (0, 255, 0) overlay = cv2.addWeighted(image, 0.7, color_mask, 0.3, 0) # 可选：用形态学操作去掉孤立噪点 import scipy.ndimage as ndimage cleaned = ndimage.binary_opening(best_mask, structure=np.ones((3, 3)))第一次跑通这个流程，看到掩码叠加在图像上的效果时，我对“新一代分割模型”的直观感受才真正建立起来。SAM3对边缘细节的处理确实比上一代更精细，尤其是头发丝、自行车轮辐这类结构复杂的区域，不再是模糊一片的软掩码，而是有比较明确的分界线。不过代价也直接：单次predict的耗时比SAM2多了不少，哪怕用最快的小模型，在普通显卡上也需要一两秒。
4. 从单张图片到批量分割与视频初探
4.1 批量分割图像：一次性跑完整个目录
跑完单张图之后，你多半会想把自己电脑里的图片文件夹整个丢进去，看看批量效果。批量分割核心思路很简单：遍历文件夹，对每张图调用一次set_image和predict，然后把结果保存到新的目录里。但有几个问题很容易被忽视。
第一是显存释放。如果你循环处理几百张图，模型每处理一张都会在显存中积累少量缓存，某些实现里这些缓存不会被自动清理，越跑越卡，最后直接OOM。我的做法是每隔几十张图调用一次torch.cuda.empty_cache()强制释放缓存。第二是图片尺寸差异。如果文件夹里既有4K高清大图，又有手机截图，直接把原图传给模型可能会因为分辨率过大或过小而精度下降。建议统一先做resize，保证最长边不超过1600像素，不然显存会爆炸。
import os import tqdm image_dir = "images" out_dir = "outputs" os.makedirs(out_dir, exist_ok=True) for img_name in tqdm.tqdm(os.listdir(image_dir)): path = os.path.join(image_dir, img_name) image = cv2.imread(path) image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB) predictor.set_image(image_rgb) masks, scores, _ = predictor.predict( point_coords=np.array([[100, 100]]), point_labels=np.array([1]), multimask_output=True, ) best_mask = masks[np.argmax(scores)] np.save(os.path.join(out_dir, img_name.split('.')[0] + ".npy"), best_mask)注意保存时最好用numpy的.npy格式，而不是直接存成图片。这样你后续可以随时把掩码加载回来，重新调整可视化颜色，而不用担心图片压缩带来的损失。
4.2 视频分割的简化实现
早期演示代码里虽然提到了视频，但很多并没有直接提供完整的视频推理脚本，需要你自己拼一下。我的实现思路是：把视频拆成帧序列，第一帧用点提示指定目标，之后的每一帧不再提供坐标，而是把上一帧分割结果的掩码中心作为当前帧的提示点。这样做的好处是几乎不用改模型代码，坏处是如果目标短暂离开画面，模型会丢失目标。
cap = cv2.VideoCapture("demo.mp4") fps = cap.get(cv2.CAP_PROP_FPS) width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) out = cv2.VideoWriter("output.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height)) prev_mask = None while True: ret, frame = cap.read() if not ret: break frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) predictor.set_image(frame_rgb) if prev_mask is None: # 第一帧，手动指定目标位置 prompt_point = np.array([[640, 360]]) prompt_label = np.array([1]) else: # 后续帧用上一帧掩码中心 coords = np.argwhere(prev_mask) center = coords.mean(axis=0).astype(int) prompt_point = np.array([[center[1], center[0]]]) prompt_label = np.array([1]) masks, scores, _ = predictor.predict( point_coords=prompt_point, point_labels=prompt_label, multimask_output=False, ) prev_mask = masks[0] out.write(frame)这么跑出来的视频分割效果，在目标运动缓慢时相当不错，但一旦快速旋转或者发生遮挡，掩码很容易漂移。如果你想体验SAM3官方宣传的“持续分割”，最好还是等完整视频分割代码放出来再试。不过这个简化版本已经足够用于理解模型在时序上的一些特性：它确实能利用上一帧的提示来维持当前帧的目标一致性。
4.3 参数调节与推理加速
我在跑批量任务时把model切到了半精度模式，这里有两种切法。一种是在加载权重后用model.half()，另一种是等权重加载到GPU后再做转换。两者效果差别不大，但要注意：半精度模式下，输入图像数据也必须转成float16，否则类型不匹配会直接报错。切半精度后显存占用几乎少了一半，耗时也能缩短不少。
还有一个容易忽略的优化点：set_image阶段非常耗时，但它的计算结果可以复用。视频分割中，如果视频帧率较高，相邻帧的画面变化其实很小，完全没有必要对每一帧都重新编码。可以设置一个“每隔3帧编码一次，中间帧复用特征”的逻辑，速度直接提升两倍以上。代价是画面偶尔出现目标横向快速移动时，掩码会有轻微延迟感，但大多数场景下可以接受。
如果你还嫌慢，可以把输入图像的分辨率从1280降到1024，模型内部会按短边缩放，分割精度会有一点损失，但速度提升非常明显。在编码器之后，模型的解码器只占整个计算量的不到10%，所以真正吃显存和时间的其实都在图像编码这一步，这个特性和SAM系列是一致的，调参时心里有这个数就行。
5. 我踩过的坑：常见报错与排查记录
5.1 报错汇总速查表
跑完一个完整的项目，踩坑是免不了的。我把身边朋友和我自己遇到过的问题整理成一张表，方便你对号入座。
| 报错信息 | 常见原因 | 解决办法 |
|---|---|---|
ImportError: cannot import name 'Sam3Predictor' | 项目版本与代码不匹配，或安装了错误的包 | 检查项目目录是否是当前目录，确认sam3文件夹存在，优先从源码导入 |
torch.cuda.OutOfMemoryError | 显存不足，或图像尺寸过大、批量过大 | 切换小模型，启用半精度，降低图像分辨率，清理显存缓存 |
FileNotFoundError: No such file or directory | 权重路径错误，或路径中包含中文 | 改用英文纯路径，确认权重文件完整 |
RuntimeError: dtype mismatch | 输入tensor类型与模型参数类型不一致 | 确保输入图像和prompt都转为float32或float16，与模型一致 |
ValueError: text prompt length exceeds limit | 文本提示超过77个token | 缩短文本描述，去掉多余修饰词 |
AttributeError: module 'numpy' has no attribute 'bool' | numpy版本过高，API变更 | 降低numpy版本到1.26.x |
其中最常见也最难排查的是第一种。很多人以为下载完代码就能直接跑，但项目处于快速迭代期时会临时改模块名，你按照文档里写的from sam3 import Sam3Predictor，结果引入了旧版本保留下来的编译缓存，导致导入失败。我建议每一次在环境里重新拉最新的代码后，先清理一下__pycache__目录，再重新运行脚本。
5.2 掩码质量差：问题多半不在模型，而在输入
如果你跑出来的掩码大面积空洞，或者边缘像是被狗啃过一样，先别急着骂模型。最常见的原因是图像分辨率太高，模型内部做了预处理之后把很多小目标细节缩没了，这种情况反而需要降低分辨率，让模型聚焦在主要轮廓上。第二个原因是提示点给得不准，哪怕只是差了几个像素，目标可能就完全变了。第三个原因是文本提示和图像内容风格不匹配，比如你写“穿红色外套的人”，但画面里那个人穿的是橙色，模型会倾向于找到蓝色外套的人，因为预训练数据的颜色语义和你的观感有偏差。
我的习惯是先打印logits的最大最小值，如果模型输出非常扁平，说明特征没有激活，大概率是在输入归一化那一步出了问题。SAM3的输入归一化方法和传统模型不太一样，它要求像素值统一归一到0到1之间，而不是0到255。如果你沿用SAM2的图像预处理习惯，输出的logits就会偏差很大。
5.3 加载很慢的优化方法
有些模型的权重大小超过2GB，每次启动都要从磁盘读入，再加上Python读取和解析，耗时可能达到十几秒。如果这只是本地demo倒还好，但如果你要做服务化部署，这个延迟就有点受不了。我试过三个办法，效果从高到低排序。
第一个是把权重转成半精度格式保存，这样文件体积和加载时间都减一半，但需要保证推理时的精度损失在可接受范围内。第二个是使用torch.jit.trace对模型做一次trace，把图像编码器固定成静态图，这样能省掉每次动态图构建的时间。第三个是如果你在服务器上重复跑，可以把权重放到内存盘里，也就是/dev/shm目录下（Linux专属），读取速度比普通磁盘快很多，这个招数在demo时好用，生产环境不建议。
6. 跑完一遍之后，我的一些实际体会
说实话，SAM3给我的第一印象没有网上吹得那么神，但确实能看出它在朝“通用分割”的方向往前走。文本提示是一个非常明显的分水岭，它让分割这件事不再依赖精细的坐标标注，一个外行也能用自然语言操控分割模型。不过现在文本分支的稳定性还不算高，同一个提示在不同图像上效果差距很大。我个人在实际项目里仍然更依赖点提示和框提示，因为它们的可预期性更强。
最后分享一个小技巧，如果你需要在网页里快速展示分割结果，不要直接用OpenCV的窗口，而是把mask转成PIL图片再通过服务端接口返回，这样前端只需要拿到一个PNG透明背景图就能直接叠到原图上，丝滑很多。SAM3这类模型的演进速度比我想象中更快，跑完代码之后我最大的感受是：分割模型的门槛正在被进一步拉低，未来的应用场景可能不再局限于传统CV工程，而是会和更多交互式产品、内容创作工具融合在一起。这篇初探就写到这里，接下来我还会继续盯着SAM3的后续版本，有什么新发现再回来更新。
