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

Mô hình này đã được đóng góp cho Hugging Face Transformers vào ngày 2025-11-19.

SAM3 Video

Tổng quan

SAM3 (Segment Anything Model 3) được giới thiệu trong SAM 3: Segment Anything with Concepts.

SAM3 Video thực hiện Phân đoạn Khái niệm Có thể Gợi ý (Promptable Concept Segmentation - PCS) trên video. PCS nhận văn bản làm đầu vào (ví dụ: “xe buýt trường học màu vàng”) và dự đoán các mặt nạ (mask) thực thể và ngữ nghĩa cho mọi đối tượng khớp với khái niệm, đồng thời duy trì danh tính của các đối tượng xuyên suốt các khung hình video.

Mô hình kết hợp một module phát hiện (SAM3) với một module theo dõi (tracker kiểu SAM2) để cho phép theo dõi đối tượng ổn định xuyên suốt các khung hình video bằng cách sử dụng prompt văn bản.

Tóm tắt từ bài báo như sau:

Chúng tôi giới thiệu Segment Anything Model (SAM) 3, một mô hình thống nhất có khả năng phát hiện, phân đoạn và theo dõi các đối tượng trong ảnh và video dựa trên các prompt khái niệm, được chúng tôi định nghĩa là các cụm danh từ ngắn (ví dụ: “yellow school bus”), các ví dụ hình ảnh, hoặc sự kết hợp của cả hai. Promptable Concept Segmentation (PCS) nhận các prompt như vậy và trả về các mặt nạ phân đoạn cùng với danh tính duy nhất cho tất cả các phiên bản đối tượng khớp. Để thúc đẩy PCS, chúng tôi xây dựng một động cơ dữ liệu có khả năng mở rộng, tạo ra một bộ dữ liệu chất lượng cao với 4 triệu nhãn khái niệm duy nhất, bao gồm cả các âm tính khó, trên cả ảnh và video. Mô hình của chúng tôi bao gồm một bộ phát hiện ở cấp độ ảnh và một bộ theo dõi video dựa trên bộ nhớ, chia sẻ một backbone duy nhất. Nhận dạng và định vị được tách rời bằng một presence head, giúp tăng độ chính xác của việc phát hiện. SAM 3 gấp đôi độ chính xác so với các hệ thống hiện có trong cả PCS trên ảnh và video, đồng thời cải thiện các khả năng trước đó của SAM trên các nhiệm vụ phân đoạn thị giác. Chúng tôi mã nguồn mở SAM 3 cùng với bộ chuẩn đánh giá mới Segment Anything with Concepts (SA-Co) của chúng tôi cho phân đoạn khái niệm có thể prompt.

Mô hình này được đóng góp bởi yonigozlan và ronghanghu.

Ví dụ sử dụng

Phân đoạn và Theo dõi Video

Suy luận video được nạp trước

Xử lý một video với tất cả các khung hình đã có sẵn bằng các lời nhắc văn bản:

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

Bạn cũng có thể theo dõi nhiều danh mục đối tượng cùng lúc bằng cách cung cấp nhiều prompt. Mô hình tái sử dụng hiệu quả các đặc trưng thị giác xuyên suốt tất cả các 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

Suy luận Video trực tiếp

⚠️ **Lưu ý về chất lượng suy luận trực tiếp (streaming inference)**: Suy luận trực tiếp sẽ vô hiệu hóa các thuật toán heuristics khởi động nóng (hotstart) nhằm loại bỏ các đối tượng không khớp và các đối tượng trùng lặp, vì các thuật toán này cần truy cập vào các khung hình tương lai để đưa ra quyết định chính xác. Điều này có thể dẫn đến nhiều phát hiện dương tính giả và các đường theo dõi đối tượng trùng lặp hơn so với suy luận trên video đã tải trước. Để đạt kết quả tốt nhất, hãy sử dụng suy luận trên video đã tải trước khi tất cả các khung hình đều có sẵn.

Đối với các ứng dụng thời gian thực, SAM3 Video hỗ trợ xử lý các khung hình video ngay khi chúng được nhận:

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

Suy luận Độ phân giải Tùy chỉnh

⚠️ **Lưu ý về hiệu năng**: Độ phân giải tùy chỉnh có thể làm giảm độ chính xác. Mô hình được thiết kế để sử dụng ở độ phân giải 1008px.

Để suy luận nhanh hơn hoặc sử dụng ít bộ nhớ hơn:

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

Tổng quan

Ví dụ sử dụng

Phân đoạn và Theo dõi Video

Suy luận video được nạp trước

Suy luận Video trực tiếp

Suy luận Độ phân giải Tùy chỉnh

Sam3VideoConfig

lớp transformers.Sam3VideoConfig

Sam3VideoProcessor

lớp transformers.Sam3VideoProcessor

__call__

postprocess_outputs

init_video_session

add_text_prompt

Sam3VideoInferenceSession

lớp 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

lớp transformers.Sam3VideoSegmentationOutput

Sam3VideoModel

lớp transformers.Sam3VideoModel

forward

propagate_in_video_iterator

call