# SAM3 Video

    
        
        
    

## Обзор

SAM3 (Segment Anything Model 3) был представлен в [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/sam-3-segment-anything-with-concepts/).

SAM3 Video выполняет **PCS (Promptable Concept Segmentation)** для видео. PCS принимает на вход текст (например, «жёлтый школьный автобус») и предсказывает маски инстансов и семантические маски для **каждого объекта**, соответствующего концепту, сохраняя идентичность объектов между кадрами видео.

Модель объединяет модуль обнаружения (SAM3) с модулем отслеживания (трекер в стиле SAM2), что обеспечивает надёжное отслеживание объектов по кадрам видео с использованием текстовых подсказок.

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

*Мы представляем Segment Anything Model (SAM) 3 — унифицированную модель, которая обнаруживает, сегментирует и отслеживает объекты на изображениях и в видео на основе концептуальных промптов, которые мы определяем как короткие именные фразы (например, «жёлтый школьный автобус»), образцы-примеры или комбинацию обоих. Promptable Concept Segmentation (PCS) принимает такие промпты и возвращает маски сегментации и уникальные идентификаторы для всех соответствующих экземпляров объектов. Для развития PCS мы создали масштабируемый движок данных, который формирует высококачественный датасет с 4 млн уникальных концептуальных меток, включая сложные негативные примеры, на изображениях и в видео. Наша модель состоит из детектора на уровне изображения и видео-трекера на основе памяти, которые используют общий бэкбон. Распознавание и локализация разделены с помощью presence head, что повышает точность обнаружения. SAM 3 удваивает точность существующих систем как в PCS для изображений, так и для видео, а также улучшает возможности предыдущих версий SAM в задачах визуальной сегментации. Мы открыли исходный код SAM 3 вместе с нашим новым бенчмарком Segment Anything with Concepts (SA-Co) для promptable concept segmentation.*

