Transformers documentation
SAM2
该模型于 2025-08-14 贡献至 Hugging Face Transformers。
SAM2
概述
SAM2（Segment Anything Model 2）由 Nikhila Ravi、Valentin Gabeur、Yuan-Ting Hu、Ronghang Hu、Chaitanya Ryali、Tengyu Ma、Haitham Khedr、Roman Rädle、Chloe Rolland、Laura Gustafson、Eric Mintun、Junting Pan、Kalyan Vasudev Alwala、Nicolas Carion、Chao-Yuan Wu、Ross Girshick、Piotr Dollár 和 Christoph Feichtenhofer 在 Segment Anything in Images and Videos 中提出。
给定输入图像或视频以及输入点或边界框，该模型可用于预测任意感兴趣对象的分割掩码。
该论文的摘要如下：
我们提出了 Segment Anything Model 2（SAM 2），这是一个旨在解决图像和视频中的可提示视觉分割问题的基础模型。我们构建了一个数据引擎，通过用户交互来改进模型和数据，从而收集了迄今为止规模最大的视频分割数据集。我们的模型采用了一种简单的 Transformer 架构，并配备了用于实时视频处理的流式内存。在我们数据上训练的 SAM 2 在广泛的任务中均表现出强劲的性能。在视频分割方面，我们观察到其精度更高，且所需的交互次数比先前方法减少了 3 倍。在图像分割方面，我们的模型比 Segment Anything Model（SAM）更准确，速度快 6 倍。我们相信，我们的数据、模型和见解将成为视频分割及相关感知任务的重要里程碑。我们将发布我们模型的版本、数据集以及一个交互式演示。
提示：
- 批量与视频支持：SAM2 原生支持批量处理和无缝视频分割，而原始 SAM 专为静态图像和更简单的单张图像处理工作流而设计。
- 准确性与泛化能力：与原始 SAM 相比，SAM2 在分割质量、鲁棒性以及针对新领域的零样本泛化能力方面均有提升，尤其是在使用混合提示时。
该模型由 sangbumchoi 和 yonigozlan 贡献。 原始代码可在此处找到。
使用示例
使用 Pipeline 自动生成掩码
SAM2 可用于自动掩码生成，通过 mask-generation 流水线对图像中的所有对象进行分割：
from transformers import pipeline
generator = pipeline("mask-generation", model="facebook/sam2.1-hiera-large", device=0)
image_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
outputs = generator(image_url, points_per_batch=64)
len(outputs["masks"]) # Number of masks generated
39基础图像分割
单击
你可以通过在想要分割的对象上单击一个点来分割对象：
from transformers import Sam2Processor, Sam2Model
import torch
from PIL import Image
import requests
model = Sam2Model.from_pretrained("facebook/sam2.1-hiera-large", device_map="auto")
processor = Sam2Processor.from_pretrained("facebook/sam2.1-hiera-large")
image_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
raw_image = Image.open(requests.get(image_url, stream=True).raw).convert("RGB")
input_points = [[[[500, 375]]]] # Single point click, 4 dimensions (image_dim, object_dim, point_per_object_dim, coordinates)
input_labels = [[[1]]] # 1 for positive click, 0 for negative click, 3 dimensions (image_dim, object_dim, point_label)
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs)
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
# The model outputs multiple mask predictions ranked by quality score
print(f"Generated {masks.shape[1]} masks with shape {masks.shape}")
Generated 3 masks with shape torch.Size(1, 3, 1500, 2250)多个用于优化的点
您可以提供多个点来细化分割：
# Add both positive and negative points to refine the mask
input_points = [[[[500, 375], [1125, 625]]]] # Multiple points for refinement
input_labels = [[[1, 1]]] # Both positive clicks
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs)
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]边界框输入
SAM2 还支持边界框输入用于分割：
# Define bounding box as [x_min, y_min, x_max, y_max]
input_boxes = [[[75, 275, 1725, 850]]]
inputs = processor(images=raw_image, input_boxes=input_boxes, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs)
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]多目标分割
您可以同时分割多个对象：
# Define points for two different objects
input_points = [[[[500, 375]], [[650, 750]]]] # Points for two objects in same image
input_labels = [[[1], [1]]] # Positive clicks for both objects
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
# Each object gets its own mask
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
print(f"Generated masks for {masks.shape[0]} objects")
Generated masks for 2 objects批量推理
批量图像
同时处理多张图像以提高效率：
from transformers import Sam2Processor, Sam2Model
import torch
from PIL import Image
import requests
model = Sam2Model.from_pretrained("facebook/sam2.1-hiera-large", device_map="auto")
processor = Sam2Processor.from_pretrained("facebook/sam2.1-hiera-large")
# Load multiple images
image_urls = [
"https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg",
"https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/dog_sam.png"
]
raw_images = [Image.open(requests.get(url, stream=True).raw).convert("RGB") for url in image_urls]
# Single point per image
input_points = [[[[500, 375]]], [[[770, 200]]]] # One point for each image
input_labels = [[[1]], [[1]]] # Positive clicks for both images
inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
# Post-process masks for each image
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
print(f"Processed {len(all_masks)} images, each with {all_masks[0].shape[0]} objects")
Processed 2 images, each with 1 objects每张图像的批量对象
使用批量推理对每张图片中的多个对象进行分割：
# Multiple objects per image - different numbers of objects per image
input_points = [
[[[500, 375]], [[650, 750]]], # Truck image: 2 objects
[[[770, 200]]] # Dog image: 1 object
]
input_labels = [
[[1], [1]], # Truck image: positive clicks for both objects
[[1]] # Dog image: positive click for the object
]
inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])批量图像与批量对象及多个点
处理每个对象包含多个点的复杂批次场景：
# Add groceries image for more complex example
groceries_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/groceries.jpg"
groceries_image = Image.open(requests.get(groceries_url, stream=True).raw).convert("RGB")
raw_images = [raw_images[0], groceries_image] # Use truck and groceries images
# Complex batching: multiple images, multiple objects, multiple points per object
input_points = [
[[[500, 375]], [[650, 750]]], # Truck image: 2 objects with 1 point each
[[[400, 300]], [[630, 300], [550, 300]]] # Groceries image: obj1 has 1 point, obj2 has 2 points
]
input_labels = [
[[1], [1]], # Truck image: positive clicks
[[1], [1, 1]] # Groceries image: positive clicks for refinement
]
inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])批量边界框
使用边界框输入处理多张图像：
# Multiple bounding boxes per image (using truck and groceries images)
input_boxes = [
[[75, 275, 1725, 850], [425, 600, 700, 875], [1375, 550, 1650, 800], [1240, 675, 1400, 750]], # Truck image: 4 boxes
[[450, 170, 520, 350], [350, 190, 450, 350], [500, 170, 580, 350], [580, 170, 640, 350]] # Groceries image: 4 boxes
]
# Update images for this example
raw_images = [raw_images[0], groceries_image] # truck and groceries
inputs = processor(images=raw_images, input_boxes=input_boxes, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs, multimask_output=False)
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
print(f"Processed {len(input_boxes)} images with {len(input_boxes[0])} and {len(input_boxes[1])} boxes respectively")
Processed 2 images with 4 and 4 boxes respectively使用之前的掩码作为输入
SAM2 可以使用先前预测的掩码作为输入来优化分割：
# Get initial segmentation
input_points = [[[[500, 375]]]]
input_labels = [[[1]]]
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)
with torch.no_grad():
outputs = model(**inputs)
# Use the best mask as input for refinement
mask_input = outputs.pred_masks[:, :, torch.argmax(outputs.iou_scores.squeeze())]
# Add additional points with the mask input
new_input_points = [[[[500, 375], [450, 300]]]]
new_input_labels = [[[1, 1]]]
inputs = processor(
input_points=new_input_points,
input_labels=new_input_labels,
original_sizes=inputs["original_sizes"],
return_tensors="pt",
).to(model.device)
with torch.no_grad():
refined_outputs = model(
**inputs,
input_masks=mask_input,
image_embeddings=outputs.image_embeddings,
multimask_output=False,
)Sam2Config
class transformers.Sam2Config
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneprompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_range: float = 0.02 )
参数
- vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig]，可选) — 视觉骨干网络的配置对象或字典。 - prompt_encoder_config (Union[
dict,Sam2PromptEncoderConfig], 可选) — 用于初始化 Sam2PromptEncoderConfig 的配置选项字典。 - mask_decoder_config (Union[
dict,Sam2MaskDecoderConfig], 可选) — 用于初始化 Sam2MaskDecoderConfig 的配置选项字典。 - initializer_range (
float，可选，默认为0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
这是用于存储 Sam2Model 配置的类。它根据指定的参数实例化 Sam2 模型，并定义模型架构。使用默认值实例化配置将生成与 facebook/sam2.1-hiera-tiny 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import (
... Sam2VisionConfig,
... Sam2PromptEncoderConfig,
... Sam2MaskDecoderConfig,
... Sam2Model,
... )
>>> # Initializing a Sam2Config with `"facebook/sam2.1_hiera_tiny"` style configuration
>>> configuration = Sam2Config()
>>> # Initializing a Sam2Model (with random weights) from the `"facebook/sam2.1_hiera_tiny"` style configuration
>>> model = Sam2Model(configuration)
>>> # Accessing the model configuration
>>> configuration = model.config
>>> # We can also initialize a Sam2Config from a Sam2VisionConfig, Sam2PromptEncoderConfig, and Sam2MaskDecoderConfig
>>> # Initializing SAM2 vision encoder, memory attention, and memory encoder configurations
>>> vision_config = Sam2VisionConfig()
>>> prompt_encoder_config = Sam2PromptEncoderConfig()
>>> mask_decoder_config = Sam2MaskDecoderConfig()
>>> config = Sam2Config(vision_config, prompt_encoder_config, mask_decoder_config)Sam2HieraDetConfig
class transformers.Sam2HieraDetConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 96num_attention_heads: int = 1num_channels: int = 3image_size: int | list[int] | None = Nonepatch_kernel_size: int | list[int] | None = Nonepatch_stride: int | list[int] | None = Nonepatch_padding: int | list[int] | None = Nonequery_stride: int | list[int] | None = Nonewindow_positional_embedding_background_size: list[int] | None = Nonenum_query_pool_stages: int = 3blocks_per_stage: list[int] | None = Noneembed_dim_per_stage: list[int] | None = Nonenum_attention_heads_per_stage: list[int] | None = Nonewindow_size_per_stage: list[int] | None = Noneglobal_attention_blocks: list[int] | None = Nonemlp_ratio: float = 4.0hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06initializer_range: float = 0.02 )
参数
- hidden_size (
int，可选，默认为96) — 隐藏表示的维度。 - num_attention_heads (
int，可选，默认为1) — Transformer 解码器中每个注意力层的注意力头数量。 - num_channels (
int，可选，默认为3) — 输入通道的数量。 - image_size (
Union[int, list[int]]，可选) — 每张图片的尺寸（分辨率）。 - patch_kernel_size (
list[int]，可选，默认为[7, 7]) — Patch 的卷积核大小。 - patch_stride (
list[int]，可选，默认为[4, 4]) — patch 的步长。 - patch_padding (
list[int]，可选，默认为[3, 3]) — 补丁的填充。 - query_stride (
list[int]，可选，默认为[2, 2]) — 各阶段之间的下采样步长。 - window_positional_embedding_background_size (
list[int]，可选，默认为[7, 7]) — 在未使用全局注意力时，每个阶段的窗口大小。 - num_query_pool_stages (
int，可选，默认为 3) — 查询池化阶段的数量。 - blocks_per_stage (
list[int]，可选，默认为[1, 2, 7, 2]) — 每个阶段的块数。 - embed_dim_per_stage (
list[int]，可选，默认为[96, 192, 384, 768]) — 每个阶段的嵌入维度。 - num_attention_heads_per_stage (
list[int]，可选，默认为[1, 2, 4, 8]) — 每个阶段的注意力头数量。 - window_size_per_stage (
list[int]，可选，默认为[8, 4, 14, 7]) — 每个阶段的窗口大小。 - global_attention_blocks (
list[int]，可选，默认为[5, 7, 9]) — 使用全局注意力的块。 - mlp_ratio (
float，可选，默认为4.0) — MLP 隐藏层维度与嵌入维度的比值。 - hidden_act (
str，可选，默认为gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu"等。 - layer_norm_eps (
float，可选，默认为1e-06) — 层归一化层所使用的 epsilon 值。 - initializer_range (
float，可选，默认为0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
这是用于存储 Sam2Model 配置的类。它根据指定的参数实例化 Sam2 模型，并定义模型架构。使用默认值实例化配置将生成与 facebook/sam2.1-hiera-tiny 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
Sam2VisionConfig
class transformers.Sam2VisionConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonebackbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonebackbone_channel_list: list[int] | None = Nonebackbone_feature_sizes: list | None = Nonefpn_hidden_size: int = 256fpn_kernel_size: int = 1fpn_stride: int = 1fpn_padding: int = 0fpn_top_down_levels: list[int] | None = Nonenum_feature_levels: int = 3hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06initializer_range: float = 0.02 )
参数
- backbone_config (
Union[dict, ~configuration_utils.PreTrainedConfig]，可选) — 主干模型的配置。 - backbone_channel_list (
List[int]，可选，默认为[768, 384, 192, 96]) — 主干网络的通道维度列表。 - backbone_feature_sizes (
List[List[int]]，可选，默认为[[256, 256], [128, 128], [64, 64]]) — 主干网络输出的特征图的空间尺寸。 - fpn_hidden_size (
int，可选，默认为 256) — FPN 的隐藏维度。 - fpn_kernel_size (
int，可选，默认为 1) — neck 中卷积的核大小。 - fpn_stride (
int，可选，默认为 1) — neck 中卷积的步长。 - fpn_padding (
int，可选，默认为 0) — neck 中卷积的填充值。 - fpn_top_down_levels (
List[int]，可选，默认为[2, 3]) — 用于自顶向下 FPN 连接的层级。 - num_feature_levels (
int，可选，默认为 3) — 要使用的 FPN 特征层数。 - hidden_act (
str，可选，默认为gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu"等。 - layer_norm_eps (
float，可选，默认为1e-06) — 层归一化层所使用的 epsilon 值。 - initializer_range (
float，可选，默认为0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
这是用于存储 Sam2Model 配置的类。它根据指定的参数实例化 Sam2 模型，并定义模型架构。使用默认值实例化配置将生成与 facebook/sam2.1-hiera-tiny 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
Sam2MaskDecoderConfig
类 transformers.Sam2MaskDecoderConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256hidden_act: str = 'gelu'mlp_dim: int = 2048num_hidden_layers: int = 2num_attention_heads: int = 8attention_downsample_rate: int = 2num_multimask_outputs: int = 3iou_head_depth: int = 3iou_head_hidden_dim: int = 256dynamic_multimask_via_stability: bool = Truedynamic_multimask_stability_delta: float = 0.05dynamic_multimask_stability_thresh: float = 0.98 )
参数
- hidden_size (
int，可选，默认为256) — 隐藏表示的维度。 - hidden_act (
str，可选，默认为gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu"等。 - mlp_dim (
int，可选，默认为 2048) — 双向 transformer 中 MLP 的维度。 - num_hidden_layers (
int，可选，默认为2) — Transformer 解码器中的隐藏层数。 - num_attention_heads (
int，可选，默认为8) — Transformer 解码器中每个注意力层的注意力头数量。 - attention_downsample_rate (
int，可选，默认为 2) — 注意力层的下采样率。 - num_multimask_outputs (
int，可选，默认为 3) — 多掩码输出的数量。 - iou_head_depth (
int, 可选，默认为 3) — IoU 头的深度。 - iou_head_hidden_dim (
int, 可选，默认为 256) — IoU 头的隐藏维度。 - dynamic_multimask_via_stability (
bool，可选，默认为True) — 是否通过稳定性使用动态多掩码。 - dynamic_multimask_stability_delta (
float，可选，默认值为 0.05) — 动态多掩码的稳定性增量。 - dynamic_multimask_stability_thresh (
float，可选，默认值为 0.98) — 动态多掩码的稳定性阈值。
这是用于存储 Sam2Model 配置的类。它根据指定的参数实例化 Sam2 模型，并定义模型架构。使用默认值实例化配置将生成与 facebook/sam2.1-hiera-tiny 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
Sam2PromptEncoderConfig
类 transformers.Sam2PromptEncoderConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256image_size: int | list[int] | tuple[int, int] = 1024patch_size: int | list[int] | tuple[int, int] = 16mask_input_channels: int = 16num_point_embeddings: int = 4hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06scale: int = 1 )
参数
- hidden_size (
int，可选，默认为256) — 隐藏表示的维度。 - image_size (
Union[int, list[int], tuple[int, int]]，可选，默认为1024) — 每张图片的尺寸（分辨率）。 - patch_size (
Union[int, list[int], tuple[int, int]]，可选，默认为16) — 每个 patch 的大小（分辨率）。 - mask_input_channels (
int，可选，默认为 16) — 输入到MaskDecoder模块的通道数。 - num_point_embeddings (
int，可选，默认为 4) — 要使用的点嵌入数量。 - hidden_act (
str，可选，默认为gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu"等。 - layer_norm_eps (
float，可选，默认为1e-06) — 层归一化层所使用的 epsilon 值。 - scale (
float，可选，默认为 1) — 提示编码器的缩放因子。
这是用于存储 Sam2Model 配置的类。它根据指定的参数实例化 Sam2 模型，并定义模型架构。使用默认值实例化配置将生成与 facebook/sam2.1-hiera-tiny 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
Sam2Processor
class transformers.Sam2Processor
< source >( image_processortarget_size: int | None = Nonepoint_pad_value: int = -10**kwargs )
构造一个 Sam2Processor，将图像处理器封装为单一处理器。
Sam2Processor 提供了 Sam2ImageProcessor 的所有功能。有关更多信息，请参阅 ~Sam2ImageProcessor。
__call__
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonesegmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Noneinput_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = Noneinput_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = Noneinput_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = Noneoriginal_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None**kwargs ) → A BatchEncoding with the following fields
参数
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], 可选) — 要预处理的图像。期望输入单张图像或一批图像，其像素值范围为 0 到 255。如果传入的图像像素值在 0 到 1 之间，请设置do_rescale=False。 - segmentation_maps (
ImageInput，可选) — 要处理的分割图。 - input_points (
list[list[list[list[float]]]],torch.Tensor, 可选) — 要添加到坐标系中的点。 - input_labels (
list[list[list[int]]]、torch.Tensor、可选) — 点的标签。 - input_boxes (
list[list[list[float]]]、torch.Tensor、可选) — 要添加到帧中的边界框。 - original_sizes (
list[list[float]]、torch.Tensor、可选) — 图像的原始尺寸。 - return_tensors (
Union[str, ~utils.generic.TensorType], 可选) — 如果设置，将返回特定框架的张量。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 NumPynp.ndarray对象。
返回值
一个包含以下字段的 BatchEncoding
pixel_values(torch.Tensor)：处理后的图像。original_sizes(list[list[float]])：图像的原始尺寸。labels(torch.Tensor)：处理后的分割掩码（如果已提供）。input_points(torch.Tensor)：处理后的点。input_labels(torch.Tensor)：处理后的标签。input_boxes(torch.Tensor): 处理后的边界框。
post_process_masks
< source >( masksoriginal_sizesmask_threshold = 0.0binarize = Truemax_hole_area = 0.0max_sprinkle_area = 0.0apply_non_overlapping_constraints = False**kwargs ) → (torch.Tensor)
参数
- masks (
Union[List[torch.Tensor], List[np.ndarray]]) — 来自 mask_decoder 的批量掩码，格式为 (batch_size, num_channels, height, width)。 - original_sizes (
Union[torch.Tensor, List[Tuple[int,int]]]) — 每张图片在调整至模型预期输入形状之前的原始尺寸，格式为 (height, width)。 - mask_threshold (
float，可选，默认值为 0.0) — 用于二值化和后处理操作的阈值。 - binarize (
bool，可选，默认为True) — 是否将掩码二值化。 - max_hole_area (
float，可选，默认为 0.0) — 要填充的孔洞的最大面积。 - max_sprinkle_area (
float, 可选，默认为 0.0) — 用于填充的 sprinkle 的最大面积。 - apply_non_overlapping_constraints (
bool，可选，默认为False) — 是否对掩码应用非重叠约束。
返回值
(torch.Tensor)
格式为 batch_size, num_channels, height, width 的批量掩码，其中 (height, width) 由 original_size 指定。
移除填充并将掩码上采样至原始图像尺寸。
Sam2ImageProcessor
class transformers.Sam2ImageProcessor
< source >( **kwargs: *<class 'transformers.models.sam2.image_processing_sam2.Sam2ImageProcessorKwargs'> )
参数
- do_convert_rgb (
bool，kwargs，可选，默认为True) — 是否将图像转换为 RGB。 - do_resize (
bool，kwargs，可选，默认为True) — 是否调整图像大小。 - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs，默认为{'height' -- 1024, 'width': 1024})： 描述输入到模型的最大尺寸。 - default_to_square (
bool，kwargs，可选，默认为True) — 当 size 为 int 时，是否在调整大小时默认使用正方形图像。 - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 应用center_crop后输出图像的尺寸。 - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs，默认为2) — 如果调整图像大小，则使用的重采样滤波器。它可以是枚举PILImageResampling中的一个值。仅当do_resize设置为True时才会生效。 - do_rescale (
bool，kwargs，可选，默认为True) — 是否对图像进行重新缩放。 - rescale_factor (
float，kwargs，可选，默认为0.00392156862745098) — 当do_rescale设置为True时，用于对图像进行缩放的缩放因子。 - do_normalize (
bool，kwargs，可选，默认为True) — 是否对图像进行归一化。 - image_mean (
Union[float, list[float], tuple[float, ...]]，kwargs，可选，默认为[0.485, 0.456, 0.406]) — 用于归一化的图像均值。仅当do_normalize设置为True时生效。 - image_std (
Union[float, list[float], tuple[float, ...]]，kwargs，可选，默认为[0.229, 0.224, 0.225]) — 用于归一化的图像标准差。仅当do_normalize设置为True时生效。 - do_pad (
bool，kwargs，可选，默认为None) — 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。 - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs，默认为None) — 用于将图像填充到的尺寸，格式为{"height": int, "width" int}。该尺寸必须大于预处理中提供的任何图像尺寸。如果未提供pad_size，图像将被填充到批次中最大的高度和宽度。仅在do_pad=True.时应用。 - do_center_crop (
bool，kwargs，可选) — 是否对图像进行中心裁剪。 - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 仅支持ChannelDimension.FIRST。为兼容旧版处理器而添加。 - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一："channels_first"或ChannelDimension.FIRST：图像采用 (num_channels, height, width) 格式。"channels_last"或ChannelDimension.LAST：图像采用 (height, width, num_channels) 格式。"none"或ChannelDimension.NONE：图像为 (height, width) 格式。
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — 用于处理视频的设备。如果未设置，则从输入视频中推断设备。 - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 如果设置为'pt'，则返回堆叠的张量，否则返回张量列表。 - disable_grouping (
bool，kwargs，可选) — 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。 如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157 - image_seq_length (
int，kwargs，可选) — 输入中每张图片所使用的图像 token 数量。 为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。 - mask_size (
dict[str, *kwargs*, int], 可选) — 用于将分割图调整大小的尺寸{"height": int, "width": int}。
构建 Sam2ImageProcessor 图像处理器。
预处理
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]segmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.models.sam2.image_processing_sam2.Sam2ImageProcessorKwargs'> ) → ~image_processing_base.BatchFeature
参数
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — 要预处理的图像。期望输入单张图像或一批图像，其像素值范围为 0 到 255。如果传入的图像像素值在 0 到 1 之间，请设置do_rescale=False。 - segmentation_maps (
ImageInput，可选) — 要预处理的分割图。 - do_convert_rgb (
bool，kwargs，可选) — 是否将图像转换为 RGB。 - do_resize (
bool，kwargs，可选) — 是否调整图像大小。 - size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 描述模型的最大输入维度。 - default_to_square (
bool, kwargs, 可选) — 当 size 为整数时，是否在调整大小时默认使用正方形图像。 - crop_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 应用center_crop后输出图像的尺寸。 - resample (
Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 如果调整图像大小，则使用的重采样滤波器。可以是枚举PILImageResampling中的一个值。仅当do_resize设置为True时生效。 - do_rescale (
bool，kwargs，可选) — 是否对图像进行重新缩放。 - rescale_factor (
float, kwargs, 可选) — 如果do_rescale设置为True，则用于对图像进行缩放的缩放因子。 - do_normalize (
bool，kwargs，可选) — 是否对图像进行归一化。 - image_mean (
Union[float, list[float], tuple[float, ...]], kwargs, 可选) — 用于归一化的图像均值。仅当do_normalize设置为True时生效。 - image_std (
Union[float, list[float], tuple[float, ...]], kwargs, 可选) — 用于归一化的图像标准差。仅当do_normalize设置为True时生效。 - do_pad (
bool, kwargs, 可选) — 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。 - pad_size (
Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 用于填充图像的{"height": int, "width" int}尺寸。必须大于为预处理提供的任何图像尺寸。如果未提供pad_size，图像将被填充到批次中最大的高度和宽度。仅在do_pad=True.时应用。 - do_center_crop (
bool，kwargs，可选) — 是否对图像进行中心裁剪。 - data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 仅支持ChannelDimension.FIRST。为兼容旧版处理器而添加。 - input_data_format (
Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一："channels_first"或ChannelDimension.FIRST：图像采用 (num_channels, height, width) 格式。"channels_last"或ChannelDimension.LAST：图像采用 (height, width, num_channels) 格式。"none"或ChannelDimension.NONE：图像为 (height, width) 格式。
- device (
Annotated[Union[str, torch.device, NoneType], None], kwargs) — 用于处理视频的设备。如果未设置，则从输入视频中推断设备。 - return_tensors (
Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 如果设置为'pt'，则返回堆叠的张量，否则返回张量列表。 - disable_grouping (
bool，kwargs，可选) — 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。 如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157 - image_seq_length (
int，kwargs，可选) — 输入中每张图片所使用的图像 token 数量。 为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。 - mask_size (
dict[str, *kwargs*, int], 可选) — 用于将分割图调整大小的尺寸{"height": int, "width": int}。
返回值
~image_processing_base.BatchFeature
- data (
dict) — 由 call 方法返回的列表/数组/张量字典（如 ‘pixel_values’ 等）。 - tensor_type (
Union[None, str, TensorType], 可选) — 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。
Sam2HieraDetModel
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )
Sam2VisionModel
class transformers.Sam2VisionModel
< source >( config: Sam2VisionConfig )
参数
- config (Sam2VisionConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
Sam 的视觉模型，顶部未添加任何头部或投影层。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )
Sam2Model
class transformers.Sam2Model
< source >( config: Sam2Config )
参数
- config (Sam2Config) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
Segment Anything Model 2 (SAM 2) 用于根据输入图像以及输入的点及标签、边界框或掩码来生成分割掩码。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Noneinput_points: typing.Optional[torch.Tensor] = Noneinput_labels: typing.Optional[torch.LongTensor] = Noneinput_boxes: typing.Optional[torch.Tensor] = Noneinput_masks: typing.Optional[torch.LongTensor] = Noneimage_embeddings: typing.Optional[torch.Tensor] = Nonemultimask_output: bool = Trueattention_similarity: typing.Optional[torch.Tensor] = Nonetarget_embedding: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam2ImageSegmentationOutput or tuple(torch.Tensor)
参数
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)，可选) — 与输入图像对应的张量。可以使用 Sam2ImageProcessor 获取像素值。有关详细信息，请参阅 Sam2ImageProcessor.call()（Sam2Processor 使用 Sam2ImageProcessor 来处理图像）。 - input_points (
torch.Tensor，形状为(batch_size, num_points, 2)) — 输入的二维空间点，提示编码器使用它来编码提示。通常能带来好得多的结果。可以通过向处理器传入列表的列表的列表来获取这些点，处理器将创建维度为 4 的相应torch张量。第一个维度是图像批次大小，第二个维度是点批次大小（即对于每个输入点，我们希望模型预测多少个分割掩码），第三个维度是每个分割掩码对应的点数（可以为单个掩码传入多个点），最后一个维度是点的 x（垂直）和 y（水平）坐标。如果为每张图像或每个掩码传入的点数不同，处理器将创建“PAD”点，这些点对应 (0, 0) 坐标，并且使用标签跳过对这些点的嵌入计算。 - input_labels (
torch.LongTensor形状为(batch_size, point_batch_size, num_points)) — 点的输入标签，用于提示编码器对提示进行编码。根据官方实现，共有 3 种标签类型1：该点是一个包含目标对象的点0：该点不包含目标对象-1：该点对应背景
我们添加了标签：
-10：该点为填充点，因此应被 prompt encoder 忽略
填充标签应由处理器自动完成。
- input_boxes (
torch.Tensor形状为(batch_size, num_boxes, 4)) — 用于点的输入框，提示编码器会用它来编码提示。通常能生成质量更好的掩码。可以通过向处理器传入列表的列表来获取这些框，这将生成一个torch张量，其各维度分别对应图像批次大小、每张图像的框数以及框的左上角和右下角点的坐标。顺序为 (x1,y1,x2,y2):x1：输入框左上角点的 x 坐标y1：输入框左上角点的 y 坐标x2：输入框右下角点的 x 坐标y2：输入框右下角点的 y 坐标
- input_masks（形状为
(batch_size, image_size, image_size)的torch.Tensor） — SAM 模型也接受分割掩码作为输入。掩码将由提示编码器嵌入，以生成相应的嵌入，随后输入到掩码解码器中。这些掩码需要由用户手动提供，且其形状必须为 (batch_size,image_size,image_size)。 - image_embeddings (
torch.Tensor，形状为(batch_size, output_channels, window_size, window_size)) — 图像嵌入，供掩码解码器生成掩码和 iou 分数。为了更节省内存，用户可以先使用get_image_embeddings方法获取图像嵌入，然后将它们传入forward方法，而不是传入pixel_values。 - multimask_output (
bool, 可选) — 在原始实现和论文中，模型始终为每张图像输出 3 个掩码（如果相关，则为每个点或每个边界框输出 3 个掩码）。不过，可以通过指定multimask_output=False来仅输出单个掩码，该掩码对应于“最佳”掩码。 - attention_similarity (
torch.Tensor, 可选) — 注意力相似度张量，当模型用于如 PerSAM 中所述的个性化时，需将其提供给掩码解码器以实现目标引导的注意力。 - target_embedding (
torch.Tensor, 可选) — 目标概念的嵌入，当模型用于 PerSAM 中介绍的个人化时，需将其提供给掩码解码器以进行目标语义提示。
返回值
Sam2ImageSegmentationOutput 或 tuple(torch.Tensor)
Sam2ImageSegmentationOutput 或 torch.Tensor 元组（如果传入 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（Sam2Config）和输入。
Sam2Model 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
- iou_scores（形状为
(batch_size, point_batch_size, num_masks)的torch.Tensor）— 预测掩码的交并比（IoU）分数。 - pred_masks（形状为
(batch_size, point_batch_size, num_masks, height, width)的torch.Tensor）— 预测的低分辨率掩码。这是low_res_masks的别名。这些掩码需要经过处理器进行后处理，才能调整到原始图像尺寸。 - object_score_logits（形状为
(batch_size, point_batch_size, 1)的torch.Tensor）— 对象得分的 logits，指示是否存在对象。 - image_embeddings (
tuple(torch.Tensor)) — 来自 FPN 的特征，供 mask decoder 使用。这是一个torch.Tensor元组，其中每个张量的形状为(batch_size, channels, height, width)。 - vision_hidden_states (
tuple(torch.Tensor)，可选，当output_hidden_states=True时返回) — 一个torch.Tensor元组（每个阶段一个输出），形状为(batch_size, height, width, hidden_size)。 视觉模型在每个阶段输出处的隐藏状态。 - vision_attentions (
tuple(torch.Tensor)，可选，当output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。 视觉模型的注意力权重。 - mask_decoder_attentions (
tuple(torch.Tensor)，可选，当output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。 掩码解码器的注意力权重。
示例：
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoModel, AutoProcessor
>>> model = AutoModel.from_pretrained("danelcsb/sam2.1_hiera_tiny")
>>> processor = AutoProcessor.from_pretrained("danelcsb/sam2.1_hiera_tiny")
>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
... raw_image = Image.open(BytesIO(response.read())).convert("RGB")
>>> input_points = [[[400, 650]]] # 2D location of a window on the car
>>> inputs = processor(images=raw_image, input_points=input_points, return_tensors="pt")
>>> # Get segmentation mask
>>> outputs = model(**inputs)
>>> # Postprocess masks
>>> masks = processor.post_process_masks(
... outputs.pred_masks, inputs["original_sizes"]
... )get_image_features
< source >( pixel_values: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam2VisionEncoderOutput or tuple(torch.Tensor)
参数
返回值
Sam2VisionEncoderOutput 或 tuple(torch.Tensor)
Sam2VisionEncoderOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（Sam2Config）和输入。
last_hidden_state（形状为
(batch_size, height, width, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
fpn_hidden_states (
tuple(torch.Tensor)) — 一个torch.Tensor元组（每个特征层一个，从高分辨率到低分辨率），形状为(batch_size, hidden_size, height, width)。来自特征金字塔网络（Feature Pyramid Network）颈部的特征图。fpn_position_encoding (
tuple(torch.Tensor)) —torch.Tensor的元组（每个特征层一个，从高分辨率到低分辨率），形状为(batch_size, hidden_size, height, width)。与fpn_hidden_states对应的位置编码。