PEFT documentation

تنسيق نقطة الحفظ لـ PEFT

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

تنسيق نقطة الحفظ لـ PEFT

يصف هذا المستند كيفية تنظيم ملفات نقاط التفتيش في PEFT وكيفية التحويل بين صيغة PEFT والصيغ الأخرى.

ملفات PEFT

تحديث طرق PEFT (التدريب الدقيق الفعال من حيث المعاملات) مجموعة فرعية صغيرة فقط من معاملات النموذج بدلاً من جميعها. وهذا أمر جيد لأن ملفات نقاط التفتيش يمكن أن تكون أصغر بكثير من ملفات النموذج الأصلية بشكل عام، مما يسهّل تخزينها ومشاركتها. ومع ذلك، يعني هذا أيضاً أنه لتحميل نموذج PEFT، يجب أن يكون النموذج الأصلي متاحاً أيضاً.

عند استدعاء save_pretrained() على نموذج PEFT، يحفظ نموذج PEFT ثلاثة ملفات، وهي موضحة أدناه:

  1. adapter_model.safetensors أو adapter_model.bin

بشكل افتراضي، يُحفظ النموذج بتنسيق safetensors، وهو بديل آمن لتنسيق bin، المعروف بأنه عرضة لـثغرات أمنية لأنه يستخدم أداة pickle في الخلفية. ومع ذلك، يخزن كلا التنسيقين نفس state_dict، ويمكن استبدال أحدهما بالآخر.

لا يحتوي state_dict إلا على معاملات وحدة المُكيّف (adapter)، وليس النموذج الأساسي. ولإبراز الفرق في الحجم، يتطلب نموذج BERT العادي مساحة قرص تبلغ حوالي 420 ميغابايت، في حين أن مُكيّف IA³ فوق هذا النموذج يتطلب فقط حوالي 260 كيلوبايت.

  1. adapter_config.json

تحتوي ملف adapter_config.json على إعدادات وحدة المحوّل، وهي ضرورية لتحميل النموذج. أدناه مثال على adapter_config.json لمحوّل IA³ مع إعدادات قياسية مطبقة على نموذج BERT:

{
  "auto_mapping": {
    "base_model_class": "BertModel",
    "parent_library": "transformers.models.bert.modeling_bert"
  },
  "base_model_name_or_path": "bert-base-uncased",
  "fan_in_fan_out": false,
  "feedforward_modules": [
    "output.dense"
  ],
  "inference_mode": true,
  "init_ia3_weights": true,
  "modules_to_save": null,
  "peft_type": "IA3",
  "revision": null,
  "target_modules": [
    "key",
    "value",
    "output.dense"
  ],
  "task_type": null
}

يحتوي ملف الإعداد على:

  • نوع وحدة المحوّل المخزّن، "peft_type": "IA3"
  • معلومات حول النموذج الأساسي مثل "base_model_name_or_path": "bert-base-uncased"
  • مراجعة النموذج (إن وجدت)، "revision": null

إذا لم يكن النموذج الأساسي نموذج Transformers مُدرَّبًا مسبقًا، فستكون الحقلان الأخيران null. بخلاف ذلك، ترتبط جميع الإعدادات بمُكيّف IA³ المحدد الذي استُخدم لضبط النموذج.

  1. README.md

الملف README.md المُولَّد هو بطاقة النموذج لنموذج PEFT ويحتوي على بعض الحقول المُعبَّأة مسبقًا. الهدف من ذلك هو تسهيل مشاركة النموذج مع الآخرين وتوفير بعض المعلومات الأساسية عنه. لا يُعدّ هذا الملف مطلوبًا لتحميل النموذج.

التحويل إلى صيغة PEFT

عند التحويل من صيغة أخرى إلى صيغة PEFT، نحتاج إلى كل من ملف adapter_model.safetensors (أو adapter_model.bin) وملف adapter_config.json.

adapter_model

بالنسبة لأوزان النموذج، من المهم استخدام الترميز الصحيح من اسم المعامل إلى القيمة حتى يتمكن PEFT من تحميل الملف. إن الحصول على هذا الترميز بشكل صحيح هو تمرين في التحقق من تفاصيل التنفيذ، إذ لا يوجد تنسيق متفق عليه بشكل عام لمُكيّفات PEFT.

