Transformers documentation

Génération automatique de docstrings

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Génération automatique de docstrings

Le décorateur @auto_docstring génère des docstrings cohérentes pour les classes et méthodes de modèles. Il intègre automatiquement les descriptions standard des arguments, de sorte que vous n’avez à documenter que les arguments nouveaux ou personnalisés. Lors de l’ajout d’un nouveau modèle, évitez les éléments de boilerplate et concentrez-vous sur ce qui est nouveau.

@auto_docstring

Importez le décorateur dans votre fichier modular_model.py (ou modeling_model.py pour les modèles plus anciens).

from ...utils import auto_docstring

Si votre modèle hérite d’un modèle d’une autre bibliothèque dans un fichier modulaire, @auto_docstring est déjà appliqué dans la classe parente. make fix-repo le copie pour vous dans le fichier généré modeling_model.py. N’appliquez le décorateur explicitement que pour personnaliser son comportement (modèles autonomes, intros personnalisés ou arguments surchargés).

Lorsque vous écrasez un décorateur dans un fichier modulaire, incluez tous les décorateurs de la fonction ou de la classe parente. Si vous n'en écrasez qu'une partie, les autres n'apparaîtront pas dans le fichier de modélisation généré.

Le décorateur accepte les arguments facultatifs suivants :

argumentdescription
custom_introUne description de la classe ou de la méthode, insérée avant la section Args. Obligatoire pour les classes qui ne se terminent pas par un suffixe reconnu comme ForCausalLM ou ForTokenClassification.
custom_argsTexte de la docstring pour des paramètres spécifiques. Utile lorsque les mêmes arguments personnalisés apparaissent à plusieurs endroits dans le fichier de modélisation.
checkpointIdentifiant de point de contrôle de modèle ("org/my-model") utilisé pour générer des exemples d'utilisation. Remplace le point de contrôle inféré automatiquement à partir de la classe de configuration. Défini généralement sur les classes de configuration.

Utilisation

Le fonctionnement de @auto_docstring dépend de l'élément décoré. Les classes de modèle récupèrent la documentation des paramètres depuis __init__, les classes de configuration depuis les annotations au niveau de la classe, les classes de processeur génèrent automatiquement des descriptions à partir de leurs composants, et les méthodes comme forward obtiennent les types de retour et des exemples d'utilisation.

Classes de modèles

Placez @auto_docstring directement au-dessus de la définition de la classe. Le décorateur dérive les descriptions des paramètres de la signature et de la docstring de la méthode __init__.

from transformers.modeling_utils import PreTrainedModel
from ...utils import auto_docstring

@auto_docstring
class MyAwesomeModel(PreTrainedModel):
    def __init__(self, config, custom_parameter: int = 10, another_custom_arg: str = "default"):
        r"""
        custom_parameter (`int`, *optional*, defaults to 10):
            Description of the custom_parameter for MyAwesomeModel.
        another_custom_arg (`str`, *optional*, defaults to "default"):
            Documentation for another unique argument.
        """
        super().__init__(config)
        self.custom_parameter = custom_parameter
        self.another_custom_arg = another_custom_arg
        # ... rest of your init

    # ... other methods

Passez custom_intro et custom_args pour un contrôle plus fin. Les arguments personnalisés peuvent être placés dans custom_args ou dans la docstring de __init__. Utilisez custom_args lorsque les mêmes arguments se répètent dans plusieurs méthodes.

@auto_docstring(
    custom_intro="""This model performs specific synergistic operations.
    It builds upon the standard Transformer architecture with unique modifications.""",
    custom_args="""
    custom_parameter (`type`, *optional*, defaults to `default_value`):
        A concise description for custom_parameter if not defined or overriding the description in `auto_docstring.py`.
    internal_helper_arg (`type`, *optional*, defaults to `default_value`):
        A concise description for internal_helper_arg if not defined or overriding the description in `auto_docstring.py`.
    """
)
class MySpecialModel(PreTrainedModel):
    def __init__(self, config: ConfigType, custom_parameter: "type" = "default_value", internal_helper_arg=None):
        # ...

Appliquez également @auto_docstring aux classes qui héritent de ModelOutput.

