diffusers/main/ko/modular_diffusers/mellon.md

Mellon에서 사용자 정의 블록 사용

Mellon은 Modular Diffusers와 통합되는 시각적 워크플로 인터페이스로, 노드 기반 워크플로를 위해 설계되었습니다.

Mellon은 초기 개발 단계에 있으며 아직 프로덕션 사용에 적합하지 않습니다. 이 내용을 통합이 어떻게 작동하는지에 대한 미리보기로 생각해 주세요!

Mellon에서는 커스텀 블록이 기본적으로 작동합니다 - 저장소에 mellon_pipeline_config.json만 추가하면 됩니다. 이 설정 파일은 Mellon이 블록의 매개변수를 UI 컴포넌트로 렌더링하는 방법을 알려줍니다.

Gemini Prompt Expander 블록을 사용한 실제 동작은 다음과 같습니다:

Mellon에서 모듈형 diffusers 커스텀 블록을 사용하려면:

1. ModularDiffusers 섹션에서 Dynamic Block Node를 드래그합니다
2. repo_id를 입력하세요 (예: diffusers/gemini-prompt-expander-mellon)
3. 커스텀 블록 로드를 클릭하세요
4. 노드는 블록의 입력과 출력을 표시하도록 변환됩니다

자신만의 커스텀 블록에 대해 이 config를 생성하는 방법을 살펴보겠습니다.

Mellon 설정을 만드는 단계

1. 파라미터에 Mellon 유형 지정 - 각 InputParam/OutputParam에는 Mellon이 어떤 UI 컴포넌트를 렌더링할지 알려주는 유형(예: "textbox", "dropdown", "image")이 필요합니다.
2. mellon_pipeline_config.json 생성 - 유틸리티를 사용하여 설정 템플릿을 생성하고 Hub 저장소에 푸시합니다.
3. (선택 사항) config 수동 조정 - 특정 요구 사항에 맞게 생성된 config를 세밀하게 조정합니다.

매개변수에 대한 Mellon 유형 지정

Mellon 타입은 각 파라미터가 UI에서 어떻게 렌더링되는지를 결정합니다. 파라미터의 타입을 지정하지 않으면 "custom"로 기본 설정되며, 이는 단순한 연결 점으로 렌더링됩니다. 생성된 config에서 나중에 언제든지 이 값을 조정할 수 있습니다.

유형	입력/출력	설명
image	둘 다	이미지 (PIL Image)
video	둘 다	Video
text	둘 다	텍스트 표시
textbox	입력	텍스트 입력
dropdown	입력	드롭다운 선택 메뉴
slider	입력	숫자 값을 위한 슬라이더
number	입력	숫자 입력
checkbox	입력	Boolean 토글

추가 구성이 필요한 파라미터(옵션이 있는 드롭다운, min/max 값이 있는 슬라이더 등)의 경우, 문자열 대신 MellonParam 인스턴스를 직접 전달합니다. 아래 클래스 메서드 중 하나를 사용하거나, MellonParam(name, label, type, ...)으로 완전히 사용자 정의된 인스턴스를 생성할 수 있습니다.

메서드	설명
MellonParam.Input.image(name)	이미지 입력
MellonParam.Input.textbox(name, default)	textarea로 텍스트 입력
MellonParam.Input.dropdown(name, options, default)	드롭다운 선택
MellonParam.Input.slider(name, default, min, max, step)	숫자 값을 위한 슬라이더
MellonParam.Input.number(name, default, min, max, step)	숫자 입력 (슬라이더 없음)
MellonParam.Input.seed(name, default)	randomize 버튼으로 시드 입력
MellonParam.Input.checkbox(name, default)	Boolean 체크박스
MellonParam.Input.model(name)	diffusers 구성 요소의 모델 입력
MellonParam.Output.image(name)	이미지 출력
MellonParam.Output.video(name)	비디오 출력
MellonParam.Output.text(name)	텍스트 출력
MellonParam.Output.model(name)	diffusers 구성 요소의 모델 출력

Mellon 유형을 지정하려면 아래 방법 중 하나를 선택하세요.

metadata를 블록 정의에 사용하는 방법

사용자가 처음부터 커스텀 블록을 정의하는 경우, metadata={"mellon": "<type>"}을 InputParam 및 OutputParam 정의에 직접 추가하세요. Hub의 기존 커스텀 블록을 편집하는 경우, 로컬로 다운로드하는 방법은 커스텀 블록 편집을 참고하세요.

class GeminiPromptExpander(ModularPipelineBlocks):
    
    @property
    def inputs(self) -> List[InputParam]:
        return [
            InputParam(
                "prompt",
                type_hint=str,
                required=True,
                description="Prompt to use",
                metadata={"mellon": "textbox"},  # Text input
            )
        ]
    
    @property
    def intermediate_outputs(self) -> List[OutputParam]:
        return [
            OutputParam(
                "prompt",
                type_hint=str,
                description="Expanded prompt by the LLM",
                metadata={"mellon": "text"},  # Text output
            ),
            OutputParam(
                "old_prompt",
                type_hint=str,
                description="Old prompt provided by the user",
<CopyLLMTxtMenu containerStyle="float: inline-end; margin-inline-start: 10px; display: inline-flex; position: relative; z-index: 10;"></CopyLLMTxtMenu>

                # No metadata - we don't want to render this in UI
            )
        ]

