Transformers documentation

Contrôles des demandes de fusion

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

and get access to the augmented documentation experience

to get started

Contrôles des demandes de fusion

Lorsque vous ouvrez une pull request, le CI de Hugging Face exécute plusieurs vérifications qui doivent aboutir avant que votre PR puisse être fusionnée.

  • Corriger la CI répertorie les commandes à exécuter localement pour passer les vérifications.
  • Les sections suivantes décrivent ce que chaque contrôle valide, comme la qualité du code et la cohérence du dépôt.
  • Tests décrit les tests exécutés, les catégories de tests et les tests lents.

Corriger la CI

Dans la plupart des cas, make style suffit pour corriger l’échec le plus fréquent, à savoir le contrôle de la qualité du code.

make style

En cas d’échec de la cohérence du dépôt, des copies ou des fichiers générés automatiquement, exécutez make fix-repo. Cette commande corrige le style, les copies, les docstrings et les fichiers générés automatiquement en une seule passe.

make fix-repo

Pour une modification plus importante, la séquence de trois commandes ci-dessous couvre toutes les vérifications. Elle est plus lourde, mais détecte tout avant que vous ne poussiez vos modifications.

make fix-repo   # auto-fix everything that can be auto-fixed
make typing     # check types and model structure, fix any errors manually
make check-repo # verify all checks pass, fix anything that remains

make typing détecte les erreurs de type et les violations de la structure du modèle, que vous corrigez manuellement. make check-repo effectue un dernier passage en lecture seule afin que vous puissiez confirmer que tout est prêt.

La CI est parfois instable. Si une vérification échoue pour une raison sans rapport avec votre modification, contactez un mainteneur afin qu’il la relance.

Qualité du code

La vérification de la qualité du code couvre le formatage, les imports, la vérification des types et les règles de structure des modèles. Elle correspond à make fix-repo et make typing.

make style (inclus dans make fix-repo) corrige automatiquement le linting et le formatage Ruff, l’ordre des imports dans __init__.py et la cohérence du mapping automatique.

make typing effectue la vérification des types avec ty et valide les règles TRansFormers (TRF), qui couvrent les conventions de nommage des classes de configuration et les signatures de forward(). Les erreurs de type et les violations TRF signalent un numéro de règle spécifique et doivent être corrigées manuellement. Les règles sont situées dans le dépôt mlinter. Exécutez python -m utils.mlinter --list-rules pour afficher toutes les règles TRF, ou python -m utils.mlinter --rule TRFXXX pour consulter la documentation complète d'une règle spécifique.

Si une règle TRF nécessite une exception, choisissez l’une de ces options (voir Supprimer les violations pour plus de détails).

  • Ajoutez le nom de votre modèle à la liste allowlist_models de la règle concernée dans utils/mlinter/rules.toml. Utilisez cette option lorsque le fichier du modèle entier nécessite une exception.
  • Ajoutez # trf-ignore: TRFXXX sur la même ligne que la construction signalée, ou sur la ligne immédiatement au-dessus. Utilisez cette méthode lorsqu’une seule construction signalée nécessite une exception.

Cohérence du dépôt

La vérification de la cohérence du dépôt est similaire à make check-repo, à l'exception près qu'elle s'arrête dès la première erreur. Elle maintient le dépôt intérieurement cohérent selon les catégories suivantes : les objets publics restent importables, le code copié reste synchronisé avec sa source, et les fichiers générés automatiquement (dummies, doctests, métadonnées) reflètent l'état actuel du code. Pour les nouveaux modèles, elle vérifie également que chaque nouvelle classe de modèle est enregistrée dans les correspondances automatiques.

CatégorieCe qu'il valideCorrigé automatiquement ?
Fichiers d'initialisationLes fichiers __init__.py dans src/transformers/models/ sont à jourmake fix-repo
Copies et modulaireLes blocs # Copied from correspondent à leur source et les fichiers générés de manière modulaire sont à jourmake fix-repo
Docstrings et documentationLes docstrings des arguments correspondent aux signatures des fonctions et à la table des matières de la documentationmake fix-repo
Fichiers générés automatiquementDummies, typage des pipelines, liste doctest, métadonnées, tableau des dépendancesmake fix-repo
Validation de la configurationLes classes de configuration ont des points de contrôle valides dans les docstrings et les attributs de configuration correspondent au fichier de modélisationManuel
Affectation des relecteursChaque répertoire de modèle et chaque règle du fichier de revue aboutit à un examinateurManuel

Affectation des relecteurs

.github/scripts/codeowners_for_review_action enregistre qui examine quels fichiers.

La propriété est résolue par fichier, en commençant par le plus spécifique.

OùSembleL'utiliser pour
Le fichier du modèle# Reviewers: @login dans le bloc de commentaire en tête de modular_<model>.py ou modeling_<model>.pyun modèle qui nécessite une personne autre que le propriétaire de sa modalité. Le convertisseur modulaire copie l'en-tête dans le fichier de modélisation généré, de sorte que le tag subsiste après régénération
Une règle de chemin/src/transformers/<area>/ @login dans .github/scripts/codeowners_for_review_actiontout ce qui n'est pas un modèle
Le tableau des modalités@@modality/vision @login, dans le même fichierchaque modèle dont la page de documentation se trouve dans cette section de docs/source/en/_toctree.yml
Le cas général* @Rocketknight1 @ArthurZuckerque ce soit quoi que ce soit, rien d'autre ne le revendique

Un nouveau modèle n’a besoin d’aucune entrée : l’ajout de sa page de documentation à _toctree.yml, ce que la vérification de la table des matières de la documentation exige déjà, le place dans une modalité, et la table des matières de la modalité le couvre à partir de là.

