Files

T

koriweb a3f63e56e2 Add ComfyUI wikified docs and youtube extracts; tidy raw→Topics

- 10_Wiki/Comfyui/: ComfyUI docs generated via /wikify
- 00_Raw/_youtube/: /youtube extraction outputs
- Move some 00_Raw originals into 10_Wiki/Topics_meeting; remove empty canvases and stray files

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-20 18:41:10 +09:00

5.4 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

Node replacement - ComfyUI

🎯 한 줄 통찰 (One-line insight)

Node Replacement API는 커스텀 노드 개발자가 구식(deprecated) 노드를 최신 노드로 자동 마이그레이션하여 워크플로우의 호환성을 유지할 수 있게 해주는 기능이다.

🧠 핵심 개념 (Core concepts)

Migration Path Definition: Node Replacement API를 통해 구 버전 노드에서 신규 노드로의 전환 경로를 정의한다.
Automated Workflow Upgrade: 노드 클래스 이름 변경, 노드 병합, 입력/출력 리팩토링 시 사용자의 워크플로우를 자동으로 업데이트한다.
Lifecycle Integration: 커스텀 노드 확장의 on_load 생명주기 훅(lifecycle hook) 단계에서 교체 로직을 등록한다.
Data Mapping: Input mapping, Output mapping, Widget ID binding을 통해 입력/출력 데이터와 위젯 값을 정밀하게 재연결한다.

🧩 추출된 패턴 (Extracted patterns)

Node Replacement Use Cases: 노드 클래스 이름 변경, 노드 병합(Merging), 입력 리팩토링, 오타 수정(Typo fix) 등 특정 목적에 따라 API를 활용함.
Registration Strategy: node_replacements.py와 같은 전용 파일을 생성하여 on_load 시점에 등록하는 구조를 가짐.
Mapping Logic:
- Input mapping: 기존 입력을 새 입력으로 매핑하거나 고정값(set_value)을 설정함.
- Output mapping: 인덱스 기반의 참조를 통해 출력 데이터를 재배치함.
Frontend Automation: 프론트엔드에서 API를 호출하여 교체 정보를 가져온 후, 사용자에게 업그레이드를 제안하고 연결 및 위젯 값을 보존함.

📖 세부 내용 (Details

🛠 NodeReplace Parameters

필드	타입	필수/선택	제약·설명
`new_node_id`	str	필수	교체될 대상 노드의 클래스 이름
`old_node_rypt_id`	str	필수	기존의 구식(deprecated) 노드 클래스 이름
`old_widget_ids`	list[str] \| None	선택	상대적 인덱스에 바인딩할 위젯 ID의 정렬된 리스트
`input_mapping`	list \| None	선택	기존 노드에서 새 노드로 입력을 매핑하는 방법
`output_mapping`	list \| None	선택	기존 노드에서 새 노드로 출력을 매핑하는 방법

📥 Input Mapping Details

입력 매핑은 다음과 같은 방식으로 정의됩니다:

기존 입력 매핑: {"new_id": "model", "old_id": "model"}
고정값 설정: {"new_id": "scheduler", "set_value": "normal"}
동적/Autogrow 입력 (Dot notation 사용): {"new_id": "images.image0", "old_id": "image1"}

📤 Output Mapping Details

출력 매핑은 인덱스 기반 참조를 사용합니다:

{"new_idx": 0, "old_idx": 0} (첫 번째 출력 매핑)
{"new_idx": 1, "old_idx": 0} (기존 출력 0을 새 출력 1로 매핑)

old_widget_ids 필드는 위젯 ID를 위치 인덱스에 매핑합니다. 워크플로우 JSON은 위젯 값을 ID가 아닌 위치로 저장하기 때문에 이 기능이 필요합니다.

예: ["steps", "cfg", "sampler"] -> index 0은 "steps"를 의미함.

🌐 REST API (GET /api/node_replacements)

등록된 모든 교체 정보를 반환하며, 응답 구조는 다음과 같습니다:

{
  "OldSamplerNode": [
    {
      "new_node_im_id": "NewSamplerNode",
      "old_node_id": "OldSamplerNode",
      "old_widget_ids": ["num_steps", "cfg_scale", "sampler_name"],
      "input_mapping": [...],
      "output_mapping": [...]
    }
  ]
}

⚖️ 모순 및 업데이트 (Contradictions & updates)

본문에서 확인되지 않음.

🛠 적용 사례 (Applied in summary)

Simple Node Merge: Load3DAnimation 노드를 Load3D로 병합.
Typo Fix: SDV_img2vid_Conditioning의 오타를 SVD_imgint2vid_Conditioning으로 수정.
Input Renaming: ImageScaleBy를 ResizeImageMaskNode로 교체하며 입력/출력 매핑 및 기본값(set_value) 적용.
Autogrow Mapping: BatchImagesNode에서 도트 노테이션을 사용하여 images.image0과 같은 동적 입력 처리.

✅ 검증 상태 및 신뢰도

상태: draft
검증 단계: conceptual
출처 신뢰도: B (Primary Source — 웹사이트 본문 직접 추출)
중복 검사 결과: 신규 생성 (New discovery)

Node Replacement API: 노드 교체 기능을 구현하기 위한 핵심 인터페이스.
Input mapping: 입력 데이터를 새 노드로 전달하는 메커니즘.
Output mapping: 출력 인덱스를 재정의하는 방법.
Widget ID binding: 위젯 위치 기반 매핑을 위한 기술적 요구사항.
on_load lifecycle hook: 교체 로직을 등록해야 하는 시점.

📝 변경 이력 (Change history)

2026-05-20: Astra /wikify 로 https://docs.comfy.org/custom-nodes/backend/node-replacement 본문에서 초안 생성.

5.4 KiB Raw Blame History