Transformers documentation
Génération automatique de docstrings
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_docstringSi 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 :
| argument | description |
|---|---|
custom_intro | Une 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_args | Texte 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. |
checkpoint | Identifiant 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 methodsPassez 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] = NoneClasses 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.pydé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’argumentlabels, 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 deConfigArgs. Les arguments de processeur standard (image_processor,tokenizer,do_resize,return_tensors, etc.) proviennent deProcessorArgsetImageProcessorArgs. 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 TypedDictXxxImageProcessorKwargspour 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
typeentre 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 estNone. - Passez le même bloc dans
custom_argslorsque les mêmes arguments se répètent dans plusieurs méthodes (voir l'exemple de fonctions ci-dessus).
- Incluez
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 dansauto_docstring.py.
- Vérifie que
@auto_docstringest 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_allListe de contrôle de référence rapide
| Faire | Ne |
|---|---|
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.
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_argumentset les noms préfixés par_. Certains paramètres privés sont renommés en leurs équivalents publics (_out_features→out_featurespour les modèles backbone).Les descriptions d’arguments courantes proviennent de
auto_docstring.py:ModelArgs(entrées du modèle),ModelOutputArgs(champs de sortie tels quehidden_states),ImageProcessorArgs(prétraitement des images),ProcessorArgs(composants du processeur multimodal) etConfigArgs(hyperparamètres de configuration).La description de chaque paramètre suit cette chaîne de priorité :
- Une docstring manuelle (bloc
r""" """oucustom_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.
- Une docstring manuelle (bloc
Pour les classes de modèles aux noms standards comme
ModelForCausalLM, ou les classes qui correspondent à un pipeline,@auto_docstringgé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éfinissezcustom_intro.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.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
checkpointremplace le checkpoint déduit de la docstring de la classe de configuration. Définissezcheckpointsur 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_MODELSdansauto_docstring.py.Pour des méthodes comme
forward, le décorateur rédige la sectionReturnsà partir du type de retour de la méthode. Lorsque le type de retour est un sous-classe de ModelOutput,@auto_docstringextrait les descriptions des champs depuis la docstring de cette classe. Un blocReturnspersonnalisé dans la docstring de la fonction prend le pas.Pour les méthodes de
UNROLL_KWARGS_METHODSet les classes deUNROLL_KWARGS_CLASSES, le décorateur développe**kwargstypé avecUnpack[KwargsTypedDict]. Chaque clé duTypedDictdevient un paramètre documenté.La même expansion s’applique aux méthodes
__call__etpreprocessdes 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.