Ultralytics SAM 预测器深度解析：从 prompt 推理到全图分割的 predict.py 实现指南

Ultralytics SAM 预测器深度解析：从 prompt 推理到全图分割的 predict.py 实现指南

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics

本文以 ultralytics/models/sam/predict.py 为核心，逐层拆解 Ultralytics 中 SAM / SAM 2 / SAM 3 系列预测器的类层级、推理流水线与关键 API。读完本文，你将能够直接使用Predictor的set_image+ 多次 prompt 推理模式复用图像特征，理解generate()全图分割各参数的作用，并掌握 SAM 2 视频追踪预测器（SAM2VideoPredictor）与 SAM 3 语义预测器（SAM3SemanticPredictor）的底层实现差异。

一、文档定位与类层级总览

docs/en/reference/models/sam/predict.md 是ultralytics/models/sam/predict.py的 API 参考页，文档列出该模块中的 8 个预测器类：Predictor、SAM2Predictor、SAM2VideoPredictor、SAM2DynamicInteractivePredictor、SAM3Predictor、SAM3SemanticPredictor、SAM3VideoPredictor、SAM3VideoSemanticPredictor。

从源码结构看（predict.py），这些类构成一条清晰的继承链：

模型到预测器的路由逻辑在 model.py 的task_map中：根据权重文件名是否包含sam2/sam3字样，SAM接口类会自动选择SAM2Predictor、SAM3Predictor或基础Predictor，任务类型固定为segment。

二、通用推理流水线：Predictor基类

Predictor继承自 ultralytics/engine/predictor.py 中的BasePredictor，构造时会强制覆盖三项配置（predict.py#L103）：

overrides.update({"task": "segment", "mode": "predict", "batch": 1}) super().__init__(cfg, overrides, _callbacks) self.args.retina_masks = True # SAM 必须使用全分辨率 mask

要点：

• 不支持批量推理：pre_transform中显式断言len(im) == 1，且使用LetterBox(self.imgsz, auto=False, center=False)做左上角对齐的缩放（predict.py#L168-L170）。
• 仅支持正方形输入尺寸：setup_source中校验imgsz[0] == imgsz[1]，随后调用self.model.set_imgsz(self.imgsz)（predict.py#L576-L579）。
• 归一化参数：setup_model使用均值[123.675, 116.28, 103.53]、标准差[58.395, 57.12, 57.375]（ImageNet 统计量，predict.py#L469-L470）；SAM 3 则改为[127.5, 127.5, 127.5]（见第六节）。
• 精度控制：quantize=16时模型权重转为float16（fp16），否则float32；同时会警告并忽略channels_last=True（predict.py#L458-L478）。
• Ultralytics 兼容性设置：setup_model中为模型打补丁，format="sam"、base_model=False、stride=32、done_warmup=True，使 SAM 这类非 Ultralytics 原生模型也能接入统一引擎（predict.py#L472-L478）。

2.1 prompt 推理：inference→prompt_inference→_inference_features

inference(im, bboxes=None, points=None, labels=None, masks=None, multimask_output=False)是整个模块的核心入口（predict.py#L172-L208）：

1. 先从self.prompts字典中 pop 掉预先通过set_prompts()存储的提示，支持“先设图、后给 prompt”的分离式调用；
2. 若bboxes、points、masks全部为空，则走generate()全图分割分支（自动置segment_all = True）；
3. 否则进入prompt_inference：首次调用时执行get_im_features(im)（即self.model.image_encoder(im)）提取图像特征并缓存在self.features，后续同图多次推理直接复用，避免重复跑图像编码器——这正是官方文档 sam.md 中“set image once, run prompts multiple times”模式的实现基础。

_inference_features展示了 SAM 三段式架构的实际调用方式（predict.py#L263-L278）：

points = (points, labels) if points is not None else None # 1. 编码 prompt（稀疏 + 稠密嵌入） sparse_embeddings, dense_embeddings = self.model.prompt_encoder(points=points, boxes=bboxes, masks=masks) # 2. 掩码解码 pred_masks, pred_scores = self.model.mask_decoder( image_embeddings=features, image_pe=self.model.prompt_encoder.get_dense_pe(), sparse_prompt_embeddings=sparse_embeddings, dense_prompt_embeddings=dense_embeddings, multimask_output=multimask_output, ) # (N, d, H, W) --> (N*d, H, W)；d 取决于 multimask_output，为 1 或 3 return pred_masks.flatten(0, 1), pred_scores.flatten(0, 1)

