Hugging Face's logo

PEFT documentation

AdaMSS

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

AdaMSS

AdaMSS (AdaMSS: Adaptive Multi-Subspace Approach for Parameter-Efficient Fine-Tuning) هي طريقة لضبط الدقة بكفاءة المعلمات تقوم بتفكيك مصفوفات الأوزان باستخدام SVD وتجميع الفضاء المفكك في عدة فضاءات فرعية قابلة للتدريب. يتعلم كل فضاء فرعي تحديثات مستقلة منخفضة الرتبة بينما تبقى الأوزان الأصلية مجمدة. كما يدعم AdaMSS تخصيص الفضاءات الفرعية التكيفي (ASA)، الذي يقصّ ديناميكيًا الفضاءات الفرعية الأقل أهمية أثناء التدريب بناءً على معلومات التدرج.

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

نقترح AdaMSS، وهو نهج متكيف متعدد الفراغات الجزئية (multi-subspace) للضبط الدقيق الموفّر للمعاملات (parameter-efficient fine-tuning) للنماذج الكبيرة. على عكس طرق الضبط الدقيق الموفّر للمعاملات التقليدية التي تعمل ضمن فراغ جزئي واحد كبير لأوزان الشبكة، يستفيد AdaMSS من تقسيم الفراغ الجزئي للحصول على عدة فراغات جزئية أصغر، ويقلل بشكل تكيفي من عدد المعاملات القابلة للتدريب أثناء التدريب، محدثًا في النهاية فقط تلك المرتبطة بمجموعة فرعية صغيرة من الفراغات الجزئية الأكثر صلة بالمهمة النهائية المستهدفة. من خلال استخدام تمثيل أدنى رتبة (lowest-rank representation)، يحقق AdaMSS تعبيرية أكثر إحكامًا وضبطًا أدق لمعاملات النموذج. تُظهر التحليلات النظرية أن AdaMSS يتمتع بضمان تعميم أفضل من LoRA وPiSSA وطرق أخرى منخفضة الرتبة (low-rank) مبنية على فراغ جزئي واحد. تُظهر التجارب الواسعة عبر مهام تصنيف الصور، وفهم اللغة الطبيعية، وتوليد اللغة الطبيعية أن AdaMSS يحقق أداءً مماثلًا للضبط الدقيق الكامل ويتفوق على طرق الضبط الدقيق الموفّر للمعاملات الأخرى في معظم الحالات، مع طلب عدد أقل من المعاملات القابلة للتدريب. ومن اللافت للنظر أنه على نموذج ViT-Large، يحقق AdaMSS دقة متوسطة أعلى بنسبة 4.7% من LoRA عبر سبع مهام، باستخدام 15.4% فقط من المعاملات القابلة للتدريب. وعلى RoBERTa-Large، يتفوق AdaMSS على PiSSA بنسبة 7% في الدقة المتوسطة عبر ست مهام، مع تقليل عدد المعاملات القابلة للتدريب بنسبة تقارب 94.4%. تُظهر هذه النتائج فعالية AdaMSS في الضبط الدقيق الموفّر للمعاملات. الكود الخاص بـ AdaMSS متاح على https: //github.com/jzheng20/AdaMSS.

تخضع AdaMSS حاليًا للقيود التالية:

  • يتم دعم طبقات nn.Linear فقط.
  • يتطلب scikit-learn لخطوة التجميع KMeans.

إذا لم تكن هذه القيود مناسبة لحالتك، فكّر في استخدام طرق أخرى بدلاً منها.

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

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

AdamssConfig

فئة peft.AdamssConfig

< >

( 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 = 100num_subspaces: int = 5subspace_rank: int = 1target_modules: Optional[Union[list[str], str]] = Noneinit_weights: Optional[Literal['orthogonal']] = 'orthogonal'modules_to_save: Optional[list[str]] = Nonelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Noneuse_asa: bool = Falseasa_target_subspaces: int = 50init_warmup: int = 50final_warmup: int = 1000mask_interval: int = 100asa_importance_beta: float = 0.85asa_uncertainty_beta: float = 0.85asa_schedule_exponent: float = 3.0use_dynamic_rank: bool = Falsesvd_threshold: float = 0.1random_seed: int = 0 )

