Hugging Face's logo

PEFT documentation

المنظّمات

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

المنظّمات

المُضَبِط (أو المُكيِّف) هو وحدة يمكن توصيلها بـ torch.nn.Module. فئة BaseTuner الأساسية للمُضَبِّطين الآخرين وتوفر طرقًا وخصائص مشتركة لتحضير إعداد المُكيِّف واستبدال الوحدة المستهدفة بوحدة المُكيِّف. BaseTunerLayer هي فئة أساسية لطبقات المُكيِّف. وهي توفر طرقًا وخصائص لإدارة المُكيِّفات مثل تفعيل المُكيِّفات وتعطيلها.

BaseTuner

فئة peft.tuners.tuners_utils.BaseTuner

< >

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

المعاملات

  • model (torch.nn.Module) — النموذج الذي ستُربط به طبقات مُعدِّل المُكيّف (adapter tuner).
  • forward (Callable) — طريقة النموذج الأمامية.
  • peft_config (Union[PeftConfig, dict[str, PeftConfig]]) — كائن إعدادات المُكيّف، يجب أن يكون قاموسًا من str إلى كائنات PeftConfig. يمكن أيضًا تمرير كائن PeftConfig وسيتم إنشاء مُكيّف جديد بالاسم الافتراضي adapter أو إنشاء قاموس جديد بمفتاح adapter_name وقيمة هي ذلك peft config.
  • config (dict[str, Any]) — كائن إعدادات النموذج، يجب أن يكون قاموسًا من كائنات str إلى كائنات Any.
  • targeted_module_names (list[str]) — قائمة أسماء الوحدات التي تم تكييفها فعليًا. قد تكون مفيدة للتدقيق السريع للتأكد من أن config.target_modules تم تحديدها بشكل صحيح.
  • targeted_parameter_names (list[str]) — قائمة أسماء المعاملات التي تم تكييفها فعليًا. قد تكون مفيدة للتدقيق السريع للتأكد من أن config.target_parameters تم تحديدها بشكل صحيح.
  • prefix (str) — البادئة الفريدة الخاصة بطريقة PEFT. على سبيل المثال "lora_" لـ LoRA.

نموذج مُعدِّل أساسي يوفر الطرق والخصائص المشتركة لجميع المُعدِّلات القابلة للحقن في torch.nn.Module

لإضافة فئة Tuner جديدة، يجب تجاوز الطرق التالية:

  • _prepare_adapter_config: طريقة خاصة لتحضير إعدادات المُكيّف في النهاية، على سبيل المثال في حال غياب الحقل target_modules.
  • _create_and_replace: طريقة خاصة لإنشاء واستبدال الوحدة المستهدفة بوحدة المُكيّف.
  • _check_target_module_exists: طريقة مساعدة خاصة للتحقق مما إذا كان اسم المفتاح الخاص بالوحدة المُمررة يطابق أيًا من الوحدات المستهدفة في adapter_config.

أسهل طريقة هي التحقق مما يتم إنجازه في فئة peft.tuners.lora.LoraModel.

delete_adapter

< >

( adapter_name: str )

المعاملات

  • adapter_name (str) — اسم المُكيّف الذي سيتم حذفه.

يحذف مُكيّفًا موجودًا.

disable_adapter_layers

< >

( )

تعطيل جميع المُكيِّفات في مكانها.

عند تعطيل جميع المُكيِّفات، يتطابق مخرَج النموذج مع مخرَج النموذج الأساسي.

enable_adapter_layers

< >

( )

تفعيل جميع المُكيِّفات في مكانها

get_model_config

< >

( model: nn.Module )

المعاملات

  • model (nn.Module) — النموذج الذي سيتم الحصول على الإعدادات منه.
  • default (dict|None، اختياري) —: ما الذي يجب إرجاعه إذا لم يكن للنموذج سمة config.

تجلب هذه الطريقة الإعدادات من نموذج على شكل قاموس. إذا لم يكن للنموذج خاصية config، فإن هذه الطريقة تُرجع إعدادات افتراضية.

inject_adapter

< >

( model: nn.Moduleadapter_name: strautocast_adapter_dtype: bool = Truelow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None )

المعاملات

  • model (nn.Module) — النموذج الذي سيتم ضبطه.
  • adapter_name (str) — اسم المُكيّف.
  • autocast_adapter_dtype (bool، اختياري) — ما إذا كان سيتم تحويل نوع بيانات المحوّل تلقائيًا. القيمة الافتراضية هي True.
  • low_cpu_mem_usage (bool, optional, defaults to False) — إنشاء أوزان مُكيّف فارغة على جهاز meta. مفيد لتسريع عملية التحميل.
  • state_dict (dict، اختياري، القيمة الافتراضية None) — إذا تم تمرير state_dict هنا، فسيتم حقن المُكيّفات (adapters) بناءً على إدخالات state_dict. يمكن أن يكون هذا مفيدًا عندما تكون target_modules الدقيقة لطريقة PEFT غير معروفة، على سبيل المثال لأن نقطة التفتيش (checkpoint) أُنشئت دون بيانات وصفية. لاحظ أن القيم من state_dict لا تُستخدم، بل تُستخدم المفاتيح فقط لتحديد الطبقات الصحيحة التي يجب تكييفها.