Эта модель была предоставлена [yonigozlan](https://huggingface.co/yonigozlan) и [ronghanghu](https://huggingface.co/ronghanghu).

## Пример использования

### Сегментация и отслеживание объектов на видео

#### Видеовычисления с предварительной загрузкой

Обработка видео, в котором все кадры уже доступны, с использованием текстовых подсказок:

```python
from transformers import Sam3VideoModel, Sam3VideoProcessor
import torch

model = Sam3VideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3")

# Load video frames
from transformers.video_utils import load_video
video_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/bedroom.mp4"
video_frames, _ = load_video(video_url)

# Initialize video inference session
inference_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt to detect and track objects
text = "person"
inference_session = processor.add_text_prompt(
    inference_session=inference_session,
    text=text,
)

# Process all frames in the video
outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=inference_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(inference_session, model_outputs)
    outputs_per_frame[model_outputs.frame_idx] = processed_outputs

print(f"Processed {len(outputs_per_frame)} frames")
Processed 51 frames

# Access results for a specific frame
frame_0_outputs = outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects")
print(f"Object IDs: {frame_0_outputs['object_ids'].tolist()}")
print(f"Scores: {frame_0_outputs['scores'].tolist()}")
print(f"Boxes shape (XYXY format, absolute coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks shape: {frame_0_outputs['masks'].shape}")
```

Вы также можете отслеживать несколько категорий объектов одновременно, передавая несколько подсказок. Модель эффективно переиспользует визуальные признаки для всех подсказок:

```python
# Add multiple text prompts (or use a list in add_text_prompt)
multi_prompt_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)
>>>
prompts = ["person", "bed", "lamp"]
processor.add_text_prompt(multi_prompt_session, prompts)
>>>
# Process video - detects objects from ALL prompts in a single pass
multi_outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=multi_prompt_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(multi_prompt_session, model_outputs)
    multi_outputs_per_frame[model_outputs.frame_idx] = processed_outputs
>>>
# Check which objects were detected by each prompt
frame_0_outputs = multi_outputs_per_frame[0]
prompt_to_obj_ids = frame_0_outputs["prompt_to_obj_ids"]
for prompt, obj_ids in prompt_to_obj_ids.items():
    print(f"{prompt}: {len(obj_ids)} objects")
person: 2 objects
bed: 1 objects
lamp: 1 objects
```

#### Потоковое видео-инференс

⚠️ **Примечание о качестве стримингового вывода**: Стриминговый вывод отключает эвристики hotstart, удаляющие несоответствующие и дублирующиеся объекты, поскольку для принятия обоснованных решений им необходим доступ к будущим кадрам. Это может привести к увеличению количества ложноположительных детекций и дублирующихся треков объектов по сравнению с выводом для предварительно загруженного видео. Для получения наилучших результатов используйте вывод для предварительно загруженного видео, когда все кадры доступны.

Для приложений реального времени SAM3 Video поддерживает обработку кадров видео по мере их поступления:

```python
# Initialize session for streaming
streaming_inference_session = processor.init_video_session(
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt
text = "person"
streaming_inference_session = processor.add_text_prompt(
    inference_session=streaming_inference_session,
    text=text,
)

# Process frames one by one (streaming mode)
streaming_outputs_per_frame = {}
for frame_idx, frame in enumerate(video_frames[:50]):  # Process first 50 frames
    # First, process the frame using the processor
    inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
    # Process frame using streaming inference - pass the processed pixel_values
    model_outputs = model(
        inference_session=streaming_inference_session,
        frame=inputs.pixel_values[0],  # Provide processed frame - this enables streaming mode
        reverse=False,
    )
...
    # Post-process outputs with original_sizes for proper resolution handling
    processed_outputs = processor.postprocess_outputs(
        streaming_inference_session,
        model_outputs,
        original_sizes=inputs.original_sizes,  # Required for streaming inference
    )
    streaming_outputs_per_frame[frame_idx] = processed_outputs
...
    if (frame_idx + 1) % 10 == 0:
        print(f"Processed {frame_idx + 1} frames...")

print(f"✓ Streaming inference complete! Processed {len(streaming_outputs_per_frame)} frames")
✓ Streaming inference complete! Processed 50 frames

# Access results
frame_0_outputs = streaming_outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects in first frame")
print(f"Boxes are in XYXY format (absolute pixel coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks are at original video resolution: {frame_0_outputs['masks'].shape}")
```

#### Вывод с настраиваемым разрешением

⚠️ **Примечание о производительности**: Использование нестандартных разрешений может снизить точность. Модель предназначена для работы с разрешением 1008px.

Для более быстрого вывода или меньшего потребления памяти:

```python
config = Sam3VideoConfig.from_pretrained("facebook/sam3")
config.image_size = 560
model = Sam3VideoModel.from_pretrained("facebook/sam3", config=config, device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3", size={"height": 560, "width": 560})
```

## Sam3VideoConfig[[transformers.Sam3VideoConfig]]

#### transformers.Sam3VideoConfig[[transformers.Sam3VideoConfig]]

```python
transformers.Sam3VideoConfig(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, detector_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, tracker_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02, low_res_mask_size: int = 288, score_threshold_detection: float = 0.5, det_nms_thresh: float = 0.1, assoc_iou_thresh: float = 0.1, trk_assoc_iou_thresh: float = 0.5, new_det_thresh: float = 0.7, recondition_on_trk_masks: bool = True, hotstart_delay: int = 15, hotstart_unmatch_thresh: int = 8, hotstart_dup_thresh: int = 8, suppress_unmatched_only_within_hotstart: bool = True, init_trk_keep_alive: int = 30, max_trk_keep_alive: int = 30, min_trk_keep_alive: int = -1, suppress_overlapping_based_on_recent_occlusion_threshold: float = 0.7, decrease_trk_keep_alive_for_empty_masklets: bool = False, fill_hole_area: int = 16, max_num_objects: int = 10000, recondition_every_nth_frame: int = 16, high_conf_thresh: float = 0.8, high_iou_thresh: float = 0.8)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/configuration_sam3_video.py#L28)

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

detector_config (`dict` или `Sam3Config`, *необязательный*) : Конфигурация для модели детектора Sam3. Если не указано, будет использоваться конфигурация Sam3Config по умолчанию.

tracker_config (`dict` или `Sam2VideoConfig`, *необязательный*) : Конфигурация для модели трекера Sam2Video. Если не указано, будет использоваться конфигурация Sam2VideoConfig по умолчанию.

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

low_res_mask_size (`int`, *optional*, по умолчанию 288) : Размер (высота и ширина) выходов маски низкого разрешения от трекера до апсемплинга до разрешения видео.

score_threshold_detection (`float`, *optional*, по умолчанию 0.5) : Порог вероятности для результатов детектирования — сохраняются только детекции с вероятностью выше этого порога.

det_nms_thresh (`float`, *optional*, по умолчанию 0.1) : Порог IoU для NMS (Non-Maximum Suppression) при обнаружении.

assoc_iou_thresh (`float`, *optional*, по умолчанию 0.1) : Порог IoU для сопоставления детекций с треками. Детекция считается «сопоставленной» с tracklet, если её пересечение с tracklet превышает этот порог. Часто используется низкий порог, например 0.1.

trk_assoc_iou_thresh (`float`, *optional*, по умолчанию 0.5) : Порог IoU для сопоставления детекций с треками, используется для определения того, является ли masklet «несопоставленным» ни с одной детекцией. Часто используется более строгий порог, например 0.5.

new_det_thresh (`float`, *необязательный*, по умолчанию 0.7) : Порог вероятности, при котором обнаружение добавляется как новый объект.

recondition_on_trk_masks (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли отслеживаемые маски (True) или маски детекции (False) для переусловливания. Используйте True, если отслеживаемые маски имеют более высокое качество, а детектор служит сигналом валидации для укрепления памяти и предотвращения дрейфа.

hotstart_delay (`int`, *optional*, по умолчанию 15) : Количество кадров, которые буферизуются для вывода во время hotstart. Мы задерживаем вывод на `hotstart_delay` кадров и удаляем tracklets на основе эвристик hotstart.

hotstart_unmatch_thresh (`int`, *optional*, по умолчанию 8) : Количество несоответствующих кадров, необходимых для удаления tracklet в период hotstart.

hotstart_dup_thresh (`int`, *optional*, по умолчанию 8) : Количество перекрывающихся кадров, необходимых для удаления дублирующего tracklet в период hotstart.

suppress_unmatched_only_within_hotstart (`bool`, *необязательный*, по умолчанию `True`) : Определяет, следует ли подавлять маски только в течение периода hotstart. Если False, маски могут подавляться даже в том случае, если они начинаются до периода hotstart.

init_trk_keep_alive (`int`, *необязательный*, по умолчанию 30) : Начальный счётчик keep-alive для новых треков.

max_trk_keep_alive (`int`, *optional*, по умолчанию 30) : Максимальное значение счётчика keep-alive. Для отслеживаемых совпавших детекций счётчик увеличивается до этого значения.

min_trk_keep_alive (`int`, *optional*, по умолчанию -1) : Минимальное значение счётчика keep-alive. Для треков с несоответствующими детекциями значение счётчика уменьшается до этого уровня.

suppress_overlapping_based_on_recent_occlusion_threshold (`float`, *optional*, по умолчанию 0.7) : Порог для подавления перекрывающихся объектов на основе недавнего перекрытия. Маски, перекрывающиеся с IoU выше этого порога, подавляются в зависимости от того, какой объект был перекрыт недавно.

decrease_trk_keep_alive_for_empty_masklets (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли уменьшать счётчик keep-alive для masklet с нулевой площадью в предсказании SAM2.

fill_hole_area (`int`, *optional*, по умолчанию 16) : Минимальная площадь (в пикселях) для заполнения отверстий в масках и удаления мелких шумов.

max_num_objects (`int`, *optional*, по умолчанию 10000) : Максимальное количество отслеживаемых объектов. Значение по умолчанию 10000 фактически отключает это ограничение.

recondition_every_nth_frame (`int`, *optional*, по умолчанию 16) : Частота повторной настройки маски (в кадрах). Установите 0, чтобы отключить повторную настройку.

high_conf_thresh (`float`, *optional*, по умолчанию 0.8) : Порог высокой уверенности для рекондиционирования. Только детекции выше этого порога могут рекондиционировать треклеты.

high_iou_thresh (`float`, *optional*, по умолчанию 0.8) : Высокий порог IoU для переусловливания. Только детекции с IoU выше этого порога могут переусловливать треклеты.

Это класс конфигурации для хранения настроек модели Sam3VideoModel. Он используется для создания модели Sam3 Video в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [facebook/sam3](https://huggingface.co/facebook/sam3)

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

Пример:
```python
>>> from transformers import Sam3VideoConfig, Sam3VideoModel

>>> # Initializing a SAM3 Video configuration with default detector and tracker
>>> configuration = Sam3VideoConfig()

>>> # Changing image size for custom resolution inference (automatically propagates to all nested configs)
>>> configuration.image_size = 560

>>> # Initializing a model from the configuration
>>> model = Sam3VideoModel(configuration)

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

## Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

#### transformers.Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

```python
transformers.Sam3VideoProcessor(image_processor, video_processor, tokenizer, target_size: int | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/processing_sam3_video.py#L39)

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

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

video_processor (`video_processor_class`) : Процессор видео является обязательным входным параметром.

tokenizer (`CLIPTokenizer`) : Токенизатор является обязательным входным параметром.

target_size (`int`, *optional*) : Целевой размер (target_size, target_size), к которому будет изменён размер изображения.

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

[Sam3VideoProcessor](/docs/transformers/v5.23.0/ru/model_doc/sam3_video#transformers.Sam3VideoProcessor) предоставляет все возможности [Sam3ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sam3#transformers.Sam3ImageProcessor), `video_processor_class` и [CLIPTokenizer](/docs/transformers/v5.23.0/ru/model_doc/clip#transformers.CLIPTokenizer). Подробнее см. в [~Sam3ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/sam3#transformers.Sam3ImageProcessor), `~video_processor_class` и [~CLIPTokenizer](/docs/transformers/v5.23.0/ru/model_doc/clip#transformers.CLIPTokenizer).

#### __call__[[transformers.Sam3VideoProcessor.__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, 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/sam3_video/processing_sam3_video.py#L55)

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

images (`ImageInput`, *необязательный*) : Изображение(я) для обработки.

segmentation_maps (`ImageInput`, *необязательный*) : карты сегментации для обработки (необязательно, для процессора изображений).

original_sizes (`list[list[float]]`, `torch.Tensor`, *необязательный*) : Исходные размеры изображений. Используется только в том случае, если images не передан.

return_tensors (`Union[str, ~utils.generic.TensorType]`, *необязательный*) : Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:  - `'pt'`: возвращает объекты `torch.Tensor` PyTorch. - `'np'`: возвращает объекты `np.ndarray` NumPy.

**Возвращает:** [BatchEncoding](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.BatchEncoding) со следующими полями

- `pixel_values` (`torch.Tensor`): Обработанное изображение или изображения.
- `original_sizes` (`list[list[float]]`): исходные размеры изображений.
- `labels` (`torch.Tensor`, *необязательный*): Обработанные карты сегментации (если предоставлены).

#### postprocess_outputs[[transformers.Sam3VideoProcessor.postprocess_outputs]]

```python
postprocess_outputs(inference_session, model_outputs, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/processing_sam3_video.py#L247)

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

inference_session (`Sam3VideoInferenceSession`) : объект сессии инференса.

model_outputs (`Sam3VideoSegmentationOutput`) : исходный вывод модели из `Sam3VideoModel.forward()`.

original_sizes (`list[list[float]]` или `torch.Tensor`, *необязательный*) : Необязательные исходные размеры кадра [высота, ширина]. Обязательно для потокового вывода, если video_height/video_width не заданы в сессии.

**Возвращает:** `dict`

Словарь, содержащий следующие ключи:
- **object_ids** (`torch.Tensor` формы `(num_objects,)`): идентификаторы объектов для каждого обнаруженного объекта.
- **scores** (`torch.Tensor` формы `(num_objects,)`): Оценки обнаружения для каждого объекта.
- **boxes** (`torch.Tensor` формы `(num_objects, 4)`): Ограничивающие рамки в формате XYXY (top_left_x, top_left_y, bottom_right_x, bottom_right_y).
- **маски** (`torch.Tensor` формы `(num_objects, height, width)`): Бинарные маски сегментации для каждого объекта в исходном разрешении видео.
- **prompt_to_obj_ids** (`dict[str, list[int]]`): Соответствие между текстом подсказки и списком идентификаторов объектов, обнаруженных этой подсказкой.

Выполните постобработку выходов модели, чтобы получить итоговые маски, рамки и оценки.

#### init_video_session[[transformers.Sam3VideoProcessor.init_video_session]]

```python
init_video_session(video: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = None, inference_device: typing.Union[str, ForwardRef('torch.device')] = 'cpu', inference_state_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, processing_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, video_storage_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, max_vision_features_cache_size: int = 1, dtype: dtype = torch.float32)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/processing_sam3_video.py#L133)

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

video (`VideoInput`, *необязательный*) : Видео для обработки. Не требуется при потоковой передаче.

inference_device (`str` или `torch.device`, *необязательный*, по умолчанию "cpu") : Устройство, используемое для вывода.

inference_state_device (`str` или `torch.device`, *необязательный*) : Устройство, на котором хранится состояние инференса.

processing_device (`str` или `torch.device`, *необязательный*) : Устройство, используемое для обработки видео.

video_storage_device (`str` или `torch.device`, *необязательный*) : Устройство, на котором будут храниться обработанные кадры видео.

max_vision_features_cache_size (`int`, *необязательный*, по умолчанию 1) : Максимальное количество визуальных признаков для кэширования.

dtype (`torch.dtype`, *необязательный*, по умолчанию `torch.float32`) : torch dtype, используемый для всей сессии.

Инициализирует видеосессию для инференса. Если видео предоставлено (асинхронный инференс), оно будет обработано и сохранено на `video_storage_device`.

#### add_text_prompt[[transformers.Sam3VideoProcessor.add_text_prompt]]

```python
add_text_prompt(inference_session: Sam3VideoInferenceSession, text: str | list[str])
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/processing_sam3_video.py#L101)

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

inference_session (`Sam3VideoInferenceSession`) : сессия инференса.

text (`str` или `list[str]`) : Текстовые промпт(ы) для добавления.

**Возвращает:** `Sam3VideoInferenceSession`

Сессия вывода с добавленным текстовым промптом(ами).

Добавьте текстовый промпт(ы) в сессию инференса.

## Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

#### transformers.Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

```python
transformers.Sam3VideoInferenceSession(video: typing.Optional[torch.Tensor] = None, video_height: int | None = None, video_width: int | None = None, inference_device: typing.Union[torch.device, str] = 'cpu', inference_state_device: typing.Union[torch.device, str] = 'cpu', video_storage_device: typing.Union[torch.device, str] = 'cpu', dtype: typing.Union[torch.dtype, str] = 'float32', max_vision_features_cache_size: int = 1)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L119)

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

video (`torch.Tensor`, *необязательный*) : Видео для обработки. Не требуется при потоковой передаче.

video_height (`int`, *необязательный*) : Высота видео.

video_width (`int`, *необязательный*) : Ширина видео.

inference_device (`torch.device`, *необязательный*, по умолчанию `"cpu"`) : Устройство, используемое для вывода.

inference_state_device (`torch.device`, *необязательный*, по умолчанию `"cpu"`) : Устройство, на котором хранится состояние инференса.

video_storage_device (`torch.device`, *необязательный*, по умолчанию `"cpu"`) : Устройство, на котором будет храниться видео.

dtype (`torch.dtype`, *необязательный*, по умолчанию `"float32"`) : Тип данных (dtype), используемый для видео.

max_vision_features_cache_size (`int`, *необязательный*, по умолчанию 1) : Максимальное количество визуальных признаков для кэширования.

Управляет параметрами, состоянием и кэшем сессии инференса видео.

#### add_mask_inputs[[transformers.Sam3VideoInferenceSession.add_mask_inputs]]

```python
add_mask_inputs(obj_idx: int, frame_idx: int, inputs: Tensor)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L255)

Добавьте входные маски с автоматическим размещением на устройстве.

#### add_new_frame[[transformers.Sam3VideoInferenceSession.add_new_frame]]

```python
add_new_frame(pixel_values: Tensor, frame_idx: int | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L384)

Добавить новый кадр с автоматическим размещением на устройстве.

#### add_prompt[[transformers.Sam3VideoInferenceSession.add_prompt]]

```python
add_prompt(prompt_text: str)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L215)

