# SAM3 فيديو

    
        
        
    

## نظرة عامة

SAM3 تم تقديم (Segment Anything Model 3) في [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/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](https://huggingface.co/yonigozlan) و[ronghanghu](https://huggingface.co/ronghanghu).

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

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

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

معالجة فيديو تكون جميع إطاراته متاحة مسبقًا باستخدام أوامر نصية:

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

يمكنك أيضًا تتبع فئات متعددة من الكائنات في الوقت نفسه من خلال تقديم عدة أوامر. يعيد النموذج استخدام ميزات الرؤية بكفاءة عبر جميع الأوامر:

```python
# 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 معالجة إطارات الفيديو لحظة وصولها:

```python
# 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 بكسل.

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

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

## Sam3VideoConfig[[transformers.Sam3VideoConfig]]

#### transformers.Sam3VideoConfig[[transformers.Sam3VideoConfig]]

```python
transformers.Sam3VideoConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, detector_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, tracker_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02, low_res_mask_size: int = 288, score_threshold_detection: float = 0.5, det_nms_thresh: float = 0.1, assoc_iou_thresh: float = 0.1, trk_assoc_iou_thresh: float = 0.5, new_det_thresh: float = 0.7, recondition_on_trk_masks: bool = True, hotstart_delay: int = 15, hotstart_unmatch_thresh: int = 8, hotstart_dup_thresh: int = 8, suppress_unmatched_only_within_hotstart: bool = True, init_trk_keep_alive: int = 30, max_trk_keep_alive: int = 30, min_trk_keep_alive: int = -1, suppress_overlapping_based_on_recent_occlusion_threshold: float = 0.7, decrease_trk_keep_alive_for_empty_masklets: bool = False, fill_hole_area: int = 16, max_num_objects: int = 10000, recondition_every_nth_frame: int = 16, high_conf_thresh: float = 0.8, high_iou_thresh: float = 0.8)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/configuration_sam3_video.py#L28)

**المعاملات:**

detector_config (`dict` أو `Sam3Config`، *اختياري*) : إعدادات نموذج كاشف Sam3. إذا لم يتم تقديمها، فسيتم استخدام Sam3Config الافتراضي.

tracker_config (`dict` أو `Sam2VideoConfig`، *اختياري*) : إعدادات لنموذج متتبع Sam2Video. إذا لم يتم تقديمها، فسيتم استخدام Sam2VideoConfig الافتراضي.

initializer_range (`float`، *اختياري*، القيمة الافتراضية 0.02) : الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة مصفوفات الأوزان.

low_res_mask_size (`int`، *اختياري*، القيمة الافتراضية 288) : حجم (الارتفاع والعرض) لإخراجات القناع منخفضة الدقة من المتتبع قبل إعادة الترميز إلى دقة الفيديو.

score_threshold_detection (`float`، *اختياري*، القيمة الافتراضية 0.5) : عتبة الاحتمال لمخرجات الكشف - يُحتفظ فقط بالكشوفات التي تتجاوز هذه العتبة.

det_nms_thresh (`float`، *اختياري*، القيمة الافتراضية 0.1) : عتبة IoU لكشف NMS (كبح غير الأقصى).

assoc_iou_thresh (`float`، *اختياري*، القيمة الافتراضية 0.1) : عتبة IoU لمطابقة الكشف مع المسار. يُعتبر الكشف "مطابقًا" لمقطع المسار إذا تجاوز تداخله مع مقطع المسار هذه العتبة. غالبًا ما تكون العتبة فضفاضة مثل 0.1.

trk_assoc_iou_thresh (`float`، *اختياري*، القيمة الافتراضية 0.5) : عتبة IoU لمطابقة الكشف مع التتبع، تُستخدم لتحديد ما إذا كان masklet غير مطابق لأي من عمليات الكشف. غالبًا ما تكون العتبة الأكثر صرامة مثل 0.5.

new_det_thresh (`float`، *اختياري*، القيمة الافتراضية 0.7) : عتبة الاحتمال التي يجب أن تتجاوزها عملية الكشف حتى تُضاف ككائن جديد.

recondition_on_trk_masks (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام الأقنعة المُتبعة (True) أو أقنعة الكشف (False) لإعادة التكييف. استخدم True عندما تكون الأقنعة المُتبعة أعلى جودة ويعمل الكاشف كإشارة تحقق لتعزيز الذاكرة ومنع الانحراف.

hotstart_delay (`int`، *اختياري*، القيمة الافتراضية 15) : عدد الإطارات التي يتم تخزينها مؤقتًا للمخرجات أثناء التشغيل الأولي. نؤخر المخرجات لمدة `hotstart_delay` إطارًا ونزيل المسارات الفرعية بناءً على قواعد التشغيل الأولي.

hotstart_unmatch_thresh (`int`، *اختياري*، القيمة الافتراضية 8) : عدد الإطارات غير المطابقة المطلوبة لإزالة المسار أثناء فترة البدء الساخن.

hotstart_dup_thresh (`int`، *اختياري*، القيمة الافتراضية 8) : عدد الإطارات المتداخلة المطلوبة لإزالة مسار مكرر (duplicate tracklet) خلال فترة التشغيل السريع (hotstart).

suppress_unmatched_only_within_hotstart (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب كبت الأقنعة فقط ضمن فترة البدء السريع. إذا كانت القيمة False، يمكننا كبت الأقنعة حتى لو بدأت قبل فترة البدء السريع.

init_trk_keep_alive (`int`، *اختياري*، القيمة الافتراضية 30) : عداد الإبقاء الأولي للمسارات الجديدة.

max_trk_keep_alive (`int`، *اختياري*، القيمة الافتراضية 30) : القيمة القصوى لعداد الإبقاء على الاتصال. تُزاد قيمة العداد للمسارات التي تتطابق مع الكشوفات حتى هذه القيمة.

min_trk_keep_alive (`int`، *اختياري*، القيمة الافتراضية -1) : الحد الأدنى لقيمة عداد الإبقاء على الاتصال. تُخفَّض قيمة عداد المسارات ذات الكشوفات غير المطابقة إلى هذه القيمة.

suppress_overlapping_based_on_recent_occlusion_threshold (`float`، *اختياري*، القيمة الافتراضية 0.7) : العتبة المستخدمة لكبت الكائنات المتداخلة بناءً على الإخفاء الأخير. تُكبت الأقنعة المتداخلة التي تتجاوز قيمتها IoU هذه العتبة بناءً على أيهما كان أخيراً في الإخفاء.

decrease_trk_keep_alive_for_empty_masklets (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب تقليل عداد keep-alive للمناطق القناعية (masklets) ذات المساحة الصفرية في تنبؤ SAM2.

fill_hole_area (`int`، *اختياري*، القيمة الافتراضية 16) : الحد الأدنى للمساحة (بالبكسل) لملء الثقوب في الأقنعة وإزالة البقع الصغيرة.

max_num_objects (`int`، *اختياري*، القيمة الافتراضية 10000) : الحد الأقصى لعدد الكائنات التي يتم تتبعها. القيمة الافتراضية 10000 تعطل هذا الحد فعليًا.

recondition_every_nth_frame (`int`، *اختياري*، القيمة الافتراضية 16) : تكرار إعادة ضبط القناع (بالإطارات). اضبطه على 0 لتعطيل إعادة الضبط.

high_conf_thresh (`float`، *اختياري*، القيمة الافتراضية 0.8) : عتبة الثقة العالية لإعادة الضبط. لا يمكن للكشفات التي تتجاوز هذه العتبة فقط إعادة ضبط مقاطع التتبع.

high_iou_thresh (`float`، *اختياري*، القيمة الافتراضية 0.8) : عتبة IoU العالية لإعادة التكييف. لا يمكن للكشفات التي تتجاوز عتبة IoU هذه فقط إعادة تكييف مقاطع المسار (tracklets).

هذه فئة الإعدادات المخزنة لإعدادات نموذج Sam3VideoModel. تُستخدم لاستحداث نموذج Sam3 Video وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [facebook/sam3](https://huggingface.co/facebook/sam3)

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

مثال:
```python
>>> from transformers import Sam3VideoConfig, Sam3VideoModel

>>> # Initializing a SAM3 Video configuration with default detector and tracker
>>> configuration = Sam3VideoConfig()

>>> # Changing image size for custom resolution inference (automatically propagates to all nested configs)
>>> configuration.image_size = 560

>>> # Initializing a model from the configuration
>>> model = Sam3VideoModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
>>> detector_config = configuration.detector_config
>>> tracker_config = configuration.tracker_config
```

## Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

#### transformers.Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

```python
transformers.Sam3VideoProcessor(image_processor, video_processor, tokenizer, target_size: int | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L39)

**المعاملات:**

image_processor (`Sam3ImageProcessor`) : مُعالج الصور هو مدخل مطلوب.

video_processor (`video_processor_class`) : معالج الفيديو هو مدخل مطلوب.

tokenizer (`CLIPTokenizer`) : مُجزِّئ الرموز هو مدخل مطلوب.

target_size (`int`، *اختياري*) : الحجم المستهدف (target_size, target_size) الذي سيُعاد تحجيم الصورة إليه.

ينشئ Sam3VideoProcessor الذي يجمع معالج الصور ومعالج الفيديو ومجزئ الرموز في معالج واحد.

يوفر [Sam3VideoProcessor](/docs/transformers/main/ar/model_doc/sam3_video#transformers.Sam3VideoProcessor) جميع وظائف [Sam3ImageProcessor](/docs/transformers/main/ar/model_doc/sam3#transformers.Sam3ImageProcessor) و`video_processor_class` و[CLIPTokenizer](/docs/transformers/main/ar/model_doc/clip#transformers.CLIPTokenizer). راجع [~Sam3ImageProcessor](/docs/transformers/main/ar/model_doc/sam3#transformers.Sam3ImageProcessor) و`~video_processor_class` و[~CLIPTokenizer](/docs/transformers/main/ar/model_doc/clip#transformers.CLIPTokenizer) لمزيد من المعلومات.

#### __call__[[transformers.Sam3VideoProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, segmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L55)

**المعاملات:**

images (`ImageInput`، *اختياري*) : الصورة أو الصور المراد معالجتها.

segmentation_maps (`ImageInput`، *اختياري*) : خرائط التقسيم المراد معالجتها (اختياري، لمعالج الصور).

original_sizes (`list[list[float]]`، `torch.Tensor`، *اختياري*) : الأحجام الأصلية للصور. يُستخدم فقط عندما لا يتم توفير الصور.

return_tensors (`Union[str, ~utils.generic.TensorType]`، *اختياري*) : إذا تم تعيينه، فسيُرجع تينسورات (Tensors) لإطار عمل معين. القيم المقبولة هي: - `'pt'`: يُرجع كائنات `torch.Tensor` من PyTorch. - `'np'`: يُرجع كائنات `np.ndarray` من NumPy.

**يعيد:** [BatchEncoding](/docs/transformers/main/ar/main_classes/tokenizer#transformers.BatchEncoding) يحتوي على الحقول التالية

- `pixel_values` (`torch.Tensor`): الصورة المعالجة أو الصور.
- `original_sizes` (`list[list[float]]`): الأبعاد الأصلية للصور.
- `labels` (`torch.Tensor`، *اختياري*): خرائط التقطيع المعالجة (إذا تم توفيرها).

#### postprocess_outputs[[transformers.Sam3VideoProcessor.postprocess_outputs]]

```python
postprocess_outputs(inference_session, model_outputs, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L247)

**المعاملات:**

inference_session (`Sam3VideoInferenceSession`) : كائن جلسة الاستدلال.

model_outputs (`Sam3VideoSegmentationOutput`) : المخرجات الخام للنموذج من `Sam3VideoModel.forward()`.

original_sizes (`list[list[float]]` أو `torch.Tensor`، *اختياري*) : أحجام الإطارات الأصلية الاختيارية [الارتفاع، العرض]. مطلوب للاستدلال البثي عندما لا تكون video_height/video_width مضبوطة في الجلسة.

**يعيد:** `dict`

قاموس يحتوي على المفاتيح التالية:
- **object_ids** (`torch.Tensor` من الشكل `(num_objects,)`): معرّفات الكائنات لكل كائن تم اكتشافه.
- **النتائج** (`torch.Tensor` بأبعاد `(num_objects,)`): نتائج الكشف عن كل كائن.
- **boxes** (`torch.Tensor` من الشكل `(num_objects, 4)`): صناديق الإحاطة بصيغة XYXY (top_left_x, top_left_y, bottom_right_x, bottom_right_y).
- **أقنعة** (`torch.Tensor` من الشكل `(num_objects, height, width)`): أقنعة تجزئة ثنائية لكل كائن عند دقة الفيديو الأصلية.
- **prompt_to_obj_ids** (`dict[str, list[int]]`): تعيين من نص الموجّه إلى قائمة معرّفات الكائنات التي اكتشفها ذلك الموجّه.

معالجة مخرجات النموذج بعد المعالجة للحصول على الأقنعة والعلب والدرجات النهائية.

#### init_video_session[[transformers.Sam3VideoProcessor.init_video_session]]

```python
init_video_session(video: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = None, inference_device: typing.Union[str, ForwardRef('torch.device')] = 'cpu', inference_state_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, processing_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, video_storage_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, max_vision_features_cache_size: int = 1, dtype: dtype = torch.float32)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L133)

**المعاملات:**

video (`VideoInput`، *اختياري*) : الفيديو المراد معالجته. لا حاجة إلى تقديمه عند البث.

inference_device (`str` أو `torch.device`، *اختياري*، الافتراضي "cpu") : الجهاز المستخدم للاستدلال.

inference_state_device (`str` أو `torch.device`، *اختياري*) : الجهاز الذي يُخزَّن عليه حالة الاستدلال.

processing_device (`str` أو `torch.device`، *اختياري*) : الجهاز المستخدم لمعالجة الفيديو.

video_storage_device (`str` أو `torch.device`، *اختياري*) : الجهاز الذي تُخزَّن عليه إطارات الفيديو المعالجة.

max_vision_features_cache_size (`int`، *اختياري*، القيمة الافتراضية 1) : الحد الأقصى لعدد ميزات الرؤية التي يجب تخزينها مؤقتًا.

dtype (`torch.dtype`، *اختياري*، الافتراضي `torch.float32`) : نوع torch الذي سيتم استخدامه للجلسة بأكملها.

يُهيّئ جلسة فيديو للاستدلال. إذا تم توفير فيديو (استدلال غير متزامن)، فسيتم معالجة الفيديو وتخزينه على `video_storage_device`.

#### add_text_prompt[[transformers.Sam3VideoProcessor.add_text_prompt]]

```python
add_text_prompt(inference_session: Sam3VideoInferenceSession, text: str | list[str])
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L101)

**المعاملات:**

inference_session (`Sam3VideoInferenceSession`) : جلسة الاستدلال.

text (`str` أو `list[str]`) : النص أو النصوص التوجيهية التي يجب إضافتها.

**يعيد:** `Sam3VideoInferenceSession`

جلسة الاستدلال مع موجه النص المضاف.

أضف موجهات نصية إلى جلسة الاستدلال.

## Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

#### transformers.Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

```python
transformers.Sam3VideoInferenceSession(video: typing.Optional[torch.Tensor] = None, video_height: int | None = None, video_width: int | None = None, inference_device: typing.Union[torch.device, str] = 'cpu', inference_state_device: typing.Union[torch.device, str] = 'cpu', video_storage_device: typing.Union[torch.device, str] = 'cpu', dtype: typing.Union[torch.dtype, str] = 'float32', max_vision_features_cache_size: int = 1)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L119)

**المعاملات:**

video (`torch.Tensor`، *اختياري*) : الفيديو الذي سيتم معالجته. لا حاجة إلى تقديمه عند البث.

video_height (`int`, *اختياري*) : ارتفاع الفيديو.

video_width (`int`, *اختياري*) : عرض الفيديو.

inference_device (`torch.device`، *اختياري*، الافتراضي `"cpu"`) : الجهاز المستخدم للاستدلال.

inference_state_device (`torch.device`، *اختياري*، الافتراضي `"cpu"`) : الجهاز الذي يُخزَّن عليه حالة الاستدلال.

video_storage_device (`torch.device`، *اختياري*، الافتراضي `"cpu"`) : الجهاز الذي سيتم تخزين الفيديو عليه.

dtype (`torch.dtype`، *اختياري*، الافتراضي `"float32"`) : نوع البيانات (dtype) المستخدم للفيديو.

max_vision_features_cache_size (`int`، *اختياري*، القيمة الافتراضية 1) : الحد الأقصى لعدد ميزات الرؤية التي يجب تخزينها مؤقتًا.

يدير معاملات جلسة الاستدلال على الفيديو وحالتها والذاكرة المؤقتة.

#### add_mask_inputs[[transformers.Sam3VideoInferenceSession.add_mask_inputs]]

```python
add_mask_inputs(obj_idx: int, frame_idx: int, inputs: Tensor)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L255)

أضف مدخلات الأقنعة مع تحديد تلقائي للأجهزة.

#### add_new_frame[[transformers.Sam3VideoInferenceSession.add_new_frame]]

```python
add_new_frame(pixel_values: Tensor, frame_idx: int | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L384)

إضافة إطار جديد مع وضع تلقائي للأجهزة.

#### add_prompt[[transformers.Sam3VideoInferenceSession.add_prompt]]

```python
add_prompt(prompt_text: str)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L215)

أضف موجه نصي إلى الجلسة وأعد معرّفه الفريد. إذا كان الموجه موجودًا مسبقًا، أعد المعرّف الموجود.

#### get_frame[[transformers.Sam3VideoInferenceSession.get_frame]]

```python
get_frame(frame_idx: int)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L400)

