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

本文以 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），这些类构成一条清晰的继承链：

类	父类	对应模型	stride	用途
Predictor	BasePredictor	SAM / MobileSAM / FastSAM	16	单图 prompt 分割 + 全图自动分割
SAM2Predictor	Predictor	SAM 2	16	SAM 2 图像分割（多级特征 + 高分辨率解码）
SAM2VideoPredictor	SAM2Predictor	SAM 2	16	视频提示分割/追踪，维护推理状态
SAM2DynamicInteractivePredictor	SAM2Predictor	SAM 2	16	图像序列/视频帧间动态交互，记忆库（memory bank）
SAM3Predictor	SAM2Predictor	SAM 3	14	SAM 3 交互式预测
SAM3SemanticPredictor	SAM3Predictor	SAM 3	14	SAM 3 文本 + 几何 prompt 语义分割
SAM3VideoPredictor	SAM2VideoPredictor + SAM3Predictor	SAM 3	—	SAM 3 视频分割
SAM3VideoSemanticPredictor	SAM3SemanticPredictor	SAM 3	—	SAM 3 视频语义分割

模型到预测器的路由逻辑在 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 不返回类别信息，该列仅为与 Ultralytics Results 结构保持一致）；
• 按 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) 调用的落点。完整参数及默认值如下：

参数	默认值	含义
crop_n_layers	0	在图像裁剪块上额外预测的层数（分层多尺度采样，0 表示只在整图上采样）
crop_overlap_ratio	512/1500 ≈ 0.34	相邻裁剪块重叠比例，随层数增加递减
crop_downscale_factor	1	每层每边采样点数的缩放因子
point_grids	None	自定义点采样网格（归一化到 [0,1]）；None 时按 stride 自动生成
points_stride	32	每边采样点间距（越小采样越密）
points_batch_size	64	每批送入 mask decoder 的点数
conf_thres	0.88	基于模型质量分数的置信度过滤阈值 [0,1]
stability_score_thresh	0.95	稳定性分数过滤阈值（不同 mask_threshold 下掩码面积差异）
stability_score_offset	0.95	计算稳定性分数使用的 mask 阈值偏移
crop_nms_thresh	0.7	跨裁剪块去重的 NMS IoU 阈值

算法流程可以概括为五步（源码见 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.1 SAM3Predictor：交互式 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.2 SAM3SemanticPredictor：文本 + 几何 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.3 SAM3VideoPredictor 与 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 速查表

方法	所属类	作用
set_image(image)	Predictor	设置单张图像并完成特征提取（内部 setup_model → setup_source → preprocess → get_im_features），断言只能设 1 张
set_prompts(prompts)	Predictor	以字典形式预存 bboxes/points/labels/masks，下一次 inference 时自动 pop 使用
reset_image()	Predictor	清空 im 与 features，切换图像前必调
inference(im, bboxes, points, labels, masks, multimask_output)	Predictor	核心推理入口，无 prompt 时自动转入 generate()
inference_features(features, src_shape, ..., multimask_output)	Predictor	对“外部提供”的特征做 prompt 预处理 + 推理，返回 (masks, bboxes)，bboxes 为 6 列（xyxy + score + cls）
generate(im, crop_n_layers, ...)	Predictor	全图分割，参数见第三节
remove_small_regions(masks, min_area, nms_thresh)	Predictor（静态）	清理碎块/孔洞并 NMS 去重
add_new_prompts(obj_id, points/labels/masks, frame_idx)	SAM2VideoPredictor	为指定对象在指定帧追加交互，条件/非条件帧自动判定
remove_object(inference_state, obj_id, strict)	SAM2VideoPredictor	删除对象并清理相关记忆与输出
clear_all_points_in_frame / _in_video	SAM2VideoPredictor	按帧/全视频清除点击
update_memory(obj_ids, points, labels, masks)	SAM2DynamicInteractivePredictor	将带 prompt 的图像状态编码进记忆库
reset_prompts()	SAM3SemanticPredictor	清空提示缓存与文本嵌入缓存

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。