2nd/10_Wiki/Comfyui/위키 Node Expansion - ComfyUI 2026-05-20.md

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

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
node-expansion---comfyui	Node Expansion - ComfyUI	10_Wiki/Topics	draft	conceptual				B	0.8	2026-05-20	2026-05-20			web wikify	https://docs.comfy.org/custom-nodes/backend/expansion

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 본문에서 초안 생성.