# SAM-HQ

## Обзор

SAM-HQ (High-Quality Segment Anything Model) был предложен в статье [Segment Anything in High Quality](https://huggingface.co/papers/2306.01567) авторами Lei Ke, Mingqiao Ye, Martin Danelljan, Yifan Liu, Yu-Wing Tai, Chi-Keung Tang, Fisher Yu.

Модель представляет собой улучшение оригинальной модели SAM, обеспечивающее значительно более высокое качество сегментационных масок при сохранении исходного проектируемого по запросу (promptable) дизайна, эффективности и способности к обобщению в режиме zero-shot.

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

SAM-HQ вносит несколько ключевых улучшений по сравнению с исходной моделью SAM:

1. Токен высокого качества: обучаемый токен, внедряемый в декодер масок SAM для повышения качества предсказания масок
2. Слияние глобальных и локальных признаков: объединяет признаки из разных этапов модели для улучшения деталей маски
3. Данные для обучения: используется тщательно отобранный набор из 44K высококачественных масок вместо SA-1B
4. Эффективность: добавляет лишь 0,5% дополнительных параметров, значительно улучшая качество маски
5. Возможность zero-shot: сохраняет высокую производительность SAM в режиме zero-shot, одновременно повышая точность

Аннотация из статьи следующая:

*Недавно представленная модель Segment Anything Model (SAM) представляет собой значительный шаг в масштабировании моделей сегментации, обеспечивая мощные возможности zero-shot и гибкое управление через промпты. Несмотря на обучение с использованием 1,1 миллиарда масок, качество предсказания масок SAM во многих случаях оставляет желать лучшего, особенно при работе с объектами, имеющими сложную структуру. Мы предлагаем HQ-SAM, который наделяет SAM способностью точно сегментировать любой объект, сохраняя при этом исходный дизайн SAM с возможностью управления промптами, его эффективность и способность к обобщению в режиме zero-shot. Наша тщательная разработка позволяет повторно использовать и сохранять веса предобученной модели SAM, вводя лишь минимальное количество дополнительных параметров и вычислений. Мы спроектировали обучаемый токен High-Quality Output Token, который внедряется в декодер масок SAM и отвечает за предсказание маски высокого качества. Вместо применения только к признакам декодера масок, мы сначала объединяем их с ранними и финальными признаками ViT для улучшения деталей маски. Для обучения введённых нами обучаемых параметров мы составили набор данных из 44K детализированных масок из нескольких источников. HQ-SAM обучается только на введённом наборе данных из 44k масок, что занимает всего 4 часа на 8 GPU.*

Советы:

- SAM-HQ формирует маски более высокого качества, чем исходная модель SAM, особенно для объектов со сложной структурой и мелкими деталями
- Модель предсказывает бинарные маски с более точными границами и лучшим обработкой тонких структур
- Как и SAM, модель показывает лучшие результаты при использовании входных 2D-точек и/или входных ограничивающих прямоугольников
- Вы можете указать несколько точек для одного изображения и получить одну высококачественную маску
- Модель сохраняет возможности SAM для обобщения в режиме zero-shot
- SAM-HQ добавляет лишь ~0,5% дополнительных параметров по сравнению с SAM
- Настройка модели пока не поддерживается

Эта модель была добавлена пользователем [sushmanth](https://huggingface.co/sushmanth). Исходный код можно найти [здесь](https://github.com/SysCV/SAM-HQ).

Ниже приведен пример того, как запустить генерацию маски, имея изображение и 2D-точку:

```python
import requests
import torch
from PIL import Image

from transformers import SamHQModel, SamHQProcessor

model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores
```

Вы также можете обрабатывать собственные маски вместе с входными изображениями в процессоре, чтобы передать их в модель:

```python
import requests
import torch
from PIL import Image

from transformers import SamHQModel, SamHQProcessor

model = SamHQModel.from_pretrained("syscv-community/sam-hq-vit-base", device_map="auto")
processor = SamHQProcessor.from_pretrained("syscv-community/sam-hq-vit-base")

img_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
raw_image = Image.open(requests.get(img_url, stream=True).raw).convert("RGB")
mask_url = "https://huggingface.co/ybelkada/segment-anything/resolve/main/assets/car.png"
segmentation_map = Image.open(requests.get(mask_url, stream=True).raw).convert("1")
input_points = [[[450, 600]]]  # 2D location of a window in the image

inputs = processor(raw_image, input_points=input_points, segmentation_maps=segmentation_map, return_tensors="pt").to(model.device)
with torch.no_grad():
    outputs = model(**inputs)

masks = processor.image_processor.post_process_masks(
    outputs.pred_masks.cpu(), inputs["original_sizes"].cpu(), inputs["reshaped_input_sizes"].cpu()
)
scores = outputs.iou_scores
```

## Ресурсы

Список официальных ресурсов Hugging Face и сообщества (отмечены значком 🌎), которые помогут вам начать работу с SAM-HQ:

- Демо-ноутбук по использованию модели (скоро)
- Реализация статьи и код: [Репозиторий SAM-HQ на GitHub](https://github.com/SysCV/SAM-HQ)

## SamHQConfig[[transformers.SamHQConfig]]

#### transformers.SamHQConfig[[transformers.SamHQConfig]]

```python
transformers.SamHQConfig(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, tie_word_embeddings: bool = True)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L155)

**Параметры:**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Объект конфигурации или словарь для визуального бэкбона.

prompt_encoder_config (Union[`dict`, `SamHQPromptEncoderConfig`], *optional*) : Словарь параметров конфигурации, используемых для инициализации [SamHQPromptEncoderConfig](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `SamHQMaskDecoderConfig`], *optional*) : Словарь параметров конфигурации, используемых для инициализации [SamHQMaskDecoderConfig](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQMaskDecoderConfig).

initializer_range (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

tie_word_embeddings (`bool`, *необязательный*, по умолчанию `True`) : Связывать ли веса эмбеддингов согласно отображению `tied_weights_keys` модели.

Это класс конфигурации для хранения настроек модели SamHQModel. Он используется для создания модели Sam Hq в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig).

## SamHQVisionConfig[[transformers.SamHQVisionConfig]]

#### transformers.SamHQVisionConfig[[transformers.SamHQVisionConfig]]

```python
transformers.SamHQVisionConfig(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 = 768, output_channels: int = 256, num_hidden_layers: int = 12, num_attention_heads: int = 12, num_channels: int = 3, image_size: int | list[int] | tuple[int, int] = 1024, patch_size: int | list[int] | tuple[int, int] = 16, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, attention_dropout: float | int = 0.0, initializer_range: float = 1e-10, qkv_bias: bool = True, mlp_ratio: float = 4.0, use_abs_pos: bool = True, use_rel_pos: bool = True, window_size: int = 14, global_attn_indexes: list[int] | tuple[int, ...] = (2, 5, 8, 11), num_pos_feats: int = 128, mlp_dim: int | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L55)

**Параметры:**

hidden_size (`int`, *optional*, по умолчанию `768`) : Размерность скрытых представлений.

output_channels (`int`, *optional*, по умолчанию 256) : Размерность выходных каналов в Patch Encoder.

num_hidden_layers (`int`, *необязательный*, по умолчанию `12`) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (`int`, *необязательный*, по умолчанию `12`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

num_channels (`int`, *необязательный*, по умолчанию `3`) : Количество входных каналов.

image_size (`Union[int, list[int], tuple[int, int]]`, *необязательный*, по умолчанию `1024`) : Размер (разрешение) каждого изображения.

patch_size (`Union[int, list[int], tuple[int, int]]`, *необязательный*, по умолчанию `16`) : Размер (разрешение) каждого патча.

hidden_act (`str`, *необязательный*, по умолчанию `gelu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

layer_norm_eps (`float`, *необязательный*, по умолчанию `1e-06`) : Значение epsilon, используемое слоями нормализации.

attention_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент dropout для вероятностей внимания.

initializer_range (`float`, *optional*, по умолчанию `1e-10`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

qkv_bias (`bool`, *необязательный*, по умолчанию `True`) : Добавлять ли смещение (bias) к запросам, ключам и значениям.

mlp_ratio (`float`, *необязательный*, по умолчанию `4.0`) : Соотношение скрытого размера MLP к размеру эмбеддинга.

use_abs_pos (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли абсолютные позиционные эмбеддинги.

use_rel_pos (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли встраивание относительных позиций.

window_size (`int`, *optional*, по умолчанию 14) : Размер окна для относительного положения.

global_attn_indexes (`list[int]`, *необязательный*, по умолчанию `[2, 5, 8, 11]`) : Индексы глобальных слоев внимания.

num_pos_feats (`int`, *optional*, по умолчанию 128) : Размерность позиционного эмбеддинга.

mlp_dim (`int`, *optional*) : Размерность слоя MLP в кодере Transformer. Если `None`, по умолчанию используется `mlp_ratio * hidden_size`.

Это класс конфигурации для хранения настроек модели SamHQModel. Он используется для создания модели Sam Hq в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig).

Пример:

```python
>>> from transformers import (
...     SamHQVisionConfig,
...     SamHQVisionModel,
... )

>>> # Initializing a SamHQVisionConfig with `"facebook/sam_hq-vit-huge"` style configuration
>>> configuration = SamHQVisionConfig()

>>> # Initializing a SamHQVisionModel (with random weights) from the `"facebook/sam_hq-vit-huge"` style configuration
>>> model = SamHQVisionModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## SamHQMaskDecoderConfig[[transformers.SamHQMaskDecoderConfig]]

#### transformers.SamHQMaskDecoderConfig[[transformers.SamHQMaskDecoderConfig]]

```python
transformers.SamHQMaskDecoderConfig(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 = 'relu', 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, layer_norm_eps: float = 1e-06, vit_dim: int = 768)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L120)

**Параметры:**

hidden_size (`int`, *optional*, по умолчанию `256`) : Размерность скрытых представлений.

hidden_act (`str`, *необязательный*, по умолчанию `relu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

mlp_dim (`int`, *optional*, по умолчанию 2048) : Размерность «промежуточного» (т.е. полносвязного) слоя в кодере Transformer.

num_hidden_layers (`int`, *необязательный*, по умолчанию `2`) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (`int`, *необязательный*, по умолчанию `8`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

attention_downsample_rate (`int`, *optional*, по умолчанию 2) : Коэффициент понижающей дискретизации слоя внимания.

num_multimask_outputs (`int`, *optional*, по умолчанию 3) : Количество выходов модуля `SamMaskDecoder`. В статье Segment Anything это значение установлено в 3.

iou_head_depth (`int`, *optional*, по умолчанию 3) : Количество слоёв в модуле IoU head.

iou_head_hidden_dim (`int`, *optional*, по умолчанию 256) : Размерность скрытых состояний в модуле IoU head.

layer_norm_eps (`float`, *необязательный*, по умолчанию `1e-06`) : Значение epsilon, используемое слоями нормализации.

vit_dim (`int`, *optional*, по умолчанию 768) : Размерность Vision Transformer (ViT), используемого в модуле `SamHQMaskDecoder`.

Это класс конфигурации для хранения настроек модели SamHQModel. Он используется для создания модели Sam Hq в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig).

## SamHQPromptEncoderConfig[[transformers.SamHQPromptEncoderConfig]]

#### transformers.SamHQPromptEncoderConfig[[transformers.SamHQPromptEncoderConfig]]

```python
transformers.SamHQPromptEncoderConfig(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)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/configuration_sam_hq.py#L29)

**Параметры:**

hidden_size (`int`, *optional*, по умолчанию `256`) : Размерность скрытых представлений.

image_size (`Union[int, list[int], tuple[int, int]]`, *необязательный*, по умолчанию `1024`) : Размер (разрешение) каждого изображения.

patch_size (`Union[int, list[int], tuple[int, int]]`, *необязательный*, по умолчанию `16`) : Размер (разрешение) каждого патча.

mask_input_channels (`int`, *необязательный*, по умолчанию 16) : Количество каналов, передаваемых в модуль `MaskDecoder`.

num_point_embeddings (`int`, *optional*, по умолчанию 4) : Количество используемых встраиваний точек.

hidden_act (`str`, *необязательный*, по умолчанию `gelu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

layer_norm_eps (`float`, *необязательный*, по умолчанию `1e-06`) : Значение epsilon, используемое слоями нормализации.

Это класс конфигурации для хранения настроек модели SamHQModel. Он используется для создания модели Sam Hq в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [syscv-community/sam-hq-vit-base](https://huggingface.co/syscv-community/sam-hq-vit-base)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/main/ru/main_classes/configuration#transformers.PreTrainedConfig).

## SamHQProcessor[[transformers.SamHQProcessor]]

#### transformers.SamHQProcessor[[transformers.SamHQProcessor]]

```python
transformers.SamHQProcessor(image_processor)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/processing_sam_hq.py#L83)

**Параметры:**

image_processor (`SamImageProcessor`) : процессор изображений является обязательным входным параметром.

Создаёт SamHQProcessor, который объединяет процессор изображений в единый процессор.

[SamHQProcessor](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQProcessor) предоставляет все возможности [SamImageProcessor](/docs/transformers/main/ru/model_doc/sam#transformers.SamImageProcessor). Подробнее см. в [~SamImageProcessor](/docs/transformers/main/ru/model_doc/sam#transformers.SamImageProcessor).

#### __call__[[transformers.SamHQProcessor.__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, **kwargs: *<class 'transformers.models.sam_hq.processing_sam_hq.SamHQProcessorKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/processing_sam_hq.py#L93)

**Параметры:**

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`, *kwargs*, *optional*) : Карты сегментации эталонных данных для обработки вместе с входными изображениями. Эти карты используются для обучения или оценки и масштабируются и нормализуются так, чтобы соответствовать размерам обработанного изображения.

input_points (`NestedList`, *kwargs*, *optional*) : Точки ввода для сегментации на основе промпта. Должно быть вложенным списком со структурой `[image_level, object_level, point_level, [x, y]]`, где каждая точка задается координатами `[x, y]` в пространстве исходного изображения. Точки нормализуются до целевого размера изображения перед передачей в модель.

input_labels (`NestedList`, *kwargs*, *optional*) : Метки для входных точек, указывающие, является ли каждая точка точкой переднего плана (1) или фона (0). Должна быть вложенным списком со структурой `[image_level, object_level, point_level]`. Должна иметь ту же структуру, что и `input_points` (за исключением размерности координат).

input_boxes (`NestedList`, *kwargs*, *optional*) : Ограничивающие рамки для сегментации на основе подсказок. Должно быть вложенным списком со структурой `[image_level, box_level, [x1, y1, x2, y2]]`, где каждая рамка задается координатами `[x1, y1, x2, y2]` в пространстве исходного изображения. Рамки нормализуются до размера целевого изображения перед передачей в модель.

point_pad_value (`int`, *kwargs*, *optional*, по умолчанию `None`) : Значение, используемое для дополнения входных точек при пакетной обработке последовательностей разной длины. Это значение помечает позиции дополнения и сохраняется при нормализации координат, чтобы отличать реальные точки от дополнения. Если `None`, используется значение дополнения по умолчанию из конфигурации процессора.

mask_size (`dict[str, *kwargs*, int]`, *необязательный*) : Словарь, задающий размер целевой маски с ключами `"height"` и `"width"`. Определяет разрешение сегментационных масок, генерируемых моделью.

mask_pad_size (`dict[str, *kwargs*, int]`, *необязательный*) : Словарь, задающий размер отступов для масок с ключами `"height"` и `"width"`. Используется при пакетной обработке масок разного размера для обеспечения единообразия размеров.

return_tensors (`str` или [TensorType](/docs/transformers/main/ru/internal/file_utils#transformers.TensorType), *optional*) : Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:  - `'pt'`: возвращает объекты `torch.Tensor` PyTorch. - `'np'`: возвращает объекты `np.ndarray` NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/ru/main_classes/processors#transformers.ProcessingKwargs), *optional*) : Дополнительные параметры обработки для каждой модальности (текст, изображения, видео, аудио). Специфичные для модели параметры перечислены выше; полный список поддерживаемых аргументов см. в классе TypedDict.

**Возвращает:** `~feature_extraction_utils.BatchFeature`

- **data** (`dict`, *необязательный*) -- Словарь списков/массивов/тензоров, возвращаемый методами __call__/pad ('input_values', 'attention_mask' и т. д.).
- **tensor_type** (`Union[None, str, TensorType]`, *необязательный*) -- Здесь можно указать tensor_type, чтобы при инициализации преобразовать списки целых чисел в тензоры PyTorch/Numpy.
- **skip_tensor_conversion** (`list[str]` или `set[str]`, *необязательный*) -- Список или множество ключей, которые НЕ следует преобразовывать в тензоры, даже если указан `tensor_type`.

## SamHQVisionModel[[transformers.SamHQVisionModel]]

#### transformers.SamHQVisionModel[[transformers.SamHQVisionModel]]

```python
transformers.SamHQVisionModel(config: SamHQVisionConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1076)

**Параметры:**

config ([SamHQVisionConfig](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQVisionConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель зрения из SamHQ без какой-либо головы или проекции сверху.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.SamHQVisionModel.forward]]

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

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1088)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`, *необязательно*) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [SamImageProcessor](/docs/transformers/main/ru/model_doc/sam#transformers.SamImageProcessor). Подробности см. в [SamImageProcessor.__call__()](/docs/transformers/main/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) ([SamHQProcessor](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQProcessor) использует [SamImageProcessor](/docs/transformers/main/ru/model_doc/sam#transformers.SamImageProcessor) для обработки изображений).

**Возвращает:** `SamHQVisionEncoderOutput` или `tuple(torch.Tensor)`

Объект `SamHQVisionEncoderOutput` или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([SamHQConfig](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQConfig)) и входных данных.

Метод forward модели [SamHQVisionModel](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQVisionModel) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **image_embeds** (`torch.Tensor` формы `(batch_size, output_dim)` *необязательный*, возвращается при инициализации модели с `with_projection=True`) -- Векторы изображений, полученные применением слоя проекции к pooler_output.
- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **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 в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **intermediate_embeddings** (`list(torch.Tensor)`, *необязательный*) -- Список промежуточных эмбеддингов, собранных из определённых блоков модели, как правило, тех, что не используют оконное внимание. Каждый элемент списка имеет форму `(batch_size, sequence_length, hidden_size)`. Это специфично для SAM-HQ и отсутствует в базовой версии SAM.

## SamHQModel[[transformers.SamHQModel]]

#### transformers.SamHQModel[[transformers.SamHQModel]]

```python
transformers.SamHQModel(config: SamHQConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1234)

**Параметры:**

config ([SamHQConfig](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Segment Anything Model HQ (SAM-HQ) для генерации масок по входному изображению и необязательным 2D-координатам и ограничивающим рамкам.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.SamHQModel.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, hq_token_only: bool = False, attention_similarity: typing.Optional[torch.Tensor] = None, target_embedding: typing.Optional[torch.Tensor] = None, intermediate_embeddings: list[torch.Tensor] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam_hq/modeling_sam_hq.py#L1318)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`, *необязательно*) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [SamImageProcessor](/docs/transformers/main/ru/model_doc/sam#transformers.SamImageProcessor). Подробности см. в [SamImageProcessor.__call__()](/docs/transformers/main/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) ([SamHQProcessor](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQProcessor) использует [SamImageProcessor](/docs/transformers/main/ru/model_doc/sam#transformers.SamImageProcessor) для обработки изображений).

input_points (`torch.Tensor` формы `(batch_size, num_points, 2)`) : Входные 2D пространственные точки, которые используются кодировщиком промпта для кодирования промпта. Как правило, это даёт значительно лучшие результаты. Точки можно получить, передав в процессор список списков списков, который создаст соответствующие тензоры `torch` размерности 4. Первая размерность — размер батча изображений, вторая — размер батча точек (то есть сколько сегментационных масок модель должна предсказать на каждую входную точку), третья — количество точек на сегментационную маску (можно передать несколько точек для одной маски), а последняя — координаты x (вертикальная) и y (горизонтальная) точки. Если для каждого изображения или для каждой маски передано разное количество точек, процессор создаст точки «PAD», соответствующие координате (0, 0), и вычисление эмбеддинга для этих точек будет пропущено с помощью меток.

input_labels (`torch.LongTensor` формы `(batch_size, point_batch_size, num_points)`) : Входные метки для точек, используются кодировщиком промпта для кодирования промпта. Согласно официальному реализованию, существует 3 типа меток  - `1`: точка содержит объект интереса - `0`: точка не содержит объект интереса - `-1`: точка соответствует фону  Мы добавили метку:  - `-10`: точка является заполнителем (padding), поэтому должна игнорироваться кодировщиком промпта  Метки заполнения должны назначаться автоматически процессором.

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_HQ также принимает в качестве входных данных маски сегментации. Маска будет закодирована prompt encoder для генерации соответствующего embedding, который затем будет передан в mask decoder. Эти маски необходимо вручную передавать пользователем, и они должны иметь форму (`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 маски на изображение (или на точку / на ограничивающий прямоугольник, если это применимо). Однако можно вывести только одну маску, соответствующую «лучшей» маске, указав `multimask_output=False`.

hq_token_only (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли только путь HQ-токенов для генерации маски. Если False, комбинируются стандартный и HQ-пути. Это специфично для архитектуры SAM-HQ.

attention_similarity (`torch.Tensor`, *необязательный*) : тензор сходства внимания, который передается декодеру маски для целевого управления вниманием в случае, если модель используется для персонализации, как описано в [PerSAM](https://huggingface.co/papers/2305.03048).

target_embedding (`torch.Tensor`, *необязательный*) : Вложение целевого концепта, которое передается декодеру маски для семантического промптинга цели, если модель используется для персонализации, как описано в [PerSAM](https://huggingface.co/papers/2305.03048).

intermediate_embeddings (`List[torch.Tensor]`, *необязательный*) : Промежуточные эмбеддинги из блоков без окон визуального энкодера, используемые SAM-HQ для повышения качества масок. Обязателен при передаче предварительно вычисленных image_embeddings вместо pixel_values.

**Возвращаемое значение:**

`list[dict[str, torch.Tensor]]`

Метод forward модели [SamHQModel](/docs/transformers/main/ru/model_doc/sam_hq#transformers.SamHQModel) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

Пример:

```python
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoModel, AutoProcessor

>>> model = AutoModel.from_pretrained("sushmanth/sam_hq_vit_b")
>>> processor = AutoProcessor.from_pretrained("sushmanth/sam_hq_vit_b")

>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")
>>> input_points = [[[400, 650]]]  # 2D location of a window on the car
>>> inputs = processor(images=image, input_points=input_points, return_tensors="pt")

>>> # Get high-quality segmentation mask
>>> outputs = model(**inputs)

>>> # For high-quality mask only
>>> outputs = model(**inputs, hq_token_only=True)

>>> # Postprocess masks
>>> masks = processor.post_process_masks(
...     outputs.pred_masks, inputs["original_sizes"], inputs["reshaped_input_sizes"]
... )
```