# GLoRA

التكيّف منخفض الرتبة المعمّم ([GLoRA](https://huggingface.co/papers/2306.07967)) هو طريقة PEFT تعمم LoRA والمناهج ذات الصلة. يقوم GLoRA بتفكيك التحديثات إلى مسارات قابلة للتهيئة (A، B، C، D، E)، حيث يمكن لكل مسار استخدام معلمات منخفضة الرتبة، أو متجهات، أو ثوابت، أو تعطيل المعلمات اعتمادًا على المسار.

يدعم كل مسار أحد أربعة أوضاع لتحديد المعلمات. وتقوم هذه الأوضاع بمقايضة **عدد المعلمات** مقابل **القدرة التعبيرية** (مدى غنى التحديث الممكن):

- `"lora"`: تحليل رتبة منخفضة (مثل LoRA القياسي). يستخدم `r * (out + in)` من المعاملات ويمكنه التعبير عن تصحيحات برتبة `r`. الأكثر تعبيراً والأكثر عدداً من المعاملات.
- `"vector"`: متجه واحد (مثل الشكل `(out, 1)`)، يُبث عبر المصفوفة. يستخدم `O(out)` من المعاملات؛ ويتيح فقط التوسع أو الإزاحة لكل قناة.
- `"constant"`: قيمة قياسية واحدة مشتركة بين جميع العناصر. يستخدم معاملًا واحدًا؛ وهو الأقل تعبيرًا بين الخيارات القابلة للتدريب.
- `"none"`: قيم صفرية بدون أي معاملات قابلة للتدريب؛ تعطّل هذا المسار بالكامل.

لا تقبل كل مسارات كل وضع (على سبيل المثال، `config_D_E` لا يدعم `"lora"`). اختيار `"lora"` على مسارات أكثر يزيد من السعة والمعاملات القابلة للتدريب؛ بينما `"vector"` أو `"constant"` أو `"none"` تقلل من كلاهما.

يُعدّ GLoRA مفيدًا بشكل خاص في البحث والتطبيقات المتقدمة حيث ترغب في تجربة أنماط التحديث المهيكلة ودمج آليات التكيف المتعددة في طبقة واحدة.

على مستوى عالٍ، يعدّل GLoRA طبقة خطية مجمّدة باستخدام:

$$ W_{\mathrm{eff}} = W_0 + W_0 \odot A + B $$

$$ b_{\mathrm{eff}} = b_0 + b_0 \odot D + E + W_0 C $$

حيث يتم تحديد معاملات كل مسار بشكل مستقل.

## GloraConfig[[peft.GloraConfig]]

#### peft.GloraConfig[[peft.GloraConfig]]

```python
peft.GloraConfig(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 = 8, target_modules: list[str] | str | None = None, bias: str = 'none', modules_to_save: list[str] | None = None, config_A_B: typing.Literal['lora', 'vector', 'constant', 'none'] = 'lora', config_C: typing.Literal['lora', 'vector', 'none'] = 'lora', config_D_E: typing.Literal['vector', 'constant', 'none'] = 'constant', init_weights: bool = True)
```

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

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

r (`int`) : رتبة التحليل منخفض الرتبة المستخدمة عند ضبط الإعداد على `lora`.

target_modules (`Optional[Union[List[str], str]]`) : أسماء الوحدات التي سيتم تطبيق Glora عليها.

config_A_B (`str`) : طريقة المعاملات لمصفوفتي A و B (التصحيحات الضربية والإضافية للأوزان). القيم الصالحة: `lora`، `vector`، `constant`، `none`.

config_C (`str`) : ترميز لمصفوفة C (اقتران الوزن بالانحياز: b += W0 @ C). القيم الصالحة: `lora`، `vector`، `none`.

config_D_E (`str`) : ترميز للمتغيرات D و E (تصحيحات الضرب والإضافة للانحراف). لا يدعم `lora` لأن D و E متجهات بحجم الانحراف وليس مصفوفات. القيم الصالحة: `vector`، `constant`، `none`.

init_weights (`bool`) : إذا كانت القيمة True (الافتراضي)، يتم تهيئة GLoRA كعملية لا شيء (صفوف). إذا كانت False، يتم استخدام تهيئة kaiming بحيث لا يكون المُكيّف عملية لا شيء.

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

تعديل Glora لطبقة خطية مجمّدة W0 على النحو التالي: `W_eff = W0 + W0 * A + B` و `b_eff = b0 + b0 * D + E + W0 @ C`.

يمكن ترميز كل مصفوفة (A، B، C، D، E) بشكل مستقل. تتحكم قيم الإعداد في عدد المعلمات المستخدمة والأشكال التي يمكنها التعبير عنها:

- `lora`: تحليل رتبة منخفضة `Xd @ Xu` بأشكال `(out, r)` و`(r, in)`. يستخدم `r * (out + in)` من المعاملات ويمكنه التعبير عن أي تصحيح بترتيب r. يشبه LoRA القياسي.
- `vector`: متجه عمودي واحد من الشكل `(out, 1)`، يُبث عبر المصفوفة الكاملة. يستخدم `out` من المعاملات؛ أي تحجيم أو إزاحة لكل قناة إخراج على حدة.
- `constant`: قيمة قياسية واحدة مشتركة بين جميع العناصر. يستخدم معاملًا واحدًا؛ وهو الأكثر تقييدًا.
- `none`: أصفار، لا توجد معاملات قابلة للتدريب. يُعطّل هذا المسار فعليًا.

### خيارات التكوين الرئيسية
- `r`: الرتبة المستخدمة عند تكوين المسار على أنه `"lora"` (الافتراضي: `8`).
- `target_modules`: قائمة أو تعبير نمطي (regex) لأسماء الوحدات المرغوب في تكييفها (مثل `["q_proj", "v_proj"]`).
- `config_A_B`: نوع المسار الخاص بـ A و B ("lora", "vector", "constant", "none").
- `config_C`: نوع المسار الخاص بـ C ("lora", "vector", "none").
- `config_D_E`: نوع المسار الخاص بـ D و E ("constant", "vector", "none").
- `bias`: معالجة الانحياز (`"none"` أو `"all"` أو `"glora_only"`).
- `init_weights`: إذا كان `True` (الافتراضي)، يتم تهيئة GLoRA كعملية لا تؤثر على النتيجة. إذا كان `False`، يتم استخدام تهيئة كايمنغ.

ملاحظات:
- `config_D_E` لا يدعم `"lora"`.
- يمكن تجاهل `target_modules` لأنواع النماذج المدعومة (يتم استخدام تعيينات PEFT الافتراضية).

## GloraModel[[peft.GloraModel]]

#### peft.GloraModel[[peft.GloraModel]]

```python
peft.GloraModel(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/glora/model.py#L34)

ينشئ نموذج Generalized Low Rank Adapter (GLoRA) من نموذج transformers مُدرَّب مسبقًا.

- يغلّف نموذجًا أساسيًا ويحقن مُكيّفات GLoRA في الوحدات المحددة.
- يدعم عدة محولات، والتبديل بين المحولات، والدمج/إلغاء الدمج، والاستدلال على دفعات مختلطة.
- استخدم `set_adapter` و`merge_and_unload` والأساليب ذات الصلة لإدارة المكيّفات.

## GloraLayer و GloraLinear[[peft.tuners.glora.GloraLayer]]

#### peft.tuners.glora.GloraLayer[[peft.tuners.glora.GloraLayer]]

```python
peft.tuners.glora.GloraLayer(base_layer: nn.Module, **kwargs)
```

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

#### peft.tuners.glora.GloraLinear[[peft.tuners.glora.GloraLinear]]

```python
peft.tuners.glora.GloraLinear(base_layer: nn.Module, adapter_name: str, config, **kwargs)
```

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

مُكيّف GLoRA يغلّف طبقة `base_layer` كثيفة من نوع `~torch.nn.Linear`.

- `GloraLayer` هو المنطق الأساسي للتكيف منخفض الرتبة المعمّم، ويدعم عدة مُكيّفات وإعدادات مسارات مرنة.
- `GloraLinear` هو بديل جاهز للاستخدام مباشرة عن `nn.Linear` مع دعم GLoRA.
- يدعم GLoRA حاليًا طبقات الأساس من نوع `torch.nn.Linear` فقط.

## مثال على الاستخدام

```python
from transformers import AutoModelForCausalLM
from peft import GloraConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("your-model-id")
glora_config = GloraConfig(
    r=8,
    target_modules=["q_proj", "v_proj"],
    config_A_B="lora",
    config_C="vector",
    config_D_E="constant",
    task_type="CAUSAL_LM",
)
model = get_peft_model(model, glora_config)
model.print_healthcheck()

# Switch adapters, merge, etc.
model.set_adapter("default")
model.merge_and_unload()
```

## ملاحظات
- يُعدّ GLoRA مجموعةً شاملةً لـ LoRA: فإعداد جميع المسارات إلى "lora" يستعيد LoRA القياسي.
- يمكنك استخدام أنواع مسارات مختلفة لـ A/B/C/D/E لتجربة استراتيجيات تكيّف جديدة.
- يدعم GLoRA جميع ميزات إدارة محولات PEFT القياسية (إضافة، حذف، تبديل، دمج، إلخ).

## انظر أيضاً
- [مرجع LoRA](./lora)
- [الورقة: https://huggingface.co/papers/2306.07967](https://huggingface.co/papers/2306.07967)