make check-repository-consistency exécute utils/check_reviewers.py, qui échoue lorsqu'un modèle n'est attribué à personne hormis le filet de sécurité, lorsqu'une règle ne correspond plus à aucun fichier, ou lorsque le tableau des modalités est en désaccord avec la table des matières. Son résolveur n'est pas une dépendance de transformers ; il est répertorié dans utils/checkers-requirements.txt, que l'exécuteur de vérificateurs installe lors de sa première exécution dans un environnement. Si l'installation ne peut pas avoir lieu — par exemple en mode hors ligne —, la vérification le signale et passe plutôt que de vous bloquer. Les chemins situés en dehors de src/transformers/models qui n'ont pas de propriétaire sont signalés en tant que note ; listez-les avec :

python utils/check_reviewers.py --strict

Tests

CI exécute un sous-ensemble ciblé de tests en fonction des modifications apportées par votre PR. CI exécute les tests dans un ordre légèrement aléatoire grâce à pytest-random-order afin de détecter les tests couplés. L’exécution affiche la graine aléatoire au début, ce qui vous permet de rejouer le même ordre avec --random-order-seed=<seed>.

Si un test réussit localement sur GPU mais échoue dans CI, définissez TRANSFORMERS_TEST_DEVICE="cpu" pour vérifier si vous pouvez reproduire l’échec sur CPU.

TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -v

Les sections ci-dessous expliquent comment fonctionne la sélection des tests, quels jobs sont exécutés et comment gérer les tests lents.

Sélection des tests

CI n’exécute pas la suite de tests complète sur chaque PR. CI ignore les tests décorés avec @slow sur chaque PR, et un mainteneur les déclenche sur GPU une fois que la PR est en cours d’examen.

utils/tests_fetcher.py suit les dépendances d’importation de vos fichiers modifiés pour identifier les tests concernés, et n’exécute que ceux-ci. Il détecte également les régressions sur d’autres modèles lorsque vous modifiez des utilitaires partagés. L’outil affiche les fichiers modifiés et les tests impactés, puis écrit la liste dans tests_torch_test_list.txt.

Utilisez le fetcher pour reproduire exactement ce que CI exécute.

python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)

La modification de fichiers principaux tels que modeling_utils.py ou generation/utils.py déclenche l'ensemble des tests de modèles, et non seulement le sous-ensemble concerné.

Vous pouvez également exécuter inconditionnellement tous les tests de votre modèle. Une exécution directe constitue un contrôle de cohérence local plus rapide, mais elle ne détectera pas les régressions dans d’autres modèles causées par du code partagé que vous avez modifié.

pytest tests/models/my_model/ -v

Catégories de tâches de test

Les tests sont répartis sur des tâches CI parallèles, et chaque tâche sélectionne les fichiers selon un motif de chemin. Les tâches pertinentes pour une PR de modèle sont les suivantes :

  • tests_torch : tests de modélisation (tests/models/*/test_modeling_*.py)
  • tests_tokenization : tests du tokenizer (tests/models/*/test_tokenization_*.py)
  • tests_processors : tests des processeurs et des extracteurs de caractéristiques (tests/models/*/test_(processing|image_processing|feature_extractor)_*.py)
  • tests_generate : tests de génération
  • pipelines_torch : tests de pipeline
  • tests_training_ci : tests de la boucle d'entraînement
  • tests_tensor_parallel_ci : tests de parallélisme de tenseurs
  • tests_fsdp_ci : tests FSDP

Tests lents

Les exécutions CI régulières ignorent les tests décorés avec @slow. Ils téléchargent de vrais points de contrôle ou nécessitent des calculs importants, ils sont donc exécutés sur des instances GPU et les mainteneurs les déclenchent une fois votre PR en cours d'examen.

Les tests lents s’exécutent sur une NVIDIA A10, et les résultats numériques peuvent varier légèrement entre le matériel de CI et votre machine locale. Les mainteneurs ajustent généralement ces valeurs dans les tests si nécessaire lors de l’ajout d’un nouveau modèle.

Exécutez les tests lents localement à l'aide de la commande ci-dessous.

RUN_SLOW=1 python -m pytest tests/models/my_model/ -v

Compilation de la documentation

Un travail build_pr_documentation compile et génère un aperçu de la documentation. Un bot publie un lien d'aperçu dans votre PR, et le contrôle doit réussir avant la fusion. La plupart des échecs sont dus à une entrée manquante dans le toctree. Pour compiler la documentation localement, consultez le README.md dans le dossier docs.

# Copié depuis syntax

Pour les nouveaux modèles, privilégiez toujours le flux de travail modulaire (modular_*.py) par rapport à # Copied from. Évitez # Copied from autant que possible.

Le mécanisme # Copied from maintient le code copié synchronisé avec sa source. Lorsque make fix-repo est exécuté, il vérifie chaque bloc # Copied from et le met à jour pour qu’il corresponde à l’original, de sorte que toute modification apportée à l’intérieur d’un bloc # Copied from est écrasée. Modifiez plutôt la source et laissez make fix-repo propager le changement.

Les formes de base de # Copied from sont les suivantes.

# Copied from transformers.models.bert.modeling_bert.BertSelfOutput

# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert->Roberta

# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert->MobileBert all-casing

La syntaxe with model->newModel applique des substitutions de chaînes après la copie. Séparez plusieurs substitutions par des virgules ; elles sont appliquées de gauche à droite. L’option all-casing remplace toutes les variantes de casse d’un coup (Bert, bert, BERT deviennent MobileBert, mobilebert, MOBILEBERT).

Update on GitHub