المعاملات

  • r (int) — الرتبة الكلية لتحليل القيم المفردة (يُرمز لها بـ R في الورقة البحثية). يحدد هذا العدد عدد المتجهات المفردة المستخدمة لتمثيل مصفوفة الأوزان قبل التجميع. القيم الأعلى تلتقط مزيدًا من المعلومات من الأوزان الأصلية لكنها تتطلب المزيد من الحسابات والذاكرة. أما القيم الأدنى فتوفر تنظيمًا أقوى. تتراوح القيم النموذجية عادةً بين 50 و500. القيمة الافتراضية هي 100.
  • num_subspaces (int) — عدد فضاءات الجزئية (K) التي يُقسَّم إليها الفضاء المُحلَّل بتفكيك القيم المفردة (SVD). يتعلم كل فضاء جزئي تحديثات مستقلة منخفضة الرتبة. يؤدي زيادة هذه القيمة إلى تكيّف أدق على مستوى التفاصيل، لكنه يزيد عدد المعاملات القابلة للتدريب بشكل متناسب. عند استخدام ASA (تخصيص فضاءات جزئية تكيفية)، يحدد هذا العدد المبدئي لفضاءات الجزئية قبل التقليم. تتراوح القيم النموذجية عادةً بين 3 و10. القيمة الافتراضية هي 5.
  • subspace_rank (int) — الرتبة (r_i) لكل فضاء فرعي قابل للتدريب. يتحكم هذا في قدرة كل فضاء فرعي على تعلّم التكيفات. تزيد القيم الأعلى من القدرة التعبيرية لكنها تزيد أيضًا من عدد المعاملات القابلة للتدريب. تتدرج المعاملات القابلة للتدريب الإجمالية وفق O(num_subspaces subspace_rank (in_dim + out_dim) / num_subspaces). لمعظم المهام، تعمل قيم تتراوح بين 1 و4 بشكل جيد. القيمة الافتراضية هي 1.
  • target_modules (Optional[Union[list[str], str]]) — أسماء الوحدات التي سيتم تطبيق AdaMSS عليها. إذا تم تحديدها، فلن يتم تكييف هذه الوحدات فقط. يمكن أن تكون قائمة بأسماء الوحدات الدقيقة أو تعبيرًا نمطيًا (regex). على سبيل المثال، ['q_proj', 'v_proj'] لطبقات الانتباه، أو '.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$' للمطابقة باستخدام تعبير نمطي.
  • modules_to_save (Optional[list[str]]) — قائمة بالوحدات، بخلاف طبقات AdaMSS، التي يجب تعيينها قابلة للتدريب وحفظها في نقطة الفحص النهائية. ستخضع هذه الوحدات لضبط دقيق كامل (وليس فقط منخفض الرتبة). وهي مطلوبة للرؤوس المهيأة عشوائياً مثل classifier أو score في مهام التصنيف.
  • init_weights (Literal["orthogonal"]) — طريقة تهيئة الأوزان القابلة للتدريب في AdaMSS. حاليًا، الطريقة المدعومة الوحيدة هي “orthogonal”، والتي تستخدم التهيئة المتعامدة لمصفوفات B (الإسقاط الناتج). يتم تهيئة مصفوفات A إلى الصفر لضمان بدء النموذج من الأوزان المُسبقة التدريب. اضبطها على None لتخطي التهيئة عند التحميل من نقطة تحقق. القيمة الافتراضية هي “orthogonal”.
  • layers_to_transform (Optional[Union[list[int], int]]) — فهارس طبقات محددة لتطبيق AdaMSS عليها. إذا تم تحديدها، فسيتم تكييف هذه الطبقات فقط، وهو ما يكون مفيدًا للتجربة مع تحديد الطبقات التي تستفيد أكثر من التكييف. يمكن أن يكون عددًا صحيحًا واحدًا أو قائمة من الأعداد الصحيحة.
  • layers_pattern (Optional[Union[list[str], str]]) — النمط المطابق لأسماء الطبقات عند تحديد layers_to_transform. يُستخدم لاستخراج فهارس الطبقات من أسماء الوحدات التي لا تتبع النمط الشائع.
  • use_asa (bool) — ما إذا كان سيتم تفعيل Adaptive Subspace Allocation (ASA). عند التفعيل، يقوم ASA بقصّ الفضاءات الجزئية الأقل أهمية ديناميكيًا أثناء التدريب بناءً على معلومات التدرج، مما يقلل من عدد المعاملات الفعّال مع الحفاظ على الأداء. يتطلب ذلك التكامل مع استدعاء تدريب (training callback). القيمة الافتراضية هي False.
  • asa_target_subspaces (int) — العدد الإجمالي المستهدف للفضاءات الجزئية النشطة عبر جميع الطبقات عند تفعيل ASA. سيقوم ASA بقص الفضاءات الجزئية تدريجياً حتى الوصول إلى هذا الهدف. تؤدي القيم المنخفضة إلى قص أكثر عدوانية وعدد أقل من المعلمات القابلة للتدريب. يجب أن تكون أقل من num_subspaces * num_target_modules. تتراوح القيم النموذجية عادةً بين 20 و100 اعتماداً على حجم النموذج. القيمة الافتراضية هي 50. يجب أن تكون عدداً صحيحاً موجباً عندما يكون use_asa=True.
  • init_warmup (int) — عدد خطوات التدريب التي يجب انتظارها قبل بدء تقليم ASA. خلال فترة التسخين، تبقى جميع الفراعات الجزئية نشطة للسماح لدرجات الأهمية بالاستقرار. تمنح القيم الأعلى وقتًا أطول لتقدير دقيق للأهمية لكنها تؤخر عملية التقليم. تتراوح القيم النموذجية عادةً بين 50 و200. القيمة الافتراضية هي 50. يجب أن تكون أصغر من final_warmup عندما يكون use_asa=True.
  • final_warmup (int) — خطوة التدريب التي يكتمل عندها التقليم في ASA ويصل إلى asa_target_subspaces من الفضاءات الجزئية النشطة. يتم توزيع التقليم بين init_warmup وfinal_warmup. يجب ضبطه بناءً على إجمالي خطوات التدريب؛ وعادةً ما يكون ما بين 1/3 و1/2 من إجمالي خطوات التدريب. القيمة الافتراضية هي 1000. يجب أن يكون أكبر من init_warmup عندما يكون use_asa=True.
  • mask_interval (int) — عدد خطوات التدريب بين تحديثات قناع ASA. تتيح القيم المنخفضة تكيّفًا أكثر تكرارًا لكنها تزيد من العبء. توفر القيم الأعلى تقديرات أكثر استقرارًا لأهمية العناصر بين التحديثات. تتراوح القيم النموذجية عادةً بين 50 و200. القيمة الافتراضية هي 100. يجب أن يكون عددًا صحيحًا موجبًا عندما يكون use_asa=True.
  • asa_importance_beta (float) — معامل متوسط الحركة الأسي (EMA) لتنعيم درجات أهمية الفضاء الجزئي. تمنح القيم الأعلى (الأقرب إلى 1.0) وزناً أكبر للأهمية التاريخية، مما يوفر استقراراً. تجعل القيم الأقل الأهمية أكثر استجابة للتدرجات الحديثة. تتراوح القيم النموذجية عادةً بين 0.8 و 0.95. القيمة الافتراضية هي 0.85.
  • asa_uncertainty_beta (float) — معامل EMA لتنعيم تقديرات عدم اليقين في الأهمية. يتحكم في سرعة تكيّف عدم اليقين مع تباين التدرّجات. يشبه asa_importance_beta، حيث توفر القيم الأعلى تقديرات أكثر استقراراً. تتراوح القيم النموذجية عادةً بين 0.8 و 0.95. القيمة الافتراضية هي 0.85.
  • asa_schedule_exponent (float) — أس أُس الجدولة الذي يتحكم في معدل التناقص من إجمالي فضاءات الجزئيات إلى asa_target_subspaces خلال فترة التسخين الأولي لـ ASA. تؤدي القيم الأعلى إلى تقليم أسرع في البداية (تخفيض مبكر أكثر عدوانية)، بينما توفر القيم الأدنى تناقصاً تدريجياً يشبه الخطي. المعادلة هي: current_active_subspaces = asa_target_subspaces + (asa_total_subspaces - asa_target_subspaces) * (progress ** exponent). تتراوح القيم النموذجية بين 1.0 (خطي) و 5.0 (عدواني). القيمة الافتراضية هي 3.0. يجب أن يكون رقماً موجباً عندما يكون use_asa=True (فإن كان الأس صفراً أو سالباً، فإن الجدولة إما تتدهور إلى إجراء دائم لا يؤثر، أو، بمجرد وصول progress إلى 0.0 بالضبط، تثير ZeroDivisionError).
  • use_dynamic_rank (bool) — ما إذا كان سيتم تحديد رتب الفضاءات الجزئية ديناميكيًا بناءً على أحجام القيم المفردة. عند تعيينها إلى True، يتم تحديد رتبة كل فضاء جزئي من خلال عدّ القيم المفردة التي تتجاوز حدًا معينًا، مما يتيح للفضاءات الجزئية المختلفة أن تمتلك رتبًا فعلية مختلفة. عند تعيينها إلى False، تستخدم جميع الفضاءات الجزئية subspace_rank الثابتة. القيمة الافتراضية هي False.
  • svd_threshold (float) — نسبة العتبة لاختيار الرتبة الديناميكي، تُستخدم فقط عندما يكون use_dynamic_rank=True. يُعتبر القيمة المفردة ذات أهمية إذا تجاوزت threshold * max_singular_value. تؤدي القيم الأعلى إلى رتب فعلية أقل (قطع أكثر عدوانية). تتراوح القيم النموذجية عادةً بين 0.05 و 0.2. القيمة الافتراضية هي 0.1 (10% من القيمة القصوى).