@auto_docstring(
    custom_intro="""
    Custom model outputs with additional fields.
    """
)
@dataclass
class MyModelOutput(ImageClassifierOutput):
    r"""
    loss (`torch.Tensor`, *optional*):
        The loss of the model.
    custom_field (`torch.Tensor` of shape `(batch_size, hidden_size)`, *optional*):
        A custom output field specific to this model.
    """

    # Standard fields (hidden_states, logits, attentions, etc.) are documented automatically when
    # the description matches the standard text. Loss typically varies per model, so document it above.
    loss: Optional[torch.Tensor] = None
    logits: Optional[torch.Tensor] = None
    hidden_states: Optional[tuple[torch.Tensor, ...]] = None
    attentions: Optional[tuple[torch.Tensor, ...]] = None
    # Custom fields need to be documented in the docstring above
    custom_field: Optional[torch.Tensor] = None

Classes de configuration

Placez @auto_docstring directement au-dessus d'une sous-classe de PreTrainedConfig, aux côtés du décorateur @strict. @strict ajoute une validation de types à l'exécution et transforme la classe en dataclass validée. Les paramètres de configuration sont des annotations au niveau de la classe (et non des arguments de __init__), et @auto_docstring les lit depuis le corps de la classe pour générer la documentation.

ConfigArgs fournit des paramètres standard tels que vocab_size, hidden_size et num_hidden_layers, de sorte qu’ils n’ont pas besoin d’être décrits sauf si leur comportement diffère. Les paramètres de base de PreTrainedConfig sont exclus automatiquement. L’argument checkpoint génère l’exemple d’utilisation.

from huggingface_hub.dataclasses import strict
from ...configuration_utils import PreTrainedConfig
from ...utils import auto_docstring

@strict
@auto_docstring(checkpoint="org/my-model-checkpoint")
class MyModelConfig(PreTrainedConfig):
    r"""
    custom_param (`int`, *optional*, defaults to 64):
        Description of a parameter specific to this model.
    another_param (`str`, *optional*, defaults to `"gelu"`):
        Description of another model-specific parameter.

    ```python
    from transformers import MyModelConfig, MyModel

    configuration = MyModelConfig()
    model = MyModel(configuration)
    configuration = model.config
    ```
    """

    model_type = "my_model"

    # Standard params (vocab_size, hidden_size, etc.) are auto-documented from ConfigArgs.
    vocab_size: int = 32000
    hidden_size: int = 768
    num_hidden_layers: int = 12
    # Model-specific params must be documented in the class docstring above.
    custom_param: int = 64
    another_param: str = "gelu"

Classes de processeur

Les processeurs multimodaux (sous-classes de ProcessorMixin, processing_*.py) utilisent toujours le simple @auto_docstring. L'introduction de la classe est générée automatiquement. Documentez uniquement les paramètres de __init__ non déjà couverts par ProcessorArgs (image_processor, tokenizer, chat_template, et autres).

Si tous les paramètres sont standards, omettez la docstring. Décorez également __call__ avec @auto_docstring. La docstring de son corps ne contient qu'une section Returns: ainsi que les arguments d'appel spécifiques au modèle. return_tensors est ajouté automatiquement.

from ...processing_utils import ProcessorMixin, ProcessingKwargs, Unpack
from ...utils import auto_docstring

class MyModelProcessorKwargs(ProcessingKwargs, total=False):
    """
    custom_call_kwarg (`bool`, *optional*, defaults to `False`):
        A parameter with a default that can passed to __call__ which is not
        covered by the standard processor arguments (including each modality).
    """
    custom_call_kwarg: bool

@auto_docstring
class MyModelProcessor(ProcessorMixin):
    valid_processor_kwargs = MyModelProcessorKwargs
    custom_call_kwarg = False

    def __init__(self, image_processor=None, tokenizer=None, custom_param: int = 4, **kwargs):
        r"""
        custom_param (`int`, *optional*, defaults to 4):
            A parameter specific to this processor not covered by the standard ProcessorArgs.
        """
        super().__init__(image_processor, tokenizer)
        self.custom_param = custom_param

    @auto_docstring
    def __call__(self, images=None, text=None, **kwargs: Unpack[MyModelProcessorKwargs]):
        r"""
        Returns:
            [BatchFeature](/docs/transformers/v5.23.0/en/main_classes/feature_extractor#transformers.BatchFeature): A [BatchFeature](/docs/transformers/v5.23.0/en/main_classes/feature_extractor#transformers.BatchFeature) with the following fields:

            - **input_ids** -- Token ids to be fed to the model.
            - **pixel_values** -- Pixel values to be fed to the model.
        """
        # ...