الحصول على إطار من الفيديو.

#### get_obj_num[[transformers.Sam3VideoInferenceSession.get_obj_num]]

```python
get_obj_num()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L251)

احصل على العدد الإجمالي للمعرّفات الفريدة للأهداف التي تم استلامها حتى الآن في هذه الجلسة.

#### get_output[[transformers.Sam3VideoInferenceSession.get_output]]

```python
get_output(obj_idx: int, frame_idx: int, output_key: str, is_conditioning_frame: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L357)

**المعاملات:**

obj_idx (int) : فهرس الكائن.

frame_idx (int) : فهرس الإطار.

output_key (str) : مفتاح المخرجات.

is_conditioning_frame (bool) : ما إذا كان المخرج مخصصًا لإطار تكييف.

احصل على المخرجات مع إدارة ذكية للأجهزة.

#### obj_id_to_idx[[transformers.Sam3VideoInferenceSession.obj_id_to_idx]]

```python
obj_id_to_idx(obj_id: int)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L229)

تعيين معرّف الكائن إلى الفهرس، مع إنشاء إدخال جديد عند الحاجة.

#### obj_idx_to_id[[transformers.Sam3VideoInferenceSession.obj_idx_to_id]]

```python
obj_idx_to_id(obj_idx: int)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L247)