فئة التهيئة لطريقة Adamss (Adaptive Multi-Subspaces).

AdaMSS هي طريقة فعّالة من حيث المعلمات للضبط الدقيق، تقوم بتفكيك مصفوفات الأوزان باستخدام SVD وتجميع الفضاء المفكك في عدة فضاءات فرعية قابلة للتدريب. إنها تتعلم تحديثات منخفضة الرتبة داخل هذه الفضاءات الفرعية مع إبقاء الأوزان الأصلية مجمّدة.

AdamssModel

class peft.AdamssModel

< >

( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict] = None ) → torch.nn.Module

المعاملات

  • model (torch.nn.Module) — النموذج الذي سيتم تكييفه.
  • config (AdamssConfig) — إعدادات نموذج Adamss.
  • adapter_name (str) — اسم المُكيّف، القيمة الافتراضية هي "default".

يعيد

torch.nn.Module

نموذج Adamss.

ينشئ نموذج Adamss (Adaptive Multi-Subspaces) من نموذج مُدرَّب مسبقًا.

تقوم الطريقة بتحليل مصفوفات الأوزان باستخدام التحليل القيمي المفرد (SVD) وتجميع الفضاء المُحلَّل في عدة فضاءات فرعية قابلة للتدريب من أجل الضبط الدقيق الموفّر للمعاملات.

