# D-FINE

## نظرة عامة

قُدم نموذج D-FINE في [D-FINE: Redefine Regression Task in DETRs as Fine-grained Distribution Refinement](https://huggingface.co/papers/2410.13842) بواسطة Yansong Peng وHebei Li وPeixi Wu وYueyi Zhang وXiaoyan Sun وFeng Wu

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

*نقدّم D-FINE، وهو مُكتشف كائنات فوري قوي يحقق دقة تحديد موقع استثنائية من خلال إعادة تعريف مهمة انحدار صندوق الحدود في نماذج DETR. يتكوّن D-FINE من مكوّنين رئيسيين: تحسين التوزيع الدقيق (FDR) والتبسيط الذاتي للتحديد الأمثل الشامل (GO-LSD). يحوّل FDR عملية الانحدار من تنبؤ إحداثيات ثابتة إلى تحسين التوزيعات الاحتمالية بشكل تكراري، مما يوفر تمثيلاً وسيطاً دقيقاً يعزز دقة تحديد الموقع بشكل كبير. أما GO-LSD فهو استراتيجية تحسين ثنائية الاتجاه تنقل معرفة تحديد الموقع من التوزيعات المُحسَّنة إلى الطبقات الأضحى عبر التبسيط الذاتي، مع تبسيط مهام التنبؤ بالمتبقي للطبقات الأعمق. بالإضافة إلى ذلك، يدمج D-FINE تحسينات خفيفة في الوحدات والعمليات كثيفة الحساب، مما يحقق توازناً أفضل بين السرعة والدقة. تحديداً، يحقق D-FINE-L / X دقة AP بنسبة 54.0% / 55.8% على مجموعة بيانات COCO بمعدل 124 / 78 إطاراً في الثانية على بطاقة NVIDIA T4. عند التدريب المسبق على Objects365، يحقق D-FINE-L / X دقة AP بنسبة 57.1% / 59.3%، متجاوزاً جميع مُكتشفي الكائنات الفورية الحالية. علاوة على ذلك، تعزز طريقتنا أداء مجموعة واسعة من نماذج DETR بنسبة تصل إلى 5.3% AP مع تكلفة إضافية شبه معدومة في المعاملات والتدريب. كودنا والنماذج المُدرَّبة مسبقاً: هذا رابط URL.*

تمت مساهمة هذا النموذج من قِبل [VladOS95-cyber](https://github.com/VladOS95-cyber). يمكن العثور على الكود الأصلي [هنا](https://github.com/Peterande/D-FINE).

## نصائح للاستخدام

```python
import torch

from transformers import AutoImageProcessor, DFineForObjectDetection
from transformers.image_utils import load_image

url = 'http://images.cocodataset.org/val2017/000000039769.jpg'
image = load_image(url)

image_processor = AutoImageProcessor.from_pretrained("ustc-community/dfine_x_coco")
model = DFineForObjectDetection.from_pretrained("ustc-community/dfine_x_coco", device_map="auto")

inputs = image_processor(images=image, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

results = image_processor.post_process_object_detection(outputs, target_sizes=[(image.height, image.width)], threshold=0.5)

for result in results:
    for score, label_id, box in zip(result["scores"], result["labels"], result["boxes"]):
        score, label = score.item(), label_id.item()
        box = [round(i, 2) for i in box.tolist()]
        print(f"{model.config.id2label[label]}: {score:.2f} {box}")
cat: 0.96 [344.49, 23.4, 639.84, 374.27]
cat: 0.96 [11.71, 53.52, 316.64, 472.33]
remote: 0.95 [40.46, 73.7, 175.62, 117.57]
sofa: 0.92 [0.59, 1.88, 640.25, 474.74]
remote: 0.89 [333.48, 77.04, 370.77, 187.3]
```

## DFineConfig[[transformers.DFineConfig]]

#### transformers.DFineConfig[[transformers.DFineConfig]]

```python
transformers.DFineConfig(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, 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, is_encoder_decoder: bool = True, initializer_range: float = 0.01, initializer_bias_prior_prob: float | None = None, layer_norm_eps: float = 1e-05, batch_norm_eps: float = 1e-05, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, freeze_backbone_batch_norms: bool = True, encoder_hidden_dim: int = 256, encoder_in_channels: list[int] | tuple[int, ...] = (512, 1024, 2048), feat_strides: list[int] | tuple[int, ...] = (8, 16, 32), encoder_layers: int = 1, encoder_ffn_dim: int = 1024, encoder_attention_heads: int = 8, dropout: float | int = 0.0, activation_dropout: float | int = 0.0, encode_proj_layers: list[int] | tuple[int, ...] = (2,), positional_encoding_temperature: int = 10000, encoder_activation_function: str = 'gelu', activation_function: str = 'silu', eval_size: int | None = None, normalize_before: bool = False, hidden_expansion: float = 1.0, d_model: int = 256, num_queries: int = 300, decoder_in_channels: list[int] | tuple[int, ...] = (256, 256, 256), decoder_ffn_dim: int = 1024, num_feature_levels: int = 3, decoder_n_points: int | list[int] = 4, decoder_layers: int = 6, decoder_attention_heads: int = 8, decoder_activation_function: str = 'relu', attention_dropout: float | int = 0.0, num_denoising: int = 100, label_noise_ratio: float = 0.5, box_noise_scale: float = 1.0, learn_initial_query: bool = False, anchor_image_size: int | list[int] | None = None, with_box_refine: bool = True, matcher_alpha: float = 0.25, matcher_gamma: float = 2.0, matcher_class_cost: float = 2.0, matcher_bbox_cost: float = 5.0, matcher_giou_cost: float = 2.0, use_focal_loss: bool = True, auxiliary_loss: bool = True, focal_loss_alpha: float = 0.75, focal_loss_gamma: float = 2.0, weight_loss_vfl: float = 1.0, weight_loss_bbox: float = 5.0, weight_loss_giou: float = 2.0, weight_loss_fgl: float = 0.15, weight_loss_ddf: float = 1.5, eos_coefficient: float = 0.0001, eval_idx: int = -1, layer_scale: int | float = 1.0, max_num_bins: int = 32, reg_scale: float = 4.0, depth_mult: float = 1.0, top_prob_values: int = 4, lqe_hidden_dim: int = 64, lqe_layers: int = 2, decoder_offset_scale: float = 0.5, decoder_method: str = 'default', up: float = 0.5, tie_word_embeddings: bool = True)
```

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

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

is_encoder_decoder (`bool`، *اختياري*، الافتراضي هو `True`) : ما إذا كان النموذج يُستخدم كمُشفِّر/مُفكِّك أم لا.

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

initializer_bias_prior_prob (`float`, *اختياري*) : الاحتمال المسبق الذي يستخدمه مُهيّئ الانحيازات (bias initializer) لتهيئة الانحيازات الخاصة بـ`enc_score_head` و`class_embed`. إذا كانت القيمة `None`، يتم حساب `prior_prob` على النحو `prior_prob = 1 / (num_labels + 1)` أثناء تهيئة أوزان النموذج.

layer_norm_eps (`float`، *اختياري*، القيمة الافتراضية `1e-05`) : قيمة الإيبسلون المستخدمة في طبقات تطبيع الطبقة.

batch_norm_eps (`float`، *اختياري*، القيمة الافتراضية `1e-05`) : قيمة الإيبسلون المستخدمة في طبقات تطبيع الدفعة.

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`، *اختياري*) : إعدادات نموذج الهيكل الأساسي.

freeze_backbone_batch_norms (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم تجميد طبقات تطبيع الدفعة في الهيكل الأساسي.

encoder_hidden_dim (`int`، *اختياري*، القيمة الافتراضية `256`) : بُعد التمثيلات المخفية.

encoder_in_channels (`list`، *اختياري*، القيمة الافتراضية `[512, 1024, 2048]`) : مدخلات ميزات متعددة المستويات للمُشفِّر.

feat_strides (`list[int]`، *اختياري*، القيمة الافتراضية `[8, 16, 32]`) : الخطوات المستخدمة في كل خريطة ميزات.

encoder_layers (`int`، *اختياري*، القيمة الافتراضية `1`) : عدد الطبقات المخفية في مُشفِّر Transformer. سيستخدم القيمة نفسها لـ`num_layers` إذا لم يتم ضبطه.

encoder_ffn_dim (`int`، *اختياري*، القيمة الافتراضية `1024`) : بُعد طبقة "الوسيطة" (التي تُسمّى غالبًا بالطبقة الأمامية) في المُشفِّر.

encoder_attention_heads (`int`، *اختياري*، القيمة الافتراضية `8`) : عدد رؤوس الانتباه لكل طبقة انتباه في مُشفِّر Transformer.

dropout (`Union[float, int]`، *اختياري*، القيمة الافتراضية `0.0`) : نسبة جميع طبقات dropout.

activation_dropout (`Union[float, int]`، *اختياري*، القيمة الافتراضية `0.0`) : نسبة الإسقاط (dropout) للتفعيلات داخل الطبقة المتصلة بالكامل.

encode_proj_layers (`list[int]`، *اختياري*، القيمة الافتراضية `[2]`) : فهارس الطبقات المُسقطَة التي سيتم استخدامها في المُشفِّر.

positional_encoding_temperature (`int`، *اختياري*، القيمة الافتراضية 10000) : معامل الحرارة المستخدم لإنشاء الترميزات الموضعية.

encoder_activation_function (`str`، *اختياري*، القيمة الافتراضية `"gelu"`) : دالة التنشيط غير الخطية (دالة أو نص) في المُشفِّر والمجمِّع. إذا كان نصًا، فالدوال المدعومة هي `"gelu"`، `"relu"`، `"silu"` و`"gelu_new"`.

activation_function (`str`، *اختياري*، القيمة الافتراضية `silu`) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، `"gelu"`، `"relu"`، `"silu"`، وما إلى ذلك.

eval_size (`tuple[int, int]`، *اختياري*) : الارتفاع والعرض المستخدمان لحساب الارتفاع والعرض الفعليين لتضمينات المواقع بعد مراعاة الخطوة (stride).

normalize_before (`bool`، *اختياري*، القيمة الافتراضية `False`) : تحديد ما إذا كان سيتم تطبيق تطبيع الطبقة في طبقة مُشفِّر الترانسفورمر قبل وحدات الانتباه الذاتي والتغذية الأمامية.

hidden_expansion (`float`، *اختياري*، القيمة الافتراضية 1.0) : نسبة التوسيع لتكبير حجم الأبعاد في RepVGGBlock و CSPRepLayer.

d_model (`int`، *اختياري*، القيمة الافتراضية `256`) : حجم طبقات المُشفِّر وطبقة المُجمِّع.

num_queries (`int`، *اختياري*، القيمة الافتراضية 300) : عدد استعلامات الكائنات.

decoder_in_channels (`list`، *اختياري*، القيمة الافتراضية `[256, 256, 256]`) : أبعاد الميزات متعددة المستويات لفك الترميز

decoder_ffn_dim (`int`، *اختياري*، القيمة الافتراضية `1024`) : بُعد طبقة "الوسيطة" (التي تُسمّى غالبًا طبقة التغذية الأمامية) في المُفكِّك.

num_feature_levels (`int`، *اختياري*، القيمة الافتراضية 3) : عدد مستويات ميزات الإدخال.

decoder_n_points (`int`، *اختياري*، القيمة الافتراضية 4) : عدد المفاتيح المُستخرجة في كل مستوى من مستويات الميزات لكل رأس من رؤوس الانتباه في المُفكِّك.

decoder_layers (`int`، *اختياري*، القيمة الافتراضية `6`) : عدد الطبقات المخفية في مُفكِّك Transformer. سيستخدم القيمة نفسها لـ`num_layers` إذا لم يتم ضبطه.

decoder_attention_heads (`int`، *اختياري*، القيمة الافتراضية `8`) : عدد رؤوس الانتباه في كل طبقة انتباه داخل مُفكِّك Transformer.

decoder_activation_function (`str`، *اختياري*، القيمة الافتراضية `"relu"`) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. إذا كان نصًا، فالدوال المدعومة هي `"gelu"`، `"relu"`، `"silu"` و`"gelu_new"`.

attention_dropout (`Union[float, int]`، *اختياري*، القيمة الافتراضية `0.0`) : نسبة الإسقاط (dropout) لاحتمالات الانتباه.

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

label_noise_ratio (`float`، *اختياري*، القيمة الافتراضية 0.5) : نسبة تسميات إزالة الضوضاء التي يجب إضافة ضوضاء عشوائية إليها.

box_noise_scale (`float`، *اختياري*، القيمة الافتراضية 1.0) : مقدار الضوضاء أو حجمها الذي سيُضاف إلى صناديق الحدود.

learn_initial_query (`bool`، *اختياري*، القيمة الافتراضية `False`) : يحدد ما إذا كان يجب تعلّم تمثيلات الاستعلام الأولية لمفكّك الترميز أثناء التدريب

anchor_image_size (`tuple[int, int]`، *اختياري*) : ارتفاع وعرض صورة الإدخال المستخدمة أثناء التقييم لتوليد أطر الحدود. إذا كانت القيمة None، يتم تطبيق توليد تلقائي للأطر.

with_box_refine (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم تطبيق تحسين تكراري لصفحات الحدود، حيث تُحسّن كل طبقة من طبقات المُفكِّك (decoder) صفحات الحدود بناءً على التنبؤات القادمة من الطبقة السابقة.

matcher_alpha (`float`، *اختياري*، القيمة الافتراضية 0.25) : معامل alpha المستخدم في Hungarian Matcher.

matcher_gamma (`float`، *اختياري*، القيمة الافتراضية 2.0) : معامل gamma المستخدم في Hungarian Matcher.

matcher_class_cost (`float`، *اختياري*، القيمة الافتراضية 2.0) : الوزن النسبي لخسارة الفئة المستخدمة في Hungarian Matcher.

matcher_bbox_cost (`float`، *اختياري*، القيمة الافتراضية 5.0) : الوزن النسبي لخسارة صندوق الحدود (bounding box loss) المستخدم في Hungarian Matcher.

matcher_giou_cost (`float`، *اختياري*، القيمة الافتراضية 2.0) : الوزن النسبي لخسارة giou المستخدمة في Hungarian Matcher.

use_focal_loss (`bool`، *اختياري*، القيمة الافتراضية `True`) : معامل يُخبر ما إذا كان يجب استخدام خسارة التركيز (focal loss).

auxiliary_loss (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام خسائر فك الترميز المساعدة (الخسائر في كل طبقة من طبقات فك الترميز).

focal_loss_alpha (`float`، *اختياري*، القيمة الافتراضية 0.75) : معامل alpha المستخدم لحساب الخسارة البؤرية (focal loss).

focal_loss_gamma (`float`، *اختياري*، القيمة الافتراضية 2.0) : معامل gamma المستخدم لحساب الخسارة البؤرية (focal loss).

weight_loss_vfl (`float`، *اختياري*، القيمة الافتراضية 1.0) : الوزن النسبي لخسارة varifocal في خسارة كشف الكائنات.

weight_loss_bbox (`float`، *اختياري*، القيمة الافتراضية 5.0) : الوزن النسبي لخسارة صندوق الحدود L1 في خسارة كشف الكائنات.

weight_loss_giou (`float`، *اختياري*، القيمة الافتراضية 2.0) : الوزن النسبي لخسارة IoU المعممة في خسارة كشف الكائنات.

weight_loss_fgl (`float`، *اختياري*، القيمة الافتراضية 0.15) : الوزن النسبي لخسارة تحديد الموقع الدقيقة في خسارة كشف الكائنات.

weight_loss_ddf (`float`، *اختياري*، القيمة الافتراضية 1.5) : الوزن النسبي لخسارة التركيز (focal loss) للتقطير المنفصل في خسارة كشف الكائنات.

eos_coefficient (`float`، *اختياري*، القيمة الافتراضية `0.0001`) : وزن التصنيف النسبي لفئة "لا يوجد كائن" في خسارة كشف الكائنات.

eval_idx (`int`، *اختياري*، القيمة الافتراضية -1) : فهرس طبقة المُفكِّك (decoder) المستخدمة للتقييم. إذا كان سالبًا، يُحسب من النهاية (مثلًا، -1 تعني استخدام الطبقة الأخيرة). وهذا يتيح التنبؤ المبكر في مكدس المُفكِّك مع الاستمرار في تدريب الطبقات اللاحقة.

layer_scale (`float`, *اختياري*, القيمة الافتراضية `1.0`) : معامل التوسيع للبعد الخفي في طبقات المُفكِّك اللاحقة. يُستخدم لضبط سعة النموذج بعد طبقة التقييم.

max_num_bins (`int`، *اختياري*، القيمة الافتراضية 32) : الحد الأقصى لعدد الخلايا (bins) لتحسين صندوق الحدود الموجّه بالتوزيع. تتيح القيم الأعلى تحديدًا أدق للموقع، لكنها تزيد من حجم الحسابات.

reg_scale (`float`، *اختياري*، القيمة الافتراضية 4.0) : معامل المقياس لتوزيع الانحدار. يتحكم في مدى ودقة عملية تحسين صندوق الحدود.

depth_mult (`float`، *اختياري*، القيمة الافتراضية 1.0) : مُضاعِف لعدد الكتل في طبقات RepNCSPELAN4. يُستخدم لتغيير عمق النموذج مع الحفاظ على بنيته.

top_prob_values (`int`، *اختياري*، القيمة الافتراضية 4) : عدد قيم الاحتمالية الأعلى التي يجب أخذها في الاعتبار من توزيع كل زاوية.

lqe_hidden_dim (`int`، *اختياري*، القيمة الافتراضية 64) : حجم البُعد المخفي لشبكة تقدير جودة الموقع (LQE).

lqe_layers (`int`، *اختياري*، القيمة الافتراضية 2) : عدد الطبقات في شبكة MLP الخاصة بمقدّر جودة الموقع.

decoder_offset_scale (`float`، *اختياري*، القيمة الافتراضية 0.5) : معامل الإزاحة المستخدم في الانتباه القابل للتشوه.

decoder_method (`str`، *اختياري*، الافتراضي `"default"`) : الطريقة المستخدمة للمفكّك: `"default"` أو `"discrete"`.

up (`float`، *اختياري*، القيمة الافتراضية 0.5) : يتحكم في الحدود العليا لدالة الوزن.

tie_word_embeddings (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب ربط ترميزات الأوزان وفقاً لخريطة `tied_weights_keys` الخاصة بالنموذج.

هذه فئة الإعدادات (configuration class) لتخزين إعدادات نموذج DFineModel. تُستخدم لاستحداث نموذج D Fine وفقًا للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ [ustc-community/dfine-xlarge-coco](https://huggingface.co/ustc-community/dfine-xlarge-coco)

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

## DFineModel[[transformers.DFineModel]]

#### transformers.DFineModel[[transformers.DFineModel]]

```python
transformers.DFineModel(config: DFineConfig)
```

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

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

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

نموذج RT-DETR (المكوّن من هيكل أساسي ومشفّر-فكّ تشفير) الذي يُخرج حالات مخفية خام دون أي رأس في الأعلى.

يرث هذا النموذج من [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.DFineModel.forward]]

```python
forward(pixel_values: Tensor, pixel_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: list[dict] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

pixel_values (`torch.Tensor` من الشكل `(batch_size, num_channels, image_size, image_size)`) : المصفوفات المتناظرة مع الصور المدخلة. يمكن الحصول على قيم البكسل باستخدام `image_processor_class`. راجع `image_processor_class.__call__` للتفاصيل (`processor_class` يستخدم `image_processor_class` لمعالجة الصور).

pixel_mask (`torch.LongTensor` من الشكل `(batch_size, height, width)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه على قيم البكسلات المعبأة. قيم القناع المختارة في `[0, 1]`: - 1 للبكسلات الحقيقية (أي **غير المقنّعة**)، - 0 للبكسلات المعبأة (أي **المقنّعة**). [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

encoder_outputs (`torch.Tensor`، *اختياري*) : Tuple يتكون من (`last_hidden_state`، *اختياري*: `hidden_states`، *اختياري*: `attentions`) `last_hidden_state` من الشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) هو تسلسل من حالات الخفاء عند مخرج الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع (cross-attention) في المُفكِّك.

inputs_embeds (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) : بدلاً من تمرير خريطة الميزات المسطحة (مخرجات العمود الفقري وطبقة الإسقاط)، يمكنك اختيار تمرير تمثيل مسطح للصورة مباشرةً.

labels (`list[Dict]` بطول `(batch_size,)`، *اختياري*) : تسميات لحساب خسارة المطابقة الثنائية. قائمة من القواميس، يحتوي كل قاموس على الأقل على المفتاحين التاليين: 'class_labels' و 'boxes' (تسميات الفئات وصناديق الحدود لصورة في الدفعة على التوالي). يجب أن تكون تسميات الفئات نفسها `torch.LongTensor` بطول `(number of bounding boxes in the image,)` وأن تكون الصناديق `torch.Tensor` بشكل `(number of bounding boxes in the image, 4)`.

**يعيد:** `DFineModelOutput` أو `tuple(torch.Tensor)`

A `DFineModelOutput` or a tuple of `torch.Tensor` (if `return_dict=False` is passed or when `config.return_dict=False`) comprising various elements depending on the configuration (`None`) and inputs.

تتجاوز طريقة [DFineModel](/docs/transformers/main/ar/model_doc/d_fine#transformers.DFineModel) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن `Module` بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.

- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, num_queries, hidden_size)`) -- تسلسل من حالات الإخفاء عند مخرج الطبقة الأخيرة من فاحص النموذج.
- **intermediate_hidden_states** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, num_queries, hidden_size)`) -- حالات مخفية وسيطة مكدسة (مخرجات كل طبقة من فاحم الشيفر).
- **intermediate_logits** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, sequence_length, config.num_labels)`) -- القيم اللوجستية الوسيطة المتراكمة (القيم اللوجستية لكل طبقة من طبقات المُفكِّك).
- **intermediate_reference_points** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, num_queries, 4)`) -- نقاط مرجعية وسيطة مكدسة (نقاط مرجعية لكل طبقة من طبقات المُفكِّك).
- **intermediate_predicted_corners** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, num_queries, 4)`) -- زوايا متوسطة متوقعة مكدّسة (الزوايا المتوقعة لكل طبقة من طبقات المُفكِّك).
- **initial_reference_points** (`torch.Tensor` من الشكل `(batch_size, num_queries, 4)`) -- نقاط المرجع الأولية المستخدمة لطبقة فك الترميز الأولى.
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, sequence_length, hidden_size)`.

  حالات المخفية (Hidden states) لمفكّك الترميز (decoder) عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي (initial embedding).
- **decoder_attentions** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه في المفكّك، بعد softmax الانتباه، المستخدمة لحساب المتوسط المرجّح في رؤوس الانتباه الذاتي.
- **cross_attentions** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه في طبقة الانتباه المتقاطع للمفكّك، بعد softmax للانتباه، وتُستخدم لحساب المتوسط المرجّح في رؤوس الانتباه المتقاطع.
- **encoder_last_hidden_state** (`torch.Tensor` بشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) -- سلسلة من حالات الإخفاء عند مخرجات الطبقة الأخيرة من المُشفِّر في النموذج.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, sequence_length, hidden_size)`.

  حالات المخفية للمشفّر عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي.
