Geração automática de docstrings

O decorador @auto_docstring gera docstrings consistentes para classes e métodos de modelos. Ele insere automaticamente as descrições padrão dos argumentos, de modo que você só precisa documentar argumentos novos ou personalizados. Ao adicionar um novo modelo, pule o boilerplate e foque no que é novo.

@auto_docstring

Importe o decorador no seu arquivo modular_model.py (ou modeling_model.py para modelos mais antigos).

from ...utils import auto_docstring

Se o seu modelo herda de um modelo de outra biblioteca em um arquivo modular, @auto_docstring já é aplicado no pai. make fix-repo copia-o para o arquivo modeling_model.py gerado para você. Aplique o decorador explicitamente apenas para personalizar seu comportamento (modelos independentes, intros personalizados ou argumentos sobrescritos).

Ao sobrescrever qualquer decorador em um arquivo modular, inclua todos os decoradores da função ou classe pai. Se você sobrescrever apenas alguns, os demais não aparecerão no arquivo de modelagem gerado.

O decorador aceita os seguintes argumentos opcionais:

Uso

A forma como o @auto_docstring funciona depende do que você está decorando. As classes de modelo obtêm a documentação dos parâmetros de __init__, as classes de configuração obtêm de anotações no nível da classe, as classes de processador geram automaticamente descrições a partir de seus componentes e métodos como forward recebem tipos de retorno e exemplos de uso.

Classes de modelo

Coloque @auto_docstring diretamente acima da definição da classe. O decorador deriva as descrições dos parâmetros a partir da assinatura e da docstring do 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

Passe custom_intro e custom_args para ter mais controle. Os argumentos personalizados podem estar em custom_args ou na docstring de __init__. Use custom_args quando os mesmos argumentos se repetem em vários 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):
        # ...

Aplique também @auto_docstring a classes que herdam 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 configuração

Coloque @auto_docstring diretamente acima de uma subclasse de PreTrainedConfig, junto com o decorador @strict. @strict adiciona validação de tipos em tempo de execução e converte a classe em um dataclass validado. Os parâmetros de configuração são anotações de nível de classe (não argumentos de __init__), e @auto_docstring os lê do corpo da classe para gerar a documentação.

ConfigArgs fornece parâmetros padrão como vocab_size, hidden_size e num_hidden_layers, de modo que não é necessário descrevê-los, a menos que o comportamento seja diferente. Os parâmetros base de PreTrainedConfig são excluídos automaticamente. O argumento checkpoint gera o exemplo 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"

Classes de processador

Processadores multimodais (subclasses de ProcessorMixin, processing_*.py) sempre usam o @auto_docstring simples. A introdução da classe é gerada automaticamente. Documente apenas os parâmetros de __init__ que ainda não estão cobertos por ProcessorArgs (image_processor, tokenizer, chat_template, e outros).

Se todos os parâmetros forem padrão, omita a docstring. Decore __call__ também com @auto_docstring. A docstring do corpo contém apenas uma seção Returns: e quaisquer argumentos de chamada específicos do modelo. return_tensors é adicionado automaticamente.

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

class MyModelProcessorKwargs(ProcessingKwargs, total=False):
    _defaults = {"text_kwargs": {"padding": False}}

@auto_docstring
class MyModelProcessor(ProcessorMixin):
    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/main/en/main_classes/feature_extractor#transformers.BatchFeature): A [BatchFeature](/docs/transformers/main/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.
        """
        # ...

Processadores de imagem e vídeo

Processadores de imagem e vídeo (subclasses de BaseImageProcessor, image_processing_*.py) seguem um de dois padrões.

Se o processador tiver parâmetros específicos do modelo, defina um TypedDict XxxImageProcessorKwargs(ImagesKwargs, total=False) com uma docstring para esses parâmetros, defina valid_kwargs na classe e use o @auto_docstring sem argumentos. O __init__ não possui 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)

Se a classe apenas define atributos de nível de classe padrão (size, resample, image_mean, etc.) sem kwargs personalizados, use @auto_docstring(custom_intro="Constructs a MyModel image processor.") no 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}

Ao sobrescrever preprocess, decore-o com @auto_docstring e documente apenas os argumentos que não estão em ImageProcessorArgs. Os argumentos padrão e return_tensors são incluídos automaticamente.

Funções

Coloque @auto_docstring diretamente acima da definição da função. O decorador deriva as descrições dos parâmetros a partir da assinatura da função.

O decorador gera o texto do valor de retorno a partir da docstring da 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.
        """
        # ...

