diffusers/main/ko/modular_diffusers/auto_docstring.md

자동 docstring 및 매개변수 템플릿

모든 ModularPipelineBlocks에는 doc 속성이 있으며, 이는 해당 블록의 description, inputs, intermediate_outputs, expected_components, expected_configs에서 자동으로 생성됩니다. 자동 docstring 시스템은 docstring이 블록의 실제 인터페이스와 항상 일치하도록 유지합니다. 파라미터 템플릿은 여러 파이프라인에 걸쳐 나타나는 파라미터에 대해 표준화된 설명을 제공합니다.

자동 문서 문자열

모듈형 파이프라인 블록은 조합이 가능합니다. 블록을 중첩하거나, 순서대로 연결하거나, 자유롭게 재배열할 수 있습니다. 이들의 docstring도 동일한 패턴을 따릅니다. SequentialPipelineBlocks가 하위 블록의 입력과 출력을 집계할 때, 수동으로 다시 작성하지 않아도 문서가 자동으로 업데이트되어야 합니다.

# auto_docstring 마커는 블록의 속성으로부터 docstring을 생성합니다. 클래스 정의 위에 추가하여 해당 클래스에 대한 자동 docstring 생성을 표시합니다.

# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...

…

python utils/modular_auto_docstring.py --fix_and_overwrite

이 유틸리티는 블록의 doc 속성을 읽고 이를 클래스 docstring으로 삽입합니다.

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

…

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

표시된 클래스 중 docstring이 누락된 경우, 체크가 실패하며 업데이트가 필요한 클래스를 나열합니다.

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.

매개변수 템플릿

InputParam과 OutputParam은 블록의 입력과 출력을 정의합니다. 직접 생성하거나, prompt, num_inference_steps, latents와 같은 일반적 파라미터의 표준화된 정의를 위해 .template()를 사용할 수 있습니다.

InputParam

InputParam은 블록의 단일 입력을 설명합니다.

필드	유형	설명
name	str	파라미터 이름
type_hint	Any	타입 어노테이션(예: str, torch.Tensor)
default	Any	기본값 (설정되지 않은 경우, 매개변수에 기본값이 없음)
required	bool	파라미터가 필수적인지 여부
description	str	사람이 읽을 수 있는 설명
kwargs_type	str	관련 매개변수에 대한 그룹 이름 (예: "denoiser_input_fields")
metadata	dict	임의의 추가 정보

InputParam을 직접 생성하기

from diffusers.modular_pipelines import InputParam

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

템플릿 사용

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

Templates는 name, type_hint, default, required, description을 자동으로 설정합니다. 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은 블록의 단일 출력을 설명합니다.

필드	유형	설명
name	str	파라미터 이름
type_hint	Any	타입 어노테이션
description	str	사람이 읽을 수 있는 설명
kwargs_type	str	관련 매개변수에 대한 그룹 이름
metadata	dict	임의의 추가 정보

OutputParam 직접 생성

from diffusers.modular_pipelines import OutputParam

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

템플릿 사용

OutputParam.template("latents")

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

사용 가능한 템플릿

INPUT_PARAM_TEMPLATES와 OUTPUT_PARAM_TEMPLATES는 modular_pipeline_utils.py에 정의되어 있습니다. prompt, image, num_inference_steps, latents, prompt_embeds와 같은 일반적인 매개변수를 포함합니다. 사용 가능한 템플릿 이름의 전체 목록은 소스 코드를 참조하세요.