حسنًا، تحديد هذا الترميز ليس معقدًا بشكل مفرط في الحالات الأساسية الشائعة. دعونا ننظر إلى مثال ملموس، وهو LoraLayer:

# showing only part of the code

class LoraLayer(BaseTunerLayer):
    # All names of layers that may contain (trainable) adapter weights
    adapter_layer_names = ("lora_A", "lora_B", "lora_embedding_A", "lora_embedding_B")
    # All names of other parameters that may contain adapter-related parameters
    other_param_names = ("r", "lora_alpha", "scaling", "lora_dropout")

    def __init__(self, base_layer: nn.Module, **kwargs) -> None:
        self.base_layer = base_layer
        self.r = {}
        self.lora_alpha = {}
        self.scaling = {}
        self.lora_dropout = nn.ModuleDict({})
        self.lora_A = nn.ModuleDict({})
        self.lora_B = nn.ModuleDict({})
        # For Embedding layer
        self.lora_embedding_A = nn.ParameterDict({})
        self.lora_embedding_B = nn.ParameterDict({})
        # Mark the weight as unmerged
        self._disable_adapters = False
        self.merged_adapters = []
        self.use_dora: dict[str, bool] = {}
        self.lora_magnitude_vector: Optional[torch.nn.ParameterDict] = None  # for DoRA
        self._caches: dict[str, Any] = {}
        self.kwargs = kwargs

في كود __init__ المستخدم في جميع فئات LoraLayer في PEFT، توجد مجموعة من المعاملات المستخدمة لتبني النموذج، لكن القليل منها فقط ذو صلة بملف نقطة الحفظ: lora_A، lora_B، lora_embedding_A، وlora_embedding_B. تُدرج هذه المعاملات في خاصية الفئة adapter_layer_names وتحتوي على المعاملات القابلة للتعلم، لذا يجب تضمينها في ملف نقطة الحفظ. أما جميع المعاملات الأخرى، مثل الرتبة r، فتُشتق من adapter_config.json ويجب تضمينها هناك (ما لم يُستخدم القيمة الافتراضية).

لنتحقق من state_dict لنموذج PEFT LoRA المطبق على BERT. عند طباعة المفاتيح الخمسة الأولى باستخدام إعدادات LoRA الافتراضية (المفاتيح المتبقية هي نفسها، لكن بأرقام طبقات مختلفة)، نحصل على:

  • base_model.model.encoder.layer.0.attention.self.query.lora_A.weight
  • base_model.model.encoder.layer.0.attention.self.query.lora_B.weight
  • base_model.model.encoder.layer.0.attention.self.value.lora_A.weight
  • base_model.model.encoder.layer.0.attention.self.value.lora_B.weight
  • base_model.model.encoder.layer.1.attention.self.query.lora_A.weight
  • إلخ.

لنقم بتحليل ذلك:

  • بشكل افتراضي، بالنسبة لنماذج BERT، يُطبَّق LoRA على طبقتي query وvalue في وحدة الانتباه. ولهذا السبب ترى attention.self.query وattention.self.value في أسماء المفاتيح لكل طبقة.
  • يقوم LoRA بتفكيك الأوزان إلى مصفوفتين منخفضتي الرتبة، lora_A وlora_B. ومن هنا يأتي مصدر lora_A وlora_B في أسماء المفاتيح.
  • تُنفَّذ مصفوفات LoRA هذه كطبقات nn.Linear، لذا تُخزَّن المعاملات في الخاصية .weight (lora_A.weight، lora_B.weight).
  • بشكل افتراضي، لا يُطبَّق LoRA على طبقة التضمين في BERT، لذا لا توجد إدخالات لـ lora_A_embedding و lora_B_embedding.
  • تبدأ مفاتيح state_dict دائمًا بـ "base_model.model.". والسبب في ذلك أنه في PEFT، نغلّف النموذج الأساسي داخل نموذج مخصص للمُحسِّن (LoraModel في هذه الحالة)، والذي يُغلَّف بدوره في نموذج PEFT عام (PeftModel). ولهذا السبب، تُضاف هاتان الباديتان إلى المفاتيح. عند التحويل إلى صيغة PEFT، يُشترط إضافة هاتين الباديتين.

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

