diffusers/v0.43.0/id/modular_diffusers/auto_docstring.md

Template docstring dan parameter otomatis

Setiap ModularPipelineBlocks memiliki properti doc yang dihasilkan secara otomatis dari description, inputs, intermediate_outputs, expected_components, dan expected_configs. Sistem docstring otomatis menjaga agar docstring tetap sinkron dengan antarmuka aktual blok. Template parameter menyediakan deskripsi standar untuk parameter yang muncul di banyak pipeline.

Dokumentasi otomatis

Blok pipeline modular bersifat dapat dikomposisi — Anda dapat menest mereka, merangkainya dalam urutan, dan menyusun ulang secara bebas. Docstring mereka mengikuti pola yang sama. Ketika SequentialPipelineBlocks mengagregasi input dan output dari sub-bloknya, dokumentasi harus diperbarui secara otomatis tanpa penulisan ulang manual.

Penanda # auto_docstring menghasilkan docstring dari properti blok. Tambahkan di atas definisi kelas untuk menandai kelas tersebut agar docstring-nya dihasilkan secara otomatis.

# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...

Jalankan perintah berikut untuk menghasilkan dan menyisipkan docstring.

python utils/modular_auto_docstring.py --fix_and_overwrite

Utilitas ini membaca properti doc dari blok dan menyisipkannya sebagai docstring kelas.

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

Anda juga dapat memeriksa tanpa menimpa, atau menargetkan file atau direktori tertentu.

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

Jika kelas yang ditandai tidak memiliki docstring, pemeriksaan gagal dan akan menampilkan daftar kelas yang perlu diperbarui.

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.

Template parameter

InputParam dan OutputParam mendefinisikan input dan output sebuah blok. Buat secara langsung atau gunakan .template() untuk definisi standar dari parameter umum seperti prompt, num_inference_steps, atau latents.

InputParam

InputParam menjelaskan satu input ke sebuah blok.

Bidang	Tipe	Deskripsi
name	str	Nama parameter
type_hint	Any	Anotasi tipe (misalnya, str, torch.Tensor)
default	Any	Nilai default (jika tidak diatur, parameter tidak memiliki nilai default)
required	bool	Apakah parameter tersebut wajib
description	str	Deskripsi yang dapat dibaca manusia
kwargs_type	str	Nama grup untuk parameter terkait (misalnya, "denoiser_input_fields")
metadata	dict	Informasi tambahan lainnya

Membuat InputParam secara langsung

from diffusers.modular_pipelines import InputParam

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

Menggunakan template

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

Templates mengatur name, type_hint, default, required, dan description secara otomatis. Timpa bidang mana pun atau tambahkan konteks dengan parameter 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 menggambarkan satu keluaran dari sebuah blok.

Bidang	Tipe	Deskripsi
name	str	Nama parameter
type_hint	Any	Anotasi tipe
description	str	Deskripsi yang dapat dibaca manusia
kwargs_type	str	Nama grup untuk parameter terkait
metadata	dict	Informasi tambahan lainnya

Membuat OutputParam secara langsung

from diffusers.modular_pipelines import OutputParam

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

Menggunakan template

OutputParam.template("latents")

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

Template yang tersedia

INPUT_PARAM_TEMPLATES dan OUTPUT_PARAM_TEMPLATES didefinisikan di modular_pipeline_utils.py. Mereka mencakup parameter umum seperti prompt, image, num_inference_steps, latents, prompt_embeds, dan lainnya. Lihat sumber untuk daftar lengkap nama template yang tersedia.