مثال:

>>> from transformers import AutoModelForImageClassification
>>> from peft import AdamssConfig, get_peft_model

>>> config = AdamssConfig(
...     r=500,
...     num_subspaces=5,
...     target_modules=["query", "value"],
... )

>>> model = AutoModelForImageClassification.from_pretrained("google/vit-base-patch16-224")
>>> adamss_model = get_peft_model(model, config)

الخصائص:

  • النموذج (~torch.nn.Module) — النموذج الذي سيتم تكييفه.
  • peft_config (AdamssConfig): إعدادات نموذج Adamss.

update_and_allocate

< >

( global_step: int )

المعاملات

  • global_step (int) — خطوة التدريب الحالية.

تحديث درجات الأهمية وتطبيق إخفاء ASA (إذا كان مفعلاً).

يجب استدعاء هذه الطريقة في كل خطوة تدريب بعد loss.backward() وقبل optimizer.zero_grad() عند تفعيل ASA. داخلياً، تقوم بما يلي:

  1. تتراكم درجات الأهمية عبر EMA في كل خطوة خلال فترة الإحماء.
  2. عند فترات الأقنعة، يطبّق إقناع أعلى K عالميًا ويعيد تعيين الأهمية.

هذا هو نقطة الدخول الوحيدة لـ ASA – فاستخدام AdamssAsaCallback مع Trainer من HuggingFace يُوكل الأمر ببساطة إلى هذه الطريقة. أما في حلقات التدريب المخصصة، فاستدعِ هذه الطريقة مباشرةً بدلاً من استخدام callback.

مثال:

for step, batch in enumerate(dataloader):
loss = model(**batch).loss loss.backward() optimizer.step() model.base_model.update_and_allocate(step)
optimizer.zero_grad()
Update on GitHub

←AdaLoRA BOFT→