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. إذا كنت تخطط للمساهمة، فيرجى قراءة هذا النص لجعل العملية سلسة قدر الإمكان.

ناقشوا الأمر واحصلوا على الموافقة قبل فتح طلب دمج

قبل فتح طلب سحب (بما في ذلك المسودة)، افتح أو ابحث عن مشكلة في huggingface/peft ونقّش مساهمتك المقترحة. إذا كانت هناك مشكلة قائمة وشخص ما يعمل عليها بالفعل، أو أعلن عن نيته في العمل عليها، أو لديه طلب سحب مفتوح، فلا يجب عليك تقديم طلب سحب منفصل. انتظر حتى يوافق صيانة PEFT أو عضو في Hugging Face صراحةً على المقترح. إذا فتحت مشكلة، فاجعل طول وصفها وتعقيده متناسبين مع تعقيد المشكلة. غالبًا ما يكون الوصف القصير مع أداة إعادة إنتاج أكثر قيمة من الوصف الطويل.

تحتوي رسالة الموافقة على النص /peft-triage approved. وقد تتضمن أيضًا اسم المساهم المُسند إليه، على سبيل المثال /peft-triage approved username أو /peft-triage approved @username. فتح طلب سحب (PR) لمشكلة لم تُسند إليك سيؤدي إلى إغلاق ذلك الطلب.

اربط المشكلة المفتوحة المعتمدة في وصف طلب الإضافة الخاص بك باستخدام #123 أو huggingface/peft#123 أو https://github.com/huggingface/peft/issues/123. استثناءً من ذلك، يجوز للمُحافظين تحديد مناقشات طويلة الأمد معينة يمكن الإشارة إليها عبر عنوان URL الكامل على GitHub دون الحاجة إلى تعليق موافقة منفصل. إذا كنت تشير إلى عدة مشكلات أو مناقشات، فإن إشارة واحدة صالحة تكفي.

يتحقق سير عمل آلي من طلبات الدمج بحثًا عن مشكلات مفتوحة أو نقاشات معتمدة. تُغلق طلبات الدمج التي لا تحتوي على مرجع صالح تلقائيًا مع تقديم شرح لذلك. يمكنك الحصول على اعتماد للمشكلة، وتحديث وصف طلب الدمج، وإعادة فتح نفس طلب الدمج؛ يرجى عدم إنشاء طلب بديل. إذا كنت تعتقد أن طلب دمجك أُغلق بشكل غير صحيح، فاطلب من المشرفين التواصل معك عبر طلب الدمج.

لا يزال بإمكان بوت التقادم المستقل إغلاق العناصر غير النشطة، حتى لو كانت موسومة بـtriaged. إذا كنت تشعر بأن المشرفين قد أغفلوا مساهمتك، يمكنك تنبيههم، ولكن ليس قبل مرور أسبوعين من عدم النشاط.

التثبيت

اتبع هذه الخطوات لبدء المساهمة:

  1. أنشئ نسخة من المستودع بالنقر على زر "Fork" في صفحة المستودع. يؤدي هذا إلى إنشاء نسخة من الكود تحت حسابك على GitHub.

  2. انسخ فرعك إلى القرص المحلي، وأضف المستودع الأساسي كمستودع بعيد. تفترض الأوامر التالية أنك قمت برفع مفتاح SSH العام الخاص بك إلى GitHub. راجع الدليل التالي لمزيد من المعلومات.

    git clone git@github.com:<your Github handle>/peft.git
    cd peft
    git remote add upstream https://github.com/huggingface/peft.git
  3. أنشئ فرعًا جديدًا لاستيعاب تغييرات التطوير الخاصة بك، وكرر ذلك لكل طلب سحب جديد تعمل عليه.

    ابدأ بمزامنة فرع main الخاص بك مع فرع upstream/main (تجد مزيداً من التفاصيل في وثائق GitHub):

    git checkout main
    git fetch upstream
    git merge upstream/main

    بمجرد مزامنة فرع main الخاص بك، أنشئ فرعًا جديدًا منه:

    git checkout -b a-descriptive-name-for-my-changes

    لا تعمل على الفرع main.

  4. قم بإعداد بيئة تطوير من خلال تنفيذ الأمر التالي في بيئة conda أو بيئة افتراضية أنشأتها للعمل على هذه المكتبة:

    pip install -e ".[test]"

    (إذا كان PEFT مثبتًا مسبقًا في البيئة الافتراضية، فقم بإزالته باستخدام pip uninstall peft قبل إعادة تثبيته.)