تعيين فهرس الكائن على جانب النموذج إلى معرّف الكائن على جانب العميل.

#### remove_mask_inputs[[transformers.Sam3VideoInferenceSession.remove_mask_inputs]]

```python
remove_mask_inputs(obj_idx: int, frame_idx: int)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L261)

إزالة مدخلات القناع.

#### remove_object[[transformers.Sam3VideoInferenceSession.remove_object]]

```python
remove_object(obj_id: int, strict: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L265)

**المعاملات:**

obj_id (`int`) : معرّف الكائن المراد إزالته.

strict (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب رفع خطأ إذا لم يكن الكائن موجودًا.

إزالة كائن من جلسة الاستدلال. يؤدي هذا إلى إزالة الكائن من جميع الإطارات في الفيديو.

#### reset_inference_session[[transformers.Sam3VideoInferenceSession.reset_inference_session]]

```python
reset_inference_session()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L416)

إعادة تعيين بيانات التتبع والذاكرة المؤقتة.

#### reset_state[[transformers.Sam3VideoInferenceSession.reset_state]]

```python
reset_state()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L428)

إعادة تعيين حالة جلسة الاستدلال.

#### reset_tracking_data[[transformers.Sam3VideoInferenceSession.reset_tracking_data]]

```python
reset_tracking_data()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L404)

إعادة تعيين بيانات التتبع مع الاحتفاظ بالذاكرة المؤقتة.

#### store_output[[transformers.Sam3VideoInferenceSession.store_output]]

```python
store_output(obj_idx: int, frame_idx: int, output_key: str | None = None, output_value: typing.Union[torch.Tensor, dict, NoneType] = None, is_conditioning_frame: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L320)

