Hugging Face's logo

Diffusers documentation

Comment contribuer à Diffusers 🧨

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

and get access to the augmented documentation experience

to get started

Comment contribuer à Diffusers 🧨

Si vous utilisez un agent IA pour contribuer, assurez-vous de lire la section Contributions assistées par IA et agentiques pour connaître nos attentes et nos directives.

Nous ❤️ les contributions de la communauté open-source ! Tout le monde est le bienvenu, et tous les types de participation – pas seulement le code – sont valorisés et appréciés. Répondre aux questions, aider les autres, prendre contact et améliorer la documentation sont tous extrêmement précieux pour la communauté, alors n’ayez pas peur et impliquez-vous si vous êtes prêt à le faire !

Nous encourageons chacun à commencer par un 👋 dans notre canal Discord public. Nous y discutons des dernières tendances en matière de modèles de diffusion, posons des questions, présentons des projets personnels, nous aidons mutuellement dans nos contributions, ou nous nous retrouvons simplement ☕. Join us on Discord

Quelle que soit la manière dont vous choisissez de contribuer, nous nous efforçons de faire partie d’une communauté ouverte, accueillante et bienveillante. Veuillez lire notre code de conduite et veiller à le respecter lors de vos interactions. Nous vous recommandons également de vous familiariser avec les lignes directrices éthiques qui guident notre projet et vous demandons d’adhérer aux mêmes principes de transparence et de responsabilité.

Nous accordons une importance considérable aux retours de la communauté. N’hésitez donc pas à vous exprimer si vous pensez avoir des retours précieux qui peuvent contribuer à améliorer la bibliothèque : chaque message, commentaire, problème (issue) et demande de tirage (pull request, PR) est lu et pris en compte.

Aperçu

Vous pouvez contribuer de nombreuses manières, allant de la réponse aux questions posées dans les issues et les discussions à l’ajout de nouveaux modèles de diffusion à la bibliothèque principale.

Dans ce qui suit, nous présentons un aperçu des différentes façons de contribuer, classées par engagement de temps requis, en ordre croissant. Toutes sont précieuses pour la communauté.

Comme indiqué précédemment, toutes les contributions sont précieuses pour la communauté. Dans la suite, nous détaillerons un peu plus chaque type de contribution.

Pour les contributions 4 à 10, à l'exception de la 6 qui se trouve sur le Hub, vous devrez ouvrir une PR. La procédure est détaillée dans Ouverture d'une pull request.

1. Poser et répondre à des questions sur GitHub Discussions ou sur Discord

Toute question ou commentaire concernant la bibliothèque Diffusers peut être posé sur GitHub Discussions ou sur Discord. Ces questions et commentaires incluent (sans s’y limiter) :

  • Rapports d'expériences d'entraînement ou d'inférence dans le but de partager des connaissances
  • Présentation de projets personnels
  • Questions aux exemples de formation non officiels
  • Propositions de projets
  • Retour général
  • Résumés d'articles
  • Demander de l'aide pour des projets personnels qui s'appuient sur la bibliothèque Diffusers
  • Questions générales
  • Questions éthiques concernant les modèles de diffusion
  • …

Chaque question posée sur GitHub Discussions ou sur Discord encourage activement la communauté à partager publiquement ses connaissances et pourrait très bien aider un débutant à l’avenir qui se pose la même question que vous. N’hésitez donc pas à poser toutes les questions que vous pourriez avoir. Dans le même esprit, vous apportez une aide immense à la communauté en répondant à ce type de questions, car vous documentez ainsi publiquement des connaissances pour que tout le monde puisse en tirer profit.

Veuillez garder à l’esprit que plus vous investissez d’efforts dans la formulation ou la réponse à une question, plus la qualité des connaissances documentées publiquement est élevée. De la même manière, des questions bien posées et bien répondues créent une base de connaissances de haute qualité accessible à tous, tandis que des questions ou des réponses mal formulées réduisent la qualité globale de la base de connaissances publique. En résumé, une question ou une réponse de haute qualité est précise, concise, pertinente, facile à comprendre, accessible et bien formatée/bien posée. Pour plus d’informations, veuillez consulter la section Comment rédiger un bon issue.

NOTE sur les canaux : GitHub Discussions est indexé par les moteurs de recherche et chaque fil peut être lié, de sorte que les questions et les réponses publiées là-bas restent accessibles pour la prochaine personne ayant le même problème. En revanche, Discord a un format de type chat qui invite à une communication rapide et interactive. Bien qu’il soit très probable que vous obteniez une réponse à votre question plus rapidement sur Discord, votre question ne sera plus visible avec le temps, et il est beaucoup plus difficile de trouver des informations publiées il y a un certain temps. Nous recommandons donc GitHub Discussions pour les questions et les réponses destinées à durer. Si une conversation sur Discord aboutit à une conclusion intéressante, publiez le résultat en tant que discussion afin que les lecteurs futurs puissent le trouver.

2. Ouvrir de nouvelles issues sur l'onglet issues de GitHub

La bibliothèque 🧨 Diffusers est robuste et fiable grâce aux utilisateurs qui nous signalent les problèmes qu'ils rencontrent. Merci donc de signaler un problème.

N'oubliez pas que les issues GitHub sont réservées aux questions techniques directement liées à la bibliothèque Diffusers, aux signalements de bugs, aux demandes de fonctionnalités ou aux retours sur la conception de la bibliothèque.

En résumé, cela signifie que tout ce qui n'est pas lié au code de la bibliothèque Diffusers (y compris la documentation) ne doit pas être soumis sous forme de problème (issue), mais plutôt posé sur GitHub Discussions ou Discord.