إذا كنت جديدًا في إنشاء طلب سحب، فالتزم بدليل إنشاء طلب سحب من GitHub.

الاختبارات وفحوصات جودة الكود

بغض النظر عن نوع المساهمة (ما لم تكن تتعلق بالتوثيق فقط)، يجب عليك تشغيل الاختبارات وفحوصات جودة الكود قبل إنشاء طلب سحب (PR) للتأكد من أن مساهمتك لا تُسبب أي أعطال وتتوافق مع معايير المشروع.

تشغيل الاختبارات والفحوصات

نوفر ملف Makefile لتنفيذ الاختبارات اللازمة. نفّذ الكود أدناه لاختبار الوحدة:

make test

شغّل أحد ما يلي للتحقق فقط من جودة الكود وأسلوبه أو للتحقق وإصلاح جودة الكود وأسلوبه:

make quality  # just check
make style  # check and fix

تشغيل make quality سيقوم أيضًا بالتحقق مما إذا كانت جميع الطرق/الفئات من واجهة PEFT العامة (أي كل ما هو مذكور في peft.__all__) مذكورة في التوثيق. لا يمكن إصلاح هذه الأخطاء عبر make style، بل يجب عليك التأكد من توثيق العناصر الجديدة في الواجهة العامة ضمن التوثيق لإصلاح هذا الخطأ.

يمكنك أيضًا إعداد pre-commit لتنفيذ هذه الإصلاحات تلقائيًا كخطافات Git عند الالتزام.

$ pip install pre-commit
$ pre-commit install

قد يستغرق تشغيل جميع الاختبارات وقتًا طويلاً، لذا أثناء التطوير قد يكون من الكفاءة تشغيل الاختبارات الخاصة بتغييرك فقط، على سبيل المثال عبر:

pytest tests/<test-file-name> -k <name-of-test>

يجب أن ينتهي هذا الأمر بشكل أسرع بكثير، مما يتيح تكرارًا أسرع.

إضافة الاختبارات

لإرشادات عامة حول إضافة اختبارات جديدة، راجع tests/README.md.

إذا كان تغييرك خاصًا بإعدادات العتاد (مثل أنه يتطلب CUDA)، فتأكد من tests/test_gpu_examples.py و tests/test_common_gpu.py لمعرفة ما إذا كان من المنطقي إضافة اختبارات هناك. إذا كان من الممكن أن يؤثر تغييرك على حفظ النماذج وتحميلها، فيرجى تشغيل الاختبارات مع علم --regression لتفعيل اختبارات الانحدار.

طلبات الدمج القديمة

قد يحدث أثناء عملك على طلب الإرسال (PR) أن يتغير الكود الأساسي بسبب دمج تغييرات أخرى. إذا حدث ذلك – لا سيما عند وجود تعارض في الدمج – يرجى تحديث فرعك بأحدث التغييرات. يمكن أن يكون ذلك دمجًا أو إعادة أساس (rebase)، وسنقوم بدمج طلب الإرسال (PR) بطريقة الضغط (squash) بمجرد جاهزيته. تجنّب الدفع القسري (force pushes) لتسهيل عمليات المراجعة.

وصف طلب الإرسال

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

