PEFT documentation

Contribuer à PEFT

PEFT

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Contribuer à PEFT

Nous sommes ravis d'accepter des contributions à PEFT. Si vous prévoyez de contribuer, veuillez lire ceci afin de rendre le processus aussi fluide que possible.

Discuter et obtenir l'approbation avant d'ouvrir une PR

Avant d’ouvrir une pull request (y compris un brouillon), ouvrez ou trouvez un issue dans huggingface/peft et discutez de votre contribution proposée. S’il existe déjà un issue et que quelqu’un y travaille déjà, a déclaré son intention d’y travailler, ou a une PR ouverte, vous ne devez pas soumettre une PR distincte. Attendez qu’un mainteneur de PEFT ou un membre de Hugging Face approuve explicitement la proposition. Si vous ouvrez un issue, gardez la longueur et la complexité de la description proportionnelles à la complexité de l’issue. Souvent, une description courte avec un reproducteur est plus précieuse qu’une description longue.

Un commentaire d’approbation contient le message /peft-triage approved. Il peut également indiquer le nom du contributeur assigné, par exemple /peft-triage approved username ou /peft-triage approved @username. Ouvrir une PR pour un problème auquel vous n’êtes pas assigné entraînera la fermeture de ladite PR.

Liez le problème ouvert et approuvé dans la description de votre PR en utilisant #123, huggingface/peft#123 ou https://github.com/huggingface/peft/issues/123. À titre d’exception, les mainteneurs peuvent désigner des discussions de longue durée spécifiques qui peuvent être référencées par leur URL GitHub complète, sans commentaire d’approbation distinct. Si vous référencez plusieurs problèmes ou discussions, une seule référence valide suffit.

Un flux de travail automatisé vérifie que les PR sont associées à des problèmes ouverts ou à des discussions approuvés. Les PR sans référence valide sont automatiquement fermées avec une explication. Vous pouvez obtenir l’approbation du problème, mettre à jour la description de la PR et rouvrir la même PR ; veuillez ne pas en créer de nouvelle. Si vous estimez que votre PR a été fermée à tort, contactez les mainteneurs sur la PR.

Le bot obsolète indépendant peut toujours fermer les éléments inactifs, même s’ils sont étiquetés triaged. Si vous estimez que les mainteneurs ont négligé votre contribution, vous pouvez les solliciter, mais pas avant deux semaines d’inactivité.

Installation

Suivez ces étapes pour commencer à contribuer :

Fork the repository en cliquant sur le bouton « Fork » de la page du dépôt. Cela crée une copie du code sous votre compte utilisateur GitHub.
Clonez votre fork sur votre disque local et ajoutez le dépôt de base en tant que distant. La commande suivante suppose que votre clé SSH publique est téléversée sur GitHub. Consultez le guide suivant pour plus d'informations.
```
git clone git@github.com:<your Github handle>/peft.git
cd peft
git remote add upstream https://github.com/huggingface/peft.git
```
Créez une nouvelle branche pour y stocker vos modifications de développement, et faites-le pour chaque nouvelle PR sur laquelle vous travaillez.

Commencez par synchroniser votre branche main avec la branche upstream/main (plus de détails dans la documentation GitHub) :
```
git checkout main
git fetch upstream
git merge upstream/main
```
Une fois que votre branche main est synchronisée, créez une nouvelle branche à partir de celle-ci :
```
git checkout -b a-descriptive-name-for-my-changes
```
Ne travaillez pas sur la branche main.
Configurez un environnement de développement en exécutant la commande suivante dans un environnement conda ou un environnement virtuel que vous avez créé pour travailler sur cette bibliothèque :
```
pip install -e ".[test]"
```
(Si PEFT était déjà installé dans l’environnement virtuel, désinstallez-le avec pip uninstall peft avant de le réinstaller.)

Si vous débutez dans la création d'une pull request, suivez le guide Creating a pull request de GitHub.

Tests et contrôles de qualité du code

Quelle que soit la nature de la contribution (sauf s’il ne s’agit que de la documentation), vous devez exécuter les tests et les contrôles de qualité du code avant de créer une PR afin de vous assurer que votre contribution ne casse rien et respecte les standards du projet.

Exécution des tests et des vérifications

Nous fournissons un Makefile pour exécuter les tests nécessaires. Exécutez le code ci-dessous pour le test unitaire :

make test

Exécutez l'une des commandes suivantes pour vérifier uniquement la qualité et le style du code, ou pour les vérifier et les corriger :

make quality  # just check
make style  # check and fix