Veuillez prendre en compte les directives suivantes lors de l’ouverture d’un nouveau problème :

  • Assurez-vous d'avoir d'abord recherché si votre problème a déjà été posé (utilisez la barre de recherche sous Issues sur GitHub).
  • Ne signalez jamais un nouveau problème dans un autre problème (connexe). Si un autre problème est fortement lié, veuillez tout de même ouvrir un nouveau problème et y lier le problème connexe.
  • Assurez-vous que votre problème est rédigé en anglais.
  • Vérifiez si votre problème peut être résolu en passant à la dernière version de Diffusers. Avant de publier votre problème, assurez-vous que python -c "import diffusers; print(diffusers.__version__)" est supérieure ou égale à la dernière version de Diffusers.
  • N'oubliez pas que plus vous investissez d'efforts dans l'ouverture d'une nouvelle issue, plus la qualité de votre réponse sera élevée et meilleure sera la qualité globale des issues de Diffusers.

Les nouvelles problématiques incluent généralement les éléments suivants.

2.1. Signalements de bugs reproductibles et minimaux

Un rapport de bug doit toujours inclure un extrait de code reproductible et être aussi minimal et concis que possible. Cela signifie plus précisément :

  • Réduisez le bug au maximum, ne fournissez pas l'intégralité de votre fichier de code.
  • Formatez votre code.
  • N'incluez aucune bibliothèque externe, sauf si Diffusers en dépend.
  • Toujours fournir toutes les informations nécessaires sur votre environnement ; pour cela, vous pouvez exécuter diffusers-cli env dans votre shell et copier-coller les informations affichées dans le problème.
  • Expliquez le problème. Si le lecteur ne sait pas de quel problème il s’agit et pourquoi il constitue un problème, il ne pourra pas le résoudre.
  • Toujours assurez-vous que le lecteur peut reproduire votre problème avec un minimum d’effort. Si votre extrait de code ne peut pas être exécuté en raison de bibliothèques manquantes ou de variables non définies, le lecteur ne pourra pas vous aider. Veillez à ce que votre extrait de code reproductible soit aussi minimal que possible et qu’il puisse être copié-collé dans un simple interpréteur Python.
  • Si la reproduction de votre problème nécessite un modèle et/ou un jeu de données, assurez-vous que le lecteur y a accès. Vous pouvez toujours téléverser votre modèle ou votre jeu de données sur le Hub pour le rendre facilement téléchargeable. Essayez de garder votre modèle et votre jeu de données aussi petits que possible, afin de rendre la reproduction de votre problème aussi simple que possible.

Pour plus d'informations, veuillez consulter la section Comment rédiger un bon problème.

Vous pouvez ouvrir un rapport de bug ici.

2.2. Demandes de fonctionnalités

Une demande de fonctionnalité de premier ordre traite les points suivants :

  1. D'abord, la motivation :
  • Est-ce lié à un problème ou à une frustration concernant la bibliothèque ? Si oui, veuillez expliquer pourquoi. Il est préférable de fournir un extrait de code qui illustre le problème.
  • Est-ce lié à quelque chose dont vous auriez besoin pour un projet ? Nous serions ravis d’en entendre parler !
  • C'est un projet sur lequel vous avez travaillé et qui, selon vous, pourrait profiter à la communauté ? Génial ! Dites-nous quel problème il a résolu pour vous.
  1. Rédigez un paragraphe complet décrivant la fonctionnalité ;
  2. Fournir un extrait de code qui illustre son utilisation future ;
  3. Si cela est lié à un article, veuillez joindre un lien ;
  4. Joignez toute information supplémentaire (dessins, captures d'écran, etc.) que vous pensez utile.

Vous pouvez ouvrir une demande de fonctionnalité ici.

2.3 Retour d'information

Les retours sur la conception de la bibliothèque et les raisons pour lesquelles elle est bonne ou non aident énormément les mainteneurs principaux à construire une bibliothèque conviviale. Pour comprendre la philosophie derrière la conception actuelle, veuillez consulter ici. Si vous estimez qu'un certain choix de conception ne correspond pas à la philosophie de conception actuelle, veuillez expliquer pourquoi et comment il devrait être modifié. Si un certain choix de conception suit la philosophie de conception de manière trop stricte, limitant ainsi les cas d'utilisation, expliquez pourquoi et comment il devrait être modifié. Si un certain choix de conception est très utile pour vous, veuillez également laisser un commentaire, car il s'agit d'un excellent retour pour les futures décisions de conception.

Vous pouvez ouvrir un ticket concernant les retours ici.

2.4 Questions techniques

Les questions techniques portent principalement sur la raison pour laquelle un certain code de la bibliothèque a été écrit d'une manière particulière, ou sur la fonction d'une certaine partie du code. Veuillez vous assurer de lier le code concerné et de fournir des détails sur la raison pour laquelle cette partie du code est difficile à comprendre.

Vous pouvez ouvrir un ticket concernant une question technique ici.

2.5 Proposition d’ajout d’un nouveau modèle, planificateur ou pipeline

Si la communauté des modèles de diffusion a publié un nouveau modèle, pipeline ou planificateur que vous aimeriez voir dans la bibliothèque Diffusers, veuillez fournir les informations suivantes :

  • Brève description du pipeline de diffusion, du modèle ou du planificateur, avec un lien vers l’article ou la publication publique.
  • Lien vers l'une de ses implémentations open source.
  • Lien vers les poids du modèle s’ils sont disponibles.

Pensez également à mentionner l’auteur original du composant (modèle, planificateur, pipeline, etc.) par son identifiant GitHub, si vous parvenez à le trouver.

Si vous souhaitez intégrer le modèle à Diffusers vous-même, consultez Publier un pipeline ou un modèle sur le Hub et Ajouter des pipelines, des modèles et des planificateurs.

Vous pouvez ouvrir une demande pour un modèle/une pipeline/un planificateur ici.

3. Répondre aux problèmes sur l'onglet issues de GitHub

Répondre aux problèmes sur GitHub peut nécessiter certaines connaissances techniques de Diffusers, mais nous encourageons tout le monde à essayer, même si vous n’êtes pas à 100 % certain que votre réponse est correcte. Quelques conseils pour donner une réponse de haute qualité à un problème :

  • Soyez aussi concis et minimal que possible.
  • Restez dans le sujet. Une réponse à la question doit porter sur la question et uniquement sur la question.
  • Fournissez des liens vers du code, des articles ou d'autres sources qui prouvent ou soutiennent votre point de vue.
  • Répondez par du code. Si un simple extrait de code constitue la réponse au problème ou montre comment le résoudre, veuillez fournir un extrait de code entièrement reproductible.

Par ailleurs, de nombreuses questions ont tendance à être hors sujet, en double avec d’autres questions, ou sans rapport. Il est très utile pour les mainteneurs que vous répondiez à ce type de questions, en encourageant l’auteur à être plus précis, à fournir le lien vers une question en double ou à le rediriger vers GitHub Discussions ou Discord.

Si vous avez vérifié que le rapport de bug est correct et qu'une correction du code source est nécessaire, veuillez consulter les sections suivantes.

Pour toutes les contributions, à l’exception de 6, vous devez ouvrir une PR. La section Ouverture d’une pull request explique comment faire.

4. Corriger un « Good first issue »

Les bonnes premières issues sont marquées par l'étiquette Good first issue. En général, l'issue explique déjà à quoi une solution potentielle devrait ressembler, ce qui facilite sa résolution. Si l'issue n'a pas été fermée et que vous souhaitez tenter de la corriger, il vous suffit de laisser un message « I would like to try this issue. ». Il y a généralement trois scénarios :

  • a.) La description du problème propose déjà un correctif. Dans ce cas, et si la solution vous semble pertinente, vous pouvez ouvrir une PR ou une PR en brouillon pour le corriger.
  • b.) La description du problème ne propose pas de correctif. Dans ce cas, proposez vous-même un correctif dans un commentaire sur le problème. Quelques phrases décrivant l’approche suffisent. Attendez qu’un membre de l’équipe Diffusers le confirme avant d’ouvrir une PR.
  • c.) Il existe déjà une PR ouverte pour corriger le problème, mais celui-ci n’a pas encore été clôturé. Si la PR est devenue obsolète, vous pouvez simplement ouvrir une nouvelle PR et y lier la PR obsolète. Les PR deviennent souvent obsolètes lorsque le contributeur d’origine, qui souhaitait corriger le problème, ne trouve soudainement plus le temps de poursuivre. Cela arrive fréquemment dans le code open source et est tout à fait normal. Dans ce cas, la communauté sera très heureuse que vous tentiez à nouveau et que vous vous appuyiez sur les connaissances contenues dans la PR existante. S’il existe déjà une PR et qu’elle est active, vous pouvez aider l’auteur en faisant des suggestions, en passant la PR en revue ou même en demandant si vous pouvez contribuer à la PR.