عند فحص أسماء المعاملات في النموذج المحمّل، قد تفاجأ باكتشاف أنها تبدو مختلفة قليلاً، على سبيل المثال base_model.model.encoder.layer.0.attention.self.query.lora_A.default.weight. الفارق هو الجزء .default في المقطع قبل الأخير. يوجد هذا الجزء لأن PEFT يسمح عمومًا بإضافة عدة محوِّلات (adapters) في آنٍ واحد (باستخدام nn.ModuleDict أو nn.ParameterDict لتخزينها). على سبيل المثال، إذا أضفت محوِّلًا آخر يُدعى “other”, فسيكون المفتاح الخاص بذلك المحوِّل base_model.model.encoder.layer.0.attention.self.query.lora_A.other.weight.

عند استدعاء save_pretrained()، يتم حذف اسم المُكيّف من المفاتيح. والسبب في ذلك أن اسم المُكيّف ليس جزءًا مهمًا من بنية النموذج؛ فهو مجرد اسم تعسفي. عند تحميل المُكيّف، يمكنك اختيار اسم مختلف تمامًا، وسيظل النموذج يعمل بالطريقة نفسها. ولهذا السبب لا يتم تخزين اسم المُكيّف في ملف نقطة الحفظ.

إذا استدعيت save_pretrained("some/path") وكان اسم المُكيّف (adapter) ليس "default"، يتم تخزين المُكيّف في مجلد فرعي يحمل نفس اسم المُكيّف. لذا إذا كان الاسم هو “other”, فسيتم تخزينه داخل some/path/other.

في بعض الحالات، قد يصبح تحديد القيم التي يجب إضافتها إلى ملف نقطة الحفظ أكثر تعقيدًا بعض الشيء. على سبيل المثال، في PEFT، يتم تنفيذ DoRA كحالة خاصة من LoRA. إذا كنت ترغب في تحويل نموذج DoRA إلى PEFT، فيجب عليك إنشاء نقطة حفظ LoRA مع إدخالات إضافية لـ DoRA. يمكنك الاطلاع على ذلك في __init__ من كود LoraLayer السابق:

self.lora_magnitude_vector: Optional[torch.nn.ParameterDict] = None  # for DoRA

يشير هذا إلى وجود معامل إضافي اختياري لكل طبقة في DoRA.

adapter_config

تحتوي جميع المعلومات الأخرى اللازمة لتحميل نموذج PEFT في ملف adapter_config.json. دعونا نفحص هذا الملف لنموذج LoRA مطبق على BERT:

{
  "alpha_pattern": {},
  "auto_mapping": {
    "base_model_class": "BertModel",
    "parent_library": "transformers.models.bert.modeling_bert"
  },
  "base_model_name_or_path": "bert-base-uncased",
  "bias": "none",
  "fan_in_fan_out": false,
  "inference_mode": true,
  "init_lora_weights": true,
  "layer_replication": null,
  "layers_pattern": null,
  "layers_to_transform": null,
  "loftq_config": {},
  "lora_alpha": 8,
  "lora_dropout": 0.0,
  "megatron_config": null,
  "megatron_core": "megatron.core",
  "modules_to_save": null,
  "peft_type": "LORA",
  "r": 8,
  "rank_pattern": {},
  "revision": null,
  "target_modules": [
    "query",
    "value"
  ],
  "task_type": null,
  "use_dora": false,
  "use_rslora": false
}

