Hugging Face's logo

Transformers documentation

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

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

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

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

Our code agent philosophy in detail

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

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

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

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

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

إذا استمتعتَ باستخدام Transformers، فلا تتردد في الإشارة إليه وإخبارنا بكيفية استخدامه، أو ذكرنا على تويتر، أو منح المستودع نجمة!

استُلهم هذا الدليل بشكل كبير من دليل scikit-learn للمساهمة.

المحتويات

  1. الإعداد
  2. فتح القضايا
  3. إضافة نموذج جديد
  4. التوثيق
  5. المساهمات الوكيلية

الإعداد

  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 وليس في كودك الخاص.

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

قم بتضمين ما يلي حتى نتمكن من حل المشكلة بسرعة.

  • نوع نظام التشغيل وإصداره وإصدارا Python وPyTorch عند الاقتضاء.
  • مقطع برمجي قصير مكتفٍ ذاتياً يتيح لنا إعادة إنتاج الخلل.
  • التتبع الكامل full إذا تم رفع استثناء.
  • أي معلومات أخرى، مثل لقطات الشاشة، قد تكون مفيدة.

للحصول على إصدارات نظام التشغيل والبرمجيات تلقائيًا، نفّذ الأمر التالي.

transformers env

طلب ميزة

افتح مشكلة ووصف:

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

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

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

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

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

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

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

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

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

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

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

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

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

    المشكلات المفتوحة الموسومة بـ “New model” هي نقطة الدخول للمساهمين الخارجيين. ابدأ بالبنى المعمارية الأكثر طلبًا لتعظيم الأثر. سنراجع العمل ونرشدك خلال العملية.

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

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

التوثيق

نرحّب دائمًا بأي تحسينات على التوثيق، مثل تصحيح الأخطاء الإملائية، أو إضافة محتوى مفقود، أو توضيح الشروح غير الواضحة. فيما يتعلق بمرجع الواجهة البرمجية (API) المولّد من ملفات المصدر، استخدم مُزيّن @auto_docstring عندما ينطبق. افتح طلب سحب (pull request) مباشرةً لإصلاحات التوثيق الجوهرية.

راجع وثائق README لمزيد من التفاصيل حول كيفية تحرير الوثائق والنحو الذي نستخدمه.

مساهمات الوكلاء

نرحّب بالمساهمات المدعومة بالذكاء الاصطناعي. يجب أن تكون منسّقة ومحدّدة النطاق ومُتحقَّقًا منها للحفاظ على قابلية حمل المراجعة.

  • لا تُقدِّم طلبات دمج (PRs) من نوع “الوكيل الخالص” (pure agent). يتحمّل المُقدِّم البشري مسؤولية مراجعة جميع الأسطر المُعدَّلة، والتحقق من السلوك من البداية إلى النهاية، وتشغيل الاختبارات ذات الصلة.
  • إذا تم استخدام أدوات الذكاء الاصطناعي، فافصح عن ذلك في وصف طلب الإضافة (PR) وشمل: رابط التنسيق، والتمييز عن طلبات الإضافة الموجودة (إن كان ذلك منطبقاً)، وأوامر الاختبار/نتائجه.
  • تجنّب طلبات الدمج التي تتضمن مهام عابرة “لا تُذكر” (مثل تصحيح خطأ إملائي واحد، أو تنظيف نمطي معزول، أو إصلاح قيمة افتراضية قابلة للتغيير واحدة، وما إلى ذلك). اجمع التنظيفات الميكانيكية ضمن نطاق واضح ومنهجي.
  • تنسيق المسائل قبل فتح طلب سحب، ومراجعة طلبات السحب المشابهة، والانتظار حتى الحصول على الموافقة.

تُوضَّح هذه المواضيع للوكلاء في AGENTS.md مع تعليمات حول كيفية تنفيذها بشكل مستقل.

Update on GitHub

←التصدير إلى بيئة الإنتاج إضافة نموذج باستخدام محولات معيارية→