- **encoder_attentions** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه للمُشفِّر، بعد softmax للانتباه، المُستخدَمة لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
- **init_reference_points** (`torch.Tensor` من الشكل `(batch_size, num_queries, 4)`) -- نقاط المرجع الأولية المُرسلة عبر مُفكِّك Transformer.
- **enc_topk_logits** (`torch.Tensor` من الشكل `(batch_size, sequence_length, config.num_labels)`) -- درجات الصناديق المحيطة المتوقعة، حيث يتم اختيار الصناديق المحيطة الأعلى تقييماً وعددها `config.two_stage_num_proposals` كإقتراحات مناطق في مرحلة المُشفِّر. مخرجات التصنيف الثنائي للصناديق المحيطة (أي المقدمة والخلفية).
- **enc_topk_bboxes** (`torch.Tensor` من الشكل `(batch_size, sequence_length, 4)`) -- قيم اللوجيتات لإحداثيات صناديق الحدود المتوقعة في مرحلة المُشفِّر.
- **enc_outputs_class** (`torch.Tensor` من الشكل `(batch_size, sequence_length, config.num_labels)`، *اختياري*، يُعاد عند `config.with_box_refine=True` و`config.two_stage=True`) -- درجات الصناديق المحيطة المتوقعة حيث يتم اختيار أعلى `config.two_stage_num_proposals` صناديق محيطة من حيث الدرجات كإقتراحات مناطق في المرحلة الأولى. مخرجات التصنيف الثنائي للصناديق المحيطة (أي المقدمة والخلفية).
- **enc_outputs_coord_logits** (`torch.Tensor` من الشكل `(batch_size, sequence_length, 4)`، *اختياري*، يُعاد عند `config.with_box_refine=True` و`config.two_stage=True`) -- قيم اللوجيتات الخاصة بإحداثيات صناديق الحدود المتوقعة في المرحلة الأولى.
- **denoising_meta_values** (`dict`، *اختياري*) -- قاموس إضافي للقيم المتعلقة بإزالة الضوضاء.