**المعاملات:**

obj_idx (int) : فهرس الكائن.

frame_idx (int) : فهرس الإطار.

output_key (Optional[str]) : مفتاح المخرجات. إذا كان None، تُخزَّن المخرجات كقاموس.

output_value (Optional[Union[torch.Tensor, dict]]) : قيمة المخرجات.

is_conditioning_frame (bool) : ما إذا كان المخرج مخصصًا لإطار تكييف.

تخزين المخرجات مع إدارة ذكية للأجهزة. إذا كانت output_key تساوي None، يتم تخزين المخرجات كقاموس.

## Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

#### transformers.Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

```python
transformers.Sam3VideoSegmentationOutput(object_ids: list[int] | None = None, obj_id_to_mask: dict[int, torch.Tensor] | None = None, obj_id_to_score: dict[int, float] | None = None, obj_id_to_tracker_score: dict[int, float] | None = None, removed_obj_ids: set[int] | None = None, suppressed_obj_ids: set[int] | None = None, frame_idx: int | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L462)

**المعاملات:**

object_ids (`list[int]`، *اختياري*) : قائمة معرّفات الكائنات التي يتم تتبعها في الإطار الحالي.

obj_id_to_mask (`dict[int, torch.Tensor]`، *اختياري*) : قاموس يربط معرّفات الكائنات بأقنعتها منخفضة الدقة المتوقعة. كل قناع له الشكل `(1, H_low, W_low)`.

obj_id_to_score (`dict[int, float]`، *اختياري*) : قاموس يربط معرّفات الكائنات بدرجة اكتشافها.

obj_id_to_tracker_score (`dict[int, float]`، *اختياري*) : قاموس يربط معرّفات الكائنات بدرجة تتبعها في الإطار الحالي.

removed_obj_ids (`set[int]`، *اختياري*) : مجموعة من معرّفات الكائنات التي تمّ حذفها (على سبيل المثال، عبر خوارزميات البدء السريع).

suppressed_obj_ids (`set[int]`، *اختياري*) : مجموعة من معرّفات الكائنات التي تم كبتها في الإطار الحالي.

frame_idx (`int`, *اختياري*) : فهرس الإطار في الفيديو.

الفئة الأساسية لمخرجات نموذج Sam3Video.

## Sam3VideoModel[[transformers.Sam3VideoModel]]

#### transformers.Sam3VideoModel[[transformers.Sam3VideoModel]]

```python
transformers.Sam3VideoModel(config: Sam3VideoConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L507)

