# DINOv2 مع السجلات

## نظرة عامة

قُدِّم نموذج DINOv2 with Registers في [Vision Transformers Need Registers](https://huggingface.co/papers/2309.16588) من قِبل Timothée Darcet وMaxime Oquab وJulien Mairal وPiotr Bojanowski.

نموذج [Vision Transformer](vit) (ViT) هو نموذج مُشفِّر (encoder) من نوع الترانسفورمر (مشابه لـ BERT) تم تقديمه في الأصل لأداء تصنيف الصور المُشرف عليه على مجموعة بيانات ImageNet.

بعد ذلك، توصل الباحثون إلى طرق تجعل [DINOv2](dinov2) و[MAE](vit_mae) تعمل بشكل فعّال جداً في استخراج ميزات الصور ذاتية الإشراف (أي تعلّم ميزات ذات معنى، تُعرف أيضاً بالتضمينات) من الصور دون الحاجة إلى أي تسميات.

لاحظ مؤلفو DINOv2 أن نماذج ViT تحتوي على شوائب في خرائط الانتباه. ويعود السبب إلى استخدام النموذج لبعض رقاقات الصور كـ«سجلات». يقترح المؤلفون حلاً: وهو إضافة بعض الرموز الجديدة (تُسمى رموز «السجل») التي تُستخدم فقط أثناء التدريب المسبق (ثم تُستبعد بعد ذلك). يؤدي هذا إلى:

- لا توجد شوائب
- خرائط انتباه قابلة للتفسير
- والمزيد من التحسينات في الأداء.

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

*برزت نماذج Transformers مؤخراً كأداة قوية لتعلم التمثيلات البصرية. في هذه الورقة، نحدد ونصف الشوائب (artifacts) الموجودة في خرائط الميزات (feature maps) في شبكات ViT المُوجَّهة ذاتياً وغير المُوجَّهة. تتوافق هذه الشوائب مع الرموز (tokens) ذات المعيار العالي (high-norm) التي تظهر أثناء الاستدلال (inference) بشكل رئيسي في مناطق الخلفية منخفضة المعلومات في الصور، والتي تُعاد توظيفها للحسابات الداخلية. نقترح حلاً بسيطاً وفعالاً يعتمد على توفير رموز إضافية لسلسلة الإدخال في محوّل الرؤية (Vision Transformer) لتأدية تلك الوظيفة. نُظهر أن هذا الحل يُصلح المشكلة بالكامل لكل من النماذج المُوجَّهة وغير المُوجَّهة ذاتياً، ويحقق مستوى فنياً جديداً (state of the art) للنماذج البصرية غير المُوجَّهة ذاتياً في مهام التنبؤ البصري الكثيف (dense visual prediction tasks)، ويمكّن طرق اكتشاف الكائنات (object discovery) باستخدام نماذج أكبر، والأهم من ذلك أنه يؤدي إلى خرائط ميزات وخرائط انتباه (attention maps) أكثر سلاسة للمعالجة البصرية اللاحقة.*

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/dinov2_with_registers_visualization.png"
alt="drawing" width="600"/>

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

نصائح:

- استخدام DINOv2 مع Registers مطابق تمامًا لاستخدامه دونها، حيث ستحصل ببساطة على أداء أفضل.

تمت مساهمة هذا النموذج من قِبل [nielsr](https://huggingface.co/nielsr). يمكن العثور على الكود الأصلي [هنا](https://github.com/facebookresearch/dinov2).

## Dinov2WithRegistersConfig[[transformers.Dinov2WithRegistersConfig]]

#### transformers.Dinov2WithRegistersConfig[[transformers.Dinov2WithRegistersConfig]]

```python
transformers.Dinov2WithRegistersConfig(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, hidden_size: int = 768, num_hidden_layers: int = 12, num_attention_heads: int = 12, mlp_ratio: int = 4, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.0, attention_probs_dropout_prob: float | int = 0.0, initializer_range: float = 0.02, layer_norm_eps: float = 1e-06, image_size: int | list[int] | tuple[int, int] = 224, patch_size: int | list[int] | tuple[int, int] = 16, num_channels: int = 3, qkv_bias: bool = True, layerscale_value: float = 1.0, drop_path_rate: float | int = 0.0, use_swiglu_ffn: bool = False, num_register_tokens: int = 4, _out_features: list[str] | None = None, _out_indices: list[int] | None = None, apply_layernorm: bool = True, reshape_hidden_states: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2_with_registers/configuration_dinov2_with_registers.py#L32)

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

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

num_hidden_layers (`int`، *اختياري*، القيمة الافتراضية `12`) : عدد الطبقات المخفية في مُفكِّك Transformer.

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

mlp_ratio (`int`، *اختياري*، القيمة الافتراضية `4`) : نسبة بُعد مخفي MLP إلى بُعد التضمين.

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

hidden_dropout_prob (`Union[float, int]`، *اختياري*، القيمة الافتراضية `0.0`) : احتمال الإسقاط (dropout) لجميع الطبقات المتصلة بالكامل في التضمينات (embeddings) والمشفّر (encoder) والمجمّع (pooler).

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

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

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

image_size (`Union[int, list[int], tuple[int, int]]`، *اختياري*، القيمة الافتراضية `224`) : حجم (دقة) كل صورة.

patch_size (`Union[int, list[int], tuple[int, int]]`، *اختياري*، القيمة الافتراضية `16`) : حجم (دقة) كل رقعة.

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

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

layerscale_value (`float`، *اختياري*، القيمة الافتراضية 1.0) : القيمة الأولية المستخدمة لمقياس الطبقة.

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

use_swiglu_ffn (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان سيتم استخدام شبكة العصبونات الأمامية SwiGLU.

num_register_tokens (`int`، *اختياري*، القيمة الافتراضية 4) : عدد رموز التسجيل (register tokens) المستخدمة.

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

reshape_hidden_states (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إعادة تشكيل خرائط الميزات إلى متجهات رباعية الأبعاد من الشكل `(batch_size, hidden_size, height, width)` في حال استخدام النموذج كهيكل أساسي. إذا كانت القيمة `False`، فستكون خرائط الميزات متجهات ثلاثية الأبعاد من الشكل `(batch_size, seq_len, hidden_size)`.

This is the configuration class to store the configuration of a Dinov2WithRegistersModel. It is used to instantiate a Dinov2 With Registers model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the [facebook/dinov2-with-registers-base](https://huggingface.co/facebook/dinov2-with-registers-base)

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

مثال:

```python
>>> from transformers import Dinov2WithRegistersConfig, Dinov2WithRegistersModel

>>> # Initializing a Dinov2WithRegisters base style configuration
>>> configuration = Dinov2WithRegistersConfig()

>>> # Initializing a model (with random weights) from the base style configuration
>>> model = Dinov2WithRegistersModel(configuration)

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

## Dinov2WithRegistersModel[[transformers.Dinov2WithRegistersModel]]

#### transformers.Dinov2WithRegistersModel[[transformers.Dinov2WithRegistersModel]]

```python
transformers.Dinov2WithRegistersModel(config: Dinov2WithRegistersConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2_with_registers/modeling_dinov2_with_registers.py#L393)

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

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

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

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

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

#### forward[[transformers.Dinov2WithRegistersModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, bool_masked_pos: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2_with_registers/modeling_dinov2_with_registers.py#L402)

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

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

bool_masked_pos (`torch.BoolTensor` من الشكل `(batch_size, sequence_length)`) : مواضع مقنّعة من نوع منطقي. تُظهر أيّ البقع مقنّعة (1) وأيّها غير مقنّع (0). ذات صلة بالتدريب المسبق فقط.

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

**يعيد:** [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/ar/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) أو `tuple(torch.Tensor)`

[BaseModelOutputWithPooling](/docs/transformers/v5.23.0/ar/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) تتكون من عناصر مختلفة اعتماداً على الإعداد ([Dinov2WithRegistersConfig](/docs/transformers/v5.23.0/ar/model_doc/dinov2_with_registers#transformers.Dinov2WithRegistersConfig)) والمدخلات.

تُعيد طريقة [Dinov2WithRegistersModel](/docs/transformers/v5.23.0/ar/model_doc/dinov2_with_registers#transformers.Dinov2WithRegistersModel) الخاصة بالتقديم (forward) تعريف الطريقة الخاصة `__call__`.

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

- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`) -- تسلسل من حالات الإخفاء (hidden-states) عند مخرج الطبقة الأخيرة من النموذج.
- **pooler_output** (`torch.Tensor` من الشكل `(batch_size, hidden_size)`) -- حالة الطبقة المخفية الأخيرة للرمز الأول في التسلسل (رمز التصنيف) بعد المعالجة الإضافية عبر الطبقات المستخدمة في مهمة ما قبل التدريب المساعدة. على سبيل المثال، بالنسبة لعائلة نماذج BERT، تُرجع هذه الخاصية رمز التصنيف بعد معالجته عبر طبقة خطية ودالة تفعيل tanh. يتم تدريب أوزان الطبقة الخطية من هدف التنبؤ بالجملة التالية (التصنيف) أثناء ما قبل التدريب.
- **hidden_states** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_hidden_states=True` أو عند تعيين `config.output_hidden_states=True`) -- مجموعة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) بأبعاد `(batch_size, sequence_length, hidden_size)`.

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

  أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

مثال:

```python
```

## Dinov2WithRegistersForImageClassification[[transformers.Dinov2WithRegistersForImageClassification]]

#### transformers.Dinov2WithRegistersForImageClassification[[transformers.Dinov2WithRegistersForImageClassification]]

```python
transformers.Dinov2WithRegistersForImageClassification(config: Dinov2WithRegistersConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2_with_registers/modeling_dinov2_with_registers.py#L439)

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

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

نموذج Dinov2WithRegisters وهو نموذج تحويلي (Transformer) مرفق برأس تصنيف صور في الأعلى (طبقة خطية فوق الحالة المخفية النهائية لرمز [CLS])، على سبيل المثال لتصنيف صور ImageNet.

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

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

#### forward[[transformers.Dinov2WithRegistersForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2_with_registers/modeling_dinov2_with_registers.py#L452)

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

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

labels (من نوع `torch.LongTensor` بأبعاد `(batch_size,)`، *اختياري*) : تسميات لحساب خسارة تصنيف/الانحدار للصور. يجب أن تكون الفهارس ضمن `[0, ..., config.num_labels - 1]`. إذا كان `config.num_labels == 1` يتم حساب خسارة الانحدار (خسارة متوسط المربع)، وإذا كان `config.num_labels > 1` يتم حساب خسارة التصنيف (الإنتروبيا المتقاطعة).

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

**يعيد:** [ImageClassifierOutput](/docs/transformers/v5.23.0/ar/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) أو `tuple(torch.Tensor)`

[ImageClassifierOutput](/docs/transformers/v5.23.0/ar/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) تتكون من عناصر مختلفة اعتماداً على الإعداد ([Dinov2WithRegistersConfig](/docs/transformers/v5.23.0/ar/model_doc/dinov2_with_registers#transformers.Dinov2WithRegistersConfig)) والمدخلات.

تُعيد طريقة [Dinov2WithRegistersForImageClassification](/docs/transformers/v5.23.0/ar/model_doc/dinov2_with_registers#transformers.Dinov2WithRegistersForImageClassification) الخاصة بالتقديم (forward) تعريف الطريقة الخاصة `__call__`.

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

- **loss** (`torch.Tensor` من الشكل `(1,)`, *اختياري*، يُعاد عند تقديم `labels`) -- خسارة التصنيف (أو الانحدار إذا كان config.num_labels==1).
- **logits** (`torch.Tensor` من الشكل `(batch_size, config.num_labels)`) -- درجات التصنيف (أو الانحدار إذا كان config.num_labels==1) (قبل SoftMax).
- **hidden_states** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل مرحلة) بشكل `(batch_size, sequence_length, hidden_size)`. حالات مخفية (تُسمى أيضًا خرائط الميزات) للنموذج عند مخرجات كل مرحلة.
- **attentions** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة (Tuple) من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, patch_size, sequence_length)`.

  أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

مثال:

```python
>>> from transformers import AutoImageProcessor, Dinov2WithRegistersForImageClassification
>>> import torch
>>> from datasets import load_dataset

>>> dataset = load_dataset("huggingface/cats-image")
>>> image = dataset["test"]["image"][0]

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/dinov2-with-registers-base")
>>> model = Dinov2WithRegistersForImageClassification.from_pretrained("facebook/dinov2-with-registers-base")

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

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> # model predicts one of the 1000 ImageNet classes
>>> predicted_label = logits.argmax(-1).item()
>>> print(model.config.id2label[predicted_label])
...
```