Добавляет текстовый промпт в сессию и возвращает его уникальный идентификатор. Если промпт уже существует, возвращает существующий идентификатор.

#### get_frame[[transformers.Sam3VideoInferenceSession.get_frame]]

```python
get_frame(frame_idx: int)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L400)

Получить кадр из видео.

#### get_obj_num[[transformers.Sam3VideoInferenceSession.get_obj_num]]

```python
get_obj_num()
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L251)

Получите общее количество уникальных идентификаторов объектов, полученных на данный момент в этой сессии.

#### get_output[[transformers.Sam3VideoInferenceSession.get_output]]

```python
get_output(obj_idx: int, frame_idx: int, output_key: str, is_conditioning_frame: bool = True)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L357)

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

obj_idx (int) : индекс объекта.

frame_idx (int) : Индекс кадра.

output_key (str) : Ключ вывода.

is_conditioning_frame (bool) : Указывает, является ли вывод для кадра, задающего условия.

Получите вывод с умным управлением устройствами.

#### obj_id_to_idx[[transformers.Sam3VideoInferenceSession.obj_id_to_idx]]

```python
obj_id_to_idx(obj_id: int)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L229)

Соответствие идентификатора объекта индексу, при необходимости создавая новую запись.

#### obj_idx_to_id[[transformers.Sam3VideoInferenceSession.obj_idx_to_id]]