5. Contribuer à la documentation

Une bonne bibliothèque a toujours une bonne documentation ! La documentation officielle est souvent l’un des premiers points de contact pour les nouveaux utilisateurs de la bibliothèque, et contribuer à la documentation constitue donc une contribution très précieuse.

Contribuer à la bibliothèque peut prendre de nombreuses formes :

  • Correction des erreurs d'orthographe ou de grammaire.
  • Corrigez le formatage incorrect de la docstring. Si vous constatez que la documentation officielle est affichée de manière inattendue ou qu’un lien est cassé, nous serions ravis que vous preniez le temps de le corriger.
  • Corriger la forme ou les dimensions d'un tenseur d'entrée ou de sortie dans une docstring.
  • Clarifier la documentation difficile à comprendre ou incorrecte.
  • Mettre à jour les exemples de code obsolètes.
  • Traduction de la documentation dans une autre langue.

Tout ce qui est affiché sur la page de documentation officielle de Diffusers fait partie de la documentation officielle et peut être corrigé ou ajusté dans la source de la documentation respective.

Veuillez consulter cette page pour savoir comment vérifier localement les modifications apportées à la documentation.

6. Publier un pipeline ou un modèle sur le Hub

Avec Modular Diffusers, un pipeline peut exister sous forme de code distant dans n’importe quel dépôt du Hub. N’importe qui peut le charger avec from_pretrained(..., trust_remote_code=True), sans attendre une nouvelle version de Diffusers. Si vous êtes un contributeur de la communauté qui apporte un nouveau pipeline ou un nouveau modèle, commencez ici. Consultez les blocs personnalisés pour publier un pipeline et les modèles personnalisés pour publier un modèle.

Faites-le-nous savoir sous la demande de modèle correspondante (ouvrez-en une s’il n’y en a pas) : nous donnons notre retour sur l’implémentation et mettons en avant celles que nous apprécions dans notre collection Community Modular Diffusers Blocks. À partir de là, nous décidons comment prendre en charge le modèle dans la bibliothèque : nous pouvons intégrer votre version en amont, travailler avec les auteurs sur une version officielle, ou simplement orienter les utilisateurs vers la vôtre. Partagez également les difficultés rencontrées en cours de route : API confuses, documentation manquante, bugs. Ce retour est aussi précieux pour nous que le pipeline.

7. Contribuer aux exemples d'entraînement

Les exemples de Diffusers sont une collection de scripts d'entraînement situés dans examples.

Nous prenons en charge deux types d'exemples d'entraînement :

  • Exemples officiels d'entraînement
  • Exemples d'entraînement de recherche

