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.2).

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

Este modelo fue aportado a Hugging Face Transformers el 2025-11-19.

SAM3 Video

Resumen

SAM3 (Segment Anything Model 3) se presentó en SAM 3: Segment Anything with Concepts.

SAM3 Video realiza Segmentación de Conceptos Promptable (PCS) en videos. PCS toma texto como entrada (por ejemplo, “yellow school bus”) y predice máscaras de instancia y semánticas para cada objeto que coincida con el concepto, mientras preserva las identidades de los objetos a lo largo de los fotogramas del video.

El modelo combina un módulo de detección (SAM3) con un módulo de seguimiento (seguimiento de estilo SAM2) para permitir un seguimiento robusto de objetos a través de los fotogramas de un video mediante indicaciones de texto.

El resumen del artículo es el siguiente:

Presentamos Segment Anything Model (SAM) 3, un modelo unificado que detecta, segmenta y realiza seguimiento de objetos en imágenes y videos basándose en prompts de concepto, que definimos como frases nominales cortas (p. ej., “yellow school bus”), ejemplos de imagen o una combinación de ambos. La Segmentación de Conceptos con Prompts (PCS) toma dichos prompts y devuelve máscaras de segmentación e identidades únicas para todas las instancias de objetos coincidentes. Para avanzar en PCS, construimos un motor de datos escalable que produce un conjunto de datos de alta calidad con 4M de etiquetas de concepto únicas, incluyendo negativos difíciles, en imágenes y videos. Nuestro modelo consiste en un detector a nivel de imagen y un rastreador de video basado en memoria que comparten un único backbone. El reconocimiento y la localización se desacoplan mediante una presencia head, lo que mejora la precisión de la detección. SAM 3 duplica la precisión de los sistemas existentes tanto en PCS de imágenes como de videos, y mejora las capacidades anteriores de SAM en tareas de segmentación visual. Publicamos SAM 3 en código abierto junto con nuestro nuevo benchmark Segment Anything with Concepts (SA-Co) para la segmentación de conceptos con prompts.

Este modelo fue aportado por yonigozlan y ronghanghu.

Ejemplo de uso

Segmentación y seguimiento de video

Inferencia de video precargado

Procesa un video con todos los fotogramas ya disponibles usando prompts de texto:

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

También puede seguir varias categorías de objetos simultáneamente proporcionando varios prompts. El modelo reutiliza de manera eficiente las características visuales entre todos los prompts:

# 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

Inferencia de video en streaming

⚠️ **Nota sobre la calidad de la inferencia en streaming**: La inferencia en streaming desactiva las heurísticas de hotstart que eliminan objetos no coincidentes y duplicados, ya que estas requieren acceso a fotogramas futuros para tomar decisiones informadas. Esto puede resultar en más detecciones falsas positivas y en pistas de objetos duplicadas en comparación con la inferencia en video precargado. Para obtener los mejores resultados, utilice la inferencia en video precargado cuando todos los fotogramas estén disponibles.

Para aplicaciones en tiempo real, SAM3 Video admite el procesamiento de fotogramas de video a medida que llegan:

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

Inferencia con resolución personalizada

⚠️ **Nota sobre el rendimiento**: Las resoluciones personalizadas pueden degradar la precisión. El modelo está diseñado para usarse con una resolución de 1008px.

Para una inferencia más rápida o un menor uso de memoria:

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

Resumen

Ejemplo de uso

Segmentación y seguimiento de video

Inferencia de video precargado

Inferencia de video en streaming

Inferencia con resolución personalizada

Sam3VideoConfig

clase transformers.Sam3VideoConfig

Sam3VideoProcessor

clase transformers.Sam3VideoProcessor

__call__

postprocess_outputs

init_video_session

add_text_prompt

Sam3VideoInferenceSession

clase 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

clase transformers.Sam3VideoSegmentationOutput

Sam3VideoModel

clase transformers.Sam3VideoModel

forward

propagate_in_video_iterator

call