```python
obj_idx_to_id(obj_idx: int)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L247)

Соответствие индекса объекта на стороне модели идентификатору объекта на стороне клиента.

#### remove_mask_inputs[[transformers.Sam3VideoInferenceSession.remove_mask_inputs]]

```python
remove_mask_inputs(obj_idx: int, frame_idx: int)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L261)

Удалите входные маски.

#### remove_object[[transformers.Sam3VideoInferenceSession.remove_object]]

```python
remove_object(obj_id: int, strict: bool = False)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L265)

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

obj_id (`int`) : Идентификатор объекта для удаления.

strict (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли вызывать ошибку, если объект не существует.

Удалить объект из сессии инференса. Это удалит объект со всех кадров видео.

#### reset_inference_session[[transformers.Sam3VideoInferenceSession.reset_inference_session]]

```python
reset_inference_session()
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L416)

Сбросить данные отслеживания и кэш.

#### reset_state[[transformers.Sam3VideoInferenceSession.reset_state]]

```python
reset_state()
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L428)

Сбросить состояние сессии вывода.

#### reset_tracking_data[[transformers.Sam3VideoInferenceSession.reset_tracking_data]]

```python
reset_tracking_data()
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L404)

Сбросить данные отслеживания, но сохранить кэш.

#### store_output[[transformers.Sam3VideoInferenceSession.store_output]]