Les exemples d’entraînement de recherche se trouvent dans examples/research_projects, tandis que les exemples d’entraînement officiels incluent tous les dossiers sous examples à l’exception des dossiers research_projects et community. Les exemples d’entraînement officiels sont maintenus par les mainteneurs principaux de Diffusers, tandis que les exemples d’entraînement de recherche sont maintenus par la communauté. C’est pour la même raison que la bibliothèque maintient un petit ensemble de pipelines officiels et de pipelines communautaires sur le Hub : il n’est pas réalisable pour les mainteneurs principaux de maintenir toutes les méthodes d’entraînement possibles pour les modèles de diffusion. Si les mainteneurs principaux de Diffusers et la communauté considèrent un certain paradigme d’entraînement comme trop expérimental ou pas assez populaire, le code d’entraînement correspondant doit être placé dans le dossier research_projects et maintenu par son auteur.

Les exemples officiels d'entraînement et de recherche consistent en un répertoire contenant un ou plusieurs scripts d'entraînement, un fichier requirements.txt et un fichier README.md. Pour que l'utilisateur puisse utiliser les exemples d'entraînement, il est nécessaire de cloner le dépôt :

git clone https://github.com/huggingface/diffusers

ainsi que pour installer toutes les dépendances supplémentaires requises pour l’entraînement :

cd diffusers
pip install -r examples/<your-example-folder>/requirements.txt

Par conséquent, lors de l’ajout d’un exemple, le fichier requirements.txt doit définir toutes les dépendances pip requises pour votre exemple d’entraînement, afin qu’une fois celles-ci installées, l’utilisateur puisse exécuter le script d’entraînement de l’exemple. Voir, par exemple, le fichier requirements.txt de DreamBooth.

Les exemples d'entraînement de la bibliothèque Diffusers doivent respecter la philosophie suivante :

  • Tout le code nécessaire pour exécuter les exemples doit se trouver dans un seul fichier Python.
  • On doit pouvoir exécuter l'exemple depuis la ligne de commande avec python <your-example>.py --args.
  • Les exemples doivent rester simples et servir d'exemple sur l'utilisation de Diffusers pour l'entraînement. L'objectif des scripts d'exemple n'est pas de créer des modèles de diffusion de pointe, mais plutôt de reproduire des schémas d'entraînement connus sans ajouter trop de logique personnalisée. En conséquence, nos exemples visent également à constituer de bons supports pédagogiques.

Pour contribuer un exemple, il est vivement recommandé de consulter des exemples existants tels que dreambooth afin de comprendre leur structure. Nous conseillons fortement aux contributeurs d'utiliser la Accelerate library, car elle est étroitement intégrée à Diffusers. Une fois qu'un script d'exemple fonctionne, assurez-vous d'ajouter un README.md complet qui décrit précisément comment utiliser l'exemple. Ce README doit inclure :

  • Un exemple de commande pour exécuter le script d’exemple tel que montré ici.
  • Un lien vers des résultats d’entraînement (journaux, modèles, etc.) montrant ce que l’utilisateur peut s’attendre à obtenir, comme indiqué ici.
  • Si vous ajoutez un exemple d’entraînement non officiel/destiné à la recherche, veuillez ne pas oublier d’ajouter une phrase indiquant que vous maintenez cet exemple d’entraînement, en y incluant votre identifiant GitHub comme indiqué ici.

Si vous contribuez aux exemples de formation officiels, veuillez également vous assurer d’ajouter un test à son dossier, tel que examples/dreambooth/test_dreambooth.py. Ce n’est pas nécessaire pour les exemples de formation non officiels.

8. Corriger un « Good second issue »

Les bonnes secondes issues sont marquées par l'étiquette Good second issue. Elles sont généralement plus complexes à résoudre que les bonnes premières issues, leur description offre moins d'indications sur la correction et elles nécessitent une bonne compréhension de la bibliothèque.

Si vous souhaitez relever le défi d’un bon second problème, partagez votre analyse du problème et l’approche que vous avez en tête en commentaire, en quelques phrases, et obtenez l’accord d’un mainteneur avant d’ouvrir la PR. Si une PR a déjà été ouverte pour le problème mais n’a pas été fusionnée, prenez le temps de comprendre pourquoi avant de proposer quelque chose de nouveau.

9. Prendre en charge un problème MVP de Diffusers

Le programme MVP de Diffusers répertorie les problèmes pour lesquels nous avons le plus besoin d’aide. Ils fonctionnent comme les « Good second issues », mais sont plus complexes et demandent plus de temps, et le programme récompense les contributeurs qui s’en chargent. Partagez d’abord votre approche en commentaire et obtenez l’accord d’un mainteneur avant d’ouvrir la PR. Le programme comporte également un volet idées : partagez-nous une idée qui augmenterait l’impact de Diffusers, en quelques phrases et sans détails d’implémentation.

10. Ajout de pipelines, de modèles et de planificateurs

Si vous êtes l’auteur du modèle, veuillez nous contacter afin que nous puissions coordonner l’intégration avec vous : ouvrez une demande de fonctionnalité, ou laissez un commentaire si une demande est déjà ouverte.

Si vous êtes un contributeur de la communauté, commencez par créer un dépôt sur le Hub, consultez Publier un pipeline ou un modèle sur le Hub, et indiquez-nous dans la demande de fonctionnalité que vous souhaitez l’intégrer en amont.

Les pipelines, les modèles et les planificateurs constituent les éléments les plus importants de la bibliothèque Diffusers. Ils offrent un accès simple aux technologies de diffusion de pointe et permettent ainsi à la communauté de construire des applications d'IA générative puissantes.

En ajoutant un nouveau modèle, pipeline ou planificateur, vous pourriez activer un nouveau cas d’usage puissant pour l’une des interfaces utilisateur s’appuyant sur Diffusers, ce qui peut avoir une valeur immense pour l’ensemble de l’écosystème de l’IA générative.

Lors de la publication d'une prise en charge d'un nouveau modèle ou d'un nouveau pipeline