أمثلة:

```python
>>> from transformers import AutoImageProcessor, DFineModel
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> image_processor = AutoImageProcessor.from_pretrained("PekingU/DFine_r50vd")
>>> model = DFineModel.from_pretrained("PekingU/DFine_r50vd")

>>> inputs = image_processor(images=image, return_tensors="pt")

>>> outputs = model(**inputs)

>>> last_hidden_states = outputs.last_hidden_state
>>> list(last_hidden_states.shape)
[1, 300, 256]
```

## DFineForObjectDetection[[transformers.DFineForObjectDetection]]

#### transformers.DFineForObjectDetection[[transformers.DFineForObjectDetection]]

```python
transformers.DFineForObjectDetection(config: DFineConfig)
```

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

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

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

نموذج RT-DETR (المكوّن من هيكل أساسي ومشفّر-فكّاش) يُخرج صناديق تحديد الحدود والقيم اللوجستية ليتم فكّ تشفيرها لاحقاً إلى درجات وفئات.

يرث هذا النموذج من [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.DFineForObjectDetection.forward]]

```python
forward(pixel_values: Tensor, pixel_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: list[dict] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

pixel_values (`torch.Tensor` من الشكل `(batch_size, num_channels, image_size, image_size)`) : المصفوفات المتناظرة مع الصور المدخلة. يمكن الحصول على قيم البكسل باستخدام `image_processor_class`. راجع `image_processor_class.__call__` للتفاصيل (`processor_class` يستخدم `image_processor_class` لمعالجة الصور).

pixel_mask (`torch.LongTensor` من الشكل `(batch_size, height, width)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه على قيم البكسلات المعبأة. قيم القناع المختارة في `[0, 1]`: - 1 للبكسلات الحقيقية (أي **غير المقنّعة**)، - 0 للبكسلات المعبأة (أي **المقنّعة**). [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

encoder_outputs (`torch.Tensor`، *اختياري*) : Tuple يتكون من (`last_hidden_state`، *اختياري*: `hidden_states`، *اختياري*: `attentions`) `last_hidden_state` من الشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) هو تسلسل من حالات الخفاء عند مخرج الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع (cross-attention) في المُفكِّك.

