# 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](https://ai.meta.com/research/publications/sam-2-segment-anything-in-images-and-videos/) 中提出。

给定输入图像或视频以及输入点或边界框，该模型可用于预测任意感兴趣对象的分割掩码。

![example image](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam2_header.gif)

该论文的摘要如下：

*我们提出了 Segment Anything Model 2（SAM 2），这是一个旨在解决图像和视频中的可提示视觉分割问题的基础模型。我们构建了一个数据引擎，通过用户交互来改进模型和数据，从而收集了迄今为止规模最大的视频分割数据集。我们的模型采用了一种简单的 Transformer 架构，并配备了用于实时视频处理的流式内存。在我们数据上训练的 SAM 2 在广泛的任务中均表现出强劲的性能。在视频分割方面，我们观察到其精度更高，且所需的交互次数比先前方法减少了 3 倍。在图像分割方面，我们的模型比 Segment Anything Model（SAM）更准确，速度快 6 倍。我们相信，我们的数据、模型和见解将成为视频分割及相关感知任务的重要里程碑。我们将发布我们模型的版本、数据集以及一个交互式演示。*

提示：

- 批量与视频支持：SAM2 原生支持批量处理和无缝视频分割，而原始 SAM 专为静态图像和更简单的单张图像处理工作流而设计。
- 准确性与泛化能力：与原始 SAM 相比，SAM2 在分割质量、鲁棒性以及针对新领域的零样本泛化能力方面均有提升，尤其是在使用混合提示时。

