Modelos de docstring e parâmetros automáticos

Cada 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 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.

# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...

Execute o seguinte comando para gerar e inserir os docstrings.

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.

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

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

Criando InputParam diretamente

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

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.

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

Criando OutputParam diretamente

from diffusers.modular_pipelines import OutputParam

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

Usando um modelo

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