Transformers documentation

المساهمة في 🤗 Transformers

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

المساهمة في 🤗 Transformers

قواعد المساهمة

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

إصلاح مشكلة. اربط المشكلة بكلمة مفتاحية للإغلاق مثل Fixes #123 في وصف طلب الدمج. يمكنك العمل على:

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

لا حاجة إلى طلب الإذن قبل العمل على مشكلة تستوفي الشروط، ولا نقوم بتعيين المشكلات إلى أشخاص. التعليقات مثل «هل يمكنني العمل على هذا؟» أو «الرجاء تعيين هذا لي» لا تضيف سوى ضجيج، لذا تجنّبها وافتح طلبك الخاص. يحصل أول طلب خاص بمشكلة على الأولوية.

قبل العمل على مشكلة contributions-welcome أو New model، تحقق مما إذا كان شخص ما قد فتح بالفعل طلب سحب (PR) لها. إذا كان الأمر كذلك، فلا تفتح طلبًا آخر. إذا لاحظت أخطاء، اترك اقتراحاتك على طلب السحب الموجود بدلاً من ذلك. لا تفتح طلب سحب منافسًا إلا إذا كان الطلب الموجود معيبًا بشكل جوهري، أو قديمًا: لم يستجب مؤلفه لتعليقات المراجعة أو يدفع تغييرات لمدة أسبوعين. طلب السحب الذي ينتظر مراجعة من أحد المشرفين ليس قديمًا. في كلتا الحالتين، اشرح السبب في المشكلة قبل فتح طلبك.

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

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

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

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

مراجعة طلبات الدمج الخاصة بالآخرين. نرحّب بمراجعات المجتمع عندما تُخبرنا بشيء جديد، لكن المُشرفين على المشروع يقرؤون كل تعليق على طلب الدمج، ونحن نستخدم بالفعل أدوات مراجعة خاصة بنا. قبل أن تكتب تعليقًا على طلب دمج لم تفتحه أنت، تأكد من أن لديك شيئًا محددًا لتقوله:

  • إذا اكتشفت مشكلة أو لديك تغيير محدد تقترحه، فترك تعليقًا مضمّنًا على الأسطر ذات الصلة، ويفضَّل أن يكون على شكل اقتراح في GitHub يمكن للمؤلف تطبيقه مباشرةً. يساعد وجود مثال قابل لإعادة إنتاج المشكلة إذا كنتَ تُبلّغ عن خطأ برمجي.
  • إذا كنت قد أبلغت عن المشكلة التي يعالجها طلب الدمج، فإن ملاحظة سريعة توضح ما إذا كان يحل حالتك مفيدة للغاية.
  • يرجى عدم نشر ملخصات عامة أو تقارير من نوع «جرّبت هذا ويعمل». فموافقات غير المشرفين لا تؤثر على ما إذا كان طلب الدمج سيُدمج أم لا، والتعليق الطويل الذي يعيد صياغة محتوى طلب الدمج يستهلك وقتنا دون تغيير النتيجة.

يعتمد أسلوب كتابة الكود علىك، لكنك تتحمل المسؤولية الكاملة عن كل ما تقدمه، وقد نقوم بحظر الحسابات التي تفتح بشكل متكرر مشاكل أو طلبات دمج منخفضة الجودة. يرجى أيضًا احترام مدونة السلوك الخاصة بنا.

