Contribuer à 🤗 Transformers

Règles de contribution

Il existe deux façons d’ouvrir une PR : corriger un problème ouvert aux contributions, ou ouvrir une PR autonome qui apporte ses propres preuves. De nouveaux modèles peuvent également être ajoutés via une PR autonome, voir Ajouter un nouveau modèle. Le personnel de Hugging Face, les mainteneurs et certains contributeurs de longue date sont exemptés de ces règles.

Corriger un problème. Associez le problème à un mot-clé de clôture tel que Fixes #123 dans la description de la PR. Vous pouvez travailler sur :

• un problème que vous avez ouvert, une fois qu’un mainteneur l’a étiqueté triaged
• un problème étiqueté contributions-welcome
• un problème étiqueté New model, voir Ajouter un nouveau modèle

Les problèmes signalés par d’autres personnes ne sont pas ouverts aux PR, sauf si un mainteneur l’a indiqué. Les PR qui font référence à un problème sur lequel vous ne pouvez pas travailler seront fermées.

Vous n’avez pas besoin de demander avant de travailler sur un problème éligible, et nous n’attribuons pas les problèmes à des personnes. Des commentaires comme « puis-je travailler sur ce problème ? » ou « veuillez m’attribuer ce problème » n’ajoutent que du bruit, alors évitez-les et ouvrez votre PR. La première PR pour un problème donné a la priorité.

Avant de travailler sur une issue contributions-welcome ou New model, vérifiez si quelqu'un a déjà ouvert une PR à ce sujet. Si c'est le cas, n'en ouvrez pas une autre. Si vous repérez des erreurs, laissez des suggestions sur la PR existante. N'ouvrez une PR concurrente que si la PR existante est fondamentalement défectueuse, ou obsolète : son auteur n'a pas répondu aux commentaires de revue ou n'a pas poussé de modifications depuis deux semaines. Une PR en attente de revue par un mainteneur n'est pas considérée comme obsolète. Dans tous les cas, expliquez pourquoi dans l'issue avant d'ouvrir la vôtre.

PR autonomes. Si personne n’a encore signalé le problème, vous pouvez ouvrir une PR sans ticket. Les PR autonomes sont destinées aux modifications courtes ayant un impact réel, comme la correction d’un bug, une amélioration des performances ou la correction d’un exemple cassé dans la documentation. La description de la PR doit contenir les mêmes preuves qu’un ticket :

• pour un bug, un court script qui échoue sur main et réussit avec votre correctif, en utilisant un point de contrôle publié, une configuration par défaut ou un flux de travail documenté
• pour une amélioration des performances, les chiffres avant et après sur une charge de travail réaliste, comme un point de contrôle publié ou une configuration par défaut, ainsi que le matériel utilisé. Un microbenchmark plus rapide d’une fonction qui ne fait pas partie d’un chemin critique ne compte pas.

Si un problème existe déjà, votre PR est associée à ce problème, que vous le mentionniez ou non. Les PR autonomes qui corrigent un problème existant, ou qui sont soumises sans preuve, seront fermées. Ces exigences ne s’appliquent pas aux nouveaux modèles.

Modifications nécessitant d’abord une issue. Les nettoyages mécaniques qui n’affectent ni la justesse ni les performances, ainsi que les corrections en masse de fautes de frappe ou de formulations dans la documentation, nécessitent une issue avant la création d’une PR. Proposez la modification, la manière dont vous la réaliserez et le nombre de fichiers concernés. Une simple correction de faute de frappe est trop petite pour une PR, quel que soit le chemin suivi.

Revue des PR d’autres personnes. Les avis de la communauté sont les bienvenus lorsqu’ils nous apportent des informations nouvelles, mais les mainteneurs lisent chaque commentaire sur une PR et nous utilisons déjà nos propres outils de revue. Avant de commenter une PR que vous n’avez pas ouverte, assurez-vous d’avoir quelque chose de précis à dire :