حافظ على طول وصف طلب الإضافة (PR) وتعقيده بما يتناسب مع حجم التغيير. لا نحتاج إلى عشرة فقرات من الشرح لتغيير سطري بسيط. لا تعيد صياغة ما هو واضح من خلال النظر إلى الاختلاف (diff) (مثلًا: «تم تصحيح الخطأ الإملائي في ‘foobaar’»).

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

إذا كان ذلك ذا صلة، فاذكر كيف اختبرت التغيير، على سبيل المثال من خلال إظهار أمر اختبار pytest أو كود إعادة الإنتاج.

ملاحظات المراجع

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

إذا قدّم المُراجِع تعليقات مضمّنة، فلا تُعلّمها كمُعالَجة إذا كنت قد عالجتَها. اترك هذه التعليقات مفتوحة، فهي تساعد المُراجِع على استئناف عمله.

بعد معالجة ملاحظات المُراجِع، أبلغ المُراجِع حتى يعلم أن طلب الدمج جاهز للمراجعة.

إصلاحات الأخطاء

يرجى تقديم وصف للظروف التي أدت إلى الخطأ. إذا كان هناك خطأ قائم مسبقًا، يرجى ربطه (مثلًا: "يحلّ #12345").

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

تحسينات التوثيق

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

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

إضافة طريقة جديدة لضبط الدقة باستخدام PEFT

تُطوَّر باستمرار طرق جديدة للضبط الدقيق الفعّال من حيث المعلمات. إذا كنت ترغب في إضافة طريقة جديدة واعدة إلى PEFT، فالرجاء اتباع الخطوات التالية.

  1. إذا لم تكن مؤلفًا للورقة الأصلية، فتأكد من وجود تطبيقات سابقة وتحقق مرة أخرى مع المؤلفين من أنهم لا ينوون تقديم طلب سحب بأنفسهم.
  2. افتح مشكلة مقترح وانتظر الموافقة الصريحة كما هو موضح أعلاه، قبل بدء أعمال التكامل الأساسية المدرجة أدناه.
  3. تحقق من أحدث الالتزامات (commits) لمعرفة طرق PEFT الجديدة التي يتم إضافتها، لتستلهم منها.
  4. بعد اعتماد المقترح، قد يكون من المفيد فتح طلب سحب مسودة مبكرًا بمجرد أن يعمل الأسلوب بشكل أساسي وتنجح الاختبارات الأولى، ثم طلب الملاحظات. اذكر المشكلة المعتمدة في وصف طلب السحب المسودة.

التكامل الأساسي لطريقة PEFT جديدة

  • افتح مشكلة على huggingface/peft واحصل على موافقة صريحة قبل استثمار الكثير من العمل.
  • اربط بمصدر الطريقة، وهو عادةً الورقة البحثية النهائية أو مرجع أساسي آخر مستقر. نريد تجنّب الأعمال التي لا تزال قيد المراجعة، إذ ينبغي أن يكون التنفيذ مستقرًا.
  • أضف عنصر PeftType جديدًا في src/peft/utils/peft_types.py.
  • أنشئ حزمة مُعدِّل جديدة تحت src/peft/tuners/ تتضمن الملفات التي يحتاجها أسلوبك (عادةً: config.py، model.py، layer.py، و__init__.py).
  • سجّل الطريقة في __init__.py الخاص بالـ tuner باستخدام register_peft_method(...).
  • صدّر الإعداد/النموذج الجديد من src/peft/tuners/__init__.py وsrc/peft/__init__.py.
  • إذا كانت الطريقة تتطلب وحدات هدف افتراضية لنماذج Transformers، أضف الترميز في src/peft/utils/constants.py.
  • أضف الطريقة إلى مصفوفة الاختبارات في tests/test_custom_models.py لأن هذه الاختبارات هي الأوسع نطاقًا والأسرع. تأكد من نجاح الاختبارات باستخدام pytest tests/test_custom_models.py -k <method-name> -v، وقم بإصلاح أي إخفاقات إن وُجدت.
  • نفّذ فحوصات التنسيق/الجودة باستخدام make style قبل الدفع.
  • في وصف طلب الإرسال، اشرح الطريقة، واربط بالورقة البحثية، ولخّص المفاضلات، وقم بتحديد ما أُضيف.