**المعاملات:**

config ([Sam3VideoConfig](/docs/transformers/main/ar/model_doc/sam3_video#transformers.Sam3VideoConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

نموذج Sam3 Video الأساسي الذي يُخرج حالات مخفية خام دون أي رأس محدد في الأعلى.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.Sam3VideoModel.forward]]

```python
forward(inference_session: Sam3VideoInferenceSession, frame_idx: int | None = None, frame: typing.Optional[torch.Tensor] = None, reverse: bool = False, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L1693)

**المعاملات:**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : كائن جلسة الاستدلال على الفيديو.

frame_idx (`int`, *اختياري*) : فهرس الإطار الذي سيتم تشغيل الاستدلال عليه. لا حاجة إلى تقديمه عند الاستدلال على إطار جديد تم بثه.

frame (`torch.Tensor`، *اختياري*) : الإطار الذي سيتم معالجته. يُقدَّم عند البث.

reverse (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب نشر القيم في الاتجاه العكسي.

نشر الكائنات عبر إطار فيديو مُبَثّ.

#### propagate_in_video_iterator[[transformers.Sam3VideoModel.propagate_in_video_iterator]]

```python
propagate_in_video_iterator(inference_session: Sam3VideoInferenceSession, start_frame_idx: int = 0, max_frame_num_to_track: int | None = None, reverse: bool = False, show_progress_bar: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L1784)

