Hugging Face's logo

PEFT documentation

PSOFT

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

and get access to the augmented documentation experience

to get started

PSOFT

PSOFT هي طريقة فعّالة من حيث المعلمات للضبط الدقيق (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 بتفكيك كل مصفوفة أوزان WpreW_{pre} إلى WpriW_{pri} و WresW_{res} باستخدام SVD: Wpre=USV⊤W_{\text{pre}} = U S V^\top

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

Wpre=Wpri+Wres=AB+Wres,W_{\text{pre}} = W_{\text{pri}} + W_{\text{res}} = AB + W_{\text{res}},

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

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

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

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

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

بعد تطبيق PSOFT:

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

الاستخدام الأساسي

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 مع تقارب صارم)

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

(PSOFT-RO: PSOFT مع ارتخاء في شرط العمودية)

config = PsoftConfig(psoft_orth=True,psoft_mag_a=True,psoft_mag_b=True)

أفضل الممارسات

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

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

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

PsoftConfig

فئة peft.PsoftConfig

< >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 32target_modules: Optional[Union[list[str], str]] = Noneexclude_modules: Optional[Union[list[str], str]] = Nonepsoft_alpha: int = 32psoft_dropout: float = 0.0fan_in_fan_out: bool = Falseab_svd_init: Literal['psoft_init', 'pissa_init'] = 'psoft_init'psoft_svd: Literal['full', 'lowrank'] = 'full'psoft_svd_lowrank_niter: int = 10random_seed: int = 0psoft_orth: bool = Truepsoft_mag_b: bool = Truepsoft_mag_a: bool = Trueuse_cayley_neumann: bool = Falsenum_cayley_neumann_terms: int = 5cayley_neumann_eps: Optional[float] = Nonemodules_to_save: Optional[list[str]] = Noneinit_weights: bool = Truelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = None )

المعاملات

  • 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’. واجهة SVD المخصصة للتشغيل الأولي: ‘full’ تستخدم torch.linalg.svd؛ بينما ‘lowrank’ تستخدم torch.svd_lowrank.
  • psoft_svd_lowrank_niter (int) — يُستخدم فقط عندما يكون psoft_svd=‘lowrank’. القيمة الافتراضية هي 10. عدد تكرارات القوة (power iterations) التي يستخدمها torch.svd_lowrank عندما يكون psoft_svd=‘lowrank’.
  • psoft_orth (bool) — القيمة الافتراضية هي ‘True’. إذا كانت True، تُقيّد المصفوفة R لتكون متعامدة عبر معادلة Cayley، مما يحافظ على العلاقات الهندسية بين أعمدة متجهات الأوزان المُدرَّبة مسبقًا. إذا كانت 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_cayley_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]) — قائمة بالوحدات، بخلاف طبقات المُكيِّف (adapter)، التي يجب تعيينها قابلة للتدريب وحفظها في نقطة الفحص النهائية.
  • 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

< >

( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None )

المعاملات

  • model — النموذج المراد تكييفه.
  • config — PsoftConfig.
  • adapter_name — اسم المُكيّف، الافتراضي “default”.
  • low_cpu_mem_usage — إنشاء أوزان المُكيِّف الفارغة على جهاز الميتا.

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

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

Update on GitHub

←Polytropon PVeRA→