PEFT documentation
طرق مساعدة
طرق مساعدة
مجموعة من الدوال المساعدة لـ PEFT.
التحقق مما إذا كان النموذج نموذج PEFT
peft.helpers.check_if_peft_model
< source >( model_name_or_path: str ) → bool
تحقق مما إذا كان النموذج نموذج PEFT.
إعادة تحجيم مقياس المحوّل مؤقتًا في وحدات LoraLayer
peft.helpers.rescale_adapter_scale
< source >( model: Modulemultiplier: float | int )
المعاملات
- model — النموذج الذي يحتوي على وحدات
LoraLayerالتي سيتم ضبط معامل التوسع الخاص بها. - multiplier (float or int) —
المضاعِف الذي يعيد تحجيم خاصية
scaling. يجب أن يكون من النوع float أو int.
يرفع
ValueError
ValueError— إذا لم يحتوي النموذج على أي من حالاتLoraLayer، مما يشير إلى أن النموذج لا يدعم التوسيع.
مدير سياق لإعادة مقياس مقياس مُكيّف LoRA مؤقتًا في نموذج.
تُستعاد قيم التوسيع الأصلية عند خروج مدير السياق. يعمل مدير السياق هذا مع نماذج transformers وdiffusers التي تم تحميل مُكيّفات LoRA فيها مباشرةً.
في حالة LoRA، فإن تطبيق مدير السياق هذا مع مُضاعِف ضمن المجال [0, 1] مكافئ تمامًا لتطبيق wise-ft (راجع #1940 للتفاصيل). يمكن أن يحسّن أداء النموذج إذا كان هناك انزياح في التوزيع بين بيانات التدريب المستخدمة للضبط الدقيق، وبيانات الاختبار المستخدمة أثناء الاستدلال.
تحذير: تم الإبلاغ عن أنه عند استخدام واجهة MPS من Apple لـ PyTorch، من الضروري إضافة فترة نوم قصيرة بعد الخروج من السياق قبل أن تُستعاد المقاييس بالكامل.
مدير سياق لتعطيل تحويل نوع البيانات المدخلة في الطريقة الأمامية لطبقات LoRA
peft.helpers.disable_input_dtype_casting
< source >( model: Moduleactive: bool = True )
تعطّل مُدير السياق (Context manager) تحويل نوع البيانات المدخلة إلى نوع بيانات الوزن.
مدير سياق لتفعيل تخزين DoRA مؤقتًا (أسرع وقت الاستدلال لكنه يتطلب ذاكرة أكثر)
مدير سياق لتفعيل تخزين مؤقت لـ DoRA، مما يحسّن سرعة استنتاج DoRA على حساب الذاكرة.
مع التخزين المؤقت النشط، يتم تخزين وزن LoRA المادي (B @ A) ومعايير الوزن (الوزن الأساسي + وزن LoRA) في ذاكرة التخزين المؤقت.
حتى في سياق التخزين المؤقت، إذا كان النموذج في وضع التدريب، يتم تعطيل التخزين المؤقت. عند تحويل النموذج إلى وضع التدريب، سيتم مسح ذاكرة التخزين المؤقت.
مثال:
>>> from peft.helpers import DoraCaching
>>> model.eval() # put in eval model for caching to work
>>> with DoraCaching(): # use as a context manager
... output = model(inputs)
>>> dora_caching = DoraCaching()
>>> dora_caching(enabled=True) # permanently enable caching
>>> output = model(inputs)
>>> dora_caching(enabled=False) # permanently disable caching
>>> output = model(inputs)إنشاء تكوين LoRA وهمي للتبديل الساخن
راجع البدء بمكيّف وهمي للحصول على سير العمل وسطر الأوامر.
peft.helpers.create_dummy_lora_config
< source >( configs: Sequence ) → LoraConfig
المعاملات
- configs (
Sequence[LoraConfig]) — سلسلة غير فارغة من تكوينات LoRA المتوافقة للنموذج الأساسي نفسه. يجب أن تحتوي كل منها علىtarget_modulesصريحة وغير فارغة؛ لا يتم دعم السلاسل النصية (بما في ذلك التعبيرات النمطية و"all-linear") أو الأهداف المستنتجة. يتم دعم LoRA القياسي وrsLoRA، دون وحدات أو انحيازات أو معاملات إضافية محفوظة.
يعيد
LoraConfig
إعداد بمعايرة مخرجات صفرية ورتبة قصوى موحدة.
يرفع
TypeError أو ValueError
TypeError— إذا لم يكن أي من التكوينات تكوين LoRA.ValueError— إذا لم يتم تقديم أي تكوينات، أو كانت إعداداتها غير مدعومة أو غير متوافقة.
أنشئ تكوين LoRA لا يؤدي أي عمل (no-op) يخصص سعة للتبديل السريع (hotswapping).
تتمثل الغاية من هذه الدالة المساعدة في إنشاء إعداد LoRA وهمي يمكن استخدامه لتبديل نموذج LoRA قبل تبديل محولات LoRA المختلفة (انظر https://huggingface.co/docs/peft/main/en/package_reference/hotswap). إحدى المشكلات المتعلقة بالتبديل هي أن محول LoRA الأول الذي يتم تحميله يحتاج إلى تثبيت أوزان LoRA على جميع الطبقات التي ستستهدفها محولات LoRA المتبادلة لاحقًا. إذا استهدفت هذه المحولات طبقات منفصلة، فلا يمكن لأي منها أن يعمل كمحول LoRA الأول. تنشئ هذه الدالة المساعدة محول LoRA وهميًا يستهدف اتحاد طبقات جميع محولات LoRA الفردية. كما أنها تخصص مسبقًا أوزان LoRA برتبة كبيرة بما يكفي.
لا يُقصد استخدام إعداد LoRA المولّد للتدريب الإضافي.
لا يتم تحميل أي أوزان لنموذج أساسي أو مُكيّف. يتم إزالة عوامل التصفية والاستثناءات للطبقات لتغطية كل مُكيّف، مما قد يؤدي إلى تخصيص مفرط لأوزان LoRA على طبقات إضافية.
أنشئ النتيجة باستخدام get_peft_model، ثم استدعِ prepare_model_for_compiled_hotswap قبل التجميع. يتم تهيئة المُكيّف الوهمي بحيث يكون عملية لا شيء (no-op)، أي أنه لا يحتاج إلى تعطيل لتشغيل الاستدلال على النموذج الأساسي.
لاحظ أن بعض حُجج LoraConfig غير مدعومة وستؤدي إلى خطأ. والسبب في ذلك أنه لن يكون من الممكن دمج تلك الإعدادات في إعداد وهمي واحد.
يوجد سكربت مساعد في مستودع PEFT لإنشاء إعداد LoRA الوهمي من سطر الأوامر:
python scripts/create-dummy-lora-for-hotswap.py adapter0 adapter1 [...] --output-dir dummy-lora
اختيار الهدف في KappaTune
KappaTuneSelector وfind_kappa_target_modules تنفّذان عملية اختيار عامة للأهداف من ورقة KappaTune.
تحديد الطريقة الوحدات ذات المرونة الأعلى (أعلى إنتروبيا تفاضلية للمخرجات) والتخصص الأدنى (حساسية أقل تجاه اتجاهات مدخلات محددة).
تجعل هذه الخصائص الوحدات المختارة مرشّحة جيدة للتخفيف من النسيان الكارثي في أي طريقة تكيّف تضيف معاملات قابلة للتدريب، بما في ذلك LoRA وDoRA وLoHa وAdaLoRA، وحتى الضبط الدقيق المباشر للأوزان الأصلية.
فئة peft.helpers.KappaTuneSelector
< source >( model: Modulemax_dim_size_to_analyze: int = 16384moe_param_suffixes: tuple[str, ...] | None = Noneshow_progress: bool = True )
أداة خفيفة الوزن لحساب أرقام الحالة لكل وحدة / لكل معامل وإرجاع أفضل أهداف LoRA.
يدعم:
- وحدات nn.Linear التقليدية (معاملات target_modules في LoraConfig)
- أوزان MoE المدمجة الحديثة المخزنة على شكل nn.Parameter ثلاثي الأبعاد (gate_up_proj / down_proj، gate_proj / up_proj، إلخ) المستخدمة في Llama-4 وQwen2_MoE وQwen3_MoE وMixtral وOLMoE ونماذج مشابهة. تُعاد هذه الأوزان عبر target_parameters.
ملاحظات:
- يتطلب حساب رقم الشرط تشغيل تحليل القيم المفردة (SVD) وقد يستغرق عدة دقائق على النماذج الكبيرة جداً. يمكن إظهار شريط التقدم أو تعطيله عبر
show_progress.
peft.find_kappa_target_modules
< source >( model: Moduletop_p: float = 0.2max_dim_size_to_analyze: int = 16384moe_param_suffixes: tuple[str, ...] | None = Noneshow_progress: bool = True )
المعاملات
- model (nn.Module) — النموذج الأساسي الذي سيتم تحليل أوزانه من حيث أرقام الحالة.
- top_p (float, اختياري) — اختر النسبة الأعلى من الوحدات/المعاملات المرشحة ذات أرقام الحالة الأدنى.
- max_dim_size_to_analyze (int, اختياري) — الحد الأعلى لأقصى بُعد للمصفوفة التي يتم تحليلها عبر SVD. القيمة الافتراضية هي 16384.
- moe_param_suffixes (Optional[tuple[str, …]], optional) —
لاحقات أسماء المعلمات المستخدمة لتحديد متجهات MoE المدمجة التي يجب إرجاعها عبر
target_parameters. إذا كانت القيمة None، تُستخدم قيم افتراضية مناسبة. - show_progress (bool, optional) — ما إذا كان يجب عرض شريط تقدّم أثناء حساب أرقام الحالة (المبنية على SVD) عبر المرشّحات/وحدات المرشّحات. عطّلها في بيئات CI أو البيئات غير التفاعلية الأخرى. القيمة الافتراضية هي True.
دالة مريحة من سطر واحد لاختيار هدف KappaTune. تُرجع كلًا من target_modules و target_parameters.