What we look for in issues and PRs
  • تشخيص دقيق للأخطاء. غالبًا ما تؤدي الحلول السريعة إلى تضخم الكود أو عدم التوافق مع نماذج أخرى. إن قضاء الوقت في تحديد السبب الدقيق للمشكلة، وتحديدًا تحديد أول التزامن الذي ظهر فيه (على سبيل المثال باستخدام git bisect) أمرٌ ذو قيمة.
  • قلّل حجم التغييرات. راجع طلب الإرسال الخاص بك للتخلص من أي تغييرات غير ضرورية. تأكد من أنك لم تُرسل أي سكربتات اختبار أو ملفات غير ذات صلة. أضف التعليقات فقط إذا كانت ضرورية حقًا. إذا كان بإمكانك تنفيذ إصلاح من سطر واحد في طلب الإرسال، فافعل ذلك. هذا يجعل مراجعة طلب الإرسال أسهل بكثير ويزيد من فرص قبوله.
  • خذ وقتك لإعادة إنتاج المشكلة. في كثير من الأحيان، عندما يبلغ المستخدم عن مشكلة، يكون السبب الفعلي هو مشاكل في بيئة العمل على جهازه، أو أنه يخطئ في تشخيص المشكلة ويقترح حلاً غير صالح. الثقة المفرطة في التقرير تؤدي إلى حلول سيئة، أحياناً لمشاكل لا وجود لها! كتابة سكربت بسيط لإعادة الإنتاج وتشغيله للتأكد من رؤيتك للمشكلة أمر قيم.
  • قارن مع نماذج أخرى. مستودع Transformers كبير جدًا، وكثير من النماذج تقوم بأشياء مشابهة. عند إصلاح خطأ برمجي، من المفيد التحقق مما إذا كان الخطأ موجودًا في نماذج أخرى. إذا ذكر طلبك الخاص (PR) أنه «تم الإصلاح باستخدام النهج نفسه المعتمد في (نموذج آخر)»، مع رابط إلى الكود ذي الصلة، فإن ذلك مفيد جدًا للمحافظين على المشروع، لأنه يخبرنا بأن الإصلاح على الأرجح صحيح ومتوافق مع بقية قاعدة الكود.
  • تجنّبوا طلبات الدمج التي لا تُضيف قيمة حقيقية. ليس لدينا وقت لتغييرات التنسيق الصغيرة أو تصحيح الأخطاء الإملائية في التعليقات، كما أننا لا نقبل إصلاحات “الأخطاء النظرية” التي تكشفها أدوات تحليل الشيفرة البرمجية والتي نادراً ما تسبب مشاكل في الممارسة العملية، ما لم يكن بالإمكان استغلالها من قِبل مهاجم.
  • تحقّق من الاختبارات محليًا وفي بيئة CI. قبل فتح طلب دمج (PR)، نفّذ make fix-repo واستخدم utils/tests_fetcher.py لعرض قائمة الاختبارات التي تغطي الملفات التي قمت بتعديلها في فرع طلب الدمج الخاص بك. نفّذ تلك الاختبارات محليًا، وتأكد من نجاحها قبل فتح طلب الدمج. بعد فتح طلب الدمج، يرجى التحقق من أن CI يعمل بنجاح (أخضر) وإصلاح أي مشاكل قبل طلب مراجعة من أي شخص! يقلل هذا من إزعاج الإشعارات بشكل كبير، مما يحافظ على راحة المساهمين.

الإعداد

  1. أنشئ نسخة خاصة بك من Transformers عبر زر Fork على GitHub، ثم استنسخها محليًا.

    git clone git@github.com:<your Github handle>/transformers.git
    cd transformers
  2. أضف مستودع Transformers كمصدر بعيد باسم upstream. يشير origin إلى نسختك المستنسخة بينما يشير upstream إلى المصدر الموثوق. يتيح لك ذلك مزامنة فرع main المحلي لديك قبل الدفع إلى origin وفتح طلب سحب.

    git remote add upstream https://github.com/huggingface/transformers.git
    git remote -v
    # origin    git@github.com:<your Github handle>/transformers.git (fetch)
    # origin    git@github.com:<your Github handle>/transformers.git (push)
    # upstream  https://github.com/huggingface/transformers.git (fetch)
    # upstream  https://github.com/huggingface/transformers.git (push)
  3. حافظ على تحديث فرعك (fork) الخاص بك وابدأ فرعًا (branch) جديدًا للعمل عليه. يمكنك أيضًا مزامنة فرعك من واجهة GitHub باستخدام زر Sync fork.

    git checkout main && git pull upstream main && git push origin main
    git switch -c a-descriptive-name-for-my-branch
  4. قم بتثبيت المكتبة في وضع قابل للتحرير. استخدم [dev] لمعظم المساهمات لأنه يتضمن أدوات التطوير اللازمة لفحوصات الأسلوب والجودة. استخدم [torch,testing] للمساهمات المتعلقة بالنماذج، أو [quality] للتغييرات التي تقتصر على التوثيق والإصلاحات الصغيرة عندما لا تكون هناك حاجة إلى مجموعة تبعيات التطوير الكاملة.

    pip install -e ".[dev]"
    
    # for model contributions
    pip install -e ".[torch,testing]"
    
    # for docs-only changes and small fixes
    pip install -e ".[quality]"

Windows

على نظام ويندوز، ما لم تكن تستخدم WSL، فعليك ضبط git لتحويل نهايات الأسطر CRLF إلى LF.

git config core.autocrlf input

طريقة واحدة لتشغيل أمر make على نظام Windows هي استخدام MSYS2.

  1. تنزيل MSYS2 (نفترض أنه مثبّت في C:\msys64).
  2. افتح سطر الأوامر C:\msys64\msys2.exe (يجب أن يكون متاحًا من قائمة ابدأ).
  3. شغّل في الطرفية: pacman -Syu ثم ثبّت make باستخدام pacman -S make.
  4. أضف C:\msys64\usr\bin إلى متغير البيئة PATH الخاص بك.

يمكنك الآن استخدام make من أي طرفية (PowerShell، cmd.exe، إلخ).

