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

Tự động tạo docstring và mẫu tham số

Mỗi ModularPipelineBlocks đều có thuộc tính doc được tạo tự động từ description, inputs, intermediate_outputs, expected_components và expected_configs. Hệ thống docstring tự động giúp đồng bộ hóa docstring với giao diện thực tế của block. Các mẫu tham số cung cấp mô tả chuẩn hóa cho các tham số xuất hiện trong nhiều pipeline khác nhau.

Tự động tạo docstring

Các khối pipeline dạng module có thể kết hợp được — bạn có thể lồng chúng vào nhau, nối chúng thành các chuỗi và sắp xếp lại chúng một cách tự do. Chuỗi chú thích (docstring) của chúng tuân theo cùng một mẫu. Khi một SequentialPipelineBlocks tổng hợp các đầu vào và đầu ra từ các khối con của nó, tài liệu nên được cập nhật tự động mà không cần viết lại thủ công.

Dấu # auto_docstring tạo docstring từ các thuộc tính của khối. Thêm nó phía trên định nghĩa lớp để đánh dấu lớp cho việc tạo docstring tự động.

# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...

Chạy lệnh sau để tạo và chèn các docstring.

python utils/modular_auto_docstring.py --fix_and_overwrite

Công cụ đọc thuộc tính doc của khối và chèn nó làm docstring của lớp.

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

Bạn cũng có thể kiểm tra mà không ghi đè, hoặc nhắm đến một tệp hoặc thư mục cụ thể.

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

Nếu bất kỳ class nào được đánh dấu thiếu docstring, kiểm tra sẽ thất bại và liệt kê các class cần cập nhật.

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.

Mẫu tham số

InputParam và OutputParam định nghĩa các đầu vào và đầu ra của một khối. Bạn có thể tạo chúng trực tiếp hoặc sử dụng .template() cho các định nghĩa chuẩn hóa của các tham số phổ biến như prompt, num_inference_steps, hoặc latents.

InputParam

InputParam mô tả một đầu vào duy nhất của một khối.

Trường	Loại	Mô tả
name	str	Tên của tham số
type_hint	Any	Ghi chú kiểu (ví dụ: str, torch.Tensor)
default	Any	Giá trị mặc định (nếu không được đặt, tham số không có giá trị mặc định)
required	bool	Có bắt buộc tham số hay không
description	str	Mô tả dễ đọc
kwargs_type	str	Tên nhóm cho các tham số liên quan (ví dụ: "denoiser_input_fields")
metadata	dict	Thông tin bổ sung tùy ý

Tạo InputParam trực tiếp

from diffusers.modular_pipelines import InputParam

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

Sử dụng một mẫu

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

Templates tự động đặt name, type_hint, default, required và description. Ghi đè bất kỳ trường nào hoặc thêm ngữ cảnh bằng tham số 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 mô tả một đầu ra duy nhất từ một khối.

Trường	Loại	Mô tả
name	str	Tên của tham số
type_hint	Any	Ghi chú kiểu
description	str	Mô tả dễ đọc
kwargs_type	str	Tên nhóm cho các tham số liên quan
metadata	dict	Thông tin bổ sung tùy ý

Tạo trực tiếp OutputParam

from diffusers.modular_pipelines import OutputParam

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

Sử dụng một mẫu

OutputParam.template("latents")

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

Các mẫu có sẵn

INPUT_PARAM_TEMPLATES và OUTPUT_PARAM_TEMPLATES được định nghĩa trong modular_pipeline_utils.py. Chúng bao gồm các tham số phổ biến như prompt, image, num_inference_steps, latents, prompt_embeds, và nhiều hơn nữa. Hãy tham khảo mã nguồn để biết danh sách đầy đủ các tên template khả dụng.