Transformers documentation

SAM3 Video

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Эта модель была добавлена в Hugging Face Transformers 19.11.2025.

SAM3 Video

Обзор

SAM3 (Segment Anything Model 3) был представлен в статье 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 и ronghanghu.

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

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

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

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

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}")

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

# 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 поддерживает обработку кадров видео по мере их поступления:

# 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.

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

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})

Transformers

SAM3 Video

Обзор

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

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

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

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

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

Sam3VideoConfig

класс transformers.Sam3VideoConfig

Sam3VideoProcessor

класс transformers.Sam3VideoProcessor

__call__

postprocess_outputs

init_video_session

add_text_prompt

Sam3VideoInferenceSession

класс transformers.Sam3VideoInferenceSession

add_mask_inputs

add_new_frame

add_prompt

get_frame

get_obj_num

get_output

obj_id_to_idx

obj_idx_to_id

remove_mask_inputs

remove_object

reset_inference_session

reset_state

reset_tracking_data

store_output

Sam3VideoSegmentationOutput

класс transformers.Sam3VideoSegmentationOutput

Sam3VideoModel

класс transformers.Sam3VideoModel

forward

propagate_in_video_iterator

call