该模型由 [sangbumchoi](https://github.com/SangbumChoi) 和 [yonigozlan](https://huggingface.co/yonigozlan) 贡献。原始代码可在[此处](https://github.com/facebookresearch/sam2/tree/main)找到。

## 使用示例

### 使用 Pipeline 自动生成掩码

SAM2 可用于自动掩码生成，通过 `mask-generation` 流水线对图像中的所有对象进行分割：

```python
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
```

### 基础图像分割

#### 单击

你可以通过在想要分割的对象上单击一个点来分割对象：

```python
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)
```

#### 多个用于优化的点

您可以提供多个点来细化分割：

```python
# 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 还支持边界框输入用于分割：

```python
# 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]
```

#### 多目标分割

您可以同时分割多个对象：

```python
# 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
```

### 批量推理

#### 批量图像

同时处理多张图像以提高效率：

```python
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
```

#### 每张图像的批量对象

使用批量推理对每张图片中的多个对象进行分割：

```python
# 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"])
```

#### 批量图像与批量对象及多个点

处理每个对象包含多个点的复杂批次场景：

```python
# 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"])
```

#### 批量边界框

使用边界框输入处理多张图像：

```python
# 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 可以使用先前预测的掩码作为输入来优化分割：

```python
# 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[[transformers.Sam2Config]]

#### transformers.Sam2Config[[transformers.Sam2Config]]

```python
transformers.Sam2Config(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, prompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/configuration_sam2.py#L220)

**参数：**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：视觉骨干网络的配置对象或字典。

prompt_encoder_config (Union[`dict`, `Sam2PromptEncoderConfig`], *可选*) : 用于初始化 [Sam2PromptEncoderConfig](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2PromptEncoderConfig) 的配置选项字典。

mask_decoder_config (Union[`dict`, `Sam2MaskDecoderConfig`], *可选*) : 用于初始化 [Sam2MaskDecoderConfig](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2MaskDecoderConfig) 的配置选项字典。

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

这是用于存储 Sam2Model 配置的类。它根据指定的参数实例化 Sam2 模型，并定义模型架构。使用默认值实例化配置将生成与 [facebook/sam2.1-hiera-tiny](https://huggingface.co/facebook/sam2.1-hiera-tiny) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> 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[[transformers.Sam2HieraDetConfig]]

#### transformers.Sam2HieraDetConfig[[transformers.Sam2HieraDetConfig]]

```python
transformers.Sam2HieraDetConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 96, num_attention_heads: int = 1, num_channels: int = 3, image_size: int | list[int] | None = None, patch_kernel_size: int | list[int] | None = None, patch_stride: int | list[int] | None = None, patch_padding: int | list[int] | None = None, query_stride: int | list[int] | None = None, window_positional_embedding_background_size: list[int] | None = None, num_query_pool_stages: int = 3, blocks_per_stage: list[int] | None = None, embed_dim_per_stage: list[int] | None = None, num_attention_heads_per_stage: list[int] | None = None, window_size_per_stage: list[int] | None = None, global_attention_blocks: list[int] | None = None, mlp_ratio: float = 4.0, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, initializer_range: float = 0.02)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/configuration_sam2.py#L25)

**参数：**

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_stride (`list[int]`, *可选*, 默认为 `[4, 4]`) : 补丁的步长。

patch_padding (`list[int]`，*可选*，默认为 `[3, 3]`)：patch 的填充。

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](https://huggingface.co/facebook/sam2.1-hiera-tiny) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## Sam2VisionConfig[[transformers.Sam2VisionConfig]]

#### transformers.Sam2VisionConfig[[transformers.Sam2VisionConfig]]

```python
transformers.Sam2VisionConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, backbone_channel_list: list[int] | None = None, backbone_feature_sizes: list | None = None, fpn_hidden_size: int = 256, fpn_kernel_size: int = 1, fpn_stride: int = 1, fpn_padding: int = 0, fpn_top_down_levels: list[int] | None = None, num_feature_levels: int = 3, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, initializer_range: float = 0.02)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/configuration_sam2.py#L103)

**参数：**

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)：颈部中卷积的核大小。

fpn_stride (`int`，*可选*，默认为 1)：颈部中卷积的步幅。

fpn_padding (`int`，*可选*，默认为 0)：颈部中卷积的填充值。

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](https://huggingface.co/facebook/sam2.1-hiera-tiny) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## Sam2MaskDecoderConfig[[transformers.Sam2MaskDecoderConfig]]

#### transformers.Sam2MaskDecoderConfig[[transformers.Sam2MaskDecoderConfig]]

```python
transformers.Sam2MaskDecoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 256, hidden_act: str = 'gelu', mlp_dim: int = 2048, num_hidden_layers: int = 2, num_attention_heads: int = 8, attention_downsample_rate: int = 2, num_multimask_outputs: int = 3, iou_head_depth: int = 3, iou_head_hidden_dim: int = 256, dynamic_multimask_via_stability: bool = True, dynamic_multimask_stability_delta: float = 0.05, dynamic_multimask_stability_thresh: float = 0.98)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/configuration_sam2.py#L181)

**参数：**

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](https://huggingface.co/facebook/sam2.1-hiera-tiny) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## Sam2PromptEncoderConfig[[transformers.Sam2PromptEncoderConfig]]

#### transformers.Sam2PromptEncoderConfig[[transformers.Sam2PromptEncoderConfig]]

```python
transformers.Sam2PromptEncoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 256, image_size: int | list[int] | tuple[int, int] = 1024, patch_size: int | list[int] | tuple[int, int] = 16, mask_input_channels: int = 16, num_point_embeddings: int = 4, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, scale: int = 1)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/configuration_sam2.py#L156)

