# Modelos de docstring e parâmetros automáticos

Cada [ModularPipelineBlocks](/docs/diffusers/main/pt/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks) possui uma propriedade `doc` gerada automaticamente a partir de seus `description`, `inputs`, `intermediate_outputs`, `expected_components` e `expected_configs`. O sistema de docstring automático mantém as docstrings sincronizadas com a interface real do bloco. Os modelos de parâmetros fornecem descrições padronizadas para parâmetros que aparecem em muitos pipelines.

## Docstring automática

Os blocos de pipeline modulares são composáveis — você pode aninhá-los, encadeá-los em sequências e reorganizá-los livremente. As docstrings deles seguem o mesmo padrão. Quando um [SequentialPipelineBlocks](/docs/diffusers/main/pt/api/modular_diffusers/pipeline_blocks#diffusers.SequentialPipelineBlocks) agrega entradas e saídas de seus subblocos, a documentação deve ser atualizada automaticamente, sem reescritas manuais.

O marcador `# auto_docstring` gera docstrings a partir das propriedades do bloco. Adicione-o acima de uma definição de classe para marcar a classe para geração automática de docstring.

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...
```

Execute o seguinte comando para gerar e inserir os docstrings.

```bash
python utils/modular_auto_docstring.py --fix_and_overwrite
```

O utilitário lê a propriedade `doc` do bloco e a insere como a docstring da classe.

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    """
    Text input processing step that standardizes text embeddings for the pipeline.

    Inputs:
        prompt_embeds (`torch.Tensor`) *required*:
            text embeddings used to guide the image generation.
        ...

    Outputs:
        prompt_embeds (`torch.Tensor`):
            text embeddings used to guide the image generation.
        ...
    """
```

Você também pode verificar sem sobrescrever, ou direcionar a um arquivo ou diretório específico.

```bash
# Check that all marked classes have up-to-date docstrings
python utils/modular_auto_docstring.py

# Check a specific file or directory
python utils/modular_auto_docstring.py src/diffusers/modular_pipelines/flux/
```

Se alguma classe marcada estiver sem docstring, a verificação falha e lista as classes que precisam de atualização.

```
Found the following # auto_docstring markers that need docstrings:
- src/diffusers/modular_pipelines/flux/encoders.py: FluxTextEncoderStep at line 42

Run `python utils/modular_auto_docstring.py --fix_and_overwrite` to fix them.
```

## Modelos de parâmetros

`InputParam` e `OutputParam` definem as entradas e saídas de um bloco. Crie-os diretamente ou use `.template()` para definições padronizadas de parâmetros comuns, como `prompt`, `num_inference_steps` ou `latents`.

### InputParam

`InputParam` descreve uma única entrada de um bloco.

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | `str` | Nome do parâmetro |
| `type_hint` | `Any` | Anotação de tipo (por exemplo, `str`, `torch.Tensor`) |
| `default` | `Any` | Valor padrão (se não definido, o parâmetro não possui valor padrão) |
| `required` | `bool` | Se o parâmetro é obrigatório |
| `description` | `str` | Descrição legível por humanos |
| `kwargs_type` | `str` | Nome do grupo para parâmetros relacionados (por exemplo, `"denoiser_input_fields"`) |
| `metadata` | `dict` | Informações adicionais arbitrárias |

#### Criando InputParam diretamente

```py
from diffusers.modular_pipelines import InputParam

InputParam(
    name="guidance_scale",
    type_hint=float,
    default=7.5,
    description="Scale for classifier-free guidance.",
)
```

#### Usando um modelo

```py
InputParam.template("prompt")
# Equivalent to:
# InputParam(name="prompt", type_hint=str, required=True,
#            description="The prompt or prompts to guide image generation.")
```

Os templates definem automaticamente `name`, `type_hint`, `default`, `required` e `description`. Substitua qualquer campo ou adicione contexto com o parâmetro `note`.

```py
# Override the default value
InputParam.template("num_inference_steps", default=28)

# Add a note to the description
InputParam.template("prompt_embeds", note="batch-expanded")
# description becomes: "text embeddings used to guide the image generation. ... (batch-expanded)"
```

### OutputParam

`OutputParam` descreve uma única saída de um bloco.

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | `str` | Nome do parâmetro |
| `type_hint` | `Any` | Anotação de tipo |
| `description` | `str` | Descrição legível por humanos |
| `kwargs_type` | `str` | Nome do grupo para parâmetros relacionados |
| `metadata` | `dict` | Informações adicionais arbitrárias |

#### Criando OutputParam diretamente

```py
from diffusers.modular_pipelines import OutputParam

OutputParam(name="image_latents", type_hint=torch.Tensor, description="Encoded image latents.")
```

#### Usando um modelo

```py
OutputParam.template("latents")

# Add a note to the description
OutputParam.template("prompt_embeds", note="batch-expanded")
```

## Modelos disponíveis

`INPUT_PARAM_TEMPLATES` e `OUTPUT_PARAM_TEMPLATES` são definidos em [modular_pipeline_utils.py](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py). Eles incluem parâmetros comuns como `prompt`, `image`, `num_inference_steps`, `latents`, `prompt_embeds`, entre outros. Consulte o código-fonte para a lista completa de nomes de templates disponíveis.