**المعاملات:**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : كائن جلسة الاستدلال على الفيديو.

start_frame_idx (`int`، *اختياري*، القيمة الافتراضية `0`) : فهرس الإطار الابتدائي للانتشار.

max_frame_num_to_track (`int`، *اختياري*) : الحد الأقصى لعدد الإطارات التي سيتم تتبعها. إذا لم يُقدَّم، فسيتم تتبع جميع الإطارات في الفيديو.

reverse (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب نشر القيم في الاتجاه العكسي.

show_progress_bar (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب عرض شريط تقدّم أثناء الانتشار.

**يعيد:** [Sam3VideoSegmentationOutput](/docs/transformers/main/ar/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) أو `tuple(torch.Tensor)`

[Sam3VideoSegmentationOutput](/docs/transformers/main/ar/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) أو مجموعة مرتبة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) تتكون من عناصر مختلفة اعتماداً على الإعداد ([Sam3VideoConfig](/docs/transformers/main/ar/model_doc/sam3_video#transformers.Sam3VideoConfig)) والمدخلات.

نشر المُوجِّهات للحصول على نتائج التثبيت (Grounding) للفيديو بأكمله. يُستخدم عند تهيئة جلسة استدلال (Inference) بفيديو كامل. يُنتج Sam3VideoSegmentationOutput لكل إطار.

- **object_ids** (`list[int]`، *اختياري*) -- قائمة بمعرّفات الكائنات التي يتم تتبعها في الإطار الحالي.
- **obj_id_to_mask** (`dict[int, torch.Tensor]`، *اختياري*) -- قاموس يربط معرّفات الكائنات بأقنعتها منخفضة الدقة المتوقعة. كل قناع له الشكل `(1, H_low, W_low)`.
- **obj_id_to_score** (`dict[int, float]`، *اختياري*) -- قاموس يربط معرّفات الكائنات بدرجة اكتشافها.
- **obj_id_to_tracker_score** (`dict[int, float]`، *اختياري*) -- قاموس يربط معرّفات الكائنات بدرجة تتبّعها في الإطار الحالي.
- **removed_obj_ids** (`set[int]`، *اختياري*) -- مجموعة من معرّفات الكائنات التي تم حذفها (على سبيل المثال، عبر خوارزميات البدء السريع).
- **suppressed_obj_ids** (`set[int]`، *اختياري*) -- مجموعة من معرّفات الكائنات التي تم كتمها في الإطار الحالي.
- **frame_idx** (`int`، *اختياري*) -- فهرس الإطار في الفيديو.