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

Model ini disumbangkan ke Hugging Face Transformers pada 2025-11-19.

SAM3 Video

Ikhtisar

SAM3 (Segment Anything Model 3) diperkenalkan dalam SAM 3: Segment Anything with Concepts.

SAM3 Video melakukan Promptable Concept Segmentation (PCS) pada video. PCS menerima teks sebagai input (misalnya, “yellow school bus”), dan memprediksi mask instance dan semantik untuk setiap objek yang cocok dengan konsep tersebut, sambil mempertahankan identitas objek di antara frame video.

Model ini menggabungkan modul deteksi (SAM3) dengan modul pelacakan (pelacak bergaya SAM2) untuk memungkinkan pelacakan objek yang andal di antara bingkai video menggunakan prompt teks.

Abstrak dari makalah tersebut adalah sebagai berikut:

Kami memperkenalkan Segment Anything Model (SAM) 3, sebuah model terpadu yang mendeteksi, memsegmentasi, dan melacak objek dalam gambar dan video berdasarkan prompt konsep, yang kami definisikan sebagai frasa nomina pendek (misalnya, “yellow school bus”), contoh gambar, atau kombinasi keduanya. Promptable Concept Segmentation (PCS) menerima prompt semacam itu dan mengembalikan mask segmentasi serta identitas unik untuk semua instans objek yang cocok. Untuk memajukan PCS, kami membangun mesin data yang dapat diskalakan yang menghasilkan dataset berkualitas tinggi dengan 4 juta label konsep unik, termasuk negatif yang sulit, di seluruh gambar dan video. Model kami terdiri dari detektor tingkat gambar dan pelacak video berbasis memori yang berbagi satu backbone tunggal. Pengenalan dan lokalisasi dipisahkan dengan presence head, yang meningkatkan akurasi deteksi. SAM 3 menggandakan akurasi sistem yang ada dalam PCS gambar dan video, serta meningkatkan kemampuan SAM sebelumnya pada tugas segmentasi visual. Kami membuka sumber SAM 3 bersama dengan benchmark baru kami, Segment Anything with Concepts (SA-Co), untuk segmentasi konsep yang dapat diprompt.

Model ini disumbangkan oleh yonigozlan dan ronghanghu.

Contoh penggunaan

Segmentasi dan Pelacakan Video

Inferensi Video Pra-muat

Proses video dengan semua frame yang sudah tersedia menggunakan prompt teks:

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

Anda juga dapat melacak beberapa kategori objek secara bersamaan dengan menyediakan beberapa prompt. Model ini secara efisien menggunakan ulang fitur visual di semua prompt:

# 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

Inferensi Video Streaming

⚠️ **Catatan tentang Kualitas Inferensi Streaming**: Inferensi streaming menonaktifkan heuristik hotstart yang menghapus objek yang tidak cocok dan duplikat, karena heuristik tersebut memerlukan akses ke frame di masa depan untuk membuat keputusan yang tepat. Hal ini dapat menghasilkan lebih banyak deteksi positif palsu dan track objek duplikat dibandingkan dengan inferensi video yang dimuat sebelumnya. Untuk hasil terbaik, gunakan inferensi video yang dimuat sebelumnya ketika semua frame tersedia.

Untuk aplikasi real-time, SAM3 Video mendukung pemrosesan bingkai video saat bingkai tersebut tiba:

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

Inferensi Resolusi Kustom

⚠️ **Catatan Kinerja**: Resolusi kustom dapat menurunkan akurasi. Model ini dimaksudkan untuk digunakan pada resolusi 1008px.

Untuk inferensi yang lebih cepat atau penggunaan memori yang lebih rendah:

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

Ikhtisar

Contoh penggunaan

Segmentasi dan Pelacakan Video

Inferensi Video Pra-muat

Inferensi Video Streaming

Inferensi Resolusi Kustom

Sam3VideoConfig

kelas transformers.Sam3VideoConfig

Sam3VideoProcessor

kelas transformers.Sam3VideoProcessor

__call__

postprocess_outputs

init_video_session

add_text_prompt

Sam3VideoInferenceSession

kelas 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

kelas transformers.Sam3VideoSegmentationOutput

Sam3VideoModel

kelas transformers.Sam3VideoModel

forward

propagate_in_video_iterator

call