L’exécution de make quality vérifie également si toutes les méthodes/classes de l’API publique de PEFT (c’est-à-dire tout ce qui est mentionné dans peft.__all__) sont documentées. Ces erreurs ne peuvent pas être corrigées par make style ; vous devez vous assurer de documenter les nouveaux éléments de l’API publique dans la documentation pour corriger cette erreur.

Vous pouvez également configurer pre-commit pour exécuter automatiquement ces correctifs en tant qu'accroches de commit Git.

$ pip install pre-commit
$ pre-commit install

L’exécution de tous les tests peut prendre un certain temps, il est donc plus efficace, pendant le développement, de n’exécuter que les tests spécifiques à votre modification, par exemple via :

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

Cela devrait se terminer beaucoup plus rapidement et permettre une itération plus rapide.

Ajout de tests

Pour un guide général sur l'ajout de nouveaux tests, consultez tests/README.md.

Si votre modification est spécifique à une configuration matérielle (par exemple, elle nécessite CUDA), consultez tests/test_gpu_examples.py et tests/test_common_gpu.py pour vérifier s'il est pertinent d'ajouter des tests à cet endroit. Si votre modification peut avoir un impact sur l'enregistrement et le chargement des modèles, veuillez exécuter les tests avec le drapeau --regression pour déclencher les tests de régression.

PRs obsolètes

Il peut arriver que, pendant que vous travaillez sur votre PR, la base de code sous-jacente change en raison d’autres modifications fusionnées. Si cela se produit – en particulier en cas de conflit de fusion – veuillez mettre à jour votre branche avec les dernières modifications. Il peut s’agir d’une fusion ou d’un rebase, et nous effectuerons un squash and merge de la PR une fois qu’elle sera prête. Évitez les force pushes pour faciliter les revues.

Description de la PR

Lors de l’ouverture d’une PR, veuillez fournir une description claire de la modification que vous proposez et référencer le problème approuvé tel que décrit ci-dessus. S’il est lié à d’autres problèmes ou PR, veuillez les référencer également. Fournir une bonne description aide non seulement les relecteurs à examiner votre code de manière plus efficace et plus rapide, mais elle peut aussi être utilisée plus tard (comme base) pour le message de commit, ce qui facilite la maintenance à long terme du projet.

Adaptez la longueur et la complexité de la description de la PR à l'ampleur de la modification. Il n'est pas nécessaire de rédiger dix paragraphes d'explication pour une modification triviale d'une seule ligne. Ne reformulez pas ce qui est évident en consultant le diff (par exemple « Corrigé la faute de frappe dans ‘foobaar’ »).

Si votre code apporte des modifications non triviales, il est également judicieux d’ajouter des commentaires pour les expliquer. Par exemple, si vous avez dû itérer sur votre implémentation à plusieurs reprises parce que la méthode la plus évidente ne fonctionnait pas, c’est un bon indicateur qu’un commentaire de code est nécessaire.

Le cas échéant, indiquez comment vous avez testé la modification, par exemple en montrant la commande de test pytest ou le code de reproduction.

Retour du relecteur

Après avoir soumis votre PR, un mainteneur donnera généralement un retour dans les deux jours. Si vous ne recevez aucun retour dans les deux semaines, votre PR a peut-être échappé à leur attention ; n’hésitez pas à relancer les mainteneurs à ce moment-là, mais pas avant.

Si le relecteur fournit des commentaires en ligne, ne les marquez pas comme résolus si vous y avez répondu. Laissez ces commentaires ouverts, car ils aident le relecteur à reprendre son travail.

Après avoir traité les retours des évaluateurs, prévenez l'évaluateur pour qu'il sache que la PR est prête à être examinée.

Corrections de bogues

Veuillez décrire les circonstances qui ont conduit au bug. S'il existe un problème existant, veuillez y faire référence (par exemple, « Resolves #12345 »).

Idéalement, lorsqu'un correctif de bug est fourni, il doit être accompagné d'un test pour ce bug. Le test doit échouer avec le code actuel et réussir avec le correctif. Ajoutez un commentaire au test qui référence le problème ou la PR. Sans test, il est plus difficile de prévenir les régressions à l'avenir.

Améliorations de la documentation

Nous sommes ravis de recevoir des correctifs pour les liens cassés et la documentation manquante ou peu claire. Prendre soin des exemples, en s’assurant qu’ils sont à jour et fonctionnent correctement dans cet environnement en constante évolution, est également très apprécié.

