Transformers documentation
PEFT
PEFT
توفّر PeftAdapterMixin دوالاً من مكتبة PEFT لإدارة المُكيّفات (adapters) مع Transformers. يدعم هذا الميكسين جميع طرق PEFT غير المعتمدة على تعلّم المُوجّهات (LoRA وIA3 وAdaLoRA وغيرها). ولا تُدعم طرق ضبط البادئة (prompt tuning وprompt learning) لأنها لا يمكن حقنها في وحدة torch.
فئة تحتوي على جميع الدوال الخاصة بتحميل أوزان المحوِّلات (adapters) واستخدامها، وهي مدعومة في مكتبة PEFT. لمزيد من التفاصيل حول المحوِّلات وكيفية حقنها في نموذج مبني على معمارية Transformer، راجع توثيق مكتبة PEFT: https://huggingface.co/docs/peft/index
جميع طرق PEFT المدعومة حاليًا هي طرق تعلُّم غير مبنية على الأوامر (LoRA، IA³، إلخ). أما نماذج PEFT الأخرى مثل prompt tuning وprompt learning فهي خارج نطاق هذا الدليل، لأن هذه المكيّفات (adapters) لا يمكن «حقنها» في وحدة torch. لاستخدام هذه الطرق، يُرجى الرجوع إلى دليل استخدام مكتبة PEFT.
مع هذا المزيج، إذا تم تثبيت الإصدار الصحيح من PEFT (>= 0.20.0)، فمن الممكن:
- حمّل مُكيِّفًا (adapter) مخزَّنًا في مسار محلي أو في مستودع بعيد على Hub، وأدرجه في النموذج
- اربط مُكيّفات جديدة في النموذج ودرّبها باستخدام Trainer أو بطريقتك الخاصة.
- إرفاق عدة محوِّلات وتفعيلها / تعطيلها بشكل متكرر
- تفعيل / تعطيل جميع المُكيّفات من النموذج.
- احصل على
state_dictللمُكيّف النشط.
load_adapter
< source >( peft_model_id: str | None = Noneadapter_name: str | None = Nonepeft_config: dict[str, typing.Any] | None = Noneadapter_state_dict: dict[str, 'torch.Tensor'] | None = Nonelow_cpu_mem_usage: bool = Falseis_trainable: bool = Falsehotswap: typing.Union[bool, typing.Literal['auto']] = 'auto'local_files_only: bool = Falseadapter_kwargs: dict[str, typing.Any] | None = Noneload_config: typing.Optional[ForwardRef('LoadStateDictConfig')] = None**kwargs )
المعاملات
- peft_model_id (
str, اختياري) — المعرّف الخاص بالنموذج الذي يجب البحث عنه على Hub، أو مسار محلي إلى ملف إعدادات المحوّل (adapter) المحفوظ وأوزان المحوّل. - adapter_name (
str، اختياري) — اسم المُكيّف (adapter) الذي سيتم استخدامه. إذا لم يتم تعيينه، فسيتم استخدام الاسم "default". - load_config (
LoadStateDictConfig، اختياري) — إعدادات تحميل لإعادة استخدامها عند جلب أوزان المُكيِّف، وعادةً منfrom_pretrained. - kwargs (
dict[str, Any]، اختياري) — حقول إضافية منLoadStateDictConfigتُمرَّر كحجج مُسمّاة. - peft_config (
dict[str, Any], اختياري) — إعدادات المُكيّف (adapter) المُراد إضافته، حيث تشمل المُكيّفات المدعومة جميع إعدادات التعلم غير المرتبطة بالاستدعاء (prompt) مثل (LoRA، IA³، وغيرها). يُستخدم هذا الحُجج في حال مرّر المستخدمون قواميس حالة PEFT مباشرةً. - adapter_state_dict (
dict[str, torch.Tensor], اختياري) — قائمة الحالة (state dict) للمُكيّف (adapter) الذي سيتم تحميله. يُستخدم هذا الحُجّة عندما يمرّر المستخدمون قوائم الحالة الخاصة بـ PEFT مباشرةً. - low_cpu_mem_usage (
bool، اختياري، القيمة الافتراضيةFalse) — يقلل من استهلاك الذاكرة أثناء تحميل مُكيّف PEFT. كما ينبغي أن يسرّع عملية التحميل. - is_trainable (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان يجب أن يكون المُكيّف قابلًا للتدريب أم لا. إذا كانت القيمةFalse، فسيتم تجميد المُكيّف ولن يمكن استخدامه إلا للاستدلال. - hotswap — (
"auto"أوbool, اختياري, الافتراضي هو"auto") ما إذا كان يجب استبدال مُكيّف (LoRA) موجود بمُكيّف جديد محمّل في مكانه. وهذا يعني أنه بدلاً من تحميل مُكيّف إضافي، سيتم أخذ أوزان المُكيّف الحالي واستبدالها بأوزان المُكيّف الجديد. يمكن أن يكون هذا أسرع وأكثر كفاءة في استخدام الذاكرة. ومع ذلك، فإن الميزة الرئيسية لـ hotswap هي أنه عند تجميع النموذج باستخدام torch.compile، فإن تحميل المُكيّف الجديد لا يتطلب إعادة تجميع النموذج. عند استخدام hotswap، يجب أن يكونadapter_nameاسم مُكيّف محمّل مسبقاً.إذا كان للمُكيّف الجديد والمُكيّف القديم رتب مختلفة و/أو قيم LoRA alphas مختلفة (أي معاملات التوسيع)، فستحتاج إلى استدعاء طريقة إضافية قبل تحميل المُكيّف:
حمّل أوزان المُكيّف من ملف أو من مجلد بعيد على Hub. إذا لم تكن على دراية بالمُكيّفات وطرق PEFT، ندعوك إلى قراءة المزيد عنها في التوثيق الرسمي لـ PEFT: https://huggingface.co/docs/peft
يتطلب تثبيت PEFT كخلفية (backend) لتحميل أوزان المحوّل (adapter).
add_adapter
< source >( adapter_configadapter_name: str | None = None )
المعاملات
- adapter_config (
~peft.PeftConfig) — إعدادات المُكيّف (adapter) المراد إضافته، حيث تشمل المُكيّفات المدعومة طرق التعلم غير المعتمدة على المُوجّهات (LoRA، IA³، إلخ). - adapter_name (
str، اختياري، القيمة الافتراضية"default") — اسم المُكيّف (adapter) الذي سيتم إضافته. إذا لم يتم تمرير اسم، فسيتم تعيين اسم افتراضي للمُكيّف.
إذا لم تكن على دراية بالمُكيِّفات (adapters) وطرق PEFT، ندعوك إلى الاطلاع على المزيد من المعلومات عنها في التوثيق الرسمي لـ PEFT: https://huggingface.co/docs/peft
يضيف مُكيّفًا جديدًا إلى النموذج الحالي لأغراض التدريب. إذا لم يتم تمرير اسم للمُكيّف، يُسند اسم افتراضي للمُكيّف لاتباع اتفاقية مكتبة PEFT (في PEFT نستخدم "default" كاسم مُكيّف افتراضي).
لاحظ أن المُكيّف المُضاف حديثًا لا يتم تفعيله تلقائيًا. لتفعيله، استخدم model.set_adapter.
set_adapter
< source >( adapter_name: list[str] | str )
إذا لم تكن على دراية بالمُكيِّفات (adapters) وطرق PEFT، ندعوك إلى قراءة المزيد عنها في التوثيق الرسمي لـ PEFT: https://huggingface.co/docs/peft
يضبط مُكيِّفًا محددًا من خلال إجبار النموذج على استخدام ذلك المُكيِّف وتعطيل المُكيِّفات الأخرى.
إذا لم تكن على دراية بالمُكيِّفات (adapters) وطرق PEFT، ندعوك إلى قراءة المزيد عنها في التوثيق الرسمي لـ PEFT: https://huggingface.co/docs/peft
تعطيل جميع المُكيّفات (adapters) المرتبطة بالنموذج. يؤدي هذا إلى الاستدلال باستخدام النموذج الأساسي فقط.
إذا لم تكن على دراية بالمُكيِّفات (adapters) وطرق PEFT، ندعوك إلى الاطلاع على المزيد من المعلومات عنها في التوثيق الرسمي لـ PEFT: https://huggingface.co/docs/peft
تفعيل المُكيّفات (adapters) المرتبطة بالنموذج.
enable_peft_hotswap
< source >( target_rank: int = 128check_compiled: typing.Literal['error', 'warn', 'ignore'] = 'error' )
المعاملات
- target_rank (
int، اختياري، القيمة الافتراضية128) — أعلى رتبة بين جميع المحوِّلات التي سيتم تحميلها. - check_compiled (
str, اختياري, الافتراضي هو"error") — كيفية التعامل مع الحالة التي يكون فيها النموذج مُجمَّعًا مسبقًا، وهو ما ينبغي تجنّبه عمومًا. الخيارات هي:- “error” (الافتراضي): يرمي خطأ
- "warn": إصدار تحذير
- “ignore”: لا تفعل شيئًا
يتيح إمكانية تبديل محركات PEFT ذات الرتب المختلفة بشكل فوري، أو، إذا كان النموذج مُجمَّعًا، دون الحاجة إلى إعادة التجميع.
حالياً، يُدعم تبديل الحار (hotswapping) فقط لتقنية LoRA.
لا يُشترط استدعاء هذه الطريقة إلا عند تبديل المحوِّلات (adapters) بشكل فوري، وفي حال كان النموذج مُجمَّعًا (compiled) أو إذا اختلفت رتب (ranks) المحوِّلات المُحمَّلة. أما إذا كانت الرتب جميعها متطابقة وكان النموذج غير مُجمَّع، فإن التبديل الفوري يعمل دون الحاجة إلى استدعاء هذه الطريقة مسبقًا.
إذا لم تكن على دراية بالمُكيِّفات (adapters) وطرق PEFT، ندعوك إلى قراءة المزيد عنها في التوثيق الرسمي لـ PEFT: https://huggingface.co/docs/peft
يحصل على المُكيِّفات (adapters) النشطة حاليًا للنموذج. في حالة الاستدلال متعدد المُكيِّفات (دمج عدة مُكيِّفات للاستدلال)، يعيد قائمة بجميع المُكيِّفات النشطة حتى يتمكن المستخدمون من التعامل معها وفقًا لذلك.
في إصدارات PEFT السابقة (التي لا تدعم الاستدلال متعدد المحوِّلات)، سيعيد module.active_adapter
نصاً واحداً فقط.
get_adapter_state_dict
< source >( adapter_name: str | None = Nonestate_dict: dict | None = None )
المعاملات
- adapter_name (
str, اختياري) — اسم المُكيّف الذي سيتم منه استخلاص قاموس الحالة. إذا لم يتم تمرير اسم، فسيتم استخدام المُكيّف النشط. - state_dict (قاموس متداخل من
torch.Tensor، اختياري) — قاموس الحالة للنموذج. سيكون الافتراضيself.state_dict()، لكن يمكن استخدامه إذا كانت هناك حاجة إلى اتخاذ احتياطات خاصة عند استعادة قاموس حالة النموذج (مثل عند استخدام توازٍ للنموذج).
إذا لم تكن على دراية بالمُكيِّفات (adapters) وطرق PEFT، ندعوك إلى قراءة المزيد عنها في التوثيق الرسمي لـ PEFT: https://huggingface.co/docs/peft
يحصل على قاموس حالة المُكيّف (adapter state dict) الذي يجب أن يحتوي فقط على تensors الأوزان الخاصة بالمُكيّف المحدد باسم adapter_name. إذا لم يتم تمرير adapter_name، يتم استخدام المُكيّف النشط.
delete_adapter
< source >( adapter_names: list[str] | str )
حذف مُكيّف PEFT من النموذج الأساسي.