```python
store_output(obj_idx: int, frame_idx: int, output_key: str | None = None, output_value: typing.Union[torch.Tensor, dict, NoneType] = None, is_conditioning_frame: bool = True)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L320)

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

obj_idx (int) : индекс объекта.

frame_idx (int) : Индекс кадра.

output_key (Optional[str]) : Ключ вывода. Если None, вывод сохраняется в виде словаря.

output_value (Optional[Union[torch.Tensor, dict]]) : Значение вывода.

is_conditioning_frame (bool) : Указывает, является ли вывод для кадра, задающего условия.

Сохраняйте вывод с умным управлением устройствами. Если output_key равно None, вывод сохраняется в виде словаря.

## Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

#### transformers.Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

```python
transformers.Sam3VideoSegmentationOutput(object_ids: list[int] | None = None, obj_id_to_mask: dict[int, torch.Tensor] | None = None, obj_id_to_score: dict[int, float] | None = None, obj_id_to_tracker_score: dict[int, float] | None = None, removed_obj_ids: set[int] | None = None, suppressed_obj_ids: set[int] | None = None, frame_idx: int | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L462)

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

object_ids (`list[int]`, *необязательный*) : Список идентификаторов объектов, отслеживаемых в текущем кадре.

obj_id_to_mask (`dict[int, torch.Tensor]`, *необязательный*) : Словарь, сопоставляющий идентификаторы объектов с их предсказанными масками низкого разрешения. Каждая маска имеет форму `(1, H_low, W_low)`.