طلب تغيير كامل لإضافة طريقة PEFT جديدة

  • تأكد من أن معاملات الإعداد الخاصة بالطريقة مُسماة ومُفسَّرة بشكل جيد، ولا تفترض أن المستخدم يعرف الورقة البحثية على نحوٍ تام.
  • اتبع معايير التسمية والبرمجة الخاصة بـ PEFT.
  • تأكد من أنك لم تقم بالخطأ بتسجيل تغييرات غير ذات صلة، مثل تغيير مُنسِّق الأكواد لملفات غير ذات صلة.
  • إذا كانت بعض اختيارات التنفيذ غير بديهية، فوثّقها بتعليق في الكود.
  • أكمل مجموعة الاختبارات الكاملة (test_config.py، test_decoder_models.py، إلخ) عن طريق إضافة طريقة PEFT إلى مصفوفة الاختبارات. تأكد من نجاح الاختبارات.
  • أضف مستندات في docs/source/package_reference/ مع شرح موجز، ورابط إلى الورقة البحثية، ومقطع استخدام، ومقاطع autodoc. اشرح الإيجابيات والسلبيات مقارنةً بطرق أخرى مثل LoRA. سجّل صفحة المستند هذه في docs/source/_toctree.yml.
  • أضف مثالًا قابلًا للتنفيذ تحت examples/ (يمكن أن يكون نسخة من مثال موجود)، مع README.md مختصر.
  • تحقق من المعايير المرجعية في method_comparison/ وأضف إعدادات التجارب لطريقتك الجديدة. هذا مكان مناسب للتحقق من صحة أن طريقة PEFT تُدرَّب كما هو متوقع. شمل تكوينًا أو تكوينين معقولين للمعايير المرجعية (واحد افتراضي، والآخر مُحسَّن للمعيار المرجعي).
  • يُوصى به: إضافة دعم عام للتكميم. بدلاً من الحاجة إلى إضافة أنواع طبقات التكميم صراحةً لكل طريقة تكميم، ادعم التكميم العام. كمثال، راجع كيفية تنفيذه في BOFT. وسّع https://github.com/huggingface/peft/blob/main/tests/test_quantization.py بإضافة طريقة PEFT الخاصة بك هناك. اطلب المساعدة من المشرفين عند الحاجة.

إجراء تغييرات على طرق PEFT الموجودة

إذا أجريت تغييرًا على طريقة PEFT قد يؤدي إلى تغيير مخرجاتها، مما يُبطل نقاط التفتيش المدربة مسبقًا، فنحتاج إلى اتخاذ احتياطات إضافية. يرجى الاطلاع على الوصف الموجود في https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md للتفاصيل. التوجيهات هناك موجهة للبشر والذكاء الاصطناعي على حد سواء.

إضافة ميزات أخرى

افتح أولاً مشكلة (Issue) على GitHub تتضمن اقتراحًا لإضافة الميزة الجديدة وانتظر موافقة صريحة كما هو موضح أعلاه. بهذه الطريقة، يمكنك مناقشة الأمر مع المشرفين لمعرفة ما إذا كان من المنطقي إضافة الميزة قبل قضاء وقت طويل في تنفيذها.

يجب أن ترافق الميزات الجديدة عادةً اختبارات وتوثيق أو أمثلة. وبدون الأخيرة، سيكون من الصعب على المستخدمين اكتشاف ميزتك الجديدة الرائعة.

يجب تنفيذ التغييرات في code بطريقة متوافقة مع الإصدارات السابقة. على سبيل المثال، يجب أن يستمر code الحالي في العمل بنفس الطريقة بعد دمج الميزة.

Update on GitHub