# GraLoRA

[**التكيّف منخفض الرتبة الدقيق (GraLoRA)**](https://huggingface.co/papers/2505.20355) هو أسلوب PEFT مصمم لتعزيز **قابلية التعبير** في التكيّف منخفض الرتبة مع تحسين **المتانة تجاه القيم الشاذة** في التفعيلات، استنادًا إلى رؤى مستمدة من مشكلات معروفة في التكميم.

![GraLoRA Overview](https://github.com/SqueezeBits/GraLoRA/raw/main/figure/gralora_overview.png)

على عكس LoRA القياسي، الذي يطبّق مُكيّفًا منخفض الرتبة واحدًا عبر كامل مساحة الميزات، يُقدّم GraLoRA مخطط تكيّف منظمًا ودقيقًا. فهو يقسم مساحة التكيّف إلى شبكة من أزواج مُكيّفات أصغر ومستقلة بعدد $𝑘^2$، حيث يتولى كل زوج مسؤولية مجموعة فرعية محلية من أبعاد الإدخال والإخراج. ونتيجةً لذلك، يعمل كل مُكيّف على فضاء فرعي أصغر بمقدار $k$ في كلا البعدين مقارنةً بمُكيّف LoRA الأصلي.

يتيح هذا التفكيك الدقيق تحديثات محلية مكانياً وواعية بالسياق، مما يزيد بشكل فعال من السعة التمثيلية دون إضافة معاملات أو تكلفة حسابية إضافية. من خلال عزل تأثير التفعيلات القصوى داخل فضاءات فرعية أصغر، تخفف GraLoRA من تشوه التدرجات وتحافظ على التوازن بين القنوات أثناء التكيف.

---

ملخص الورقة البحثية هو:

*تُعدّ التكيّف منخفض الرتبة (LoRA) طريقة شائعة للتكيّف الفعال من حيث المعاملات (PEFT) للنماذج التوليدية، وتُقدَّر لبساطتها وفعاليتها. وعلى الرغم من التحسينات الأخيرة، لا يزال LoRA يعاني من قيد أساسي: الإفراط في التكيّف عند توسيع عنق الزجاجة. يُحقق أفضل أداء عند الرتب 32–64، غير أن دقته تتوقف عن التحسن أو تتراجع عند الرتب الأعلى، ولا تزال دون أداء التكيّف الكامل (FFT). حددنا السبب الجذري في عنق الزجاجة الهيكلي لـ LoRA، الذي يُدخل تشابكًا في التدرجات إلى قنوات الإدخال غير المرتبطة ويُشوّه انتشار التدرجات. لمعالجة ذلك، نُقدّم بنية جديدة، وهي التكيّف الحبيبي منخفض الرتبة (GraLoRA)، التي تُقسّم مصفوفات الأوزان إلى كتل فرعية، لكل منها مُكيّف منخفض الرتبة خاص به. وبكلفة حسابية أو تخزينية شبه معدومة، يتجاوز GraLoRA قيود LoRA، ويزيد الفعالية التمثيلية بشكل فعّال، ويُقارب سلوك FFT بشكل أقرب. تُظهر التجارب على معايير توليد الأكواد، والاستدلال الشائع، والاستدلال الرياضي، وفهم اللغة العام، وتوليد الصور، أن GraLoRA يتفوق باستمرار على LoRA والقواعد الأساسية الأخرى، محققًا مكسبًا مطلقًا يصل إلى +8.5% في Pass@1 على HumanEval+. وتبقى هذه التحسينات سارية عبر أحجام النماذج وإعدادات الرتب، مما يجعل GraLoRA حلًا قابلًا للتوسع ومتينًا لـ PEFT.*

## نظرة عامة على الاختبارات

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=GRALORA" frameborder="0" width="850" height="1000"
>

# واجهة برمجة التطبيقات

## GraloraConfig[[peft.GraloraConfig]]

#### peft.GraloraConfig[[peft.GraloraConfig]]

```python
peft.GraloraConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, r: int = 32, hybrid_r: int = 0, target_modules: list[str] | str | None = None, alpha: int = 64, gralora_dropout: float = 0.0, gralora_k: int = 2, fan_in_fan_out: bool = False, bias: str = 'none', modules_to_save: list[str] | None = None, init_weights: bool = True, layers_to_transform: list[int] | int | None = None, layers_pattern: str | None = None)
```

[المصدر](https://github.com/huggingface/peft/blob/main/src/peft/tuners/gralora/config.py#L23)

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

r (`int`) : بُعد انتباه GraLoRA يحدد رتبة مُكيّف GraLoRA. العدد الإجمالي للمعاملات في مُكيّف GraLoRA هو نفسه في LoRA ذات الرتبة r نفسها، بينما تتضاعف القدرة التعبيرية بمعامل gralora_k.

hybrid_r (`int`) : رتبة Hybrid GraLoRA تحدد الرتبة المخصصة لطريقة LoRA التقليدية عند استخدام طريقة Hybrid GraLoRA. تصبح طريقة Hybrid GraLoRA، وهي مزيج من GraLoRA وLoRA التقليدية، متاحة عندما يكون hybrid_r > 0. عدد معاملات مُكيّف GraLoRA هو r + hybrid_r.

target_modules (`Union[List[str], str]`) : قائمة بأسماء الوحدات أو تعبير نمطي (regex) لأسماء الوحدات التي سيتم استبدالها بـ GraLoRA. على سبيل المثال، ['q', 'v'] أو '.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'. يمكن أن يكون هذا أيضاً برمز التعميم 'all-linear' الذي يطابق جميع الخطية/Conv1D (إذا كان النموذج PreTrainedModel، يتم استبعاد طبقة الإخراج). إذا لم يتم تحديد ذلك، سيتم اختيار الوحدات وفقاً لبنية النموذج. إذا لم تكن البنية معروفة، سيتم رفع خطأ -- في هذه الحالة، يجب عليك تحديد الوحدات المستهدفة يدوياً.

alpha (`int`) : ألفا الخاص بـ GraLoRA. يُعدّ GraLoRA alpha عامل التوسيع الخاص بمُكيّف GraLoRA. يصبح التوسيع alpha / (r + hybrid_r).

gralora_dropout (`float`) : Dropout الخاص بـ GraLoRA هو احتمال dropout لمُكيّف GraLoRA. يُستخدم لمنع الإفراط في التخصيص وتحسين تعميم مُكيّف GraLoRA.

gralora_k (`int`) : يحدد GraLoRA k عدد الحزم الفرعية في مُكيّف GraLoRA. يجب أن يكون الرتبة r قابلة للقسمة على gralora_k لكي يكون مُكيّف GraLoRA صالحًا. يبقى إجمالي عدد المعاملات محفوظًا بغض النظر عن قيمة gralora_k. تزداد الرتبة الكاملة لمُكيّف GraLoRA بمقدار gralora_k، بينما تنخفض رتبة كل حزمة فرعية بمقدار gralora_k. يُوصى باستخدام gralora_k=2 للرتبة 32 أو أقل، و gralora_k=4 للرتبة 64 أو أعلى.

fan_in_fan_out (`bool`) : اضبط هذا على True إذا كانت الطبقة التي سيتم استبدالها تخزن الأوزان على شكل (fan_in, fan_out). على سبيل المثال، يستخدم gpt-2 `Conv1D` الذي يخزن الأوزان على شكل (fan_in, fan_out)، وبالتالي يجب ضبط هذا على `True`.

bias (`str`) : نوع الانحياز (Bias) الخاص بـ gralora. يمكن أن يكون 'none' أو 'all' أو 'gralora_only'. إذا كان 'all' أو 'gralora_only'، فسيتم تحديث الانحيازات المقابلة أثناء التدريب. انتبه إلى أن هذا يعني أن النموذج لن ينتج نفس المخرجات التي كان سينتجها النموذج الأساسي دون تكييف، حتى عند تعطيل المكيّفات (adapters).

modules_to_save (`Optional[list[str]]`) : قائمة بالوحدات التي يجب ضبطها لتكون قابلة للتدريب وحفظها في نقطة الفحص النهائية، بخلاف طبقات gralora. على سبيل المثال، في مهام تصنيف التسلسل أو تصنيف الرموز، يتم تهيئة الطبقة النهائية `classifier/score` بشكل عشوائي، وبالتالي تحتاج إلى أن تكون قابلة للتدريب والحفظ.

init_weights (`bool`) : ما إذا كان سيتم تهيئة أوزان طبقات GraLoRA باستخدام التهيئة الافتراضية الخاصة بها. لا تغيّر هذا الإعداد إلا إذا كنت تعرف بالضبط ما تفعله.

layers_to_transform (`Union[List[int], int]`) : فهارس الطبقات المراد تحويلها، إذا تم تحديد هذا الحُجج، فسيقوم PEFT بتحويل فهارس الطبقات المحددة داخل هذه القائمة فقط. إذا تم تمرير عدد صحيح واحد، فسيقوم PEFT بتحويل الطبقة الموجودة عند هذا الفهرس فقط. يعمل هذا فقط عندما يكون target_modules قائمة من str.

layers_pattern (`Optional[Union[List[str], str]]`) : اسم نمط الطبقة، يُستخدم فقط إذا كان `layers_to_transform` مختلفًا عن None وإذا لم يكن نمط الطبقة ضمن أنماط الطبقات الشائعة. يعمل هذا فقط عندما يكون target_modules قائمة من str. يجب أن يستهدف هذا `nn.ModuleList` الخاص بالنموذج، والذي يُسمى غالبًا `'layers'` أو `'h'`.

هذه هي فئة الإعدادات لتخزين إعدادات [GraloraModel](/docs/peft/main/ar/package_reference/gralora#peft.GraloraModel).

## GraloraModel[[peft.GraloraModel]]

#### peft.GraloraModel[[peft.GraloraModel]]

```python
peft.GraloraModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[المصدر](https://github.com/huggingface/peft/blob/main/src/peft/tuners/gralora/model.py#L28)

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

model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) : النموذج الذي سيتم تكييفه.

config ([GraloraConfig](/docs/peft/main/ar/package_reference/gralora#peft.GraloraConfig)) : إعدادات نموذج Gralora.

adapter_name (`str`) : اسم المُكيِّف، القيمة الافتراضية هي `"default"`.

**يعيد:** `torch.nn.Module`

نموذج Gralora.

ينشئ نموذج تكييف المصفوفة العشوائية القائم على المتجهات (Gralora) من نموذج transformers مُدرَّب مسبقًا.

مثال:

```py
>>> from transformers import AutoModelForCausalLM
>>> from peft import GraloraConfig, get_peft_model

>>> base_model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
>>> config = GraloraConfig(r=128)
>>> model = get_peft_model(base_model, config)
```

**الخصائص**:
- **النموذج** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- النموذج الذي سيتم تكييفه.
- **peft_config** ([GraloraConfig](/docs/peft/main/ar/package_reference/gralora#peft.GraloraConfig)): إعدادات نموذج Gralora.