koriweb
a3f63e56e2
- 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>
106 lines
5.4 KiB
Markdown
106 lines
5.4 KiB
Markdown
---
|
|
id: node-replacement---comfyui
|
|
title: "Node replacement - ComfyUI"
|
|
category: "10_Wiki/Topics"
|
|
status: "draft"
|
|
verification_status: "conceptual"
|
|
canonical_id: ""
|
|
aliases: []
|
|
duplicate_of: ""
|
|
source_trust_level: "B"
|
|
confidence_score: 0.8
|
|
created_at: 2026-05-20
|
|
updated_at: 2026-05-20
|
|
review_reason: ""
|
|
merge_history: []
|
|
tags: ["web", "wikify"]
|
|
raw_sources: ["https://docs.comfy.org/custom-nodes/backend/node-replacement"]
|
|
applied_in: []
|
|
github_commit: ""
|
|
---
|
|
|
|
# [[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로 매핑)
|
|
|
|
### 🔗 Widget ID Binding
|
|
`old_widget_ids` 필드는 위젯 ID를 위치 인덱스에 매핑합니다. 워크플로우 JSON은 위젯 값을 ID가 아닌 위치로 저장하기 때문에 이 기능이 필요합니다.
|
|
- 예: `["steps", "cfg", "sampler"]` -> index 0은 "steps"를 의미함.
|
|
|
|
### 🌐 REST API (GET /api/node_replacements)
|
|
등록된 모든 교체 정보를 반환하며, 응답 구조는 다음과 같습니다:
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
## 🔗 관련 문서 링크 (Related document links)
|
|
- [[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 본문에서 초안 생성. |