Veuillez vous abstenir d’envoyer des pull requests qui ne corrigent que des erreurs de frappe, car elles génèrent généralement plus de travail qu’elles n’en évitent. De telles modifications sont mieux regroupées avec des correctifs plus substantiels (comme la correction de liens cassés ou l’extension/mise à jour de la documentation).

Ajouter une nouvelle méthode de fine-tuning PEFT

De nouvelles méthodes de fine-tuning à efficacité paramétrique sont développées en permanence. Si vous souhaitez ajouter une nouvelle méthode prometteuse à PEFT, veuillez suivre les étapes ci-dessous.

Si vous n’êtes pas l’auteur de l’article original, vérifiez s’il existe des implémentations existantes et confirmez auprès des auteurs qu’ils ne prévoient pas de soumettre eux-mêmes une demande de pull.
Ouvrez une proposition de problème et attendez une approbation explicite, comme décrit ci-dessus, avant de commencer les travaux d'intégration principale listés ci-dessous.
Consultez les derniers commits pour découvrir les nouvelles méthodes PEFT ajoutées, afin de vous en inspirer.
Une fois la proposition approuvée, il peut être utile d’ouvrir une PR en brouillon tôt, dès que la méthode fonctionne de manière basique et que les premiers tests passent, puis de demander des retours. Référencez le problème approuvé dans la description de la PR en brouillon.

Intégration au cœur d'une nouvelle méthode PEFT

PR complète pour ajouter une nouvelle méthode PEFT

Assurez-vous que les arguments de configuration spécifiques à la méthode sont bien nommés et expliqués, sans supposer que l’utilisateur connaît le papier sur le bout des doigts.
Respectez les conventions de nommage et de codage de PEFT.
Assurez-vous de ne pas avoir accidentellement enregistré des modifications non liées, par exemple des fichiers non liés modifiés par le formatteur de code.
Si certains choix d’implémentation ne sont pas évidents, documentez-les à l’aide d’un commentaire de code.
Complétez la suite de tests complète (test_config.py, test_decoder_models.py, etc.) en ajoutant la méthode PEFT à la matrice de tests. Assurez-vous que les tests passent.
Ajoutez des documents dans docs/source/package_reference/ avec une brève explication, un lien vers l’article, un extrait d’utilisation et des blocs autodoc. Expliquez les avantages et les inconvénients par rapport à d’autres méthodes comme LoRA. Enregistrez cette page de documentation dans docs/source/_toctree.yml.
Ajoutez un exemple exécutable sous examples/ (il peut s’agir d’une copie d’un exemple existant), avec un court README.md.
Consultez les benchmarks dans method_comparison/ et ajoutez les paramètres d’expérimentation pour votre nouvelle méthode. C’est un bon endroit pour vérifier que la méthode PEFT s’entraîne comme prévu. Incluez une ou deux configurations de benchmark raisonnables (une par défaut, une optimisée pour le benchmark).
Recommandé : ajouter une prise en charge générique de la quantification. Plutôt que d’ajouter explicitement des types de couches de quantification pour chaque méthode de quantification, prenez en charge la quantification générique. À titre d’exemple, consultez la façon dont elle est implémentée dans BOFT. Étendez https://github.com/huggingface/peft/blob/main/tests/test_quantization.py en y ajoutant votre méthode PEFT. Demandez de l’aide aux mainteneurs si nécessaire.

Apporter des modifications aux méthodes PEFT existantes

Si vous apportez une modification à une méthode PEFT susceptible d’en changer les sorties, invalidant ainsi des points de contrôle déjà entraînés, des précautions supplémentaires sont nécessaires. Veuillez consulter la description à https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md pour plus de détails. Les instructions qui s’y trouvent s’adressent aussi bien aux humains qu’aux IA.

Ajouter d'autres fonctionnalités

Ouvrez d'abord un ticket sur GitHub avec une proposition d'ajout de la nouvelle fonctionnalité et attendez une approbation explicite, comme décrit ci-dessus. De cette manière, vous pouvez discuter avec les mainteneurs de la pertinence d'ajouter la fonctionnalité avant d'y consacrer trop de temps pour son implémentation.

Les nouvelles fonctionnalités doivent généralement être accompagnées de tests et de documentation ou d’exemples. Sans ces derniers, les utilisateurs auront du mal à découvrir votre nouvelle fonctionnalité.

Les modifications apportées au code doivent être implémentées de manière rétrocompatible. Par exemple, le code existant doit continuer à fonctionner de la même manière après la fusion de la fonctionnalité.

Update on GitHub

←torch.compile Dépannage→