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这些类构成一条清晰的继承链类父类对应模型stride用途PredictorBasePredictorSAM / MobileSAM / FastSAM16单图 prompt 分割 全图自动分割SAM2PredictorPredictorSAM 216SAM 2 图像分割多级特征 高分辨率解码SAM2VideoPredictorSAM2PredictorSAM 216视频提示分割/追踪维护推理状态SAM2DynamicInteractivePredictorSAM2PredictorSAM 216图像序列/视频帧间动态交互记忆库memory bankSAM3PredictorSAM2PredictorSAM 314SAM 3 交互式预测SAM3SemanticPredictorSAM3PredictorSAM 314SAM 3 文本 几何 prompt 语义分割SAM3VideoPredictorSAM2VideoPredictorSAM3PredictorSAM 3—SAM 3 视频分割SAM3VideoSemanticPredictorSAM3SemanticPredictorSAM 3—SAM 3 视频语义分割模型到预测器的路由逻辑在 model.py 的task_map中根据权重文件名是否包含sam2/sam3字样SAM接口类会自动选择SAM2Predictor、SAM3Predictor或基础Predictor任务类型固定为segment。二、通用推理流水线Predictor基类Predictor继承自 ultralytics/engine/predictor.py 中的BasePredictor构造时会强制覆盖三项配置predict.py#L103overrides.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, autoFalse, centerFalse)做左上角对齐的缩放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-L470SAM 3 则改为[127.5, 127.5, 127.5]见第六节。精度控制quantize16时模型权重转为float16fp16否则float32同时会警告并忽略channels_lastTruepredict.py#L458-L478。Ultralytics 兼容性设置setup_model中为模型打补丁formatsam、base_modelFalse、stride32、done_warmupTrue使 SAM 这类非 Ultralytics 原生模型也能接入统一引擎predict.py#L472-L478。2.1 prompt 推理inference→prompt_inference→_inference_featuresinference(im, bboxesNone, pointsNone, labelsNone, masksNone, multimask_outputFalse)是整个模块的核心入口predict.py#L172-L208先从self.prompts字典中 pop 掉预先通过set_prompts()存储的提示支持“先设图、后给 prompt”的分离式调用若bboxes、points、masks全部为空则走generate()全图分割分支自动置segment_all True否则进入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-L278points (points, labels) if points is not None else None # 1. 编码 prompt稀疏 稠密嵌入 sparse_embeddings, dense_embeddings self.model.prompt_encoder(pointspoints, boxesbboxes, masksmasks) # 2. 掩码解码 pred_masks, pred_scores self.model.mask_decoder( image_embeddingsfeatures, image_peself.model.prompt_encoder.get_dense_pe(), sparse_prompt_embeddingssparse_embeddings, dense_prompt_embeddingsdense_embeddings, multimask_outputmultimask_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_outputTrue时每个 prompt 会输出 3 个候选掩码及其质量分数用于模糊提示下挑选最优结果。2.2 prompt 坐标换算_prepare_prompts原始 prompt 以输入图像像素为坐标系而网络内部工作在imgsz × imgsz的目标坐标系中。_prepare_promptspredict.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 中 HW256通过LetterBox最近邻插值到目标尺寸points的形状从(N, 2)升维为(N, 1, 2)以兼容多目标批处理。2.3 后处理postprocesspostprocesspredict.py#L486-L536完成掩码回投影与结果封装用ops.scale_masks(..., paddingFalse)把预测掩码缩放回原图尺寸再按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_layers1, points_stride64)调用的落点。完整参数及默认值如下参数默认值含义crop_n_layers0在图像裁剪块上额外预测的层数分层多尺度采样0 表示只在整图上采样crop_overlap_ratio512/1500 ≈ 0.34相邻裁剪块重叠比例随层数增加递减crop_downscale_factor1每层每边采样点数的缩放因子point_gridsNone自定义点采样网格归一化到 [0,1]None时按 stride 自动生成points_stride32每边采样点间距越小采样越密points_batch_size64每批送入 mask decoder 的点数conf_thres0.88基于模型质量分数的置信度过滤阈值 [0,1]stability_score_thresh0.95稳定性分数过滤阈值不同 mask_threshold 下掩码面积差异stability_score_offset0.95计算稳定性分数使用的 mask 阈值偏移crop_nms_thresh0.7跨裁剪块去重的 NMS IoU 阈值算法流程可以概括为五步源码见 predict.py#L375-L441generate_crop_boxes((ih, iw), crop_n_layers, crop_overlap_ratio)生成整图及分层裁剪区域对每个裁剪块F.interpolate回插到整图尺寸 → 提取特征 → 按point_grids[layer_idx] * points_scale生成采样点 → 分points_batch_size批调用_inference_features(crop_features, points, multimask_outputTrue)逐批过滤先按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裁剪块内部用torchvision.ops.nms(bboxes, scores, self.args.iou)去重再把框和掩码uncrop_*回投影到整图坐标系多裁剪块之间用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_area0, nms_thresh0.7)predict.py#L594-L644用于清理 SAM 输出中的碎块先调用amg.remove_small_regions分别以modeholes与modeislands删除小孔洞和孤立小岛再对重算后的框做 NMS被修改过的掩码得分为 0、未修改的得分为 1使 NMS 优先保留“干净”掩码。四、SAM 2 图像预测器SAM2Predictor的差异点SAM2Predictorpredict.py#L695-L834在基类之上做三处关键改造1prompt 合并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-L784return {image_embed: feats[-1], high_res_feats: feats[:-1]}若模型配置directly_add_no_mem_embed为真还会给最低层特征加上无记忆嵌入no_mem_embed。3高分辨率掩码解码_inference_features用model.sam_prompt_encoder注意此时boxesNone框已并入 points编码提示model.sam_mask_decoder解码时额外传入high_res_features与repeat_image标志输出高分辨率掩码pred_masks, pred_scores, _, _ self.model.sam_mask_decoder( image_embeddingsfeatures, image_peself.model.sam_prompt_encoder.get_dense_pe(), sparse_prompt_embeddingssparse_embeddings, dense_prompt_embeddingsdense_embeddings, multimask_outputmultimask_output, repeat_imagebatched_mode, # 多目标批处理时重复图像嵌入 high_res_featureshigh_res_features, )多目标判定逻辑为points is not None and points[0].shape[0] 1一次调用中多个对象。五、SAM 2 视频预测器SAM2VideoPredictor的推理状态机SAM2VideoPredictorpredict.py#L837-L1867把“视频追踪”建模为带状态的推理过程适合交互式逐帧提示场景。5.1 状态结构init_state/_init_statepredict.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_statepredict.py#L1297-L1323点与掩码互斥add_new_prompts断言(masks is None) ^ (points is None)同一次调用只能二选一。5.2 逐帧推理流程inferencepredict.py#L906-L977在每帧执行若该帧还没有任何条件输出cond_frame_outputs为空把本帧 prompt 视为初始化输入逐对象调用add_new_prompts(obj_idi, ...)propagate_in_video_preflight()先整合临时输出temp_output_dict_per_obj合并进output_dict并校验一致性分三种情况取当前帧结果已整合的条件帧 → 直接读取缓存已整合的非条件帧 → 读取缓存否则调用_run_single_frame_inference执行model.track_step并写入缓存随后_prune_non_cond_memory修剪非条件记忆_add_output_per_object为每个对象生成输出切片供后续与单个对象交互过滤空掩码后返回掩码与全 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等状态管理 APIpredict.py#L1688-L1828。六、SAM 3 系列语义与视频预测6.1SAM3Predictor交互式 SAM 3SAM3Predictorpredict.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, compileself.args.compile)构建。6.2SAM3SemanticPredictor文本 几何 prompt这是 SAM 3 的语义开放词汇分割入口inference(im, bboxesNone, labelsNone, textNone)同时支持两类提示# 优先级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, autoFalse, centerFalse, scale_fillTrue)即 SAM 3 采用 fill 式缩放而非 padding 式 letterbox几何 prompt_prepare_geometric_prompts把 xyxy 框转为归一化 xywh除以源图像宽高封装进Prompt对象sam3.geometry_encoders.Prompt若只传框不传文本自动补上visual文本提示前向model.forward_grounding(backbone_outfeatures, text_ids..., geometric_prompt...)文本变化时先model.set_classes(texttext)后处理pred_scores sigmoid(pred_logits) * sigmoid(presence_logit_dec)乘上“类别存在性”分数按args.conf过滤后做 NMSagnostic_nms为假时框按类别偏移 7680 倍掩码经F.interpolate回原图并二值化特征复用inference_features提供与基类同名的“外部特征”入口便于调用方自行编码图像后复用文本嵌入reset_prompts()同时清空self.prompts与self.model.text_embeddings缓存。6.3SAM3VideoPredictor与SAM3VideoSemanticPredictorSAM3VideoPredictorpredict.py#L2439-L2492多重继承自SAM2VideoPredictor与SAM3Predictor覆写了propagate_in_video以适配 SAM 3 的条件/非条件帧缓存逻辑。SAM3VideoSemanticPredictorpredict.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无视频文件的状态记忆SAM2DynamicInteractivePredictorpredict.py#L1869-L2198支持“支持图 查询图”式交互先在带 prompt 的图像上update_memory后续图像即可无需 prompt 直接预测。构造参数max_obj_num默认 3限制同时追踪对象数用于固定特征张量尺寸obj_id_to_idx OrderedDict(enumerate(range(max_obj_num)))inference(im, bboxesNone, masksNone, pointsNone, labelsNone, obj_idsNone, update_memoryFalse)有两种模式update_memoryTrue时要求obj_ids及框/点/掩码提示逐个对象执行track_step后经model._encode_new_memory把高分辨率掩码编码为maskmem_features追加进memory_bank含非重叠约束开关non_overlap_masks_for_mem_enctrack_step在无记忆时给视觉特征加no_mem_embed有记忆时走model.memory_attention(curr..., memory...)融合最后model._forward_sam_heads输出掩码、obj_ptr与object_score_logits对象分数原始范围约 [-32, 32]代码将其clamp(score/32, min0)映射到 [0,1] 作为存在性置信度predict.py#L1988-L1991use_mask_input_as_output_without_samTrue时掩码输入被直接当作 GT 输出跳过 prompt encoder mask decoder。文档中的官方示例用法predictor SAM2DynamicInteractivePredictor(cfgDEFAULT_CFG) predictor(sourcesupport_img1, bboxesbboxes1, obj_idslabels1, update_memoryTrue) results1 predictor(sourcequery_img1) # 无需 prompt直接利用记忆 predictor(sourcesupport_img2, bboxesbboxes2, obj_idslabels2, update_memoryTrue) results2 predictor(sourcequery_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 modelsam_b.pt sourcepath/to/image.jpg8.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(overridesoverrides) # 设置图像只需一次特征被缓存到 predictor.features predictor.set_image(ultralytics/assets/zidane.jpg) # 图像文件路径 predictor.set_image(cv2.imread(ultralytics/assets/zidane.jpg)) # 或 np.ndarrayBGR # 框提示 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(overridesoverrides) results predictor(sourceultralytics/assets/zidane.jpg, crop_n_layers1, points_stride64)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 clsgenerate(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_videoSAM2VideoPredictor按帧/全视频清除点击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正方形、conf0.25、generate()的conf_thres0.88、stability_score_thresh0.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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这些类构成一条清晰的继承链类父类对应模型stride用途PredictorBasePredictorSAM / MobileSAM / FastSAM16单图 prompt 分割 全图自动分割SAM2PredictorPredictorSAM 216SAM 2 图像分割多级特征 高分辨率解码SAM2VideoPredictorSAM2PredictorSAM 216视频提示分割/追踪维护推理状态SAM2DynamicInteractivePredictorSAM2PredictorSAM 216图像序列/视频帧间动态交互记忆库memory bankSAM3PredictorSAM2PredictorSAM 314SAM 3 交互式预测SAM3SemanticPredictorSAM3PredictorSAM 314SAM 3 文本 几何 prompt 语义分割SAM3VideoPredictorSAM2VideoPredictorSAM3PredictorSAM 3—SAM 3 视频分割SAM3VideoSemanticPredictorSAM3SemanticPredictorSAM 3—SAM 3 视频语义分割模型到预测器的路由逻辑在 model.py 的task_map中根据权重文件名是否包含sam2/sam3字样SAM接口类会自动选择SAM2Predictor、SAM3Predictor或基础Predictor任务类型固定为segment。二、通用推理流水线Predictor基类Predictor继承自 ultralytics/engine/predictor.py 中的BasePredictor构造时会强制覆盖三项配置predict.py#L103overrides.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, autoFalse, centerFalse)做左上角对齐的缩放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-L470SAM 3 则改为[127.5, 127.5, 127.5]见第六节。精度控制quantize16时模型权重转为float16fp16否则float32同时会警告并忽略channels_lastTruepredict.py#L458-L478。Ultralytics 兼容性设置setup_model中为模型打补丁formatsam、base_modelFalse、stride32、done_warmupTrue使 SAM 这类非 Ultralytics 原生模型也能接入统一引擎predict.py#L472-L478。2.1 prompt 推理inference→prompt_inference→_inference_featuresinference(im, bboxesNone, pointsNone, labelsNone, masksNone, multimask_outputFalse)是整个模块的核心入口predict.py#L172-L208先从self.prompts字典中 pop 掉预先通过set_prompts()存储的提示支持“先设图、后给 prompt”的分离式调用若bboxes、points、masks全部为空则走generate()全图分割分支自动置segment_all True否则进入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-L278points (points, labels) if points is not None else None # 1. 编码 prompt稀疏 稠密嵌入 sparse_embeddings, dense_embeddings self.model.prompt_encoder(pointspoints, boxesbboxes, masksmasks) # 2. 掩码解码 pred_masks, pred_scores self.model.mask_decoder( image_embeddingsfeatures, image_peself.model.prompt_encoder.get_dense_pe(), sparse_prompt_embeddingssparse_embeddings, dense_prompt_embeddingsdense_embeddings, multimask_outputmultimask_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_outputTrue时每个 prompt 会输出 3 个候选掩码及其质量分数用于模糊提示下挑选最优结果。2.2 prompt 坐标换算_prepare_prompts原始 prompt 以输入图像像素为坐标系而网络内部工作在imgsz × imgsz的目标坐标系中。_prepare_promptspredict.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 中 HW256通过LetterBox最近邻插值到目标尺寸points的形状从(N, 2)升维为(N, 1, 2)以兼容多目标批处理。2.3 后处理postprocesspostprocesspredict.py#L486-L536完成掩码回投影与结果封装用ops.scale_masks(..., paddingFalse)把预测掩码缩放回原图尺寸再按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_layers1, points_stride64)调用的落点。完整参数及默认值如下参数默认值含义crop_n_layers0在图像裁剪块上额外预测的层数分层多尺度采样0 表示只在整图上采样crop_overlap_ratio512/1500 ≈ 0.34相邻裁剪块重叠比例随层数增加递减crop_downscale_factor1每层每边采样点数的缩放因子point_gridsNone自定义点采样网格归一化到 [0,1]None时按 stride 自动生成points_stride32每边采样点间距越小采样越密points_batch_size64每批送入 mask decoder 的点数conf_thres0.88基于模型质量分数的置信度过滤阈值 [0,1]stability_score_thresh0.95稳定性分数过滤阈值不同 mask_threshold 下掩码面积差异stability_score_offset0.95计算稳定性分数使用的 mask 阈值偏移crop_nms_thresh0.7跨裁剪块去重的 NMS IoU 阈值算法流程可以概括为五步源码见 predict.py#L375-L441generate_crop_boxes((ih, iw), crop_n_layers, crop_overlap_ratio)生成整图及分层裁剪区域对每个裁剪块F.interpolate回插到整图尺寸 → 提取特征 → 按point_grids[layer_idx] * points_scale生成采样点 → 分points_batch_size批调用_inference_features(crop_features, points, multimask_outputTrue)逐批过滤先按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裁剪块内部用torchvision.ops.nms(bboxes, scores, self.args.iou)去重再把框和掩码uncrop_*回投影到整图坐标系多裁剪块之间用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_area0, nms_thresh0.7)predict.py#L594-L644用于清理 SAM 输出中的碎块先调用amg.remove_small_regions分别以modeholes与modeislands删除小孔洞和孤立小岛再对重算后的框做 NMS被修改过的掩码得分为 0、未修改的得分为 1使 NMS 优先保留“干净”掩码。四、SAM 2 图像预测器SAM2Predictor的差异点SAM2Predictorpredict.py#L695-L834在基类之上做三处关键改造1prompt 合并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-L784return {image_embed: feats[-1], high_res_feats: feats[:-1]}若模型配置directly_add_no_mem_embed为真还会给最低层特征加上无记忆嵌入no_mem_embed。3高分辨率掩码解码_inference_features用model.sam_prompt_encoder注意此时boxesNone框已并入 points编码提示model.sam_mask_decoder解码时额外传入high_res_features与repeat_image标志输出高分辨率掩码pred_masks, pred_scores, _, _ self.model.sam_mask_decoder( image_embeddingsfeatures, image_peself.model.sam_prompt_encoder.get_dense_pe(), sparse_prompt_embeddingssparse_embeddings, dense_prompt_embeddingsdense_embeddings, multimask_outputmultimask_output, repeat_imagebatched_mode, # 多目标批处理时重复图像嵌入 high_res_featureshigh_res_features, )多目标判定逻辑为points is not None and points[0].shape[0] 1一次调用中多个对象。五、SAM 2 视频预测器SAM2VideoPredictor的推理状态机SAM2VideoPredictorpredict.py#L837-L1867把“视频追踪”建模为带状态的推理过程适合交互式逐帧提示场景。5.1 状态结构init_state/_init_statepredict.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_statepredict.py#L1297-L1323点与掩码互斥add_new_prompts断言(masks is None) ^ (points is None)同一次调用只能二选一。5.2 逐帧推理流程inferencepredict.py#L906-L977在每帧执行若该帧还没有任何条件输出cond_frame_outputs为空把本帧 prompt 视为初始化输入逐对象调用add_new_prompts(obj_idi, ...)propagate_in_video_preflight()先整合临时输出temp_output_dict_per_obj合并进output_dict并校验一致性分三种情况取当前帧结果已整合的条件帧 → 直接读取缓存已整合的非条件帧 → 读取缓存否则调用_run_single_frame_inference执行model.track_step并写入缓存随后_prune_non_cond_memory修剪非条件记忆_add_output_per_object为每个对象生成输出切片供后续与单个对象交互过滤空掩码后返回掩码与全 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等状态管理 APIpredict.py#L1688-L1828。六、SAM 3 系列语义与视频预测6.1SAM3Predictor交互式 SAM 3SAM3Predictorpredict.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, compileself.args.compile)构建。6.2SAM3SemanticPredictor文本 几何 prompt这是 SAM 3 的语义开放词汇分割入口inference(im, bboxesNone, labelsNone, textNone)同时支持两类提示# 优先级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, autoFalse, centerFalse, scale_fillTrue)即 SAM 3 采用 fill 式缩放而非 padding 式 letterbox几何 prompt_prepare_geometric_prompts把 xyxy 框转为归一化 xywh除以源图像宽高封装进Prompt对象sam3.geometry_encoders.Prompt若只传框不传文本自动补上visual文本提示前向model.forward_grounding(backbone_outfeatures, text_ids..., geometric_prompt...)文本变化时先model.set_classes(texttext)后处理pred_scores sigmoid(pred_logits) * sigmoid(presence_logit_dec)乘上“类别存在性”分数按args.conf过滤后做 NMSagnostic_nms为假时框按类别偏移 7680 倍掩码经F.interpolate回原图并二值化特征复用inference_features提供与基类同名的“外部特征”入口便于调用方自行编码图像后复用文本嵌入reset_prompts()同时清空self.prompts与self.model.text_embeddings缓存。6.3SAM3VideoPredictor与SAM3VideoSemanticPredictorSAM3VideoPredictorpredict.py#L2439-L2492多重继承自SAM2VideoPredictor与SAM3Predictor覆写了propagate_in_video以适配 SAM 3 的条件/非条件帧缓存逻辑。SAM3VideoSemanticPredictorpredict.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无视频文件的状态记忆SAM2DynamicInteractivePredictorpredict.py#L1869-L2198支持“支持图 查询图”式交互先在带 prompt 的图像上update_memory后续图像即可无需 prompt 直接预测。构造参数max_obj_num默认 3限制同时追踪对象数用于固定特征张量尺寸obj_id_to_idx OrderedDict(enumerate(range(max_obj_num)))inference(im, bboxesNone, masksNone, pointsNone, labelsNone, obj_idsNone, update_memoryFalse)有两种模式update_memoryTrue时要求obj_ids及框/点/掩码提示逐个对象执行track_step后经model._encode_new_memory把高分辨率掩码编码为maskmem_features追加进memory_bank含非重叠约束开关non_overlap_masks_for_mem_enctrack_step在无记忆时给视觉特征加no_mem_embed有记忆时走model.memory_attention(curr..., memory...)融合最后model._forward_sam_heads输出掩码、obj_ptr与object_score_logits对象分数原始范围约 [-32, 32]代码将其clamp(score/32, min0)映射到 [0,1] 作为存在性置信度predict.py#L1988-L1991use_mask_input_as_output_without_samTrue时掩码输入被直接当作 GT 输出跳过 prompt encoder mask decoder。文档中的官方示例用法predictor SAM2DynamicInteractivePredictor(cfgDEFAULT_CFG) predictor(sourcesupport_img1, bboxesbboxes1, obj_idslabels1, update_memoryTrue) results1 predictor(sourcequery_img1) # 无需 prompt直接利用记忆 predictor(sourcesupport_img2, bboxesbboxes2, obj_idslabels2, update_memoryTrue) results2 predictor(sourcequery_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 modelsam_b.pt sourcepath/to/image.jpg8.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(overridesoverrides) # 设置图像只需一次特征被缓存到 predictor.features predictor.set_image(ultralytics/assets/zidane.jpg) # 图像文件路径 predictor.set_image(cv2.imread(ultralytics/assets/zidane.jpg)) # 或 np.ndarrayBGR # 框提示 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(overridesoverrides) results predictor(sourceultralytics/assets/zidane.jpg, crop_n_layers1, points_stride64)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 clsgenerate(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_videoSAM2VideoPredictor按帧/全视频清除点击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正方形、conf0.25、generate()的conf_thres0.88、stability_score_thresh0.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