obj_id_to_score (`dict[int, float]`, *необязательный*) : Словарь, сопоставляющий идентификаторы объектов с их оценками обнаружения.

obj_id_to_tracker_score (`dict[int, float]`, *необязательный*) : Словарь, сопоставляющий идентификаторы объектов их оценкам отслеживания для текущего кадра.

removed_obj_ids (`set[int]`, *optional*) : Множество идентификаторов объектов, которые были удалены (например, с помощью эвристик hotstart).

suppressed_obj_ids (`set[int]`, *optional*) : Множество идентификаторов объектов, подавленных в текущем кадре.

frame_idx (`int`, *необязательный*) : Индекс кадра видео.

Базовый класс для вывода модели Sam3Video.

## Sam3VideoModel[[transformers.Sam3VideoModel]]

#### transformers.Sam3VideoModel[[transformers.Sam3VideoModel]]

```python
transformers.Sam3VideoModel(config: Sam3VideoConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L507)

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

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

Модель Sam3 Video, выводящая «сырые» скрытые состояния без какого-либо специализированного слоя на выходе.

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

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

#### forward[[transformers.Sam3VideoModel.forward]]

```python
forward(inference_session: Sam3VideoInferenceSession, frame_idx: int | None = None, frame: typing.Optional[torch.Tensor] = None, reverse: bool = False, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L1693)

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

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : объект сессии видеоинференса.

