# PSOFT

[PSOFT](https://hf.co/papers/2505.11235) هي طريقة فعّالة من حيث المعلمات للضبط الدقيق (Parameter-Efficient Fine-Tuning) تعتمد على الضبط الدقيق المتعامد (OFT)، وتحافظ على العلاقات الهندسية لمُتجهات أعمدة الأوزان المُسبقة التدريب، مع تحقيق توازن بين الأداء والكفاءة متعددة الأبعاد، بما في ذلك عدد المعلمات، واستخدام الذاكرة، والتكلفة الحسابية. ومن خلال تقييد التحويلات المتعامدة في فضاء رئيسي منخفض الرتبة مشتق من الأوزان المُسبقة التدريب، تُسهم PSOFT في سد الفجوة بين LoRA وOFT، مما يوفر ضمانات نظرية وقابلية عملية للتكيف. وقد تم التحقق من فعاليتها من خلال تقييمات شاملة على مجموعة متنوعة من المعايير المرجعية، بما في ذلك GLUE وVTAB-1K وGSM8K وMATH ومعايير الاستدلال الشائع.

- يتم دعم طبقات `nn.Linear` فقط.
- لا يتم دعم الطبقات المُكمّاة.

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

*دفع النمو السريع في عدد معاملات النماذج إلى أن يصبح الضبط الدقيق الفعال للمعاملات (PEFT) أمرًا أساسيًا لتكييف النماذج الكبيرة مع مهام متنوعة في المراحل اللاحقة ضمن موارد حاسوبية محدودة. في إطار هذا النموذج، يحافظ الضبط الدقيق المتعامد ومتغيراته على التمثيلات الدلالية للنماذج المُدرَّبة مسبقًا، لكنه يصارع لتحقيق كلٍّ من القدرة التعبيرية والكفاءة من حيث عدد المعاملات والذاكرة والحساب. للتغلب على هذه القيود، نقترح الضبط الدقيق المتعامد الفعال مع تكيّف الفضاء الجزئي الرئيسي (PSOFT)، والذي يقيّد التحويلات المتعامدة بالفضاء الجزئي الرئيسي للأوزان المُدرَّبة مسبقًا. على وجه التحديد، يبني PSOFT هذا الفضاء الجزئي عبر تحليل المصفوفات لتمكين التحويلات المتوافقة، ويحدد شرطًا نظريًا يحافظ بصرامة على هندسة هذا الفضاء الجزئي لضمان الحفاظ على الدلالات الأساسية، ويقدم متجهات قابلة للضبط بكفاءة تخفف من شرط التعامد تدريجيًا أثناء التدريب لتعزيز المرونة. تُظهر تجارب موسّعة على 35 مهمة في مجال معالجة اللغة الطبيعية (NLP) والرؤية الحاسوبية (CV) عبر أربعة نماذج تمثيلية أن PSOFT يوفر حلًا عمليًا وقابلًا للتوسع لتحقيق الحفاظ على الدلالات والقدرة التعبيرية والكفاءة متعددة الأبعاد في PEFT في آنٍ واحد.*

## كيف يعمل PSOFT

يقوم PSOFT بتفكيك كل مصفوفة أوزان $W_{pre}$ إلى $W_{pri}$ و$W_{res}$ باستخدام SVD: $W_{\text{pre}} = U S V^\top$

يُبنى الفضاء الجزئي الرئيسي $W_{\text{pri}} = U_r S_r V_r^\top = AB$ من المكونات المفردة الأولى $r$:

$W_{\text{pre}} = W_{\text{pri}} + W_{\text{res}} = AB + W_{\text{res}},$

$W_{\text{ps-tuned}} = ARB + W_{\text{res}}.$ (PSOFT-SO: PSOFT مع تقارب صارم)

$W_{\text{ps-tuned}} = A \, \mathrm{diag}(\alpha) \, R \, \mathrm{diag}(\beta) \, B + W_{\text{res}}.$ (PSOFT-RO: PSOFT مع استرخاء شرط العمودية)

أثناء التدريب، تُجمَّد $A$ و$B$ و$W_{\text{res}}$، ولا يمكن تدريب سوى $R$ (أو $R$ مع $\alpha$ و$\beta$).

للتوافق مع إطار عمل PEFT (الذي يتوقع تحديثات أوزان إضافية)، يتم تنفيذ PSOFT بالشكل الإضافي التالي: $W_{\text{ps-tuned}} = W_{\text{pre}} + A (R - I_r) B$

## المعاملات القابلة للتدريب

بعد تطبيق PSOFT:

- تُجمَّد أوزان النموذج الأصلية ($A$، $B$، و$W_{\text{res}}$).
- المصفوفة المتعامدة $R$ (و$\alpha$، $\beta$ اختيارياً) هي القابلة للتدريب فقط.
- لا يتم إدخال أي معاملات انحياز إضافية.

## الاستخدام الأساسي
```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PsoftConfig, get_peft_model

# Load base model
model_id = "facebook/opt-125m"
model = AutoModelForCausalLM.from_pretrained(model_id)

# Configure PSOFT
config = PsoftConfig(
    r=32,                                   # the dimension of trainable matrix R,
    psoft_alpha=32,                         # scaling factor (typically set to r in PSOFT),
    target_modules=["q_proj", "v_proj"],    # target attention projection layers
    ab_svd_init="psoft_init",        # principal subspace initialization
    psoft_svd="full",                       # SVD method
    psoft_orth=True,                        # enable orthogonal R (Cayley parameterization)
    psoft_mag_a=True,                       # enable tunable vector alpha
    psoft_mag_b=True,                       # enable tunable vector beta
    use_cayley_neumann=False,               # disable Cayley–Neumann approximation
    num_cayley_neumann_terms=5,             # number of Neumann series terms
    cayley_neumann_eps=None,                # improve numerical stability
)

# Apply PSOFT
model = get_peft_model(model, config)
model.train()

tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token

# Train
inputs = tokenizer("Hello world", return_tensors="pt", padding=True)
loss = model(**inputs, labels=inputs["input_ids"]).loss
loss.backward()

trainable = [p for p in model.parameters() if p.requires_grad]
optimizer = torch.optim.AdamW(trainable, lr=5e-4)
optimizer.step()
optimizer.zero_grad(set_to_none=True)
```
## خيارات التهيئة

### وضع مختلف

(PSOFT-SO: PSOFT مع تقارب صارم)

```python
config = PsoftConfig(psoft_orth=True,psoft_mag_a=False,psoft_mag_b=False)
```

(PSOFT-RO: PSOFT مع ارتخاء في شرط العمودية)
```python
config = PsoftConfig(psoft_orth=True,psoft_mag_a=True,psoft_mag_b=True)
```

### أفضل الممارسات
1. **اختيار الرتبة**: الرتب الأصغر (مثل `32–128`) مناسبة للمهام الأبسط، بينما توفر الرتب الأكبر (مثل `64–256`) قدرة تعبيرية أكبر للمهام الأكثر تعقيدًا على حساب زيادة عدد المعاملات والحسابات.
2. **معامل التوسيع**: يُضبط معامل التوسيع عادةً على $r$ في PSOFT.
3. **معدل التعلم**: استخدم معدلات تعلم قياسية (مثل `1e-4` إلى `5e-3`) لتحقيق تدريب مستقر.
4. **تهيئة SVD**: الخيار `lowrank` أكثر كفاءةً من حيث الذاكرة والحساب من الخيار `full`، مما يجعله أكثر ملاءمةً للنماذج الكبيرة.
5. **تقريب كيلي–نيومان**: عندما يكون الرتبة كبيرة، فإن تفعيل تقريب كيلي–نيومان يمكن أن يحسّن الكفاءة الحسابية بشكل كبير، بينما يكون الفائد أقل وضوحاً في حالة الرتب الصغيرة. عملياً، فإن عددًا صغيرًا من حدود سلسلة نيومان (عادةً `5`) يوفر عادةً توازنًا جيدًا بين الدقة والكفاءة.

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

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

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

## PsoftConfig[[peft.PsoftConfig]]

#### peft.PsoftConfig[[peft.PsoftConfig]]

```python
peft.PsoftConfig(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, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, psoft_alpha: int = 32, psoft_dropout: float = 0.0, fan_in_fan_out: bool = False, ab_svd_init: Literal['psoft_init', 'pissa_init'] = 'psoft_init', psoft_svd: Literal['full', 'lowrank'] = 'full', psoft_svd_lowrank_niter: int = 10, random_seed: int = 0, psoft_orth: bool = True, psoft_mag_b: bool = True, psoft_mag_a: bool = True, use_cayley_neumann: bool = False, num_cayley_neumann_terms: int = 5, cayley_neumann_eps: Optional[float] = None, modules_to_save: Optional[list[str]] = None, init_weights: bool = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None)
```

[المصدر](https://github.com/huggingface/peft/blob/v0.22.0/src/peft/tuners/psoft/config.py#L26)

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

r (`int`) : القيمة الافتراضية هي 32. يتحكم ترتيب PSOFT (r) في سعة المُكيّف (adapter) من خلال تحويل r*r R. عادةً ما تكون الترتيبات الأصغر بين 32 و128 كافية للمهام البسيطة، بينما قد تستفيد المهام الأكثر تعقيدًا من نطاق 64-256، مما يزيد من القدرة التعبيرية على حساب المعلمات والحسابات الإضافية. راجع الورقة البحثية للحصول على إعدادات مُثبتة تجريبيًا: https://openreview.net/forum?id=FSHrinMArK.

target_modules (`Optional[Union[List[str], str]]`) : أسماء الوحدات التي سيتم تطبيق المُكيّف عليها. إذا تم تحديد هذا، فسيتم استبدال الوحدات التي تحمل الأسماء المحددة فقط. عند تمرير نص، سيتم إجراء مطابقة باستخدام تعبير نمطي. عند تمرير قائمة من النصوص، سيتم إجراء مطابقة دقيقة أو يتم التحقق مما إذا كان اسم الوحدة ينتهي بأي من النصوص الممررة. إذا تم تحديد هذا على أنه 'all-linear'، فسيتم اختيار جميع وحدات linear/Conv1D (إذا كان النموذج PreTrainedModel، باستثناء طبقة الإخراج). إذا لم يتم تحديده، فسيتم اختيار الوحدات وفقًا لبنية النموذج. إذا لم تكن البنية معروفة، فسيتم رفع خطأ -- في هذه الحالة، يجب عليك تحديد الوحدات المستهدفة يدويًا.

exclude_modules (`Optional[Union[List[str], str]]`) : أسماء الوحدات التي لا يُطبَّق عليها المُكيّف. عند تمرير نص، يتم إجراء مطابقة باستخدام تعبير نمطي. عند تمرير قائمة من النصوص، يتم إما إجراء مطابقة دقيقة أو التحقق مما إذا كان اسم الوحدة ينتهي بأي من النصوص المُمرَّرة.

psoft_alpha (`int`) : القيمة الافتراضية هي 32. يتحكم في معامل تحجيم PSOFT. له نفس الدلالات الخاصة بـ LoRA alpha.

psoft_dropout (`float`) : القيمة الافتراضية هي 0.0. إسقاط (Dropout) لمسار PSOFT. له نفس الدلالات الخاصة بإسقاط LoRA.

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

ab_svd_init (`Literal["psoft_init", "pissa_init"]`) : القيمة الافتراضية هي 'psoft_init'. استراتيجية التهيئة الخاصة بـ A و B المستخدمة لبناء الفضاء الجزئي الرئيسي في PSOFT. 'psoft_init': تهيئة مبنية على SVD مع A متعامد الصفوف، مما يضمن تقابلاً صارماً (PSOFT). 'pissa_init': تهيئة مبنية على SVD مع A و B متماثلين (PiSSA القياسي).

psoft_svd (`Literal["full", "lowrank"]`) : القيمة الافتراضية هي 'full'. الخلفية (backend) الخاصة بتفكيك القيم المفردة (SVD) للمبادرة: يستخدم 'full' دالة torch.linalg.svd، بينما يستخدم 'lowrank' دالة torch.svd_lowrank.

psoft_svd_lowrank_niter (`int`) : يُستخدم فقط عندما يكون psoft_svd='lowrank'. القيمة الافتراضية هي 10. عدد تكرارات القوة المستخدمة بواسطة torch.svd_lowrank عندما يكون psoft_svd='lowrank'.

psoft_orth (`bool`) : القيمة الافتراضية هي 'True'. إذا كانت True، تُقيّد R لتكون متعامدة عبر معلمات كيلي، مما يحافظ على العلاقات الهندسية بين أعمدة متجهات الأوزان المُدرَّبة مسبقًا. إذا كانت False، تكون R مصفوفة حرة دون قيود على التعامد.

psoft_mag_b (`bool`) : القيمة الافتراضية هي 'True'. إذا كانت True، يتعلم متجه تحجيم قطري على جانب 'output' من R. يُستخدم عادةً مع psoft_mag_a لزيادة قابلية التكيف مع المهمة، مع تشويه طفيف للهندسة المُدرَّبة مسبقًا.

psoft_mag_a (`bool`) : القيمة الافتراضية هي 'True'. إذا كانت True، يتعلم متجه تحجيم قطري على جانب 'input' من R. يُستخدم عادةً مع psoft_mag_b لزيادة قابلية التكيف مع المهمة، مع تشويه طفيف للهندسة المُدرَّبة مسبقًا.

use_cayley_neumann (`bool`) : القيمة الافتراضية هي 'False'. هل سيتم استخدام صياغة Cayley-Neumann لـ PSOFT أم لا. اضبطها على True لتحسين الكفاءة الحسابية، لكن ذلك يأتي على حساب زيادة خطأ التقريب فيما يتعلق بالتعامودية.

num_cayley_neumann_terms (`int`) : القيمة الافتراضية هي 5. يُستخدم فقط عندما يكون use_cayley_neumann=True. عدد حدود Cayley-Neumann التي سيتم استخدامها. يؤدي العدد الأعلى إلى تقليل خطأ التقريب فيما يتعلق بالتعامد.

cayley_neumann_eps (`optional[float]`) : القيمة الافتراضية هي 'None'. يُستخدم فقط عندما يكون use_cayenburg_neumann=True. حد اختياري لنورم فروبينيوس لمصفوفة المولّد Q في تقريب كيلي-نيومان. إذا كانت القيمة None (الافتراضية)، فلا يُطبَّق أي إعادة تحجيم. إذا تم ضبطها على قيمة ضمن المجال (0, 1) (مثل 0.9)، فإن Q يُعاد تحجيمه كلما تجاوز ||Q||_F الحد المخصص لتحسين الاستقرار العددي. راجع https://spherelab.ai/oftv2/ للتفاصيل.

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

modules_to_save (`List[str]`) : قائمة بالوحدات التي يجب ضبطها لتكون قابلة للتدريب وحفظها في نقطة الفحص النهائية، باستثناء طبقات المحوّل.

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

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

إعدادات PSOFT (التحسين الدقيق المتعامد الفعال مع تكيّف الفضاء الجزئي الرئيسي).

تُدخِل PSOFT تحويلًا متعامدًا R*r بين المصفوفات منخفضة الرتبة A و B، بحيث يكون التحديث منخفض الرتبة هو ΔW = B @ (R-I) @ A. يتم تدريب R (والمتجهات القابلة للضبط الاختيارية) فقط؛ بينما تُهيَّأ A و B باستخدام psoft_init (المبنية على التحليل القيمي المفرد SVD، مع A متعامدة الصفوف) وتُجمَّد.

## PsoftModel[[peft.PsoftModel]]

#### peft.PsoftModel[[peft.PsoftModel]]

```python
peft.PsoftModel(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/v0.22.0/src/peft/tuners/psoft/model.py#L28)

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

model : النموذج المراد تكييفه.

config : PsoftConfig.

adapter_name : اسم المُكيّف، الافتراضي "default".

low_cpu_mem_usage : إنشاء أوزان مُكيّف فارغة على جهاز الميتا.

PSOFT نموذج (Efficient Orthogonal Fine-Tuning with Principal Subspace Adaptation).

يُدرج تحويلًا متعامدًا (أو مُقيَّمًا) R من الرتبة r*r بين A وB منخفضي الرتبة: ΔW = B @ (R-I) @ A. استخدم ab_svd_init="psoft_init" لتبديء A/B من SVD وتجميدهما، مع تدريب R فقط (والمتجهات الاختيارية للمقدار).

