Transformers documentation

SAM3 فيديو

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 في 2025-11-19.

SAM3 فيديو

نظرة عامة

تم تقديم SAM3 (نموذج تقسيم أي شيء 3) في SAM 3: Segment Anything with Concepts.

يُنفّذ SAM3 Video تجزئة المفاهيم القابلة للتوجيه (PCS) على مقاطع الفيديو. حيث يستقبل PCS نصاً كمدخل (مثل "حافلة مدرسية صفراء")، ويتنبأ بأقنعة كائنات وأقنعة دلالية لكل كائن فردي يطابق المفهوم، مع الحفاظ على هويات الكائنات عبر إطارات الفيديو.

يجمع النموذج بين وحدة كشف (SAM3) ووحدة تتبع (متتبع بنمط SAM2) لتمكين التتبع القوي للأهداف عبر إطارات الفيديو باستخدام أوامر نصية.

المستخلص من الورقة البحثية هو كالتالي:

نقدّم نموذج Segment Anything Model (SAM) 3، وهو نموذج موحّد يكشف عن الكائنات ويقسّمها ويتتبّعها في الصور والفيديوهات بناءً على محفّزات المفاهيم، والتي نعرّفها إما على أنها عبارات اسمية قصيرة (مثل "حافلة مدرسية صفراء")، أو أمثلة مصوّرة، أو مزيج من الاثنين معاً. يستقبل تقسيم المفاهيم القابل للمحفّز (PCS) هذه المحفّزات ويعيد أقنعة التقسيم والهويات الفريدة لجميع حالات الكائنات المطابقة. ولتطوير PCS، بنينا محرك بيانات قابل للتوسّع ينتج مجموعة بيانات عالية الجودة تحتوي على 4 ملايين تسمية مفهوم فريدة، بما في ذلك السلبات الصعبة، عبر الصور والفيديوهات. يتكوّن نموذجنا من كاشف على مستوى الصورة ومتتبّع فيديو يعتمد على الذاكرة، يتشاركان في عمود فقري واحد. يتم فصل التعرّف عن تحديد الموقع بواسطة رأس حضور، مما يعزّز دقة الكشف. يضاعف SAM 3 دقة الأنظمة الحالية في كل من PCS للصور والفيديوهات، ويحسّن قدرات SAM السابقة في مهام التقسيم البصري. نفتح مصدر SAM 3 مع معيارنا الجديد Segment Anything with Concepts (SA-Co) لتقسيم المفاهيم القابل للمحفّز.

تمت مساهمة هذا النموذج من قِبل 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

الاستدلال على الفيديو عبر البث

⚠️ **ملاحظة حول جودة الاستدلال البثّي**: يُعطّل الاستدلال البثّي خوارزميات البدء السريع التي تُزيل الكائنات غير المطابقة والمكررة، إذ تتطلب هذه الخوارزميات الوصول إلى الإطارات المستقبلية لاتخاذ قرارات مدروسة. وقد يؤدي ذلك إلى زيادة في اكتشافات الإيجابية الكاذبة ومسارات الكائنات المكررة مقارنةً بالاستدلال على الفيديو المُحمَّل مسبقًا. للحصول على أفضل النتائج، استخدم الاستدلال على الفيديو المُحمَّل مسبقًا عندما تكون جميع الإطارات متاحة.

لتطبيقات الوقت الفعلي، يدعم 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}")

الاستدلال بدقة مخصصة

⚠️ **ملاحظة حول الأداء**: قد تؤدي الدقات المخصصة إلى تدهور الدقة. صُمم النموذج للاستخدام عند دقة 1008 بكسل.

للحصول على استنتاج أسرع أو استخدام أقل للذاكرة:

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 فيديو

نظرة عامة

مثال على الاستخدام

تجزئة الفيديو وتتبعه

استدلال الفيديو المُحمَّل مسبقًا

الاستدلال على الفيديو عبر البث

الاستدلال بدقة مخصصة

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