Processeurs d'images et de vidéos

Les processeurs d’images et de vidéos (sous-classes de BaseImageProcessor, image_processing_*.py) suivent l’un des deux modèles suivants.

Si le processeur possède des paramètres spécifiques au modèle, définissez un TypedDict XxxImageProcessorKwargs(ImagesKwargs, total=False) avec une docstring pour ces paramètres, définissez valid_kwargs sur la classe et utilisez @auto_docstring tel quel. Le __init__ n'a pas de docstring.

class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    r"""
    custom_threshold (`float`, *optional*, defaults to `self.custom_threshold`):
        A parameter specific to this image processor.
    """
    custom_threshold: float | None

@auto_docstring
class MyModelImageProcessor(TorchvisionBackend):
    valid_kwargs = MyModelImageProcessorKwargs
    custom_threshold: float = 0.5

    def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
        super().__init__(**kwargs)

Si la classe ne définit que des attributs de classe standard (size, resample, image_mean, etc.) sans kwargs personnalisés, utilisez @auto_docstring(custom_intro="Constructs a MyModel image processor.") à la place.

@auto_docstring(custom_intro="Constructs a MyModel image processor.")
class MyModelImageProcessor(TorchvisionBackend):
    resample = PILImageResampling.BICUBIC
    image_mean = IMAGENET_STANDARD_MEAN
    image_std = IMAGENET_STANDARD_STD
    size = {"height": 224, "width": 224}

Lors de la surcharge de preprocess, décorez-le avec @auto_docstring et documentez uniquement les arguments non présents dans ImageProcessorArgs. Les arguments standard et return_tensors sont inclus automatiquement.

Fonctions

Placez @auto_docstring directement au-dessus de la définition de la fonction. Le décorateur dérive les descriptions des paramètres de la signature de la fonction.

Le décorateur génère le texte de la valeur de retour à partir de la docstring de la classe ModelOutput.

class MyModel(PreTrainedModel):
    # ...
    @auto_docstring
    def forward(
        self,
        input_ids: Optional[torch.Tensor] = None,
        attention_mask: Optional[torch.Tensor] = None,
        new_custom_argument: Optional[torch.Tensor] = None,
        # ... other arguments
    ) -> Union[Tuple, ModelOutput]:
        r"""
        new_custom_argument (`torch.Tensor`, *optional*):
            Description of this new custom argument and its expected shape or type.
        """
        # ...

Passez custom_intro et custom_args pour un contrôle plus fin. Utilisez custom_args pour définir une fois la documentation des arguments partagés lorsque les mêmes paramètres apparaissent dans plusieurs méthodes.

MODEL_COMMON_CUSTOM_ARGS = r"""
    common_arg_1 (`torch.Tensor`, *optional*, defaults to `default_value`):
        Description of common_arg_1
    common_arg_2 (`torch.Tensor`, *optional*, defaults to `default_value`):
        Description of common_arg_2
"""

class MyModel(PreTrainedModel):
    # ...
    @auto_docstring(
        custom_intro="""This is a custom introduction for the function.""",
        custom_args=MODEL_COMMON_CUSTOM_ARGS
    )
    def forward(self, input_ids=None, common_arg_1=None, common_arg_2=None) -> ModelOutput:
        r"""method-specific args go here"""
        # ...

Écrivez manuellement les sections Returns et Examples dans la docstring pour remplacer les versions générées automatiquement.

    def forward(self, input_ids=None) -> torch.Tensor:
        r"""
        Returns:
            `torch.Tensor`: A custom Returns section for non-ModelOutput return types.

        Example:

        ```python
        model = MyModel.from_pretrained("org/my-model")
        output = model(input_ids)
        ```
        """
        # ...