Un nouveau modèle ou pipeline peut être inclus dans une version si vous coordonnez l’intégration avec l’équipe Diffusers à l’avance. N’hésitez pas à nous contacter, soit via une issue sur le dépôt Diffusers, soit par e-mail à diffusers@huggingface.co.

Une publication ne se déclenche pas automatiquement lorsqu'une demande de fusion (pull request) de modèle ou de pipeline est fusionnée. Avant une publication, les mainteneurs vérifient d'abord que l'intégration est complète et que les tests de publication réussissent.

La prise en charge d’un nouveau modèle ou d’un nouveau pipeline est normalement intégrée à la prochaine version mineure. L’intégration est fusionnée dans main et la branche de publication est créée à partir de celle-ci. La publication contient tous les changements fusionnés depuis la publication précédente, et non uniquement l’intégration du modèle ou du pipeline.

Les notes de version mettent en avant le nouveau modèle ou le nouveau pipeline et récapitulent également les autres modifications incluses dans la version. Les versions de correctif sont normalement réservées aux corrections d’une version existante.

Diffusers comporte quelques demandes de fonctionnalités ouvertes pour les trois composants – n’hésitez pas à les parcourir si vous ne savez pas encore quel composant spécifique vous souhaitez ajouter :

Avant d’ajouter l’un des trois composants, il est vivement recommandé de lire le Guide de philosophie afin de mieux comprendre la conception de chacun des trois composants. Veuillez noter que nous ne pouvons pas fusionner des ajouts de modèles, de planificateurs ou de pipelines qui s’écartent fortement de notre philosophie de conception, car cela entraînerait des incohérences dans l’API. Si vous êtes fondamentalement en désaccord avec un choix de conception, veuillez plutôt ouvrir un ticket de retour d’information afin que l’on puisse discuter de la nécessité de modifier un certain motif de conception/choix de conception dans toute la bibliothèque et de mettre à jour notre philosophie de conception. La cohérence à travers la bibliothèque est très importante pour nous.

Assurez-vous d'ajouter des liens vers le code source et le papier d'origine dans la PR, et idéalement de mentionner directement l'auteur original sur la PR afin qu'il puisse suivre les progrès et éventuellement répondre aux questions.

Si vous êtes incertain ou bloqué dans la PR, n’hésitez pas à laisser un message pour demander une première revue ou de l’aide.

Copié depuis mechanism

Une fonctionnalité unique et importante à comprendre lors de l’ajout de tout code de pipeline, de modèle ou de planificateur est le mécanisme # Copied from. Vous le verrez partout dans la base de code Diffusers, et la raison pour laquelle nous l’utilisons est de garder la base de code facile à comprendre et à maintenir. Marquer du code avec le mécanisme # Copied from force le code marqué à être identique au code dont il a été copié. Cela facilite la mise à jour et la propagation des modifications à travers de nombreux fichiers à chaque fois que vous exécutez make fix-copies.

Par exemple, dans l’exemple de code ci-dessous, StableDiffusionPipelineOutput est le code d’origine et AltDiffusionPipelineOutput utilise le mécanisme # Copied from pour le copier. La seule différence est le changement du préfixe de la classe de Stable à Alt.

# Copied from diffusers.pipelines.stable_diffusion.pipeline_output.StableDiffusionPipelineOutput with Stable->Alt
class AltDiffusionPipelineOutput(BaseOutput):
    """
    Output class for Alt Diffusion pipelines.

    Args:
        images (`List[PIL.Image.Image]` or `np.ndarray`)
            List of denoised PIL images of length `batch_size` or NumPy array of shape `(batch_size, height, width,
            num_channels)`.
        nsfw_content_detected (`List[bool]`)
            List indicating whether the corresponding generated image contains "not-safe-for-work" (nsfw) content or
            `None` if safety checking could not be performed.
    """

Pour en savoir plus, lisez cette section de l’article de blog ~Ne répétez pas~ vous-même*.

Comment rédiger un bon ticket

