Ultralytics SAM 模型接口全解析统一 Segment AnythingSAM / SAM2 / SAM3家族的 Python API 参考【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本篇文章基于 Ultralytics 仓库中 docs/en/reference/models/sam/model.md 所对应的 API 参考页以 ultralytics/models/sam/model.py 中的SAM类为主线系统讲解它在推理、加载、任务调度上的接口设计、默认行为与底层实现。读完你不仅能熟练使用from ultralytics import SAM完成框选、点选、负点提示等 promptable 分割还能理解该类如何通过一个入口同时兼容 SAM、SAM 2 与 SAM 3 三类权重并掌握其背后的 Predictor 推理流水线。一、ultralytics.models.sam.model模块定位在 Ultralytics 的代码树中models/sam/目录专门承载 Segment Anything 系列模型的封装与推理逻辑其中 ultralytics/models/sam/model.py 是最上层的模型接口文件定义了向用户暴露的SAM类同目录的 predict.py 实现底层预测器build.py 负责按权重构建具体网络结构build_sam3.py 负责构建 SAM 3 交互模型。模块导出集中在 ultralytics/models/sam/init.py对外提供SAM、Predictor、SAM2Predictor、SAM2VideoPredictor、SAM2DynamicInteractivePredictor、SAM3Predictor等符号同时顶层包 ultralytics/init.py 将SAM与YOLO、FastSAM、RTDETR等并列导出因此日常使用只需from ultralytics import SAM根据类注释model.pySAM类是面向实时图像分割任务的接口类设计目标是promptable segmentation可提示分割支持以边界框、点、标签等作为提示来产生目标掩码并具备zero-shot零样本迁移能力——它由基于 SA-1B 数据集的 Segment Anything 项目发展而来可适应未见过的图像分布与任务。它沿用了标准的 Ultralytics 引擎接口.predict()、.info()、task等但仅用于推理task固定为segment不支持训练、验证与导出。二、单一入口兼容三代模型构造函数与权重加载SAM继承自引擎基类Model见 ultralytics/engine/model.py构造签名非常简单def __init__(self, model: str sam_b.pt) - None:默认权重为sam_b.pt。构造函数内部依次做了三件事model.py扩展名校验要求权重文件后缀必须是.pt或.pth否则抛出NotImplementedError(SAM prediction requires pre-trained *.pt or *.pth model.)。这与 YOLO 等可端到端训练/导出的任务不同——SAM 只接受预训练检查点。版本探测依据文件名stem是否包含sam2/sam3设置布尔标志self.is_sam2、self.is_sam3。例如sam2_b.pt→is_sam2Truesam3_l.pt→is_sam3True而sam_b.pt两者皆 False。以tasksegment调用父类初始化使该模型归入实例分割任务体系。_load不同代际权重的构建分派真正的网络加载发生在_load()model.pyif self.is_sam3: from .build_sam3 import build_interactive_sam3 self.model build_interactive_sam3(weights) else: from .build import build_sam # slow import self.model build_sam(weights)可见 SAM 3 权重走 build_sam3.py 中的build_interactive_sam3而 SAM 1 / SAM 2 / MobileSAM 等统一走 build.py 的build_sam。其中 import 被刻意做成局部延迟导入以加快包的整体加载速度。支持的预定义权重build.py 中的sam_model_map给出了所有内置可识别的权重名及其构建函数既包括官方 SAM 系列也覆盖 Meta 的 SAM 2 / SAM 2.1 检查点家族预定义权重名备注SAM 1Meta 原始 SAMsam_h.pt、sam_l.pt、sam_b.ptViT-H/L/B 主干MobileSAMmobile_sam.pt轻量化的移动端变体SAM 2sam2_t.pt、sam2_s.pt、sam2_b.pt、sam2_l.ptTiny/Small/Base/LargeSAM 2.1sam2.1_t.pt、sam2.1_s.pt、sam2.1_b.pt、sam2.1_l.pt复用 SAM 2 的构建函数若传入的权重名不在此映射内build_sam会抛出FileNotFoundError并列出可用模型。你也可以传入自定义.pt/.pth文件的路径只要后缀合法即可例如SAM(path/to/custom_checkpoint.pt)。注意尽管sam_model_map支持sam_h.pt、mobile_sam.pt等官方文档 docs/en/models/sam.md 中可用模型表格仅正式列出sam_b.pt与sam_l.pt两个权重均只支持 Inference✅训练、验证、导出为 ❌。MobileSAM 的完整介绍见 docs/en/models/mobile-sam.md。三、推理入口predict与__call__SAM.predict()是整个接口的核心model.pydef predict(self, source, stream: bool False, bboxesNone, pointsNone, labelsNone, **kwargs):参数含义source图像或视频路径也可以是PIL.Image或np.ndarray。stream为True时开启实时流式处理。bboxes用于框提示的边界框坐标列表格式为 XYXY。points用于点提示的坐标列表格式为像素坐标。labels点提示对应的标签列表1表示前景要分割的目标0表示背景排除区域。**kwargs透传给底层预测器的其它参数。SAM.__call__model.py是predict的别名因此model(...)与model.predict(...)等价。默认覆盖参数override在predict内部方法先构造一组默认 override再与用户传入的kwargs合并用户值优先这是理解 SAM 行为的关键overrides {conf: 0.25, task: segment, mode: predict, imgsz: 1024} kwargs {**overrides, **kwargs, retina_masks: True} prompts {bboxes: bboxes, points: points, labels: labels} return super().predict(source, stream, promptsprompts, **kwargs)默认项值含义conf0.25掩码质量分数过滤阈值tasksegment分割任务modepredict推理模式SAM 不支持训练/导出imgsz1024输入边长仅支持正方形retina_masksTrue强制保留原始分辨率掩码而非下采样掩码也就是说提示词bboxes/points/labels并不作为普通 kwargs 直接下传而是统一打包成prompts字典交给引擎再由引擎路由到对应预测器的prompt_inference流程。bboxes、points、labels之外底层预测器同样支持masks作为掩码提示用于基于上一轮输出的细化迭代见 predict.py。典型调用示例以仓库自带的示例图 ultralytics/assets/zidane.jpg 为例与 docs/en/models/sam.md 一致from ultralytics import SAM # 加载模型默认 sam_b.pt也可显式指定权重 model SAM(sam_b.pt) # 打印模型结构信息可选 model.info() # ① 边界框提示一次框选一个目标 results model(ultralytics/assets/zidane.jpg, bboxes[439, 437, 524, 709]) # ② 单点提示labels[1] 表示该点是前景 results model(points[900, 370], labels[1]) # ③ 多点提示同一对象给出多个正点增强鲁棒性 results model(points[[400, 370], [900, 370]], labels[1, 1]) # ④ 单对象多提示的嵌套写法注意三层括号 results model(points[[[400, 370], [900, 370]]], labels[[1, 1]]) # ⑤ 负点提示一个正点 一个负点排除误分区域 results model(points[[[400, 370], [900, 370]]], labels[[1, 0]])当bboxes、points、masks提示全部为空时预测器会自动切换为Segment Everything全图自动分割模式见 predict.py即对整张图像做无提示的密集掩码生成# 全图分割不给任何提示 model(path/to/image.jpg)对应的 CLI 用法为yolo predict modelsam_b.pt sourcepath/to/image.jpg所有返回的results都是标准 Results 对象可直接访问results[0].masks获取掩码、results[0].boxes获取框SAM 不产出类别框中的cls仅为对齐 Ultralytics 结果格式的占位符注释见 predict.py。四、task_map如何自动选择正确的 Predictortask_map是只读属性model.py返回segment任务对应的预测器类其分派完全由构造时探测到的is_sam2/is_sam3标志决定return { segment: {predictor: SAM2Predictor if self.is_sam2 else SAM3Predictor if self.is_sam3 else Predictor} }也就是说同一个SAM类在加载不同权重后会自动装配不同代际的预测器权重家族is_sam2is_sam3实际使用的 Predictorsam_b.pt/sam_l.pt/mobile_sam.ptFalseFalsePredictorpredict.pysam2_t.pt/sam2_b.pt/sam2.1_*TrueFalseSAM2Predictorpredict.pysam3_*FalseTrueSAM3Predictor预测器家族的类定义位于 predict.py该文件被 docs/en/reference/models/sam/predict.md 文档化并随 ultralytics/models/sam/init.py 对外暴露。SAM 2 系列还额外提供面向视频流的分割跟踪器SAM2VideoPredictor与支持运行中动态追加提示的SAM2DynamicInteractivePredictor它们的行为在 docs/en/models/sam-2.md 中有完整示例。五、info()模型结构信息info()model.py委托给工具函数model_infodef info(self, detailed: bool False, verbose: bool True): return model_info(self.model, detaileddetailed, verboseverbose)detailedTrue会输出各层/运算的详细信息返回的元组内含模型字符串表示info[0]即概要信息。该函数来自 ultralytics/utils/torch_utils.py与 YOLO 系列共用同一套参数统计逻辑。六、源码纵深SAM背后的推理流水线要从会调用进阶到懂原理需要理解SAM类如何对接 predict.py 中的Predictor。以下几点最能体现 SAM 与 YOLO 推理的根本差异1. 一次性编码 多轮提示提示型分割的核心优化是图像只编码一次、可反复施加提示。Predictor提供set_image()/reset_image()predict.pyset_image预处理图像并经get_im_features调用self.model.image_encoder(im)缓存特征到self.features此后每次仅用轻量的 prompt encoder mask decoder 产出新掩码无需重跑图像编码器。因此更高效的交互写法是import cv2 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) # 设置图像既支持文件路径也支持 cv2 读入的 BGR ndarray predictor.set_image(ultralytics/assets/zidane.jpg) # 同一张图反复施加不同提示 results predictor(bboxes[439, 437, 524, 709]) # 框提示 results predictor(points[900, 370], labels[1]) # 单点 results predictor(points[[[400, 370], [900, 370]]], labels[[1, 0]]) # 正负点 predictor.reset_image() # 清空图像与缓存特征Predictor.__init__中固定batch: 1并把retina_masks置 Truepre_transform使用LetterBox填充为正方形autoFalse, centerFalse且断言只支持单图、不支持批处理predict.py。2. 三段式网络结构prompt_inferencepredict.py完整呈现了 SAM 的图像编码器 提示编码器 掩码解码器三段式推理先取缓存特征经_prepare_prompts把像素坐标的框/点按 letterbox 缩放比映射到 1024×1024 特征空间并自动把缺省labels置为全1即默认视为正点随后调用self.model.prompt_encoder(...)生成 sparse/dense 嵌入最后self.model.mask_decoder(...)输出掩码与质量分数。multimask_output为 True 时每个提示会返回多个候选掩码以消解歧义。SAM 2 的SAM2Predictor则改用model.forward_imagesam_prompt_encodersam_mask_decoder并把 box 提示折叠进 point 序列附加[2, 3]标签同时维护多尺度高层特征high_res_featspredict.py。3. 全图分割的参数面generate()predict.py支撑Segment Everything它按参数网格采样点、逐批推理、裁剪区域投票并做 NMS 去重。常用可调参数包括参数默认值含义points_stride32图像每边采样点的间隔越小点越密points_batch_size64每批处理的提示点数conf_thres0.88掩码质量分数过滤阈值stability_score_thresh0.95掩码稳定性分数阈值crop_n_layers0是否在图像裁剪块上额外预测0 提升细节crop_nms_thresh0.7裁剪块之间去重的 IoU 阈值例如希望更细粒度地全图分割可调用predictor(sourceultralytics/assets/zidane.jpg, crop_n_layers1, points_stride64)。完整签名见 predict.py。4. 输入预处理与归一化setup_modelpredict.py中 SAM 使用 ImageNet 风格均方差做归一化mean[123.675, 116.28, 103.53]、std[58.395, 57.12, 57.375]与通用检测模型不同同时设置model.stride 32、model.format sam并提示channels_lastTrue不被支持。SAM 的imgsz只接受正方形且推理 dtype 默认 float16由self.model.fp16决定。七、与任务型分割模型的选型差异值得强调的是SAM 是一类通用提示分割基础模型与闭集实例分割的 YOLO-seg 定位不同二者并非替代关系提示驱动 / 零样本SAM 可通过框、点、掩码提示分割任意未见过的对象类别适合交互式标注、目标提案、边缘检测、图文掩码text-to-mask等下游任务而 YOLO11/YOLO26 的-seg系列在固定类别上速度与体积优势明显。能力边界在 Ultralytics 框架中SAM 权重只支持预测推理而 YOLO 分割模型支持训练、验证、导出与部署。官方在 docs/en/models/sam.md 中给出了 SAM-b 与各代 YOLO-seg 在体积、参数量与 CPU 耗时上的对比参考供选型时查阅。自动标注SAM 常被用于检测模型出框、SAM 出掩码的自动标注流水线即auto_annotate工具见 ultralytics/data/annotator.py可快速把检测数据扩成实例分割训练集from ultralytics.data.annotator import auto_annotate auto_annotate(datapath/to/images, det_modelyolo26x.pt, sam_modelsam_b.pt)八、小结与导航SAM类以极小的 API 面构造、predict/__call__、info、task_map屏蔽了 SAM / SAM 2 / SAM 3 在网络构建与推理细节上的差异构造函数根据文件名后缀自动探测is_sam2/is_sam3_load据此分派到build_sam或build_interactive_sam3task_map再据此装配Predictor/SAM2Predictor/SAM3Predictor。理解这套分派机制是排查自定义权重兼容性与扩展新预测器时的关键。若需继续深入可在本仓库中对照阅读类与接口实现ultralytics/models/sam/model.py底层预测器实现与Predictor/generate全量参数ultralytics/models/sam/predict.py、docs/en/reference/models/sam/predict.md权重注册表与网络构建ultralytics/models/sam/build.py、ultralytics/models/sam/build_sam3.py模型使用教程与能力对比docs/en/models/sam.md、docs/en/models/sam-2.md、docs/en/models/sam-3.md任务定义与 Results 对象docs/en/tasks/segment.md、docs/en/modes/predict.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），仅供参考