inputs_embeds (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) : بدلاً من تمرير `input_ids`، يمكنك اختيار تمرير تمثيل مضمّن مباشرةً. هذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارس `input_ids` إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.

labels (`list[Dict]` بطول `(batch_size,)`، *اختياري*) : تسميات لحساب خسارة المطابقة الثنائية. قائمة من القواميس، يحتوي كل قاموس على الأقل على المفتاحين التاليين: 'class_labels' و 'boxes' (تسميات الفئات وصناديق الحدود لصورة في الدفعة على التوالي). يجب أن تكون تسميات الفئات نفسها `torch.LongTensor` بطول `(number of bounding boxes in the image,)` وأن تكون الصناديق `torch.Tensor` بشكل `(number of bounding boxes in the image, 4)`.

**يعيد:** `DFineObjectDetectionOutput` أو `tuple(torch.Tensor)`

`DFineObjectDetectionOutput` أو مجموعة مرتبة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتمادًا على الإعداد (`None`) والمدخلات.

تتجاوز طريقة [DFineForObjectDetection](/docs/transformers/main/ar/model_doc/d_fine#transformers.DFineForObjectDetection) الأمامية الطريقة الخاصة `__call__`.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن `Module` بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.

- **loss** (`torch.Tensor` of shape `(1,)`, *اختياري*, يُعاد عند توفير `labels`) -- إجمالي الخسارة على شكل تركيبة خطية من سلبية الاحتمال اللوغاريتمي (الإنتروبيا المتقاطعة) للتنبؤ بالفئة وخسارة صندوق الحدود. تُعرَّف الأخيرة على أنها تركيبة خطية من خسارة L1 وخسارة IoU العامة غير المعتمدة على المقياس.
- **loss_dict** (`Dict`، *اختياري*) -- قاموس يحتوي على الخسائر الفردية. مفيد للتسجيل.
- **logits** (`torch.Tensor` من الشكل `(batch_size, num_queries, num_classes + 1)`) -- قيم التصنيف (تشمل فئة "لا يوجد كائن") لجميع الاستعلامات.
- **pred_boxes** (`torch.Tensor` من الشكل `(batch_size, num_queries, 4)`) -- إحداثيات صناديق مُطبَّعة لجميع الاستعلامات، ممثّلة على شكل (center_x, center_y, width, height). هذه القيم مُطبَّعة ضمن [0, 1]، نسبةً إلى حجم كل صورة فردية في الدفعة (مع تجاهل أي حشو محتمل). يمكنك استخدام `~DFineImageProcessor.post_process_object_detection` لاسترجاع صناديق الحدود غير المُطبَّعة (المطلقة).
- **auxiliary_outputs** (`list[Dict]`، *اختياري*) -- اختياري، يُعاد فقط عند تفعيل الخسائر المساعدة (أي عند ضبط `config.auxiliary_loss` على `True`) وتوفير التسميات. وهو قائمة من القواميس تحتوي على المفتاحين المذكورين أعلاه (`logits` و`pred_boxes`) لكل طبقة من طبقات فك الترميز.
- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, num_queries, hidden_size)`) -- تسلسل من حالات الإخفاء عند مخرج الطبقة الأخيرة من فاحص النموذج.
- **intermediate_hidden_states** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, num_queries, hidden_size)`) -- حالات مخفية وسيطة مكدسة (مخرجات كل طبقة من فاحم الشيفر).
- **intermediate_logits** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, num_queries, config.num_labels)`) -- القيم اللوجستية الوسيطة المتراكمة (القيم اللوجستية لكل طبقة من طبقات المُفكِّك).
- **intermediate_reference_points** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, num_queries, 4)`) -- نقاط مرجعية وسيطة مكدسة (نقاط مرجعية لكل طبقة من طبقات المُفكِّك).
- **intermediate_predicted_corners** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, num_queries, 4)`) -- زوايا متوسطة متوقعة مكدّسة (الزوايا المتوقعة لكل طبقة من طبقات المُفكِّك).
- **initial_reference_points** (`torch.Tensor` من الشكل `(batch_size, config.decoder_layers, num_queries, 4)`) -- نقاط مرجعية أولية مكدسة (النقاط المرجعية الأولية لكل طبقة من طبقات المُفكِّك).
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, sequence_length, hidden_size)`.

  حالات المخفية (Hidden states) لمفكّك الترميز (decoder) عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي (initial embedding).