ينشئ طبقات المُكيِّف (adapter) ويستبدل الوحدات المستهدفة بطبقات المُكيِّف. يُستدعى هذا الأسلوب في الخلفية بواسطة peft.mapping.get_peft_model إذا تم تمرير فئة مُكيِّف غير مبنية على ضبط التلميح (non-prompt tuning).

يتم استرجاع إعداد PEFT المقابل مباشرةً من خاصية peft_config في فئة BaseTuner.

merge_adapter

< >

( adapter_names: Optional[list[str]] = Nonesafe_merge: bool = False )

المعاملات

  • adapter_names (list[str], اختياري) — قائمة أسماء المحوِّلات (adapters) التي يجب دمجها. إذا كانت None، فسيتم دمج جميع المحوِّلات النشطة. القيمة الافتراضية هي None.
  • safe_merge (bool، اختياري) — إذا كان True، فسيتم تنفيذ عملية الدمج في نسخة من الأوزان الأصلية والتحقق من قيم NaN قبل دمج الأوزان. هذا مفيد إذا كنت تريد التحقق مما إذا كانت عملية الدمج ستنتج قيم NaN. القيمة الافتراضية هي False.

تقوم هذه الطريقة بدمج طبقات المُكيِّف (adapter) في النموذج الأساسي.

قد يؤدي دمج المُكيّفات إلى تسريع مسار الأمامي. لا يزال يتم الاحتفاظ بنسخة من أوزان المُكيّفات في الذاكرة، وهو أمر مطلوب لفك دمج المُكيّفات. من أجل دمج أوزان المُكيّفات دون الاحتفاظ بها في الذاكرة، يرجى استدعاء merge_and_unload.

بمجرد أن يدمج طبقة ما أوزان المُكيِّف، فإن مرورها الأمامي يستخدم تلك الأوزان فقط. لذلك، إذا لم تغطي adapter_names جميع المُكيِّفات النشطة، فلن تُطبَّق المُكيِّفات النشطة المتبقية بصمت، على الرغم من أنها ما تزال مُبلَّغًا عنها كنشطة. إما ادمج جميع المُكيِّفات النشطة أو استدعِ unmerge_adapter أولاً. لاحظ أن هذا السلوك مُزمَع تغييره في إصدار v1.0.

merge_and_unload

< >

( progressbar: bool = Falsesafe_merge: bool = Falseadapter_names: Optional[list[str]] = None )

المعاملات

  • progressbar (bool) — ما إذا كان يجب عرض شريط تقدم يُظهر عملية التحميل والدمج (الافتراضي: False).
  • safe_merge (bool) — ما إذا كان سيتم تفعيل فحص الدمج الآمن للتحقق من وجود أي قيم Nan محتملة في أوزان المحوّل.
  • adapter_names (List[str]، اختياري) — قائمة أسماء المحوِّلات (adapters) التي يجب دمجها. إذا كانت القيمة None، فسيتم دمج جميع المحوِّلات النشطة. القيمة الافتراضية هي None.

تقوم هذه الطريقة بدمج طبقات المُكيِّف (adapter) في النموذج الأساسي.

هذا مطلوب إذا أراد أحد ما استخدام النموذج الأساسي كنموذج مستقل. النموذج المُعاد له نفس البنية المعمارية للنموذج الأساسي الأصلي.

من المهم إسناد النموذج المُعاد إلى متغير واستخدامه، فهذه ليست عملية تتم في الموقع!

مثال:

>>> from transformers import AutoModelForCausalLM
>>> from peft import PeftModel

>>> model_id = ...
>>> base_model = AutoModelForCausalLM.from_pretrained(model_id)
>>> peft_model_id = ...
>>> model = PeftModel.from_pretrained(base_model, peft_model_id)
>>> merged_model = model.merge_and_unload()

set_adapter

< >

( adapter_name: str | list[str]inference_mode: bool = False )

المعاملات

  • adapter_name (str, list[str]) — أسماء المُكيِّف (المُكيِّفات) التي سيتم تعيينها كفعّالة
  • inference_mode (bool, اختياري) — ما إذا كان يجب تجميد المُكيّف المُفعّل (أي requires_grad=False). القيمة الافتراضية هي False.

اضبط المُكيّف (المُكيّفات) النشط(ة).

set_requires_grad

< >

( adapter_names: str | Sequence[str]requires_grad: bool = True )

المعاملات

  • adapter_names (str أو Sequence[str]) — اسم المُكيِّف (أو المُكيِّفات) التي يجب تمكين/تعطيل التدرجات الخاصة بها.
  • requires_grad (bool, اختياري) — ما إذا كان سيتم تفعيل (True، الافتراضي) أو تعطيل (False).

