---
id: node-expansion---comfyui
title: "Node Expansion - 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/expansion"]
applied_in: []
github_commit: ""
---

# [[Node Expansion - ComfyUI]]

## 🎯 한 줄 통찰 (One-line insight)
[[Node Expansion]]은 노드가 실행 시점에 새로운 [[subgraph]]를 반환하여 그래프 내에서 해당 노드를 대체하도록 함으로써, [[loop]]와 같은 고급 기능을 구현할 수 있게 하는 기술입니다.

## 🧠 핵심 개념 (Core concepts)
- **Node Expansion**: 노드의 실행 결과로 기존 노드를 대체할 새로운 [[subgraph]]를 반환하는 고급 기법입니다.
- **GraphBuilder**: [[subgraph]] 생성 시 실수를 방방지하기 위해 권장되는 클래스로, 효율적인 그래프 구축을 지원합니다.
 ello
- **Efficient Subgraph Caching**: 확장된 [[subgraph]] 내의 노드들을 개별적으로 캐싱하여, 변경 사항 발생 시 전체 재로드 없이 특정 모델만 유지할 수 있도록 하는 최적화 전략입니다.
- **Expansion Requirements**: 확장을 수행하는 노드는 반드시 결과값(`result`)과 확장될 그래프(`expand`)를 포함하는 딕셔너리를 반환해야 합니다.

## 🧩 추출된 패턴 (Extracted patterns)
- **구조적 대체 패턴**: 기존의 노드 실행 방식(즉시 결과 반환)에서 벗어나, 실행 중에 새로운 노드 구조를 생성하여 그래프에 삽입하는 패턴을 가집니다.
- **캐싱 최적화 전략**: [[subgraph]] 내의 입력을 전달할 때, 직접적인 값 대신 [[subgraph]] 객체에 대한 링크를 전달하여 캐싱 효율을 높이는 패턴을 사용합니다.
- **수동 구현 제약 사항**: [[GraphBuilder]]를 사용하지 않을 경우, 노드 ID의 고유성 및 결정론적 유지를 위해 개발자가 직접 관리해야 하는 규칙(ID 중복 방지, 일관된 ID 유지)이 존재합니다.

## 📖 세부 내용 (Details)

### 🛠️ Node Expansion 구현 요구사항
노드가 확장을 수행하기 위해서는 반드시 아래의 키를 포함하는 딕셔너리를 반환해야 합니다.

| 키 (Key) | 설명 |
| :--- | :--- |
| `result` | 노드의 출력값에 대한 튜플. 일반적인 최종 값과 노드 출력값이 혼합될 수 있음. |
| `expand` | 확장에 사용될 최종화된 그래프. [[GraphBuilder]]를 사용하지 않을 경우 별도의 규칙 준수 필요. |

### 🛠️ GraphBuilder 미사용 시 추가 요구사항
[[GraphBuilder]]를 사용하지 않고 수동으로 구현할 경우, 다음의 조건을 직접 처리해야 합니다.
- **Node ID 고유성**: 그래프 전체에서 노드 ID는 반드시 고유해야 합니다 (리스트 사용으로 인한 동일 노드의 다중 실행 포함).
- **결정론적 ID**: 그래프의 여러 실행(캐싱에 의한 부분 실행 포함) 사이에서 노드 ID는 결정론적이고 일관되어야 합니다.
- **ID 관리 도구**: `GraphBuilder.alloc_prefix()` 또는 `comfy.graph_utils.add_graph_prefix`를 사용하여 기존 그래프를 수정하거나 접두사를 생성할 수 있습니다.

### 🛠️ 효율적인 Subgraph 캐싱 (Efficient Subgraph Caching)
- [[torch.Tensor]]와 같은 비리터럴 입력을 [[subgraph]] 내 노드에 전달할 수 있으나, 이는 캐싱을 저해할 수 있습니다.
- 가능한 경우, 노드 자체보다는 [[subgraph]] 객체에 대한 링크를 전달하는 것이 권장됩니다.
- 입력의 `Additional Parameters`에서 `rawLink`로 선언하여 쉽게 구현할 수 있습니다.

## ⚖️ 모tes 및 업데이트 (Contradictions & updates)
본문 내 상충되는 정보는 없으나, [[GraphBuilder]] 사용 여부에 따라 개발자가 책임져야 하는 요구사항의 범위가 달라짐을 명시하고 있습니다.

## 🛠️ 적용 사례 (Applied in summary)
- **Checkpoint Merging 예시**: `load_and_merge_checkpoints` 함수를 통해 두 개의 체크포인트를 로드하고, 이를 병합하는 새로운 노드 구조(`ModelMergeSimple`, `ClipMergeSimple`)를 생성하여 반환하는 구체적인 코드가 제시되었습니다. 이 과정에서 [[GraphBuilder]]를 사용하여 확장을 구현하는 방식이 예로 들었습니다.

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

## 🔗 관련 문서 링크 (Related document links)
- [[Node Expansion]]: 노드가 새로운 그래프 구조를 반환하는 핵심 기술입니다.
- [[GraphBuilder]]: [[subgraph]] 생성 시 실수를 방지하기 위해 권장되는 도구입니다.
- [[subgraph]]: 확장을 통해 새롭게 생성되어 그래프에 삽입될 노드들의 집합입니다.
- [[loop]]: [[Node Expansion]]을 통해 구현 가능한 고급 기능의 예시입니다.
- [[Efficient Subgraph Caching]]: 확장된 노드의 재사용성을 높이기 위한 최적화 기법입니다.

## 📝 변경 이력 (Change history)
- 2026-05-20: Astra /wikify 로 https://docs.comfy.org/custom-nodes/backend/expansion 본문에서 초안 생성.