- **decoder_attentions** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه في المفكّك، بعد softmax الانتباه، المستخدمة لحساب المتوسط المرجّح في رؤوس الانتباه الذاتي.
- **cross_attentions** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه في طبقة الانتباه المتقاطع للمفكّك، بعد softmax للانتباه، وتُستخدم لحساب المتوسط المرجّح في رؤوس الانتباه المتقاطع.
- **encoder_last_hidden_state** (`torch.Tensor` بشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) -- سلسلة من حالات الإخفاء عند مخرجات الطبقة الأخيرة من المُشفِّر في النموذج.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, sequence_length, hidden_size)`.

  حالات المخفية للمشفّر عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي.
- **encoder_attentions** (`tuple[torch.Tensor]`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه للمُشفِّر، بعد softmax للانتباه، المُستخدَمة لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
- **init_reference_points** (`torch.Tensor` من الشكل `(batch_size, num_queries, 4)`) -- نقاط المرجع الأولية المُرسلة عبر مُفكِّك Transformer.
- **enc_topk_logits** (`torch.Tensor` من الشكل `(batch_size, sequence_length, config.num_labels)`، *اختياري*، يُعاد عند `config.with_box_refine=True` و`config.two_stage=True`) -- قيم اللوجيتات الخاصة بإحداثيات صناديق الحدود المتوقعة في المُشفِّر.
- **enc_topk_bboxes** (`torch.Tensor` من الشكل `(batch_size, sequence_length, 4)`، *اختياري*، يُعاد عند `config.with_box_refine=True` و`config.two_stage=True`) -- قيم اللوجيتات الخاصة بإحداثيات صناديق الحدود المتوقعة في المُشفِّر.
- **enc_outputs_class** (`torch.Tensor` من الشكل `(batch_size, sequence_length, config.num_labels)`، *اختياري*، يُعاد عند `config.with_box_refine=True` و`config.two_stage=True`) -- درجات الصناديق المحيطة المتوقعة حيث يتم اختيار أعلى `config.two_stage_num_proposals` صناديق محيطة من حيث الدرجات كإقتراحات مناطق في المرحلة الأولى. مخرجات التصنيف الثنائي للصناديق المحيطة (أي المقدمة والخلفية).
- **enc_outputs_coord_logits** (`torch.Tensor` من الشكل `(batch_size, sequence_length, 4)`، *اختياري*، يُعاد عند `config.with_box_refine=True` و`config.two_stage=True`) -- قيم اللوجيتات الخاصة بإحداثيات صناديق الحدود المتوقعة في المرحلة الأولى.
- **denoising_meta_values** (`dict`، *اختياري*) -- قاموس إضافي للقيم المتعلقة بإزالة الضوضاء

مثال:

```python
>>> import torch
>>> from transformers.image_utils import load_image
>>> from transformers import AutoImageProcessor, DFineForObjectDetection

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> image = load_image(url)