Plus votre problème est bien rédigé, plus les chances qu'il soit résolu rapidement sont élevées.

  1. Assurez-vous d’avoir utilisé le bon modèle pour votre problème. Vous pouvez choisir entre Bug Report, Feature Request, Feedback about API Design, New model/pipeline/scheduler addition ou un problème vierge. Veillez à sélectionner le bon modèle lors de l’ouverture de a new issue. Les questions d’utilisation doivent être posées dans GitHub Discussions, et non dans un problème.
  2. Soyez précis : Donnez à votre problème un titre approprié. Essayez de formuler la description de votre problème de la manière la plus simple possible. Plus vous êtes précis lors de la soumission d'un problème, moins il faudra de temps pour le comprendre et potentiellement le résoudre. Assurez-vous d'ouvrir un problème pour un seul problème et non pour plusieurs. Si vous avez trouvé plusieurs problèmes, ouvrez simplement plusieurs problèmes. Si votre problème est un bug, essayez d'être aussi précis que possible sur la nature du bug – vous ne devriez pas simplement écrire « Error in diffusers ».
  3. Reproductibilité : pas d'extrait de code reproductible == pas de solution. Si vous rencontrez un bug, les mainteneurs doivent pouvoir le reproduire. Assurez-vous d'inclure un extrait de code qui peut être copié-collé dans un interpréteur Python pour reproduire le problème. Vérifiez que votre extrait de code fonctionne, c'est-à-dire qu'il ne manque ni import ni lien vers des images, … Votre problème doit contenir un message d'erreur et un extrait de code qui peut être copié-collé sans aucune modification pour reproduire exactement le même message d'erreur. Si votre problème utilise des poids de modèle locaux ou des données locales auxquelles le lecteur n'a pas accès, le problème ne peut pas être résolu. Si vous ne pouvez pas partager vos données ou votre modèle, essayez de créer un modèle factice ou des données factices.
  4. Minimaliste : Aidez le lecteur à comprendre le problème le plus rapidement possible en restant aussi concis que possible. Supprimez tout code ou toute information sans rapport avec le problème. Si vous avez trouvé un bug, essayez de créer l’exemple de code le plus simple possible pour démontrer votre problème, ne déversez pas tout votre flux de travail dans le problème dès que vous avez trouvé un bug. Par exemple, si vous entraînez un modèle et que vous obtenez une erreur à un certain point de l’entraînement, vous devez d’abord essayer de comprendre quelle partie du code d’entraînement est responsable de l’erreur et essayer de la reproduire avec quelques lignes. Essayez d’utiliser des données factices plutôt que des jeux de données complets.
  5. Contexte : Décrivez ce sur quoi vous travailliez lorsque vous avez rencontré le bug ou eu besoin de la fonctionnalité, par exemple une application construite sur Diffusers, un projet de recherche, ou un agent que vous avez exécuté pour trouver des bugs dans la bibliothèque. Une ou deux phrases suffisent, et un lien vers le projet est le bienvenu. Nous recevons plus de problèmes et de PR que nous ne pouvons en traiter à la fois, donc le contexte nous aide à prioriser selon l'impact.
  6. Ajoutez des liens. Si vous faites référence à un nom, une méthode ou un modèle en particulier, veillez à fournir un lien afin que le lecteur comprenne mieux votre propos. Si vous faites référence à une PR ou à un problème spécifique, assurez-vous de le lier à votre problème. Ne supposez pas que le lecteur sait de quoi vous parlez. Plus vous ajoutez de liens à votre problème, mieux c'est.
  7. Mise en forme. Veillez à formater proprement votre problème en utilisant la syntaxe de code Python pour le code et la syntaxe de code standard pour les messages d’erreur. Consultez la documentation officielle de la mise en forme GitHub pour plus d’informations.
  8. Considérez votre problème non pas comme un ticket à résoudre, mais plutôt comme une belle entrée dans une encyclopédie bien rédigée. Chaque problème ajouté est une contribution au savoir accessible au public. En rédigeant un problème de manière soignée, vous facilitez non seulement la résolution de votre problème par les mainteneurs, mais vous aidez également toute la communauté à mieux comprendre un aspect particulier de la bibliothèque.