تفعيل أو تعطيل التدرجات على المُكيِّف (المُكيِّفات) المُحدَّد.

supports_lora_conversion

< >

( adapter_name: str = 'default' )

ما إذا كان من الممكن تحويل مُكيّف هذا النموذج إلى LoRA.

عادةً، يعمل هذا إذا كانت طريقة PEFT إضافية، أي W’ = W_base + delta_weight.

تفريغ

< >

( )

أعد النموذج الأساسي عن طريق إزالة جميع وحدات PEFT.

من المهم إسناد النموذج المُعاد إلى متغير واستخدامه، فهذه ليست عملية تتم في الموقع!

unmerge_adapter

< >

( )

تقوم هذه الطريقة بإلغاء دمج جميع طبقات المُكيِّف المُدمجة من النموذج الأساسي.

BaseTunerLayer

فئة peft.tuners.tuners_utils.BaseTunerLayer

< >

( )

المعاملات

  • is_pluggable (bool، اختياري) — ما إذا كان بإمكان طبقة المُكيّف (adapter) أن تُوصَل بأي وحدة في PyTorch
  • active_adapters (Union[Liststr, str], اختياري) — اسم المُكيّف النشط.

مزيج طبقة مُعدِّل (tuner layer mixin) يوفر الطرق والخصائص المشتركة لجميع المُعدِّلات.

delete_adapter

< >

( adapter_name: str )

المعاملات

  • adapter_name (str) — اسم المُكيّف الذي سيتم حذفه

حذف مُكيّف من الطبقة

يجب استدعاء هذا على جميع طبقات المُكيِّف (adapter)، وإلا سنحصل على حالة غير متسقة.

ستقوم هذه الطريقة أيضًا بإعداد مُكيّف نشط جديد إذا كان المُكيّف المحذوف مُكيّفًا نشطًا. من المهم أن يتم اختيار المُكيّف الجديد بطريقة حتمية، بحيث يُختار نفس المُكيّف في جميع الطبقات.

enable_adapters

< >

( enabled: bool )

المعاملات

  • enabled (bool) — True لتفعيل المُكيّفات، False لتعطيل المُكيّفات

تبديل تفعيل أو تعطيل المحوِّلات

يتولى ضبط علم requires_grad لأوزان المُكيِّف.

get_base_layer

< >

( )

الحصول على base_layer (بشكل تكراري).

هذا ضروري في الحالة التي تغلف فيها طبقة الضبط طبقة ضبط أخرى.

get_base_weight

< >

( )

إرجاع وزن الطبقة الأساسية.

يتولى هذا الأمر إلغاء تكميم الوزن في حال كان مكمَّمًا.

set_adapter

< >

( adapter_names: str | list[str]inference_mode: bool = False )

المعاملات

  • adapter_names (str أو list[str]) — أسماء المُكيِّف (المُكيِّفات) التي يجب تعيينها كفعّالة.
  • inference_mode (bool, اختياري) — ما إذا كان يجب تجميد المُكيّف المُفعّل (أي requires_grad=False). القيمة الافتراضية هي False.

اضبط المُكيّف (المُكيّفات) النشط(ة).

بالإضافة إلى ذلك، ستقوم هذه الدالة بجعل المُكيّف المحدد قابلًا للتدريب (أي requires_grad=True) ما لم يكن inference_mode بقيمة True.

set_base_weight

< >

( weight_data: torch.Tensor )

يُعيّن الوزن الأساسي للطبقة الأساسية إلى الموتر الجديد

يعمل هذا أيضًا مع الأوزان المُكمّاة.

set_requires_grad

< >

( adapter_names: str | Sequence[str]requires_grad: bool = True )

المعاملات

  • adapter_names (str أو Sequence[str]) — اسم المُكيِّف (أو المُكيِّفات) التي يجب تمكين/تعطيل التدرجات الخاصة بها.
  • requires_grad (bool, اختياري) — ما إذا كان سيتم تفعيل (True، الافتراضي) أو تعطيل (False).

تفعيل أو تعطيل التدرجات على المُكيِّف (المُكيِّفات) المُحدَّد.

set_training

< >

( adapter_names: str | Sequence[str]training: bool = True )

المعاملات

  • adapter_names (str أو Sequence[str]) — اسم المُكيّف (أو المُكيّفات) الذي يجب تحديث وضع التدريب الخاص به.
  • training (bool، اختياري) — ما إذا كان سيتم تفعيل وضع التدريب (True، الافتراضي) أو تعطيله (False).

تفعيل أو تعطيل وضع التدريب على وحدات المحوّل المحددة.

supports_lora_conversion

< >

( adapter_name: str = 'default' )

ما إذا كان من الممكن تحويل هذا النوع من الطبقات إلى LoRA.

عادةً، يعمل هذا إذا كانت طريقة PEFT إضافية، أي W’ = W_base + delta_weight.

Update on GitHub

←الإعداد AdaLoRA→