>>> image_processor = AutoImageProcessor.from_pretrained("ustc-community/dfine-xlarge-coco")
>>> model = DFineForObjectDetection.from_pretrained("ustc-community/dfine-xlarge-coco")

>>> # prepare image for the model
>>> inputs = image_processor(images=image, return_tensors="pt")

>>> # forward pass
>>> outputs = model(**inputs)

>>> logits = outputs.logits
>>> list(logits.shape)
[1, 300, 80]

>>> boxes = outputs.pred_boxes
>>> list(boxes.shape)
[1, 300, 4]

>>> # convert outputs (bounding boxes and class logits) to Pascal VOC format (xmin, ymin, xmax, ymax)
>>> target_sizes = torch.tensor([image.size[::-1]])
>>> results = image_processor.post_process_object_detection(outputs, threshold=0.9, target_sizes=target_sizes)
>>> result = results[0]  # first image in batch

>>> for score, label, box in zip(result["scores"], result["labels"], result["boxes"]):
...     box = [round(i, 2) for i in box.tolist()]
...     print(
...         f"Detected {model.config.id2label[label.item()]} with confidence "
...         f"{round(score.item(), 3)} at location {box}"
...     )
Detected cat with confidence 0.958 at location [344.49, 23.4, 639.84, 374.27]
Detected cat with confidence 0.956 at location [11.71, 53.52, 316.64, 472.33]
Detected remote with confidence 0.947 at location [40.46, 73.7, 175.62, 117.57]
Detected sofa with confidence 0.918 at location [0.59, 1.88, 640.25, 474.74]
```