تحتوي هذه القائمة على عدد كبير من العناصر، وقد يبدو الأمر مرهقًا في البداية عند محاولة تحديد جميع القيم الصحيحة التي يجب إدخالها. ومع ذلك، فإن معظم هذه العناصر ليست ضرورية لتحميل النموذج. وهذا إما لأنها تستخدم القيم الافتراضية ولا تحتاج إلى إضافتها، أو لأنها تؤثر فقط على تهيئة أوزان LoRA، وهو أمر غير ذي صلة عند الحديث عن تحميل النموذج. إذا اكتشفت أنك لا تعرف وظيفة معلمة معينة، مثل "use_rslora",، فلا تضيفها، وستكون الأمور على ما يرام. لاحظ أيضًا أنه مع إضافة المزيد من الخيارات، ستزداد عدد العناصر في هذا الملف في المستقبل، لكن يجب أن يبقى متوافقًا مع الإصدارات السابقة.

بحد أدنى، يجب أن تتضمن ما يلي:

{
  "target_modules": ["query", "value"],
  "peft_type": "LORA"
}

ومع ذلك، يُوصى بإضافة أكبر عدد ممكن من العناصر، مثل الرتبة r أو base_model_name_or_path (إذا كان نموذج Transformers). يمكن أن تساعد هذه المعلومات الآخرين في فهم النموذج بشكل أفضل ومشاركته بسهولة أكبر. للتحقق من المفاتيح والقيم المتوقعة، راجع ملف config.py (كمثال، هذا هو ملف الإعداد الخاص بـ LoRA) في كود PEFT المصدري.

تخزين النموذج

في بعض الحالات، قد ترغب في تخزين نموذج PEFT بالكامل، بما في ذلك الأوزان الأساسية. وقد يكون ذلك ضرورياً إذا كان النموذج الأساسي غير متاح للمستخدمين الذين يحاولون تحميل نموذج PEFT، على سبيل المثال. يمكنك دمج الأوزان أولاً أو تحويله إلى نموذج Transformer.

دمج الأوزان

أبسط طريقة لتخزين نموذج PEFT بالكامل هي دمج أوزان المُكيّف (adapter) مع الأوزان الأساسية:

merged_model = model.merge_and_unload()
merged_model.save_pretrained(...)

ومع ذلك، هناك بعض العيوب في هذا النهج:

  • بمجرد استدعاء merge_and_unload()، تحصل على نموذج أساسي لا يحتوي على أي وظائف خاصة بـ PEFT. وهذا يعني أنك لن تتمكن من استخدام أي من الطرق الخاصة بـ PEFT بعد الآن.
  • لا يمكنك إلغاء دمج الأوزان، أو تحميل عدة محوِّلات في وقت واحد، أو تعطيل المحوِّل، وما إلى ذلك.
  • لا تدعم جميع طرق PEFT دمج الأوزان.
  • قد تسمح بعض طرق PEFT بشكل عام بدمج النموذج، لكن ليس مع إعدادات محددة (مثل عند استخدام تقنيات تكميم معينة).
  • سيكون النموذج الكامل أكبر بكثير من نموذج PEFT، إذ سيحتوي على جميع الأوزان الأساسية أيضًا.

لكن الاستدلال باستخدام نموذج مدمج يجب أن يكون أسرع قليلاً.

التحويل إلى نموذج Transformers

طريقة أخرى لحفظ النموذج بالكامل، بافتراض أن النموذج الأساسي هو نموذج Transformers، هي استخدام هذا النهج غير القياسي لإدراج أوزان PEFT مباشرةً في النموذج الأساسي وحفظه، وهو ما يعمل فقط إذا «خدعت» Transformers على أن نموذج PEFT ليس نموذج PEFT. يعمل هذا مع LoRA فقط لأن بقية المحوِّلات غير مُنفَّذة في Transformers.

model = ...  # the PEFT model
...
# after you finish training the model, save it in a temporary location
model.save_pretrained(<temp_location>)
# now load this model directly into a transformers model, without the PEFT wrapper
# the PEFT weights are directly injected into the base model
model_loaded = AutoModel.from_pretrained(<temp_location>)
# now make the loaded model believe that it is _not_ a PEFT model
model_loaded._hf_peft_config_loaded = False
# now when we save it, it will save the whole model
model_loaded.save_pretrained(<final_location>)
# or upload to Hugging Face Hub
model_loaded.push_to_hub(<final_location>)
Update on GitHub