Documenter les arguments

Suivez ces règles lors de la documentation des différents types d’arguments.

  • auto_docstring.py définit les arguments standard (input_ids, attention_mask, pixel_values, etc.) et les inclut automatiquement. Ne les redéfinissez pas localement, sauf si l’argument se comporte différemment dans votre modèle.

    Si un argument standard se comporte différemment dans votre modèle, définissez-le localement dans un bloc r""" """. La définition locale a la priorité. L’argument labels, par exemple, est souvent personnalisé pour chaque modèle et nécessite fréquemment une surcharge.

  • Les arguments de configuration standard (vocab_size, hidden_size, num_hidden_layers, etc.) suivent le même principe mais proviennent de ConfigArgs. Les arguments de processeur standard (image_processor, tokenizer, do_resize, return_tensors, etc.) proviennent de ProcessorArgs et ImageProcessorArgs. Ne documentez un paramètre que s'il est spécifique au modèle ou s'il se comporte différemment de la description standard.

  • Documentez les nouveaux arguments ou les arguments personnalisés dans un bloc r""" """. Placez-les après la signature pour les fonctions, dans la docstring de __init__ pour les classes de modèles ou de processeurs, dans la docstring du corps de la classe pour les classes de configuration, ou dans le corps du TypedDict XxxImageProcessorKwargs pour les processeurs d'images.

    argument_name (`type`, *optional*, defaults to `X`):
        Description of the argument.
        Explain its purpose, expected shape/type if complex, and default behavior.
        This can span multiple lines.
    • Incluez type entre guillemets.
    • Ajoutez facultatif si l'argument n'est pas requis ou s'il possède une valeur par défaut.
    • Ajoutez « par défaut X » s’il existe une valeur par défaut. Il n’est pas nécessaire d’ajouter « par défaut None » si la valeur par défaut est None.
    • Passez le même bloc dans custom_args lorsque les mêmes arguments se répètent dans plusieurs méthodes (voir l'exemple de fonctions ci-dessus).
  • Le décorateur extrait automatiquement les types à partir des signatures de fonctions. Si un paramètre possède une annotation de type, il n’est pas nécessaire de répéter le type dans la chaîne de formatage de la docstring. Lorsque les deux sont présents, le type de la signature prévaut. Le type de la docstring sert de repli pour les paramètres non annotés.

Vérification des docstrings

Un script utilitaire valide les docstrings lorsque vous ouvrez une pull request. La CI exécute le script et vérifie les éléments suivants.

Si vous voyez un [ERROR] dans la sortie, ajoutez la description du paramètre à la docstring ou à la classe Args appropriée dans auto_docstring.py.

  • Vérifie que @auto_docstring est appliqué aux classes de modèles et méthodes publiques concernées.
  • Valide l’exhaustivité et la cohérence des arguments : les arguments documentés doivent exister dans la signature, et les types et valeurs par défaut doivent correspondre. Les arguments inconnus sans description locale sont signalés.
  • Détecte les espaces réservés incomplets tels que <fill_type> et <fill_docstring>.
  • Vérifie que les docstrings respectent le style de formatage attendu.

Exécutez la vérification localement avant de valider.

make fix-repo

make fix-repo exécute également plusieurs autres vérifications. Pour n’exécuter que les vérifications de docstring et de docstring automatique, utilisez la commande ci-dessous.

# to only check files included in the diff without fixing them
python utils/check_docstrings.py
# to fix and overwrite the files in the diff
# python utils/check_docstrings.py --fix_and_overwrite
# to fix and overwrite all files
# python utils/check_docstrings.py --fix_and_overwrite --check_all

Liste de contrôle de référence rapide

FaireNe
Appliquez @auto_docstring aux classes de modèle, de configuration et de processeur ainsi qu'à leurs méthodes principales (forward, __call__, preprocess).Ajoutez @auto_docstring aux modèles hérités dans les fichiers modulaires, car il est repris automatiquement.
Documentez uniquement les nouveaux arguments ou les arguments spécifiques au modèle.Redefinir les arguments standard (input_ids, attention_mask, vocab_size, etc.) qui se comportent de la même manière que leurs descriptions par défaut.
Placez les paramètres de configuration dans la docstring du corps de la classe en tant qu'annotations de niveau classe.Placez les paramètres de configuration dans __init__.
Placez les paramètres du processeur d’images dans un TypedDict XxxImageProcessorKwargs.Placez les paramètres du processeur d'images dans __init__.
Exécutez python utils/check_docstrings.py --fix_and_overwrite avant de committer.Ignorez la sortie [ERROR] car elle signifie qu'un paramètre n'est pas documenté.

Fonctionnement

Le décorateur @auto_docstring génère des docstrings selon les étapes suivantes.

  1. Le décorateur inspecte la signature pour lire les arguments, les types et les valeurs par défaut depuis le __init__ de la classe décorée ou depuis la fonction décorée. Pour les classes de configuration, il parcourt les annotations au niveau de la classe le long de la chaîne d'héritage et s'arrête avant PreTrainedConfig, excluant ainsi les champs des classes de base.

    Il filtre automatiquement des paramètres tels que self, kwargs, args, deprecated_arguments et les noms préfixés par _. Certains paramètres privés sont renommés en leurs équivalents publics (_out_features → out_features pour les modèles backbone).

  2. Les descriptions d’arguments courantes proviennent de auto_docstring.py : ModelArgs (entrées du modèle), ModelOutputArgs (champs de sortie tels que hidden_states), ImageProcessorArgs (prétraitement des images), ProcessorArgs (composants du processeur multimodal) et ConfigArgs (hyperparamètres de configuration).

  3. La description de chaque paramètre suit cette chaîne de priorité :

    • Une docstring manuelle (bloc r""" """ ou custom_args) a la priorité.
    • Le dictionnaire source prédéfini (ModelArgs, ModelForArgs, ConfigArgs, ImageProcessorArgs, ProcessorArgs, ModelOutputArgs) sert de repli.
    • Si aucune des sources ne contient de description, le paramètre est signalé avec [ERROR] dans la sortie de compilation.
  4. Pour les classes de modèles aux noms standards comme ModelForCausalLM, ou les classes qui correspondent à un pipeline, @auto_docstring génère l’introduction. Pour les processeurs multimodaux, l’introduction énumère les composants (tokenizer, image processor, etc.) que la classe encapsule. Consultez ClassDocstring pour la liste complète.

    Si le nom de la classe n’est pas dans ClassDocstring, définissez custom_intro.

  5. Les docstrings prédéfinies peuvent référencer des valeurs dynamiques des auto_modules de Transformers, telles que {processor_class}, {image_processor_class} et {config_class}. Les espaces réservés sont résolus automatiquement.

  6. Le décorateur sélectionne des exemples d’utilisation en fonction de la tâche ou de la compatibilité pipeline du modèle. Il lit les métadonnées du checkpoint depuis la classe de configuration afin que les exemples utilisent de vrais identifiants de modèles. L’argument checkpoint remplace le checkpoint déduit de la docstring de la classe de configuration. Définissez checkpoint sur les classes de configuration, ou lorsque la déduction du checkpoint échoue. Si vous voyez une erreur comme "Config not found for <model_name>", ajoutez une entrée à HARDCODED_CONFIG_FOR_MODELS dans auto_docstring.py.

  7. Pour des méthodes comme forward, le décorateur rédige la section Returns à partir du type de retour de la méthode. Lorsque le type de retour est un sous-classe de ModelOutput, @auto_docstring extrait les descriptions des champs depuis la docstring de cette classe. Un bloc Returns personnalisé dans la docstring de la fonction prend le pas.

  8. Pour les méthodes de UNROLL_KWARGS_METHODS et les classes de UNROLL_KWARGS_CLASSES, le décorateur développe **kwargs typé avec Unpack[KwargsTypedDict]. Chaque clé du TypedDict devient un paramètre documenté.

    La même expansion s’applique aux méthodes __call__ et preprocess des sous-classes de BaseImageProcessor et ProcessorMixin. Les types de base génériques (TextKwargs, ImagesKwargs, VideosKwargs, AudioKwargs) sont ignorés. Seules les sous-classes spécifiques à un modèle sont dépliées.

Update on GitHub