Passe custom_intro e custom_args para ter mais controle. Use custom_args para definir a documentação de argumentos compartilhados uma única vez quando os mesmos parâmetros aparecem em vários 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"""
        # ...

Escreva as seções Returns e Examples manualmente no docstring para substituir as versões geradas automaticamente.

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

Documentando argumentos

Siga estas regras ao documentar diferentes tipos de argumento.

• auto_docstring.py define argumentos padrão (input_ids, attention_mask, pixel_values, etc.) e os inclui automaticamente. Não os redefina localmente, a menos que o argumento se comporte de forma diferente no seu modelo.

  Se um argumento padrão se comporta de forma diferente no seu modelo, sobrescreva-o localmente em um bloco r""" """. A definição local tem prioridade. O argumento labels, por exemplo, é comumente personalizado por modelo e frequentemente precisa de uma sobrescrita.

• Os argumentos de configuração padrão (vocab_size, hidden_size, num_hidden_layers, etc.) seguem o mesmo princípio, mas vêm de ConfigArgs. Os argumentos de processador padrão (image_processor, tokenizer, do_resize, return_tensors, etc.) vêm de ProcessorArgs e ImageProcessorArgs. Documente um parâmetro apenas se ele for específico do modelo ou se comportar de forma diferente da descrição padrão.

• Documente novos ou argumentos personalizados em um bloco r""" """. Coloque-os após a assinatura, no caso de funções, na docstring de __init__ para classes de modelo ou processador, na docstring do corpo da classe para classes de configuração, ou no corpo do TypedDict XxxImageProcessorKwargs para processadores de imagem.

  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.

  • Inclua type entre crases.
  • Adicione opcional se o argumento não for obrigatório ou se tiver um valor padrão.
  • Adicione “padrão é X” se houver um valor padrão. Não é necessário adicionar “padrão é None” se o valor padrão for None.
  • Passe o mesmo bloco para custom_args quando os mesmos argumentos se repetirem em vários métodos (veja o exemplo de funções acima).

• O decorador extrai os tipos automaticamente das assinaturas de funções. Se um parâmetro possui uma anotação de tipo, não é necessário repetir o tipo na string de formato da docstring. Quando ambos estão presentes, o tipo da assinatura tem precedência. O tipo da docstring atua como um recurso para parâmetros sem anotação.

Verificando as docstrings

Um script de utilitário valida as docstrings quando você abre um pull request. O CI executa o script e verifica o seguinte.

Se você vir um [ERROR] na saída, adicione a descrição do parâmetro ao docstring ou à classe Args apropriada em auto_docstring.py.

• Verifica se @auto_docstring é aplicado às classes de modelo e aos métodos públicos relevantes.
• Valida a completude e a consistência dos argumentos: os argumentos documentados devem existir na assinatura, e os tipos e valores padrão devem corresponder. Argumentos desconhecidos sem uma descrição local são sinalizados.
• Sinaliza placeholders incompletos, como <fill_type> e <fill_docstring>.
• Verifica se as docstrings seguem o estilo de formatação esperado.

Execute a verificação localmente antes de fazer o commit.

make fix-repo

make fix-repo também executa várias outras verificações. Para executar apenas as verificações de docstring e auto-docstring, use o comando abaixo.

# 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 verificação rápida

Como funciona

O decorador @auto_docstring gera docstrings por meio das seguintes etapas.

1. O decorador inspeciona a assinatura para ler argumentos, tipos e valores padrão do __init__ da classe decorada ou da função decorada. Para classes de configuração, ele percorre as anotações de nível de classe ao longo da cadeia de herança e para antes de PreTrainedConfig, excluindo os campos da classe base.

   Ele filtra automaticamente parâmetros como self, kwargs, args, deprecated_arguments e nomes com o prefixo _. Alguns parâmetros privados são renomeados para seus equivalentes públicos (_out_features → out_features para modelos de backbone).

2. As descrições comuns de argumentos vêm de auto_docstring.py: ModelArgs (entradas do modelo), ModelOutputArgs (campos de saída como hidden_states), ImageProcessorArgs (pré-processamento de imagens), ProcessorArgs (componentes do processador multimodal) e ConfigArgs (hiperparâmetros de configuração).

3. A descrição de cada parâmetro segue esta cadeia de prioridade:

   • Uma docstring manual (bloco r""" """ ou custom_args) tem prioridade.
   • O dicionário de origem predefinido (ModelArgs, ModelForArgs, ConfigArgs, ImageProcessorArgs, ProcessorArgs, ModelOutputArgs) é o recurso de fallback.
   • Se nenhuma das fontes tiver uma descrição, o parâmetro é sinalizado com [ERROR] na saída de compilação.

4. Para classes de modelo com nomes padrão, como ModelForCausalLM, ou classes que mapeiam para um pipeline, @auto_docstring gera a introdução. Para processadores multimodais, a introdução lista quais componentes (tokenizer, image processor, etc.) a classe encapsula. Consulte ClassDocstring para a lista completa.

   Se o nome da classe não estiver em ClassDocstring, defina custom_intro.

5. Docstrings predefinidas podem referenciar valores dinâmicos dos auto_modules do Transformers, como {processor_class}, {image_processor_class} e {config_class}. Os placeholders são resolvidos automaticamente.

6. O decorador seleciona exemplos de uso com base na tarefa ou na compatibilidade com o pipeline do modelo. Ele lê os metadados do checkpoint da classe de configuração para que os exemplos utilizem IDs de modelo reais. O argumento checkpoint substitui o checkpoint inferido a partir da docstring da classe de configuração. Defina checkpoint nas classes de configuração, ou quando a inferência do checkpoint falhar. Se você vir um erro como "Config not found for <model_name>", adicione uma entrada em HARDCODED_CONFIG_FOR_MODELS em auto_docstring.py.

7. Para métodos como forward, o decorador escreve a seção Returns a partir do tipo de retorno do método. Quando o tipo de retorno é uma subclasse de ModelOutput, @auto_docstring extrai as descrições dos campos da docstring dessa classe. Um bloco Returns personalizado na docstring da função tem precedência.

8. Para os métodos em UNROLL_KWARGS_METHODS e as classes em UNROLL_KWARGS_CLASSES, o decorador expande **kwargs tipado com Unpack[KwargsTypedDict]. Cada chave do TypedDict se torna um parâmetro documentado.

   A mesma expansão se aplica aos métodos __call__ e preprocess em subclasses de BaseImageProcessor e ProcessorMixin. Os tipos de base genéricos (TextKwargs, ImagesKwargs, VideosKwargs, AudioKwargs) são ignorados. Apenas subclasses específicas do modelo são expandidas.