multimask_output=True时每个 prompt 会输出 3 个候选掩码及其质量分数，用于模糊提示下挑选最优结果。

2.2 prompt 坐标换算：_prepare_prompts

原始 prompt 以输入图像像素为坐标系，而网络内部工作在imgsz × imgsz的目标坐标系中。_prepare_prompts（predict.py#L280-L329）负责换算：

r = 1.0 if self.segment_all else min(dst_shape[0] / src_shape[0], dst_shape[1] / src_shape[1])

• points、bboxes统一乘以比例r；
• 未显式传labels时默认全部视为正前景点（labels = np.ones(...)），并断言点数量与标签数量一致；
• masks（低分辨率输入掩码，SAM 中 H=W=256）通过LetterBox最近邻插值到目标尺寸；
• points的形状从(N, 2)升维为(N, 1, 2)，以兼容多目标批处理。

2.3 后处理：postprocess

postprocess（predict.py#L486-L536）完成掩码回投影与结果封装：

• 用ops.scale_masks(..., padding=False)把预测掩码缩放回原图尺寸，再按self.model.mask_threshold二值化；
• 全图分割模式下pred_bboxes来自generate()的返回；prompt 模式下由batched_mask_to_box(masks)从掩码反推；
• 类别列为占位符cls = arange(N)（源码注释明确说明 SAM 不返回类别信息，该列仅为与 UltralyticsResults结构保持一致）；
• 按args.conf过滤低置信度掩码，最后包装为 Results 对象返回；
• 结束时重置segment_all = False，保证下一次调用回到 prompt 模式。

三、全图自动分割：generate()及参数详解

不传任何 prompt 时，inference会转入generate()（predict.py#L331-L441），对整图做“segment everything”。这是官方文档 sam.md 中predictor(source=..., crop_n_layers=1, points_stride=64)调用的落点。完整参数及默认值如下：

算法流程可以概括为五步（源码见 predict.py#L375-L441）：

1. generate_crop_boxes((ih, iw), crop_n_layers, crop_overlap_ratio)生成整图及分层裁剪区域；
2. 对每个裁剪块：F.interpolate回插到整图尺寸 → 提取特征 → 按point_grids[layer_idx] * points_scale生成采样点 → 分points_batch_size批调用_inference_features(crop_features, points, multimask_output=True)；
3. 逐批过滤：先按pred_score > conf_thres，再按calculate_stability_score(...)与stability_score_thresh比较（来自 amg.py），最后masks > model.mask_threshold二值化并batched_mask_to_box生成框，剔除靠近裁剪块边缘的框（is_box_near_crop_edge）；
4. 裁剪块内部用torchvision.ops.nms(bboxes, scores, self.args.iou)去重，再把框和掩码uncrop_*回投影到整图坐标系；
5. 多裁剪块之间用crop_nms_thresh做二次 NMS（以1/区域面积作为分数偏好大块），消除跨块重复掩码。

返回三元组(pred_masks, pred_scores, pred_bboxes)，分别对应掩码 (N,H,W)、置信度 (N,)、框 (N,4)。

3.1 掩码清理工具：remove_small_regions

静态方法remove_small_regions(masks, min_area=0, nms_thresh=0.7)（predict.py#L594-L644）用于清理 SAM 输出中的碎块：先调用amg.remove_small_regions分别以mode="holes"与mode="islands"删除小孔洞和孤立小岛，再对重算后的框做 NMS；被修改过的掩码得分为 0、未修改的得分为 1，使 NMS 优先保留“干净”掩码。

四、SAM 2 图像预测器：SAM2Predictor的差异点

SAM2Predictor（predict.py#L695-L834）在基类之上做三处关键改造：

1）prompt 合并：SAM 2 的 prompt encoder 接口不接受独立的 boxes 参数，_prepare_prompts会把框转成两个角点(256,256)→(128,128)→(64,64)三级特征尺寸，框点标签固定为[2, 3]（bbox_labels），再与用户点拼接成单一points输入（predict.py#L757-L768）。

2）多级图像特征：get_im_features不再返回单层特征图，而是调用model.forward_image(im)+model._prepare_backbone_features，输出三级视觉特征并组装为字典（predict.py#L775-L784）：

return {"image_embed": feats[-1], "high_res_feats": feats[:-1]}

若模型配置directly_add_no_mem_embed为真，还会给最低层特征加上无记忆嵌入no_mem_embed。