• Si vous avez trouvé un problème ou avez une modification concrète à proposer, laissez un commentaire en ligne sur les lignes concernées, idéalement sous forme de suggestion GitHub que l’auteur peut appliquer directement. Un script de reproduction est utile si vous signalez un bug.
• Si vous avez signalé le problème que la PR corrige, un bref message indiquant si elle résout votre cas est vraiment utile.
• Veuillez ne pas publier de résumés généraux ni de rapports du type « J’ai testé et ça marche ». Les approbations de non-mainteneurs n’influencent pas la fusion d’une PR, et un long commentaire qui reformule le contenu de la PR nous coûte du temps sans modifier le résultat.

La manière dont vous écrivez votre code vous appartient, mais vous êtes responsable de tout ce que vous soumettez, et nous pouvons bloquer les comptes qui ouvrent de manière répétée des issues ou des PR de faible qualité. Veuillez également respecter notre code de conduite.

Configuration

1. Faites un fork de Transformers à l’aide du bouton Fork sur GitHub pour obtenir une copie sous votre compte, puis clonez-le localement.

   Copié

   git clone git@github.com:<your Github handle>/transformers.git
   cd transformers

2. Ajoutez le dépôt Transformers en tant que distant nommé upstream. origin pointe vers votre fork et upstream pointe vers la source de vérité. Cela vous permet de synchroniser votre main local avant de pousser vers origin et d’ouvrir une PR.

   Copié

   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. Gardez votre fork à jour et créez une branche pour y travailler. Vous pouvez également synchroniser votre fork depuis l’interface GitHub à l’aide du bouton Sync fork.

   Copié

   git checkout main && git pull upstream main && git push origin main
   git switch -c a-descriptive-name-for-my-branch

4. Installez la bibliothèque en mode éditable. Utilisez [dev] pour la plupart des contributions, car il inclut les outils de développement nécessaires aux contrôles de style et de qualité. Utilisez [torch,testing] pour les contributions de modèles, ou [quality] pour les modifications limitées à la documentation et les correctifs mineurs lorsque l’ensemble complet des dépendances de développement n’est pas requis.

   Copié

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

Windows

Sur Windows, sauf si vous utilisez WSL, configurez git pour convertir les fins de ligne CRLF en LF.

git config core.autocrlf input

Une façon d'exécuter la commande make sous Windows est d'utiliser MSYS2.

1. Télécharger MSYS2 (nous supposons qu’il est installé dans C:\msys64).
2. Ouvrez la ligne de commande C:\msys64\msys2.exe (elle devrait être disponible depuis le menu Démarrer).
3. Exécutez dans le shell : pacman -Syu et installez make avec pacman -S make.
4. Ajoutez C:\msys64\usr\bin à votre variable d'environnement PATH.

Vous pouvez désormais utiliser make depuis n'importe quel terminal (PowerShell, cmd.exe, etc.).

Ouverture de tickets

Utilisez les modèles de ticket et vérifiez que le problème n’a pas déjà été signalé (utilisez la barre de recherche GitHub sous Issues). Un rapport de bug doit concerner un bug dans Transformers, et non dans votre propre code, et il doit affecter des cas d’usage réels et des checkpoints réels ; un « bug théorique » découvert en lisant le code, qui nécessite une configuration très non standard pour se déclencher, ne sera pas trié à moins qu’il ne s’agisse d’un problème de sécurité. Incluez un script court et autonome qui reproduit le bug sur la dernière version publiée ou sur main, en utilisant un checkpoint publié ou une configuration par défaut. Les rapports de bug sans reproducteur exécutable ne seront pas triés.

Si vous n’êtes pas sûr que le bug provienne de votre code ou de la bibliothèque, posez d’abord la question sur le forum ou sur Discord. Cela aide à garder GitHub concentré sur les problèmes de bibliothèque actionnables.

Ajout d'un nouveau modèle