frame_idx (`int`, *optional*) : Индекс кадра, на котором выполняется инференс. Не требуется указывать при инференсе на новом потоковом кадре.

frame (`torch.Tensor`, *необязательный*) : Кадры для обработки. Укажите при потоковой обработке.

reverse (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли распространять в обратном направлении.

Передайте объекты через кадр потокового видео.

#### propagate_in_video_iterator[[transformers.Sam3VideoModel.propagate_in_video_iterator]]

```python
propagate_in_video_iterator(inference_session: Sam3VideoInferenceSession, start_frame_idx: int = 0, max_frame_num_to_track: int | None = None, reverse: bool = False, show_progress_bar: bool = False)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L1784)

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

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : объект сессии видеоинференса.

start_frame_idx (`int`, *необязательный*, по умолчанию `0`) : Начальный индекс кадра для распространения.

max_frame_num_to_track (`int`, *optional*) : Максимальное количество кадров для отслеживания. Если не указано, будут отслеживаться все кадры в видео.

reverse (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли распространять в обратном направлении.

show_progress_bar (`bool`, *необязательный*, по умолчанию `False`) : Показывать ли индикатор прогресса во время распространения.

**Возвращает:** [Sam3VideoSegmentationOutput](/docs/transformers/v5.23.0/ru/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) или `tuple(torch.Tensor)`

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

Передайте промпты, чтобы получить результаты локализации для всего видео. Используется при инициализации сессии инференса с полным видео. Возвращает Sam3VideoSegmentationOutput для каждого кадра.

- **object_ids** (`list[int]`, *необязательный*) -- Список идентификаторов объектов, отслеживаемых в текущем кадре.
- **obj_id_to_mask** (`dict[int, torch.Tensor]`, *необязательный*) -- Словарь, сопоставляющий идентификаторы объектов с их предсказанными масками низкого разрешения. Каждая маска имеет форму `(1, H_low, W_low)`.
- **obj_id_to_score** (`dict[int, float]`, *необязательный*) -- Словарь, сопоставляющий идентификаторы объектов с их оценками обнаружения.
- **obj_id_to_tracker_score** (`dict[int, float]`, *необязательный*) -- Словарь, сопоставляющий идентификаторы объектов их оценкам трекера для текущего кадра.
- **removed_obj_ids** (`set[int]`, *необязательный*) -- Множество идентификаторов объектов, которые были удалены (например, с помощью эвристик hotstart).
- **suppressed_obj_ids** (`set[int]`, *необязательный*) -- Множество идентификаторов объектов, подавленных в текущем кадре.
- **frame_idx** (`int`, *необязательный*) -- Индекс кадра видео.

