Plantillas de docstring y parámetros automáticas

Cada ModularPipelineBlocks tiene una propiedad doc que se genera automáticamente a partir de su description, inputs, intermediate_outputs, expected_components y expected_configs. El sistema de docstrings automáticos mantiene las docstrings sincronizadas con la interfaz real del bloque. Las plantillas de parámetros proporcionan descripciones estandarizadas para parámetros que aparecen en muchos pipelines.

Auto docstring

Los bloques de pipeline modulares son componibles: puedes anidarlos, encadenarlos en secuencias y reorganizarlos libremente. Sus docstrings siguen el mismo patrón. Cuando un SequentialPipelineBlocks agrega las entradas y salidas de sus subbloques, la documentación debe actualizarse automáticamente sin reescrituras manuales.

El marcador # auto_docstring genera docstrings a partir de las propiedades del bloque. Añádelo sobre la definición de una clase para marcarla para la generación automática de docstrings.

# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...

Ejecuta el siguiente comando para generar e insertar las docstrings.

python utils/modular_auto_docstring.py --fix_and_overwrite

La utilidad lee la propiedad doc del bloque y la inserta como docstring de la clase.

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

También puede verificar sin sobrescribir, o apuntar a un archivo o directorio 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/

Si alguna clase marcada carece de docstring, la comprobación falla y enumera las clases que necesitan actualizarse.

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.

Plantillas de parámetros

InputParam y OutputParam definen las entradas y salidas de un bloque. Créalos directamente o usa .template() para definiciones estandarizadas de parámetros comunes como prompt, num_inference_steps o latents.

InputParam

InputParam describe una sola entrada de un bloque.

Creación de InputParam directamente

from diffusers.modular_pipelines import InputParam

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

Usando una plantilla

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

Las plantillas establecen automáticamente name, type_hint, default, required y description. Sobrescribe cualquier campo o añade contexto con el 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 describe una sola salida de un bloque.

Creación de OutputParam directamente

from diffusers.modular_pipelines import OutputParam

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

Usando una plantilla

OutputParam.template("latents")

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

Plantillas disponibles

INPUT_PARAM_TEMPLATES y OUTPUT_PARAM_TEMPLATES se definen en modular_pipeline_utils.py. Incluyen parámetros comunes como prompt, image, num_inference_steps, latents, prompt_embeds, entre otros. Consulte el código fuente para obtener la lista completa de nombres de plantillas disponibles.