3）高分辨率掩码解码：_inference_features用model.sam_prompt_encoder（注意此时boxes=None，框已并入 points）编码提示，model.sam_mask_decoder解码时额外传入high_res_features与repeat_image标志，输出高分辨率掩码：

pred_masks, pred_scores, _, _ = self.model.sam_mask_decoder( image_embeddings=features, image_pe=self.model.sam_prompt_encoder.get_dense_pe(), sparse_prompt_embeddings=sparse_embeddings, dense_prompt_embeddings=dense_embeddings, multimask_output=multimask_output, repeat_image=batched_mode, # 多目标批处理时重复图像嵌入 high_res_features=high_res_features, )

多目标判定逻辑为points is not None and points[0].shape[0] > 1（一次调用中多个对象）。

五、SAM 2 视频预测器：SAM2VideoPredictor的推理状态机

SAM2VideoPredictor（predict.py#L837-L1867）把“视频追踪”建模为带状态的推理过程，适合交互式逐帧提示场景。

5.1 状态结构

init_state/_init_state（predict.py#L1189-L1246）在数据源为视频模式时（setup_source中检测dataset.mode == "video"）自动初始化inference_state，核心字段：

inference_state = { "num_frames": num_frames, "point_inputs_per_obj": {}, # 每个对象在每帧的点输入 "mask_inputs_per_obj": {}, # 每个对象在每帧的掩码输入 "obj_id_to_idx": OrderedDict(), # 客户端对象 id → 模型对象 index 双向映射 "obj_idx_to_id": OrderedDict(), "obj_ids": [], "output_dict": { "cond_frame_outputs": {}, # 条件帧输出（有交互输入） "non_cond_frame_outputs": {}, # 非条件帧输出（纯传播） }, "output_dict_per_obj": {}, # 每对象输出切片视图（共享同一内存） "temp_output_dict_per_obj": {}, # 用户新增点击/掩码的临时缓存 "consolidated_frame_inds": {...}, # 已合并输出的帧索引集合 "tracking_has_started": False, "frames_already_tracked": [], }

值得注意的两点限制（源码有明确断言/异常）：

• 新对象只能在追踪开始前添加：_obj_id_to_idx中allow_new_object = not inference_state["tracking_has_started"]，否则抛出RuntimeError提示调用reset_state（predict.py#L1297-L1323）；
• 点与掩码互斥：add_new_prompts断言(masks is None) ^ (points is None)，同一次调用只能二选一。

5.2 逐帧推理流程

inference（predict.py#L906-L977）在每帧执行：

1. 若该帧还没有任何条件输出（cond_frame_outputs为空），把本帧 prompt 视为初始化输入，逐对象调用add_new_prompts(obj_id=i, ...)；
2. propagate_in_video_preflight()先整合临时输出（temp_output_dict_per_obj合并进output_dict）并校验一致性；
3. 分三种情况取当前帧结果：已整合的条件帧 → 直接读取缓存；已整合的非条件帧 → 读取缓存；否则调用_run_single_frame_inference执行model.track_step并写入缓存，随后_prune_non_cond_memory修剪非条件记忆；
4. _add_output_per_object为每个对象生成输出切片，供后续与单个对象交互；
5. 过滤空掩码后返回掩码与全 1 分数（视频追踪模式下分数不做质量估计）。

postprocess额外套用非重叠约束：result.masks.data = self.model._apply_non_overlapping_constraints(...)（由self.non_overlap_masks = True控制），保证多对象掩码互不重叠（predict.py#L997-L1003）。

get_model会调用model.set_binarize(True)开启掩码二值化，get_im_features支持batch参数把特征扩展到多对象批（predict.py#L896-L904）。此外还提供remove_object（删除指定对象并级联清理记忆）、clear_all_points_in_frame、clear_all_points_in_video等状态管理 API（predict.py#L1688-L1828）。

六、SAM 3 系列：语义与视频预测

6.1SAM3Predictor：交互式 SAM 3

SAM3Predictor（predict.py#L2201-L2222）相对SAM2Predictor的差异很小但很关键：

• stride从 16 改为14，背特征尺寸相应变为(288,288)/(144,144)/(72,72)；
• setup_model覆写归一化参数为mean = std = 127.5（对应“减 127.5 后除以 127.5”的标准 ImageNet 预处理，与 SAM 1/2 的均值/方差归一化不同）；
• 模型通过 build_sam3.py 的build_interactive_sam3(self.args.model, compile=self.args.compile)构建。

6.2SAM3SemanticPredictor：文本 + 几何 prompt

这是 SAM 3 的语义（开放词汇）分割入口，inference(im, bboxes=None, labels=None, text=None)同时支持两类提示：

# 优先级：bboxes > text > 预置类别（model.names） nc = 1 if bboxes is not None else len(text) if text is not None else len(self.model.names)

实现细节（predict.py#L2239-L2436）：

• 预处理差异：pre_transform使用LetterBox(self.imgsz, auto=False, center=False, scale_fill=True)，即 SAM 3 采用 fill 式缩放而非 padding 式 letterbox；
• 几何 prompt：_prepare_geometric_prompts把 xyxy 框转为归一化 xywh（除以源图像宽高），封装进Prompt对象（sam3.geometry_encoders.Prompt）；若只传框不传文本，自动补上"visual"文本提示；
• 前向：model.forward_grounding(backbone_out=features, text_ids=..., geometric_prompt=...)，文本变化时先model.set_classes(text=text)；
• 后处理：pred_scores = sigmoid(pred_logits) * sigmoid(presence_logit_dec)（乘上“类别存在性”分数），按args.conf过滤后做 NMS（agnostic_nms为假时框按类别偏移 7680 倍），掩码经F.interpolate回原图并二值化；
• 特征复用：inference_features提供与基类同名的“外部特征”入口，便于调用方自行编码图像后复用文本嵌入；reset_prompts()同时清空self.prompts与self.model.text_embeddings缓存。

6.3SAM3VideoPredictor与SAM3VideoSemanticPredictor

SAM3VideoPredictor（predict.py#L2439-L2492）多重继承自SAM2VideoPredictor与SAM3Predictor，覆写了propagate_in_video以适配 SAM 3 的条件/非条件帧缓存逻辑。SAM3VideoSemanticPredictor（predict.py#L2493 起）则是视频 + 语义的组合体，内部实现了完整的“检测 → 追踪 → 记忆更新”管线，包括：

• run_backbone_and_detection/_extract_detection_outputs：单帧检测，allow_new_detections控制是否允许新目标出现；
• run_tracker_propagation/_recondition_masklets：目标传播与 masklet 重条件化；
• run_tracker_update_planning_phase/run_tracker_update_execution_phase：规划-执行两阶段更新（含_suppress_overlapping_based_on_recent_occlusion、_get_objects_to_suppress_based_on_most_recently_occluded等遮挡处理）；
• _associate_det_trk：检测与追踪假设关联；_process_hotstart：初始帧热启动；
• _tracker_add_new_objects/_tracker_remove_objects/_tracker_update_memories：目标增删与记忆维护，并有_drop_new_det_with_obj_limit对新检测做数量上限裁剪。

从源码结构看，这套两阶段更新机制与SAM2VideoPredictor的轻量状态机相比明显更重，服务于自动开放词汇视频分割场景（无交互点击、完全自动检测追踪）。

七、SAM2DynamicInteractivePredictor：无视频文件的状态记忆

SAM2DynamicInteractivePredictor（predict.py#L1869-L2198）支持“支持图 + 查询图”式交互：先在带 prompt 的图像上update_memory，后续图像即可无需 prompt 直接预测。

• 构造参数max_obj_num（默认 3）限制同时追踪对象数，用于固定特征张量尺寸：obj_id_to_idx = OrderedDict(enumerate(range(max_obj_num)))；
• inference(im, bboxes=None, masks=None, points=None, labels=None, obj_ids=None, update_memory=False)有两种模式：update_memory=True时要求obj_ids及框/点/掩码提示，逐个对象执行track_step后经model._encode_new_memory把高分辨率掩码编码为maskmem_features追加进memory_bank（含非重叠约束开关non_overlap_masks_for_mem_enc）；
• track_step在无记忆时给视觉特征加no_mem_embed，有记忆时走model.memory_attention(curr=..., memory=...)融合，最后model._forward_sam_heads输出掩码、obj_ptr与object_score_logits；
• 对象分数原始范围约 [-32, 32]，代码将其clamp(score/32, min=0)映射到 [0,1] 作为存在性置信度（predict.py#L1988-L1991）；
• use_mask_input_as_output_without_sam=True时，掩码输入被直接当作 GT 输出，跳过 prompt encoder + mask decoder。

文档中的官方示例用法：

predictor = SAM2DynamicInteractivePredictor(cfg=DEFAULT_CFG) predictor(source=support_img1, bboxes=bboxes1, obj_ids=labels1, update_memory=True) results1 = predictor(source=query_img1) # 无需 prompt，直接利用记忆 predictor(source=support_img2, bboxes=bboxes2, obj_ids=labels2, update_memory=True) results2 = predictor(source=query_img2)

八、实战使用：配置、调用与 API 速查

8.1 通过SAM接口调用（推荐入口）

SAM模型类（model.py）在predict中注入默认配置：

overrides = {"conf": 0.25, "task": "segment", "mode": "predict", "imgsz": 1024} kwargs = {**overrides, **kwargs, "retina_masks": True} prompts = {"bboxes": bboxes, "points": points, "labels": labels}

因此SAM("sam_b.pt")(image, points=[[500, 375]])这类调用中，conf默认 0.25、imgsz默认 1024、retina_masks强制为 True，且要求权重为.pt/.pth文件（否则抛出NotImplementedError）。CLI 对应形式：

yolo predict model=sam_b.pt source=path/to/image.jpg

8.2 直接使用Predictor（特征复用模式）

来自官方模型文档 docs/en/models/sam.md 的完整示例（此处路径已按仓库相对路径给出）：

import cv2 from ultralytics.models.sam import Predictor as SAMPredictor # 创建 SAMPredictor：注意 model 指向具体权重，imgsz 必须为正方形 overrides = {"conf": 0.25, "task": "segment", "mode": "predict", "imgsz": 1024, "model": "mobile_sam.pt"} predictor = SAMPredictor(overrides=overrides) # 设置图像（只需一次，特征被缓存到 predictor.features） predictor.set_image("ultralytics/assets/zidane.jpg") # 图像文件路径 predictor.set_image(cv2.imread("ultralytics/assets/zidane.jpg")) # 或 np.ndarray（BGR） # 框提示 results = predictor(bboxes=[439, 437, 524, 709]) # 单点提示 results = predictor(points=[900, 370], labels=[1]) # 多点提示（多个独立对象） results = predictor(points=[[400, 370], [900, 370]], labels=[1, 1]) # 正负点提示（[[x,y],[x,y]] 属于同一对象的多个点） results = predictor(points=[[[400, 370], [900, 370]]], labels=[[1, 0]]) # 重置图像与特征缓存 predictor.reset_image()

全图自动分割模式：

from ultralytics.models.sam import Predictor as SAMPredictor overrides = {"conf": 0.25, "task": "segment", "mode": "predict", "imgsz": 1024, "model": "mobile_sam.pt"} predictor = SAMPredictor(overrides=overrides) results = predictor(source="ultralytics/assets/zidane.jpg", crop_n_layers=1, points_stride=64)

8.3 关键 API 速查表

8.4 与Results的衔接

所有模式最终返回的都是 Results 对象，可通过results[0].masks.data获取二值掩码、results[0].boxes获取 6 列框张量。由于 SAM 无类别信息，names按{"0": "0", "1": "1", ...}顺序编号（postprocess中names = dict(enumerate(str(i) for i in range(N)))），下游业务需自行维护掩码与目标的对应关系；视频模式下obj_id → 模型 index的映射则由inference_state["obj_idx_to_id"]提供。

九、小结

ultralytics/models/sam/predict.py以“基类流水线 + 子类覆写”的方式把 SAM 家族三代模型的推理逻辑统一进 Ultralytics 引擎：

• Predictor定义了三段式架构（image encoder / prompt encoder / mask decoder）的标准调用、prompt 坐标换算、全图分割算法与Results封装；
• SAM2Predictor引入多级特征与高分辨率解码，SAM2VideoPredictor/SAM2DynamicInteractivePredictor在其上分别构建视频状态机与静态记忆库；
• SAM 3 系列（SAM3Predictor→SAM3SemanticPredictor→ 两个视频变体）在 stride、归一化、预处理（scale_fill）与 grounding 前向上做了系统性适配，并新增了文本提示、presence 分数与 NMS 后处理。

理解这条继承链后，你可以按“单图 prompt 推理选基类Predictor、SAM 2 单图选SAM2Predictor、视频交互选SAM2VideoPredictor、图像序列状态记忆选SAM2DynamicInteractivePredictor、开放词汇语义分割选SAM3SemanticPredictor”的口径直接选取合适的预测器，并依据本文列出的参数默认值（imgsz正方形、conf=0.25、generate()的conf_thres=0.88、stability_score_thresh=0.95等）进行针对性调优。相关文档可继续参考 docs/en/models/sam.md、docs/en/models/sam-2.md 与 docs/en/models/sam-3.md。

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics