Generación automática de docstrings

El decorador @auto_docstring genera docstrings coherentes para clases y métodos de modelos. Incorpora automáticamente las descripciones estándar de los argumentos, por lo que solo debes escribir documentación para argumentos nuevos o personalizados. Al agregar un nuevo modelo, omite el código repetitivo y concéntrate en lo que es nuevo.

@auto_docstring

Importa el decorador en tu archivo modular_model.py (o modeling_model.py para modelos más antiguos).

from ...utils import auto_docstring

Si tu modelo hereda de un modelo de otra biblioteca en un archivo modular, @auto_docstring ya se aplica en el padre. make fix-repo lo copia por ti en el archivo generado modeling_model.py. Aplica el decorador de forma explícita solo para personalizar su comportamiento (modelos independientes, intros personalizados o argumentos sobrescritos).

Al sobrescribir cualquier decorador en un archivo modular, incluye todos los decoradores de la función o clase padre. Si solo sobrescribes algunos, el resto no aparecerá en el archivo de modelado generado.

El decorador acepta los siguientes argumentos opcionales:

Uso

El funcionamiento de @auto_docstring depende de lo que se esté decorando. Las clases de modelo obtienen la documentación de los parámetros de __init__, las clases de configuración la obtienen de las anotaciones a nivel de clase, las clases de procesador generan automáticamente intros a partir de sus componentes, y los métodos como forward reciben tipos de retorno y ejemplos de uso.

Clases de modelos

Coloca @auto_docstring directamente sobre la definición de la clase. El decorador deriva las descripciones de los parámetros de la firma y la docstring del método __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

Pasa custom_intro y custom_args para tener más control. Los argumentos personalizados pueden ir en custom_args o en la docstring de __init__. Usa custom_args cuando los mismos argumentos se repiten en varios métodos.

@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):
        # ...

También aplica @auto_docstring a las clases que heredan 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

Clases de configuración

Coloca @auto_docstring directamente sobre una subclase de PreTrainedConfig, junto al decorador @strict. @strict añade validación de tipos en tiempo de ejecución y convierte la clase en un dataclass validado. Los parámetros de la configuración son anotaciones a nivel de clase (no argumentos de __init__), y @auto_docstring los lee del cuerpo de la clase para generar la documentación.

ConfigArgs proporciona parámetros estándar como vocab_size, hidden_size y num_hidden_layers, por lo que no requieren una descripción a menos que el comportamiento difiera. Los parámetros base de PreTrainedConfig se excluyen automáticamente. El argumento checkpoint genera el ejemplo de uso.

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"

Clases de procesador

Los procesadores multimodales (subclases de ProcessorMixin, processing_*.py) siempre usan el @auto_docstring simple. La introducción de la clase se genera automáticamente. Documenta solo los parámetros de __init__ que no estén ya cubiertos por ProcessorArgs (image_processor, tokenizer, chat_template, y otros).

Si todos los parámetros son estándar, omita la docstring. Decore también __call__ con @auto_docstring. La docstring de su cuerpo contiene solo una sección Returns: más cualquier argumento de llamada específico del modelo. return_tensors se agrega automáticamente.

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.
        """
        # ...

Procesadores de imágenes y videos

Los procesadores de imágenes y videos (subclases de BaseImageProcessor, image_processing_*.py) siguen uno de dos patrones.

Si el procesador tiene parámetros específicos del modelo, defina un TypedDict XxxImageProcessorKwargs(ImagesKwargs, total=False) con una docstring para esos parámetros, establezca valid_kwargs en la clase y use @auto_docstring sin argumentos. El __init__ no tiene 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 clase solo establece atributos de nivel de clase estándar (size, resample, image_mean, etc.) sin kwargs personalizados, use @auto_docstring(custom_intro="Constructs a MyModel image processor.") en su lugar.

@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}

Al sobrescribir preprocess, decóralo con @auto_docstring y documenta solo los argumentos que no estén en ImageProcessorArgs. Los argumentos estándar y return_tensors se incluyen automáticamente.

Funciones

Coloca @auto_docstring directamente sobre la definición de la función. El decorador deriva las descripciones de los parámetros de la firma de la función.

El decorador genera el texto del valor de retorno a partir de la docstring de la clase 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.
        """
        # ...

Pasa custom_intro y custom_args para tener más control. Usa custom_args para definir la documentación de argumentos compartidos una sola vez cuando los mismos parámetros aparecen en varios métodos.

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"""
        # ...

Escribe las secciones Returns y Examples manualmente en el docstring para reemplazar las versiones generadas automáticamente.

    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)
        ```
        """
        # ...

Documentar argumentos

Siga estas reglas al documentar diferentes tipos de argumentos.

• auto_docstring.py define los argumentos estándar (input_ids, attention_mask, pixel_values, etc.) y los incluye automáticamente. No los redefinas localmente a menos que el argumento se comporte de manera diferente en tu modelo.

  Si un argumento estándar se comporta de manera diferente en tu modelo, sobrescríbelo localmente en un bloque r""" """. La definición local tiene prioridad. El argumento labels, por ejemplo, se personaliza comúnmente por modelo y a menudo requiere una sobrescritura.

• Los argumentos de configuración estándar (vocab_size, hidden_size, num_hidden_layers, etc.) siguen el mismo principio, pero provienen de ConfigArgs. Los argumentos de procesador estándar (image_processor, tokenizer, do_resize, return_tensors, etc.) provienen de ProcessorArgs y ImageProcessorArgs. Documenta un parámetro solo si es específico del modelo o se comporta de manera diferente a la descripción estándar.

• Documenta los argumentos nuevos o personalizados en un bloque r""" """. Colócalos después de la firma en el caso de las funciones, en la docstring de __init__ para las clases de modelos o procesadores, en la docstring del cuerpo de la clase para las clases de configuración, o en el cuerpo del TypedDict XxxImageProcessorKwargs para los procesadores de imágenes.

  Copiado

  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.

  • Incluye type entre comillas angulares.
  • Añada opcional si el argumento no es obligatorio o tiene un valor predeterminado.
  • Añada “por defecto es X” si tiene un valor por defecto. No es necesario añadir “por defecto es None” si el valor por defecto es None.
  • Pasa el mismo bloque a custom_args cuando los mismos argumentos se repiten en varios métodos (consulta el ejemplo de funciones anterior).

• El decorador extrae los tipos de las firmas de funciones automáticamente. Si un parámetro tiene una anotación de tipo, no es necesario repetir el tipo en la cadena de formato de la docstring. Cuando ambos están presentes, el tipo de la firma tiene prioridad. El tipo de la docstring actúa como alternativa para los parámetros sin anotar.

Revisando las docstrings

Un script de utilidades valida las docstrings cuando abres una pull request. CI ejecuta el script y verifica lo siguiente.

Si ves un [ERROR] en la salida, añade la descripción del parámetro al docstring o a la clase Args correspondiente en auto_docstring.py.

• Comprueba que @auto_docstring se aplica a las clases de modelos y métodos públicos relevantes.
• Valida la completitud y la coherencia de los argumentos: los argumentos documentados deben existir en la firma, y los tipos y los valores predeterminados deben coincidir. Se marcan los argumentos desconocidos que no tienen una descripción local.
• Detecta marcadores incompletos como <fill_type> y <fill_docstring>.
• Verifica que las docstrings sigan el estilo de formato esperado.

Ejecuta la comprobación localmente antes de confirmar los cambios.

make fix-repo

make fix-repo también ejecuta varias otras comprobaciones. Para ejecutar solo las comprobaciones de docstring y auto-docstring, usa el siguiente comando.

# 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

Lista de verificación de referencia rápida

Cómo funciona

El decorador @auto_docstring genera docstrings mediante los siguientes pasos.

1. El decorador inspecciona la firma para leer los argumentos, tipos y valores predeterminados desde el __init__ de la clase decorada o desde la función decorada. Para las clases de configuración, recorre las anotaciones a nivel de clase a lo largo de la cadena de herencia y se detiene antes de PreTrainedConfig, excluyendo los campos de la clase base.

   Filtra automáticamente parámetros como self, kwargs, args, deprecated_arguments y nombres con prefijo _. Algunos parámetros privados se renombran a sus equivalentes públicos (_out_features → out_features para modelos backbone).

2. Las descripciones de argumentos comunes provienen de auto_docstring.py: ModelArgs (entradas del modelo), ModelOutputArgs (campos de salida como hidden_states), ImageProcessorArgs (preprocesamiento de imágenes), ProcessorArgs (componentes del procesador multimodal) y ConfigArgs (hiperparámetros de configuración).

3. La descripción de cada parámetro sigue esta cadena de prioridad:

   • Una docstring manual (bloque r""" """ o custom_args) tiene prioridad.
   • El diccionario de origen predefinido (ModelArgs, ModelForArgs, ConfigArgs, ImageProcessorArgs, ProcessorArgs, ModelOutputArgs) es el valor predeterminado.
   • Si ninguna de las fuentes tiene una descripción, el parámetro se marca con [ERROR] en la salida de compilación.

4. Para las clases de modelos con nombres estándar como ModelForCausalLM, o las clases que se mapean a un pipeline, @auto_docstring genera la introducción. Para los procesadores multimodales, la introducción enumera qué componentes (tokenizador, procesador de imágenes, etc.) encapsula la clase. Consulte ClassDocstring para obtener la lista completa.

   Si el nombre de la clase no está en ClassDocstring, establece custom_intro.

5. Las docstrings predefinidas pueden hacer referencia a valores dinámicos de los auto_modules de Transformers, como {processor_class}, {image_processor_class} y {config_class}. Los marcadores de posición se resuelven automáticamente.

6. El decorador selecciona ejemplos de uso en función de la tarea o la compatibilidad con el pipeline del modelo. Lee los metadatos del checkpoint de la clase de configuración para que los ejemplos utilicen IDs de modelo reales. El argumento checkpoint reemplaza el checkpoint inferido desde la docstring de la clase de configuración. Establece checkpoint en las clases de configuración, o cuando la inferencia del checkpoint falla. Si ves un error como "Config not found for <model_name>", añade una entrada a HARDCODED_CONFIG_FOR_MODELS en auto_docstring.py.

7. Para métodos como forward, el decorador escribe la sección Returns a partir del tipo de retorno del método. Cuando el tipo de retorno es una subclase de ModelOutput, @auto_docstring extrae las descripciones de los campos de la docstring de esa clase. Un bloque Returns personalizado en la docstring de la función tiene prioridad.

8. Para los métodos en UNROLL_KWARGS_METHODS y las clases en UNROLL_KWARGS_CLASSES, el decorador expande **kwargs tipado con Unpack[KwargsTypedDict]. Cada clave del TypedDict se convierte en un parámetro documentado.

   La misma expansión se aplica a los métodos __call__ y preprocess en las subclases de BaseImageProcessor y ProcessorMixin. Se omiten los tipos base genéricos (TextKwargs, ImagesKwargs, VideosKwargs, AudioKwargs). Solo se despliegan las subclases específicas de cada modelo.