Transformers documentation
SAM-HQ
Эта модель была опубликована в HF papers 02.06.2023 и добавлена в Hugging Face Transformers 28.04.2025.
SAM-HQ
Обзор
SAM-HQ (High-Quality Segment Anything Model) был предложен в статье Segment Anything in High Quality авторами Lei Ke, Mingqiao Ye, Martin Danelljan, Yifan Liu, Yu-Wing Tai, Chi-Keung Tang, Fisher Yu.
Модель представляет собой улучшение исходной модели SAM, обеспечивающее значительно более высокое качество сегментационных масок при сохранении оригинального проектирования SAM с возможностью управления по запросу, эффективности и способности к обобщению без дообучения.
SAM-HQ вносит несколько ключевых улучшений по сравнению с исходной моделью SAM:
- Высокоточный выходной токен: обучаемый токен, внедряемый в декодер масок SAM для повышения качества предсказания масок
- Слияние глобальных и локальных признаков: объединяет признаки из разных этапов модели для улучшения деталей маски
- Данные для обучения: используется тщательно отобранный набор из 44K высококачественных масок вместо SA-1B
- Эффективность: добавляет лишь 0,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 для обобщения без предварительной настройки
- SAM-HQ добавляет лишь ~0,5% дополнительных параметров по сравнению с SAM
- Настройка модели пока не поддерживается
Эта модель была предоставлена пользователем sushmanth. Исходный код можно найти здесь.
Ниже приведен пример того, как запустить генерацию маски, имея изображение и 2D-точку:
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Вы также можете обрабатывать собственные маски вместе с входными изображениями в процессоре, чтобы передать их в модель:
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
SamHQConfig
класс transformers.SamHQConfig
< 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.02tie_word_embeddings: bool = True )
Параметры
- vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации визуального бэкбона. - prompt_encoder_config (Union[
dict,SamHQPromptEncoderConfig], необязательный) — Словарь с параметрами конфигурации, используемыми для инициализации SamHQPromptEncoderConfig. - mask_decoder_config (Union[
dict,SamHQMaskDecoderConfig], необязательный) — Словарь с параметрами конфигурации, используемыми для инициализации 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
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
SamHQVisionConfig
класс transformers.SamHQVisionConfig
< 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 = 768output_channels: int = 256num_hidden_layers: int = 12num_attention_heads: int = 12num_channels: int = 3image_size: int | list[int] | tuple[int, int] = 1024patch_size: int | list[int] | tuple[int, int] = 16hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06attention_dropout: float | int = 0.0initializer_range: float = 1e-10qkv_bias: bool = Truemlp_ratio: float = 4.0use_abs_pos: bool = Trueuse_rel_pos: bool = Truewindow_size: int = 14global_attn_indexes: list[int] | tuple[int, ...] = (2, 5, 8, 11)num_pos_feats: int = 128mlp_dim: int | None = None )
Параметры
- hidden_size (
int, необязательный, по умолчанию768) — Размерность скрытых представлений. - output_channels (
int, необязательный, по умолчанию 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, необязательный, по умолчанию1e-10) — Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов. - qkv_bias (
bool, необязательный, по умолчаниюTrue) — Добавлять ли смещение к запросам, ключам и значениям. - mlp_ratio (
float, необязательный, по умолчанию4.0) — Соотношение скрытого размера MLP к размеру эмбеддинга. - use_abs_pos (
bool, необязательный, по умолчаниюTrue) — Использовать ли абсолютные позиционные эмбеддинги. - use_rel_pos (
bool, необязательный, по умолчаниюTrue) — Использовать ли относительное встраивание позиций. - window_size (
int, необязательный, по умолчанию 14) — Размер окна для относительного позиционирования. - global_attn_indexes (
list[int], необязательный, по умолчанию[2, 5, 8, 11]) — Индексы слоёв глобального внимания. - num_pos_feats (
int, необязательный, по умолчанию 128) — Размерность позиционного эмбеддинга. - mlp_dim (
int, необязательный) — Размерность слоя MLP в кодере Transformer. ЕслиNone, по умолчанию используетсяmlp_ratio * hidden_size.
Это класс конфигурации для хранения конфигурации модели SamHQModel. Он используется для создания модели Sam Hq в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации syscv-community/sam-hq-vit-base
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Пример:
>>> 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.configSamHQMaskDecoderConfig
класс transformers.SamHQMaskDecoderConfig
< 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 = 'relu'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 = 256layer_norm_eps: float = 1e-06vit_dim: int = 768 )
Параметры
- hidden_size (
int, необязательный, по умолчанию256) — Размерность скрытых представлений. - hidden_act (
str, необязательный, по умолчаниюrelu) — Нелинейная функция активации (функция или строка) в декодере. Например,"gelu","relu","silu"и т. д. - mlp_dim (
int, необязательный, по умолчанию 2048) — Размерность «промежуточного» (т. е. полносвязного) слоя в кодере Transformer. - num_hidden_layers (
int, необязательный, по умолчанию2) — Количество скрытых слоев в декодере Transformer. - num_attention_heads (
int, необязательный, по умолчанию8) — Количество головок внимания в каждом слое внимания декодера Transformer. - attention_downsample_rate (
int, необязательный, по умолчанию 2) — Коэффициент понижающей дискретизации слоя внимания. - num_multimask_outputs (
int, необязательный, по умолчанию 3) — Количество выходов модуляSamMaskDecoder. В статье Segment Anything это значение установлено в 3. - iou_head_depth (
int, необязательный, по умолчанию 3) — Количество слоёв в модуле IoU head. - iou_head_hidden_dim (
int, необязательный, по умолчанию 256) — Размерность скрытых состояний в модуле IoU head. - layer_norm_eps (
float, необязательный, по умолчанию1e-06) — Значение epsilon, используемое слоями нормализации. - vit_dim (
int, необязательный, по умолчанию 768) — Размерность Vision Transformer (ViT), используемого в модулеSamHQMaskDecoder.
Это класс конфигурации для хранения конфигурации модели SamHQModel. Он используется для создания модели Sam Hq в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации syscv-community/sam-hq-vit-base
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
SamHQPromptEncoderConfig
класс transformers.SamHQPromptEncoderConfig
< 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-06 )
Параметры
- hidden_size (
int, необязательный, по умолчанию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, необязательный, по умолчанию 4) — Количество используемых точечных эмбеддингов. - hidden_act (
str, необязательный, по умолчаниюgelu) — Нелинейная функция активации (функция или строка) в декодере. Например,"gelu","relu","silu"и т. д. - layer_norm_eps (
float, необязательный, по умолчанию1e-06) — Значение epsilon, используемое слоями нормализации.
Это класс конфигурации для хранения конфигурации модели SamHQModel. Он используется для создания модели Sam Hq в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации syscv-community/sam-hq-vit-base
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
SamHQProcessor
класс transformers.SamHQProcessor
< source >( image_processor )
Создаёт SamHQProcessor, который объединяет процессор изображений в единый процессор.
SamHQProcessor предоставляет все возможности SamImageProcessor. Подробнее см. в ~SamImageProcessor.
__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] = None**kwargs: *<class 'transformers.models.sam_hq.processing_sam_hq.SamHQProcessorKwargs'> ) → ~feature_extraction_utils.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, kwargs, optional) — Сегментационные карты эталонных данных для обработки вместе с входными изображениями. Эти карты используются для обучения или оценки и масштабируются и нормализуются так, чтобы соответствовать размерам обработанного изображения. - input_points (
NestedList, kwargs, optional) — Точки ввода для сегментации на основе подсказок. Должно быть вложенным списком со структурой[image_level, object_level, point_level, [x, y]], где каждая точка задается координатами[x, y]в исходном пространстве изображения. Точки нормализуются до целевого размера изображения перед передачей в модель. - input_labels (
NestedList, kwargs, необязательный) — Метки для входных точек, указывающие, является ли каждая точка точкой переднего плана (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, необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:'pt': возвращает объектыtorch.TensorPyTorch.'np': возвращает объекты NumPynp.ndarray.
- **kwargs (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
< source >( config: SamHQVisionConfig )
Параметры
- config (SamHQVisionConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.
Модель зрения из SamHQ без какой-либо головы или проекции сверху.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → SamHQVisionEncoderOutput or tuple(torch.Tensor)
Параметры
- pixel_values (
torch.Tensorформы(batch_size, num_channels, image_size, image_size), необязательный) — Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью SamImageProcessor. Подробности см. в SamImageProcessor.call() (SamHQProcessor использует SamImageProcessor для обработки изображений).
Возвращает
SamHQVisionEncoderOutput или tuple(torch.Tensor)
Объект SamHQVisionEncoderOutput или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (SamHQConfig) и входных данных.
Метод forward модели 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
< source >( config: SamHQConfig )
Параметры
- config (SamHQConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
Модель Segment Anything Model HQ (SAM-HQ) для генерации масок по входному изображению и необязательным 2D-координатам и ограничивающим рамкам.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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 = Truehq_token_only: bool = Falseattention_similarity: typing.Optional[torch.Tensor] = Nonetarget_embedding: typing.Optional[torch.Tensor] = Noneintermediate_embeddings: list[torch.Tensor] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )
Параметры
- pixel_values (
torch.Tensorформы(batch_size, num_channels, image_size, image_size), необязательный) — Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью SamImageProcessor. Подробности см. в SamImageProcessor.call() (SamHQProcessor использует 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)) — Входные метки для точек. Используются prompt encoder для кодирования промпта. Согласно официальному реализованию, существует 3 типа меток1: точка, содержащая объект интереса0: точка, не содержащая объекта интереса-1: точка соответствует фону
Мы добавили метку:
-10: точка является заполнителем, поэтому должна игнорироваться prompt encoder
Метки для отступов должны добавляться автоматически процессором.
- input_boxes (
torch.Tensorформы(batch_size, num_boxes, 4)) — Входные рамки для точек. Используются prompt encoder для кодирования промпта. Как правило, это приводит к значительно более качественным сгенерированным маскам. Рамки можно получить, передав в processor список списков списков, который сгенерирует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. - target_embedding (
torch.Tensor, необязательный) — Векторное представление целевого концепта, которое передается декодеру маски для семантического промптинга по целевому объекту, если модель используется для персонализации, как описано в PerSAM. - intermediate_embeddings (
List[torch.Tensor], необязательный) — Промежуточные эмбеддинги из блоков vision encoder без окон, используемые SAM-HQ для повышения качества масок. Обязателен при передаче предварительно вычисленных image_embeddings вместо pixel_values.
Метод forward модели SamHQModel переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
Пример:
>>> 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"]
... )