Hugging Face's logo

Transformers documentation

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

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

تشرح هذه الصفحة كيفية حساب تطبيق التضمين الدوّاري (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 كما في سلسلة نماذج Phi-2.
"llama3"توسيع RoPE كما في Llama3.1.

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

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

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 المطابق بناءً على نوع الطبقة المُعلن عنه.

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 الثلاث.

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

< >

( )

المعاملات

  • 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]، اختياري) — يُستخدم مع RoPE متعدد الوسائط (MRoPE). أحجام نطاقات التردد المتجاورة للمحاور متعددة الوسائط (عادةً الزمنية، والارتفاع، والعرض، حيث يساوي مجموعها head_dim // 2).

class .dict

( )

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

Update on GitHub

←أدوات مساعدة لسلاسل زمنية متغيرات البيئة→