فتح القضايا

استخدم القوالب الخاصة بالمسائل، وتأكد من أن المسألة لم تُبلَّغ عنها من قبل (استخدم شريط البحث في GitHub تحت Issues). يجب أن يكون تقرير الخطأ متعلقًا بخطأ في Transformers وليس في كودك الخاص، وأن يؤثر على الاستخدام الفعلي والنقاط المحفوظة الفعلية؛ فـ«الخطأ النظري» الذي يُكتشف بقراءة الكود ويتطلب إعدادًا غير قياسي للغاية ليُستفز لن يُصنَّف إلا إذا كان مشكلة أمنية. شمل تقريرك سكربتًا قصيرًا مكتفيًا بذاته يعيد إنتاج الخطأ على أحدث إصدار أو main، باستخدام نقطة محفوظة منشورة أو إعداد افتراضي. لن تُصنَّف تقارير الأخطاء التي لا تتضمن أداة إعادة إنتاج قابلة للتشغيل.

إذا كنت غير متأكد مما إذا كان الخطأ في كودك أو في المكتبة، فاطلب المساعدة أولاً في المنتدى أو على Discord. يساعد ذلك في إبقاء GitHub متركزاً على مشاكل المكتبة القابلة للتنفيذ.

إضافة نموذج جديد

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

اتبع الأدلة أدناه.

  1. إضافة نموذج باستخدام Transformers المعياري — قم بتنفيذ النموذج باستخدام الملف المعياري وتوليد ملفات نمذجة مستقلة.
  2. توليد توثيق تلقائي — استخدم مُزيِّن @auto_docstring لتوليد توثيق متسق دون الحاجة إلى أكواد مكررة.
  3. الاختبار — اكتب ونفّذ اختبارات النموذج للتحقق من الصواب والحفاظ على قابلية المساهمة للصيانة. بالنسبة لنماذج اللغة السببية، ورّث من مُختبِر نموذج اللغة السببية حيثما أمكن. أعطِ الأولوية لاختبارات التكامل لأنها تتحقق من مسار المعالج الكامل، ومجزّئ النص، والنموذج مقابل نقاط التفتيش الفعلية.
  4. قواعد بنية النموذج — تأكد من أن ملفاتك تجتاز قواعد بنية النموذج الثابتة التي يفرضها make typing.

تتطلب بعض إضافات النماذج عملاً إضافياً على مستوى التكامل.

جدول زمني لإضافة النماذج

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

  • التكامل من اليوم الأول: جعل النموذج متاحًا في Transformers في يوم الإصدار مع إصدار نسخة جديدة. نقدم المساعدة لدعم أهم الميزات الأساسية (مثل التكميم، وFlashAttention، وذاكرة KV، وغيرها)، ونراجع المسودات المبكرة، كما يمكننا تولي تنفيذ النموذج اعتمادًا على الجدول الزمني.

    أرسل بريدًا إلكترونيًا إلى transformers@huggingface.co قبل أسابيع قليلة، خاصةً في حال البنى المعمارية الجديدة. سنعمل معك على فرع خاص حتى يصبح نقطة التفتيش الخاصة بك والإصدار جاهزين.

  • التكامل خلال الأسبوع نفسه: عادةً ما تُضاف النماذج ذات الطلب العالي خلال أسبوع واحد، حتى عندما لا يتواصل المؤلف.

    افتح مشكلة باستخدام قالب النموذج الجديد لتقديم طلب. المشكلات ذات النشاط الأعلى تتقدم في قائمة الانتظار بشكل أسرع.

  • التكامل بعد الإصدار: تُضاف النماذج التي لا تحظى بطلب قوي، أو التي لا نملك السعة الكافية للتعامل معها، بعد الإصدار في المنبع.

    يمكن للمساهمين الخارجيين فتح طلب سحب (PR) لنموذج جديد مباشرةً، سواء مع وجود مشكلة (issue) أو بدونها. قبل أن تبدأ، تحقق من المشكلات المفتوحة الموسومة بـ “New model” وطلبات السحب المفتوحة للتأكد من أن أحداً لم يبدأ بإضافة النموذج بالفعل. سنراجع طلبك ونرشدك خلال العملية.

  • إصدار يعتمد على Hub: انشر نموذجك مباشرةً على Hub عبر دعم remote-code في Transformers، دون الحاجة إلى طلب دمج (PR) في المستودع الأصلي.

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

التوثيق

بالنسبة إلى مرجع الواجهة البرمجية (API) المولّد من ملفات المصدر، استخدم الزخرفة @auto_docstring عندما ينطبق ذلك. راجع README الخاص بالتوثيق لمزيد من التفاصيل حول كيفية تحرير التوثيق والنحو الذي نستخدمه.

Update on GitHub