# أدوات التضمينات الدوارة

تشرح هذه الصفحة كيفية حساب تطبيق التضمين الدوّاري (Rotary Embedding) في Transformers والأنواع المدعومة من RoPE.

## نظرة عامة

تُعدّ تضمينات الموضع الدوّارية (Rotary Position Embeddings) تقنيةً تُستخدم لحقن معلومات الموضع في آليات الانتباه دون الاعتماد على ترميزات موضع صريحة. وبدلاً من إضافة متجهات الموضع إلى تضمينات الرموز، يقوم RoPE بتدوير متجهات الاستعلام والمفتاح في المستوى المركّب وفقاً لمواضعها، مما يتيح إدراكاً للمواضع النسبية واستقراءً أفضل نحو أطوال التسلسلات غير المرئية.

توفر مكتبة Transformers تنفيذاً مرنًا وقابلًا للتوسيع لأنواع مختلفة من RoPE محددة في ``~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS``، بما في ذلك المتغيرات الافتراضية والمقيّسة:

| نوع روبي | الوصف |
|------------|-------------|
| `"default"` | تضمين دوّاري قياسي كما في LLaMA. |
| `"linear"` | RoPE المُقيَّم خطياً والذي يتيح نوافذ سياق أطول. |
| `"dynamic"` | تحجيم واعٍ بـ NTK يُحسب عن طريق إعادة تحجيم الأساس الترددي (`θ`) للسياق الأطول. |
| `"yarn"` | نسخة توسيع YaRN التي توفر استقراءً أكثر سلاسة واستقراراً. |
| `"longrope"` | مقياس [LongRoPE](https://github.com/microsoft/LongRoPE) كما في سلسلة نماذج Phi-2. |
| `"llama3"` | توسيع RoPE كما في Llama3.1. |

## الإعدادات في ملفات تكوين النموذج

لتفعيل التضمينات الدوّارة وتخصيصها، أضف حقل `rope_parameters` إلى ملف إعدادات النموذج الخاص بك (`config.json`). يتحكم هذا الحقل في سلوك RoPE عبر طبقات النموذج. لاحظ أن كل متغير من متغيرات RoPE يحدد مجموعه الخاص من المفاتيح المتوقعة، وسيؤدي غياب أي مفتاح إلى رفع خطأ. راجع المثال أدناه الذي ينشئ إعدادات llama مع معاملات RoPE الافتراضية:

```python
from transformers import LlamaConfig

config = LlamaConfig()
config.rope_parameters = {
    "rope_type": "default", # type of RoPE to use
    # rope_theta is optional — omitting it uses the model’s default_theta (typically 10000.0)
}

# If we want to apply a scaled RoPE type, we need to pass extra parameters
config.rope_parameters = {
    "rope_type": "linear",
    "rope_theta": 10000.0,  # can be omitted to fall back to default_theta
    "factor": 8.0  # scale factor for context extension
}
```

## إعداد RoPE حسب نوع الطبقة

تستخدم بعض النماذج مثل Gemma-3 أنواعًا مختلفة من الطبقات مع آليات انتباه مختلفة، أي "انتباه كامل" في بعض الكتل و"انتباه نافذة منزلقة" في أخرى. يدعم Transformers تحديد معاملات RoPE مميزة لكل نوع طبقة لهذه النماذج. في هذه الحالة، يجب أن يكون `rope_parameters` قاموسًا متداخلًا، حيث تتوافق المفاتيح في المستوى العلوي مع `config.layer_types` والقيم هي معاملات RoPE لكل نوع. أثناء تهيئة النموذج، ستبحث كل طبقة فكّ الترميز تلقائيًا عن إعداد RoPE المطابق بناءً على نوع الطبقة المُعلن عنه.

```python
from transformers import Gemma3Config

config = Gemma3Config()
config.rope_parameters = {
    "full_attention": {
        "rope_type": "dynamic",
        "rope_theta": 1000000.0,
        "factor": 8.0,
        "original_max_position_embeddings": 8096,
    },
    "sliding_attention": {
        "rope_type": "default",
        "rope_theta": 10000.0,
    }
}
```

## MRoPE

MRoPE هو نوع من الدوران يُطبَّق في النماذج متعددة الوسائط ويُعرَّف بواسطة `mrope_section`. وهو ليس بندًا مستقلًا في جدول `rope_type`. يمكنك ما زال تطبيق توسيع rope (`linear`، `dynamic`) معه.

تحدد أحجام `mrope_section` نطاقات التردد المتجاورة لمحاور الزمن والارتفاع والعرض (حيث أن مجموع هذه الأحجام يساوي `head_dim // 2`). ثم تُكرَّر الترددات بحيث يمتد التضمين على كامل `head_dim`. بالنسبة للمدخلات متعددة الوسائط (عادةً الرؤية)، يُطبَّق RoPE دفعة واحدة (عبر الضرب المصفوفي أو الضرب العنصري للترددات مع الموضعيات). يعيد `mrope_section` ترتيب تلك الترددات على طول `(t, h, w)` أولاً، كما في `recomposition_frequencies` الخاص بـ Qwen2-VL. تحافظ نصوص الاستعلام والرموز المولَّدة على RoPE أحادي البُعد العادي من خلال استخدام معرّفات موضعيات متطابقة على شبكات THW الثلاث.

```python
from transformers import Qwen2VLConfig

config = Qwen2VLConfig()
config.text_config.rope_parameters = {
    "rope_type": "default",
    "rope_theta": 1000000.0,
    "mrope_section": [16, 24, 24],  # temporal, height, width frequency band sizes
}
```

يستخدم Qwen2-VL `mrope_section = [16, 24, 24]` (16 زمني، 24 ارتفاع، 24 عرض عندما يكون `head_dim` هو 128). غالبًا ما تستخدم النماذج متعددة الوسائط هذا الترتيب في العمود الفقري للنص (Qwen2-VL، GLM-4V). بعض نماذج VLM لا تستخدم MRoPE وتبقى على RoPE النصي ثنائي الأبعاد العادي بدلاً من ذلك. تحقق من `mrope_section` في إعدادات النص.

## RoPE المحوري

بشكل منفصل، `"axial"` هو نوع `rope_type` مسجّل لنماذج الرؤية، لكنه غير مدرج في `ROPE_INIT_FUNCTIONS`. يبقى إعداد الترددات على عاتق النموذج. عادةً ما يطبّق الترددات نفسها (`head_dim // 4` لكل محور مكاني) لمواقع الارتفاع والعرض، ولا يسمح بالتوسع فوق ذلك. تشمل الأمثلة نموذج الرؤية Qwen2-VL ومكدسات الرؤية الأخرى مثل Pixtral.

## أدوات[[transformers.RopeParameters]]

#### transformers.RopeParameters[[transformers.RopeParameters]]

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_rope_utils.py#L678)

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

rope_theta (`float`، *اختياري*، القيمة الافتراضية هي `RotaryEmbeddingConfigMixin.default_theta`) : الفترة الأساسية لتضمينات RoPE. اختياري في التكوينات المُسلسلة — إذا حُذف، تُستخدم قيمة `default_theta` الخاصة بالنموذج (عادةً 10000.0).

rope_type (`str`، *اختياري*، القيمة الافتراضية هي "default") : نوع الفرع من RoPE الذي سيتم استخدامه. يمكن أن يكون أحد القيم التالية: ['default', 'linear', 'dynamic', 'yarn', 'longrope', 'llama3', 'proportional', 'axial']، حيث يمثل 'default' التنفيذ الأصلي لـ RoPE.

partial_rotary_factor (`float`، *اختياري*) : نسبة من تضمين رأس الاستعلام ورأس المفتاح التي سيُطبَّق عليها RoPE.

factor (`float`, *اختياري*) : يُستخدم مع جميع أنواع rope باستثناء 'default'. عامل التوسيع الذي يجب تطبيقه على تضمينات RoPE. في معظم أنواع التوسيع، سيتيح عامل `factor` بقيمة x للنموذج التعامل مع تسلسلات بطول x * الحد الأقصى الأصلي للطول المُدرَّب عليه مسبقًا.

original_max_position_embeddings (`int`، *اختياري*) : يُستخدم مع 'yarn' و'longrope' و'llama3'. تمثيلات المواقع القصوى الأصلية المستخدمة أثناء التدريب المسبق.

attention_factor (`float`، *اختياري*) : يُستخدم مع 'yarn' و'longrope'. عامل التوسيع الذي سيُطبَّق على حساب الانتباه. إذا لم يُحدَّد، فسيُستخدم القيمة الموصى بها من قبل التنفيذ، مع الاستعانة بحقل `factor` لاستنتاج القيمة المقترحة.

beta_fast (`float`، *اختياري*) : يُستخدم فقط مع 'yarn'. معامل لضبط حد الاستقراء (فقط) في دالة التدرج الخطي. إذا لم يُحدد، فإن القيمة الافتراضية هي 32.

beta_slow (`float`، *اختياري*) : يُستخدم فقط مع 'yarn'. معامل لضبط الحدّ الفاصل للاستيفاء (فقط) في دالة الميل الخطي. إذا لم يُحدد، فإن القيمة الافتراضية هي 1.

short_factor (`list[float]`، *اختياري*) : يُستخدم فقط مع 'longrope'. عامل التوسيع الذي يجب تطبيقه على السياقات القصيرة (< `original_max_position_embeddings`). يجب أن يكون قائمة من الأرقام بنفس طول حجم المخفي مقسوماً على عدد رؤوس الانتباه مقسوماً على 2

long_factor (`list[float]`، *اختياري*) : يُستخدم فقط مع 'longrope'. عامل التوسيع الذي يجب تطبيقه على السياقات الطويلة (< `original_max_position_embeddings`). يجب أن يكون قائمة من الأرقام بنفس طول حجم المخفي مقسوماً على عدد رؤوس الانتباه مقسوماً على 2

low_freq_factor (`float`، *اختياري*) : يُستخدم فقط مع 'llama3'. عامل التوسيع المطبَّق على المكونات منخفضة التردد في RoPE

high_freq_factor (`float`، *اختياري*) : يُستخدم فقط مع 'llama3'. عامل التوسيع المطبَّق على المكونات عالية التردد في RoPE

mscale (`float`، *اختياري*) : يُستخدم فقط مع 'yarn'. إذا كان `attention_factor` هو `None` وتم توفير كل من `mscale` و`mscale_all_dim`، فإن `mscale` يعمل كمقياس يوسّع `log(factor)` عند حساب البسط للقيمة المستنتجة لـ`attention_factor`. إذا لم يتم توفيره، فسيتم حساب `attention_factor` بناءً على `factor` فقط.

mscale_all_dim (`float`, *اختياري*) : يُستخدم فقط مع 'yarn'. إذا كان `attention_factor` هو `None` وتم توفير كل من `mscale` و`mscale_all_dim`، فإن `mscale_all_dim` يعمل كمقياس (scalar) يعزز `log(factor)` عند حساب المقام للقيمة المستنتجة لـ`attention_factor`. إذا لم يتم توفيره، فسيتم حساب `attention_factor` بناءً على `factor` فقط.

truncate (`bool`، *اختياري*) : يُستخدم فقط مع 'yarn'. ما إذا كان يجب اقتطاع نطاق التصحيح باستخدام `math.floor` و`math.ceil`. إذا لم يُحدد، فإن القيمة الافتراضية هي `True`.

mrope_section (`list[int]`، *اختياري*) : يُستخدم مع Multimodal RoPE (MRoPE). أحجام نطاقات التردد المتجاورة لمحاور الوسائط المتعددة (عادةً المحور الزمني، والارتفاع، والعرض، حيث يساوي مجموعها `head_dim // 2`).

#### dict[[transformers.RopeParameters.__call__]]

dict() -> قاموس جديد فارغ dict(mapping) -> قاموس جديد مُهيّأ من أزواج (المفتاح، القيمة) في كائن mapping dict(iterable) -> قاموس جديد مُهيّأ كما لو تم عبر: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> قاموس جديد مُهيّأ بأزواج name=value في قائمة معاملات الكلمات المفتاحية. على سبيل المثال: dict(one=1, two=2)