Comment rédiger une bonne PR

  1. Commencez toujours par un problème. Trouvez le problème que votre pull request traite, ou ouvrez-en un si personne ne l’a fait, et donnez aux mainteneurs l’occasion de répondre avant d’écrire du code. Le flux de travail qui fonctionne le mieux pour nous consiste à ouvrir un problème, puis à discuter de la solution, puis à ouvrir une PR basée sur cette discussion. Cela nous permet de concentrer notre temps sur les problèmes les plus impactants, de convenir du périmètre avant l’existence du code et d’éviter les travaux en double. Mentionnez le numéro du problème dans la description de la PR (par exemple Fixes #1234) afin que les deux soient liés.
  2. Soyez un caméléon. Comprenez les modèles de conception et la syntaxe existants et assurez-vous que vos ajouts de code s'intègrent harmonieusement à la base de code existante. Les demandes de fusion qui s'écartent significativement des modèles de conception ou des interfaces utilisateur existants ne seront pas fusionnées.
  3. Soyez d’une précision chirurgicale. Une pull request doit résoudre un seul problème, et un seul. Veillez à ne pas tomber dans le piège du « en passant, on corrige aussi un autre problème ». Il est beaucoup plus difficile de relire des pull requests qui résolvent plusieurs problèmes sans rapport entre eux en une seule fois.
  4. Corrigez les motifs, pas les cas isolés. Un problème peut concerner de nombreux fichiers : si le même bug réapparaît à travers le code, recherchez chaque instance et corrigez-les toutes dans une seule PR avec un périmètre clair et systématique (par exemple « corriger les valeurs par défaut mutables dans tous les planificateurs »), plutôt qu’une PR par instance.
  5. Le titre de votre pull request doit résumer sa contribution. Pour indiquer un travail en cours, préfixez le titre par [WIP] ; cela évite les travaux dupliqués et distingue la PR de celles prêtes à être fusionnées.
  6. Essayez de formuler et de mettre en forme votre texte comme expliqué dans Comment rédiger un bon issue.
  7. Examinez votre propre diff avant d’ouvrir la PR. Lisez-le comme le ferait un examinateur et corrigez ce que vous y trouvez. Nous recommandons vivement d’exécuter la compétence self-review : elle applique le même barème que l’examinateur CI @claude. Configurez votre agent comme décrit dans Coding with AI agents et suivez AI-assisted and agentic contributions. Mentionnez dans la description les points que vous avez délibérément laissés tels quels, afin que l’examinateur sache qu’il s’agit d’un choix et non d’une omission.
  8. Vérifiez que les tests existants passent.
  9. Ajoutez des tests à forte couverture. Pas de tests de qualité = pas de fusion.
  • Si vous ajoutez de nouveaux tests @slow, assurez-vous qu’ils passent en utilisant RUN_SLOW=1 python -m pytest tests/test_my_new_model.py. CircleCI n’exécute pas les tests lents, mais GitHub Actions le fait chaque nuit !
  1. Toutes les méthodes publiques doivent avoir des docstrings informatives qui s’affichent bien en markdown. Consultez pipeline_latent_diffusion.py pour un exemple.
  2. En raison de la croissance rapide du dépôt, il est important de s’assurer qu’aucun fichier qui alourdirait significativement le dépôt n’est ajouté. Cela inclut les images, les vidéos et autres fichiers non textuels. Nous préférons utiliser un dataset hébergé sur hf.co, comme hf-internal-testing ou huggingface/documentation-images, pour y placer ces fichiers. S’il s’agit d’une contribution externe, n’hésitez pas à ajouter les images à votre PR et à demander à un membre de Hugging Face de migrer vos images vers ce dataset.

Comment ouvrir une PR

Avant d’écrire du code, nous vous recommandons vivement de parcourir les PR et les issues existants afin de vous assurer que personne ne travaille déjà sur le même sujet. En cas de doute, il est toujours judicieux d’ouvrir une issue pour obtenir des retours.

Vous devez maîtriser les bases de git pour pouvoir contribuer à 🧨 Diffusers. git n'est pas l'outil le plus simple à utiliser, mais il possède la meilleure documentation. Tapez git --help dans un shell et profitez-en. Si vous préférez les livres, Pro Git est une excellente référence.

Suivez ces étapes pour commencer à contribuer (versions de Python prises en charge) :

  1. 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.

  2. Clonez votre fourche sur votre disque local et ajoutez le dépôt de base en tant que distant :

    $ git clone git@github.com:<your GitHub handle>/diffusers.git
$ cd diffusers
$ git remote add upstream https://github.com/huggingface/diffusers.git

  3. Créez une nouvelle branche pour y placer vos modifications de développement :

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

Ne travaillez pas sur la branche main.

  1. Configurez un environnement de développement en exécutant la commande suivante dans un environnement virtuel :

    $ pip install -e ".[dev]"

Si vous avez déjà cloné le dépôt, il est possible que vous deviez exécuter git pull pour récupérer les modifications les plus récentes de la bibliothèque.

  1. Développez les fonctionnalités sur votre branche.

Lorsque vous travaillez sur les fonctionnalités, vous devez vous assurer que la suite de tests passe. Vous devez exécuter les tests impactés par vos modifications de la manière suivante :

$ pytest tests/<TEST_TO_RUN>.py

Avant d'exécuter les tests, assurez-vous d'installer les dépendances requises pour les tests. Vous pouvez le faire avec cette commande :

$ pip install -e ".[test]"

Vous pouvez également exécuter la suite de tests complète avec la commande suivante, mais il faut maintenant une machine puissante pour obtenir un résultat en un temps raisonnable, Diffusers ayant beaucoup grandi. Voici la commande :

$ make test

🧨 Diffusers s'appuie sur black et isort pour formater son code source de manière cohérente. Après avoir effectué des modifications, appliquez les corrections de style automatiques et les vérifications de code qui ne peuvent pas être automatisées en une seule fois avec :

$ make style

🧨 Diffusers utilise également ruff et quelques scripts personnalisés pour détecter les erreurs de codage. Le contrôle qualité s'exécute dans le CI, mais vous pouvez également lancer les mêmes vérifications avec :

$ make quality

Une fois que vous êtes satisfait de vos modifications, ajoutez les fichiers modifiés à l’aide de git add et effectuez un commit avec git commit pour enregistrer vos modifications localement :

$ git add modified_file.py
$ git commit -m "A descriptive message about your changes."

Il est judicieux de synchroniser régulièrement votre copie du code avec le dépôt d'origine. Vous pourrez ainsi prendre en compte rapidement les modifications :

$ git pull upstream main

Poussez les modifications vers votre compte à l'aide de :

$ git push -u origin a-descriptive-name-for-my-changes

  1. Une fois que vous êtes satisfait, rendez-vous sur la page web de votre fork sur GitHub. Cliquez sur « Pull request » pour envoyer vos modifications aux mainteneurs du projet pour examen.

  2. Il est normal que les mainteneurs vous demandent des modifications. Cela arrive même aux contributeurs principaux ! Pour que tout le monde puisse voir les modifications dans la Pull request, travaillez sur votre branche locale et poussez les modifications vers votre fork. Elles apparaîtront automatiquement dans la pull request.

Tests

Une suite de tests étendue est incluse pour tester le comportement de la bibliothèque et plusieurs exemples. Les tests de la bibliothèque se trouvent dans le dossier tests.

Nous préférons pytest et pytest-xdist car c’est plus rapide. Depuis la racine du dépôt, voici comment exécuter les tests avec pytest pour la bibliothèque :

$ python -m pytest -n auto --dist=loadfile -s -v ./tests/

En fait, c’est ainsi que make test est implémenté !

Vous pouvez spécifier un ensemble de tests plus restreint afin de tester uniquement la fonctionnalité sur laquelle vous travaillez.

Par défaut, les tests lents sont ignorés. Définissez la variable d’environnement RUN_SLOW sur yes pour les exécuter. Cela téléchargera plusieurs gigaoctets de modèles — assurez-vous de disposer d’un espace disque suffisant et d’une bonne connexion Internet, ou d’une grande patience !

$ RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/

unittest est entièrement pris en charge, voici comment exécuter des tests avec :

$ python -m unittest discover -s tests -t . -v
$ python -m unittest discover -s examples -t examples -v

Synchroniser le main forqué avec le main en amont (HuggingFace)

Afin d'éviter de solliciter le dépôt en amont, ce qui ajoute des notes de référence à chaque PR en amont et envoie des notifications inutiles aux développeurs impliqués dans ces PR, lors de la synchronisation de la branche principale d'un dépôt forké, veuillez suivre ces étapes :

  1. Lorsque c’est possible, évitez de synchroniser avec l’amont en utilisant une branche et une PR sur le dépôt forké. Fusionnez plutôt directement dans le main du dépôt forké.
  2. Si une PR est absolument nécessaire, utilisez les étapes suivantes après avoir effectué le checkout de votre branche :
$ git checkout -b your-branch-for-syncing
$ git pull --squash --no-commit upstream main
$ git commit -m '<your message without GitHub references>'
$ git push --set-upstream origin your-branch-for-syncing

Guide de style

Pour les chaînes de documentation, 🧨 Diffusers suit le style Google.

Programmation avec des agents IA

Le dépôt conserve la configuration des agents IA dans .ai/, qui est également publié en tant que plugin d’agent afin que les compétences de tâches à la demande s’installent en une seule étape.

  • Lecture seule pour les contributeurs — .ai/ est maintenu par les mainteneurs principaux. Veuillez ne pas modifier les fichiers situés sous .ai/ (ou les liens symboliques racine AGENTS.md / CLAUDE.md, ou les .agents/skills / .claude/skills installés) dans votre PR. Si vous constatez une omission ou une erreur, ouvrez un ticket ou signalez-le sur la PR et un mainteneur le mettra à jour.
  • Guidelines — .ai/AGENTS.md est chargé dans chaque session d'agent via les liens symboliques racine AGENTS.md / CLAUDE.md ; les guides de référence sous .ai/references/ sont lus à la demande lorsqu'un lien est suivi :
  • Skills (sous .ai/skills/, chargées à la demande pour des tâches spécifiques) :
    • model-integration — ajout d’un nouveau modèle ou pipeline à diffusers de bout en bout (structure des fichiers, liste de contrôle d’intégration, organisation des tests, conversion des poids)
    • self-review — vérifiez vos modifications par rapport aux règles du projet avant d'ouvrir une PR
    • diffusers-cli — exécuter des pipelines et inspecter des schémas depuis le terminal
    • custom-blocks — packaging d'une sous-classe de ModularPipelineBlocks pour le Hub

Quelle que soit la voie choisie, demandez à votre agent de confirmer sa propre configuration avant de commencer — python utils/check_ai.py vérifie que les guides et les compétences sont cohérents, et diffusers-cli skills list affiche les compétences dont il dispose réellement.

Contributions assistées par l'IA et agentiques

Les agents IA sont les bienvenus pour contribuer à Diffusers. Nous vous encourageons à configurer votre agent avec le guide des agents de Diffusers et à utiliser les compétences spécifiques aux tâches pertinentes, telles que model-integration et self-review. Installez le plugin (ou les compétences individuelles) comme décrit ci-dessus, puis suivez le guide pour définir le périmètre, implémenter, tester et examiner votre contribution. Vous restez responsable de la compréhension, des tests et de la maintenance des modifications dans votre PR.

Les contributions assistées par IA sont les bienvenues, mais elles doivent être coordonnées, cadrées et vérifiées afin de maintenir la charge de revue à un niveau gérable. Les PR qui ne respectent pas ces directives peuvent être fermées sans revue détaillée.

  • Coordonnez-vous avant d’ouvrir une PR. Trouvez ou ouvrez un issue, examinez les PR similaires (ouvertes et récemment fermées) et attendez une confirmation explicite d’un mainteneur sur cet issue avant d’ouvrir une PR. Cela nous permet de discuter du périmètre, d’éviter les travaux en double et de valider l’approche.
  • Corrigez les schémas, pas les cas isolés. Si vous repérez un problème récurrent, recherchez dans la base de code des instances similaires et ouvrez un seul problème avec un périmètre clair et systématique (par exemple « corriger les valeurs par défaut mutables dans tous les planificateurs ») plutôt que de nombreux problèmes ou PR pour des instances individuelles.
  • Auto-évaluation avant ouverture. Exécutez la compétence self-review — elle examine votre diff par rapport à .ai/references/review-rules.md, la même grille d’évaluation utilisée par le réviseur CI @claude — et traitez ce qu’elle signale — c’est un outil d’assistance, pas une autorité, et il peut se tromper. Concentrez-vous sur les problèmes bloquants qui vous semblent pertinents et nettoyez le code mort/inutilisé autant que possible. Si vous êtes en désaccord avec une suggestion, il est acceptable de la laisser pour que le réviseur en discute après l’ouverture de la PR — les notes que vous partagez (voir ci-dessous) indiquent au réviseur qu’il s’agit d’un choix délibéré.
  • Partagez vos notes d’auto-évaluation. Publiez le rapport d’auto-évaluation final — la ronde qui reflète la diff que vous soumettez — sur la PR, dans la description ou en commentaire, en incluant les constats que vous avez délibérément laissés sans correction et les raisons. Cela aide le relecteur à voir ce qui a déjà été vérifié et quels choix ont été faits intentionnellement, et permet généralement d’éviter plusieurs allers-retours.
  • Gardez la communication de votre PR concise. Tout ce qu’un examinateur lit sur votre PR — la description, les messages de commit, les commentaires et les réponses, les commentaires de code — doit être facile à comprendre pour un humain. Si votre agent l’a rédigée, ne vous contentez pas d’un coup d’œil. Lisez-la, et demandez à l’agent de la réviser jusqu’à ce qu’elle dise quelque chose de sensé et de concis que vous auriez écrit vous-même. Vous êtes l’auteur de tout ce que vous publiez.
  • Include in the PR description:
    • Un lien de coordination vers le problème ou la discussion où un mainteneur a reconnu le travail.
    • Les commandes de test que vous avez exécutées et leurs résultats (collez la sortie pertinente, pas seulement « tests passés »).
    • Vos notes d'auto-évaluation (ou un lien vers le commentaire de PR les contenant), comme décrit ci-dessus.

Si vous êtes l’auteur d’un modèle ou membre d’une équipe qui en assure officiellement la maintenance, nous vous encourageons à utiliser des agents pour l’intégration d’un nouveau modèle. Suivez la configuration recommandée du dépôt et utilisez la compétence model-integration. Coordonnez le périmètre avec les mainteneurs avant d’ouvrir une PR — voir Ajout de pipelines, de modèles et de planificateurs.

Update on GitHub

←Génération contrôlée Lignes directrices éthiques de Diffusers→