Ajouter un modèle à Transformers le rend disponible pour que n’importe qui puisse le charger, l’affiner ou exécuter une inférence. Avant de commencer l’implémentation, isolez les différences entre votre architecture et les modèles d’état de l’art récents déjà présents dans Transformers. Expliquez ces différences dans le ticket ou la PR afin que les relecteurs puissent rapidement comprendre les défis que le modèle pose, quelles parties peuvent réutiliser des motifs existants et ce qui devrait être standardisé entre les modèles.

Suivez les guides ci-dessous.

1. Ajouter un modèle avec Transformers modulaire — implémenter le modèle à l'aide du fichier modulaire et générer des fichiers de modélisation autonomes.
2. Générer automatiquement les docstrings — utilisez le décorateur @auto_docstring pour générer des docstrings cohérentes sans code répétitif.
3. Tests — rédigez et exécutez des tests de modèle pour vérifier la justesse et maintenir la contribution. Pour les modèles de langage causaux, héritez du testeur de LM causal lorsque c’est possible. Priorisez les tests d’intégration, car ils valident le chemin complet du processeur, du tokeniseur et du modèle face à de vrais points de contrôle.
4. Règles de structure des modèles — vérifiez que vos fichiers respectent les règles statiques de structure des modèles appliquées par make typing.

Certaines ajouts de modèles nécessitent un travail d'intégration supplémentaire.

• Ajoutez des composants de traitement visuel si votre modèle nécessite des entrées d'images ou de vidéos.
• Chargement dynamique des poids si les noms des paramètres du point de contrôle publié ne correspondent pas à l'implémentation Transformers.

Chronologie d'ajout des modèles

Il existe quatre délais pour l’ajout de modèles, en fonction du contributeur du modèle et de la demande de la communauté pour une architecture donnée.

• Intégration dès le jour J : rendre le modèle disponible dans Transformers le jour de sa sortie, avec une nouvelle version. Nous fournissons de l’assistance pour prendre en charge les fonctionnalités centrales les plus importantes (quantification, FlashAttention, cache KV, etc.), examinons les brouillons initiaux et pouvons également nous charger de l’implémentation du modèle selon les délais.

  Envoyez un e-mail à transformers@huggingface.co quelques semaines à l’avance, en particulier pour les architectures novatrices. Nous itérerons avec vous sur un fork privé jusqu’à ce que votre checkpoint et votre publication soient prêts.

• Intégration dans la même semaine : les modèles très demandés sont généralement intégrés dans la semaine, même si l'auteur ne prend pas contact.

  Ouvrez un ticket avec le modèle de nouveau modèle pour en faire la demande. Les tickets avec plus d’activité montent plus rapidement dans la file d’attente.

• Intégration post-sortie : les modèles sans forte demande, ou pour lesquels nous n’avons pas la capacité de les prendre en charge, sont intégrés après la sortie en amont.

  Les contributeurs externes peuvent ouvrir directement une PR pour un nouveau modèle, avec ou sans issue. Avant de commencer, vérifiez les issues « New model » ouvertes et les PR ouvertes pour vous assurer que personne ne l’ajoute déjà. Nous examinerons votre contribution et vous guiderons tout au long du processus.

• Publication centrée sur le Hub : publiez votre modèle directement sur le Hub grâce à la prise en charge du remote-code par Transformers, sans avoir à soumettre de PR en amont.

  Les modèles Hub-first populaires sont souvent intégrés à Transformers par la suite, ce qui débloque une documentation de premier ordre, une maintenance et des optimisations. Hub-first est la méthode la plus simple pour ajouter un modèle. Cependant, elle peut s’avérer plus fragile si le modèle nécessite une conversion de poids ou présente d’autres problèmes de compatibilité ascendante.

Docs

Pour la référence API générée à partir des fichiers source, utilisez le décorateur @auto_docstring lorsque cela s’applique. Consultez le README de la documentation pour plus de détails sur la manière de modifier la documentation et la syntaxe que nous utilisons.