UI 구성에 대한 완전한 제어를 위해 MellonParam 인스턴스를 직접 전달합니다:

from diffusers.modular_pipelines.mellon_node_utils import MellonParam

InputParam(
    "mode",
    type_hint=str,
    default="balanced",
    metadata={"mellon": MellonParam.Input.dropdown("mode", options=["fast", "balanced", "quality"])},
)

input_types와 output_types를 사용하여 설정 생성

기존 파이프라인을 사용 중이거나 블록 정의를 깔끔하게 유지하기를 원한다면, input_types/output_types 인수를 사용하여 설정을 생성할 때 유형을 지정하세요:

from diffusers.modular_pipelines.mellon_node_utils import MellonPipelineConfig

mellon_config = MellonPipelineConfig.from_custom_block(
    blocks,
    input_types={"prompt": "textbox"},
    output_types={"prompt": "text"}
)

metadata와 input_types/output_types가 모두 지정된 경우, 인수가 metadata를 덮어씁니다.

Mellon 설정을 생성하고 push합니다

블록에 메타데이터를 추가한 후, 기본 Mellon 구성 템플릿을 생성하여 Hub에 push합니다:

from diffusers import ModularPipelineBlocks
from diffusers.modular_pipelines.mellon_node_utils import MellonPipelineConfig

# load your custom blocks from your local dir
blocks = ModularPipelineBlocks.from_pretrained("/path/local/folder", trust_remote_code=True)

# Generate the default config template
mellon_config = MellonPipelineConfig.from_custom_block(blocks)
# push the default template to `repo_id`, you will need to pass the same local folder path so that it will save the config locally first
mellon_config.save(
    local_dir="/path/local/folder",
    repo_id= repo_id,
    push_to_hub=True
)

이 작업은 저장소에 mellon_pipeline_config.json 파일을 생성합니다.

config 검토 및 조정

생성된 템플릿은 시작점일 뿐이며, 필요에 맞게 조정할 수 있습니다. Gemini Prompt Expander의 생성된 설정을 함께 살펴보겠습니다:

{
  "label": "Gemini Prompt Expander",
  "default_repo": "",
  "default_dtype": "",
  "node_params": {
    "custom": {
      "params": {
        "prompt": {
          "label": "Prompt",
          "type": "string",
          "display": "textarea",
          "default": ""
        },
        "out_prompt": {
          "label": "Prompt",
          "type": "string",
          "display": "output"
        },
        "old_prompt": {
          "label": "Old Prompt",
          "type": "custom",
          "display": "output"
        },
        "doc": {
          "label": "Doc",
          "type": "string",
          "display": "output"
        }
      },
      "input_names": ["prompt"],
      "model_input_names": [],
      "output_names": ["out_prompt", "old_prompt", "doc"],
      "block_name": "custom",
      "node_type": "custom"
    }
  }
}

구조 이해하기

params 딕셔너리는 각 UI 요소가 어떻게 렌더링되는지 정의합니다. input_names, model_input_names, output_names 목록은 이러한 UI 요소를 ModularPipelineBlocks의 I/O 인터페이스에 매핑합니다:

Mellon 설정	ModularPipelineBlocks
input_names	inputs 속성
model_input_names	expected_components 속성
output_names	intermediate_outputs 속성

이 예시에서: prompt가 유일한 입력입니다. 모델 구성 요소는 없으며, 출력에는 out_prompt, old_prompt, doc가 포함됩니다.

이제 params 딕셔너리를 살펴보겠습니다:

• prompt: display: "textarea" (텍스트 입력 박스로 렌더링됨), label: "Prompt" (UI에 표시됨), default: "" (빈 상태로 시작)를 가진 입력 매개변수입니다. Mellon에서 type: "string" 필드는 어떤 노드끼리 연결될 수 있는지를 결정하기 때문에 중요합니다. 동일한 타입끼리만 "noodles"로 연결할 수 있습니다.

• out_prompt: 확장된 프롬프트 출력입니다. 입력과 출력이 동일한 이름(prompt)을 공유하므로 설정에서 이름 충돌을 피하기 위해 out_ 접두사가 자동으로 추가되었습니다. display: "output"를 가지고 있어 출력 소켓으로 렌더링됩니다.

• old_prompt: 메타데이터를 지정하지 않았기 때문에 type: "custom"입니다. UI에서는 단순한 점으로 표시됩니다. 실제로 UI에 노출할 의도가 없으므로 제거할 수 있습니다.

• doc: 문서 출력으로, 모든 커스텀 블록에 자동으로 추가됩니다.

조절하기

더 이상 사용하지 않으므로 old_prompt를 params와 output_names 양쪽에서 제거하세요.

{
  "label": "Gemini Prompt Expander",
  "default_repo": "",
  "default_dtype": "",
  "node_params": {
    "custom": {
      "params": {
        "prompt": {
          "label": "Prompt",
          "type": "string",
          "display": "textarea",
          "default": ""
        },
        "out_prompt": {
          "label": "Prompt",
          "type": "string",
          "display": "output"
        },
        "doc": {
          "label": "Doc",
          "type": "string",
          "display": "output"
        }
      },
      "input_names": ["prompt"],
      "model_input_names": [],
      "output_names": ["out_prompt", "doc"],
      "block_name": "custom",
      "node_type": "custom"
    }
  }
}

최종 설정은 diffusers/gemini-prompt-expander-mellon에서 확인하세요.