**参数：**

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](https://huggingface.co/facebook/sam2.1-hiera-tiny) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## Sam2Processor[[transformers.Sam2Processor]]

#### transformers.Sam2Processor[[transformers.Sam2Processor]]

```python
transformers.Sam2Processor(image_processor, target_size: int | None = None, point_pad_value: int = -10, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/processing_sam2.py#L37)

**参数：**

image_processor (`Sam2ImageProcessor`)：图像处理器是必需的输入。

target_size (`int`, *optional*) : 用于归一化输入点和边界框的目标尺寸（以像素为单位）。如果未提供，则默认使用图像处理器的大小配置。所有输入坐标（点和框）在传递给模型之前都会归一化到该尺寸。这确保了无论原始图像尺寸如何，坐标表示都保持一致。

point_pad_value (`int`, *可选*，默认为 -10) : 在对不同长度的序列进行批处理时，用于填充输入点的值。该值用于标记填充位置，并在坐标归一化过程中保留。

构造一个 Sam2Processor，将图像处理器封装为单一处理器。

[Sam2Processor](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2Processor) 提供了 [Sam2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2ImageProcessor) 的所有功能。有关更多信息，请参阅 [~Sam2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2ImageProcessor)。

#### __调用__[[transformers.Sam2Processor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, 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, input_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = None, input_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = None, input_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = None, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/processing_sam2.py#L53)

**参数：**

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'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

**返回：** 一个包含以下字段的 [BatchEncoding](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.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[[transformers.Sam2Processor.post_process_masks]]

```python
post_process_masks(masks, original_sizes, mask_threshold = 0.0, binarize = True, max_hole_area = 0.0, max_sprinkle_area = 0.0, apply_non_overlapping_constraints = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/processing_sam2.py#L459)

**参数：**

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)：用于填充的 sprinkles 的最大面积。

apply_non_overlapping_constraints (`bool`, *可选*, 默认为 `False`) : 是否对掩码应用非重叠约束。

**返回：** (`torch.Tensor`)

格式为 batch_size, num_channels, height, width 的批量掩码，其中 (height, width) 由 original_size 指定。

移除填充并将掩码上采样至原始图像尺寸。

## Sam2ImageProcessor[[transformers.Sam2ImageProcessor]]

#### transformers.Sam2ImageProcessor[[transformers.Sam2ImageProcessor]]

```python
transformers.Sam2ImageProcessor(**kwargs: *<class 'transformers.models.sam2.image_processing_sam2.Sam2ImageProcessorKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/image_processing_sam2.py#L369)

**参数：**

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 为整数时，是否在调整大小时默认使用正方形图像。

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 图像处理器。

#### preprocess[[transformers.Sam2ImageProcessor.preprocess]]

```python
preprocess(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'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/image_processing_sam2.py#L389)

**参数：**

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 为 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*) : 如果调整图像大小，则使用的重采样滤波器。它可以是枚举 `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[[transformers.Sam2HieraDetModel]]

#### transformers.Sam2HieraDetModel[[transformers.Sam2HieraDetModel]]

```python
transformers.Sam2HieraDetModel(config: Sam2HieraDetConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/modeling_sam2.py#L603)

#### forward[[transformers.Sam2HieraDetModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/modeling_sam2.py#L646)

## Sam2VisionModel[[transformers.Sam2VisionModel]]

#### transformers.Sam2VisionModel[[transformers.Sam2VisionModel]]

```python
transformers.Sam2VisionModel(config: Sam2VisionConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/modeling_sam2.py#L677)

**参数：**

config ([Sam2VisionConfig](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2VisionConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

Sam 的视觉模型，顶部未添加任何头部或投影层。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.Sam2VisionModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/modeling_sam2.py#L699)

## Sam2Model[[transformers.Sam2Model]]

#### transformers.Sam2Model[[transformers.Sam2Model]]

```python
transformers.Sam2Model(config: Sam2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/modeling_sam2.py#L1314)

**参数：**

config ([Sam2Config](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2Config))：模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

Segment Anything Model 2 (SAM 2) 用于生成分割掩码，给定输入图像以及输入点和标签、框或掩码。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.Sam2Model.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, input_points: typing.Optional[torch.Tensor] = None, input_labels: typing.Optional[torch.LongTensor] = None, input_boxes: typing.Optional[torch.Tensor] = None, input_masks: typing.Optional[torch.LongTensor] = None, image_embeddings: typing.Optional[torch.Tensor] = None, multimask_output: bool = True, attention_similarity: typing.Optional[torch.Tensor] = None, target_embedding: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/modeling_sam2.py#L1413)

**参数：**

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*)：与输入图像对应的张量。可以使用 [Sam2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2ImageProcessor) 获取像素值。有关详细信息，请参阅 [Sam2ImageProcessor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（[Sam2Processor](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2Processor) 使用 [Sam2ImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2ImageProcessor) 处理图像）。

input_points (`torch.Tensor`，形状为 `(batch_size, num_points, 2)`)：输入的二维空间点，供提示编码器（prompt encoder）用于编码提示。通常能带来显著更好的结果。可以通过向处理器传入列表的列表的列表来获取这些点，处理器将创建维度为 4 的相应 `torch` 张量。第一个维度是图像批次大小，第二个维度是点批次大小（即对于每个输入点，我们希望模型预测多少个分割掩码），第三个维度是每个分割掩码对应的点数（可以为单个掩码传入多个点），最后一个维度是点的 x（垂直）和 y（水平）坐标。如果为每张图像或每个掩码传入的点数不同，处理器将创建“PAD”点，这些点对应 (0, 0) 坐标，并且在使用标签时，将跳过对这些点的嵌入计算。

input_labels (`torch.LongTensor`，形状为 `(batch_size, point_batch_size, num_points)`)：点的输入标签，供提示编码器用于编码提示。根据官方实现，共有 3 种标签类型 - `1`：该点包含感兴趣的对象 - `0`：该点不包含感兴趣的对象 - `-1`：该点对应背景 我们添加了标签： - `-10`：该点为填充点，因此应被提示编码器忽略 填充标签应由处理器自动处理。

input_boxes (`torch.Tensor`，形状为 `(batch_size, num_boxes, 4)`)：用于点的输入框，提示编码器使用它来编码提示。通常能生成质量更好的掩码。可以通过向处理器传入列表的列表的列表来获取这些框，这将生成一个 `torch` 张量，其各维度分别对应图像批次大小、每张图像的框数量以及框左上角和右下角点的坐标。顺序为 (`x1`, `y1`, `x2`, `y2`)： - `x1`：输入框左上角点的 x 坐标 - `y1`：输入框左上角点的 y 坐标 - `x2`：输入框右下角点的 x 坐标 - `y2`：输入框右下角点的 y 坐标

input_masks (`torch.Tensor`，形状为 `(batch_size, image_size, image_size)`)：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](https://huggingface.co/papers/2305.03048) 中所述的个性化时，需将其提供给掩码解码器以实现目标引导的注意力。

target_embedding (`torch.Tensor`, *可选*) : 目标概念的嵌入，当模型用于个性化（如 [PerSAM](https://huggingface.co/papers/2305.03048) 中所述）时，需将其提供给掩码解码器以进行目标语义提示。

**返回：** `Sam2ImageSegmentationOutput` 或 `tuple(torch.Tensor)`

`Sam2ImageSegmentationOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Sam2Config](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2Config)）和输入。

[Sam2Model](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.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)`。掩码解码器的注意力权重。

示例：

```python
>>> 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[[transformers.Sam2Model.get_image_features]]

```python
get_image_features(pixel_values: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam2/modeling_sam2.py#L1589)

**参数：**

pixel_values (`torch.Tensor`) : 形状为 `(batch_size, num_channels, height, width)` 的输入像素值。

**返回：** `Sam2VisionEncoderOutput` 或 `tuple(torch.Tensor)`

`Sam2VisionEncoderOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Sam2Config](/docs/transformers/v5.23.0/zh/model_doc/sam2#transformers.Sam2Config)）和输入。

- **last_hidden_state**（形状为 `(batch_size, height, width, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **pooler_output**（形状为 `(batch_size, hidden_size)` 的 `torch.Tensor`）-- 序列中第一个 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` 对应的位置编码。

示例：

```python
```

