ComfyUI의 시각적 편집 상태와 노드 간의 논리적 연결을 Litegraph 표준에 따라 완벽하게 보존하여, 인간의 재편집과 기계적 실행 사이의 가교 역할을 수행하는 전제 상태(Full State) 스냅샷 [1, 2].
🧠 핵심 개념 (Core concepts)
Litegraph 표준 준수: ComfyUI 웹 인터페이스의 캔버스 레이아웃을 정의하는 라이브러리인 Litegraph 형식을 따르며, 시각적 렌더링에 필요한 모든 데이터를 포함한다 [1, 2].
시각적 메타데이터(Visual Metadata): 노드의 좌표(pos), 크기(size), 그룹 구성, 색상, 노드의 축소(collapsed) 또는 고정(pinned) 상태 등의 정보를 상세히 기록한다 [1, 3, 4].
명시적 링크 구조(Explicit Links): 노드 간의 연결을 별도의 links 배열 내에서 고유 ID를 가진 명시적 객체로 관리하여 그래프의 시각적 연결성을 유지한다 [2, 3, 5].
노드 식별자(Node Identification): 각 노드는 주로 숫자 형태의 고유 문자열 ID(예: "1", "2")로 식별되며, 이는 그래프 탐색 및 UI 렌더링의 기준이 된다 [1, 2, 6].
🧩 추출된 패턴 (Extracted patterns)
Full UI Export 패턴: 단순히 실행 로직만 저장하는 것이 아니라, 사용자가 작업하던 환경을 그대로 복구할 수 있도록 캔버스의 모든 상태를 캡처하는 방식이다 [7, 8].
Metadata Embedding 패턴: 생성된 PNG 이미지의 tEXt 또는 zTXt 청크에 Frontend JSON 데이터를 주입하여 이미지 자체가 워크플로우 백업 파일 역할을 하도록 설계되었다 [9-11].
역방향 실행 모델(Execution Model Inversion): JSON 내에 수많은 노드가 존재하더라도 실행 엔진은 출력 노드(Save Image 등)부터 역추적하여 필요한 노드만 실행하며, 사용되지 않는 노드는 성능에 영향을 주지 않고 보존된다 [12].
📖 세부 내용 (Details)
Frontend Format인 workflow.json은 ComfyUI의 기본 저장 형식으로, 사용자가 웹 인터페이스에서 워크플로우를 저장하거나 공유할 때 주로 사용된다 [1, 2, 13].
1. 주요 데이터 구조
nodes: 워크플로우를 구성하는 개별 노드들의 배열이다. 각 노드 객체는 클래스 타입(type), 좌표(pos), 크기(size), 실행 순서(order), 모드(mode, 활성/우회 등), 그리고 위젯 설정값(widgets_values)을 포함한다 [4, 14].
links: 노드 사이의 와이어(Wire) 연결을 정의하는 최상위 배열이다. 각 링크는 보통 6개의 요소를 가진 배열이나 객체 형태로, 소스 노드 ID, 소스 슬롯, 타겟 노드 ID, 타겟 슬롯 정보를 담고 있다 [5].
groups: 캔버스 상에서 노드들을 논리적으로 묶어주는 시각적 그룹 정보를 저장한다 [4].
2. API Format(Backend)과의 차이점
Frontend Format은 사용자 인터페이스 정보를 모두 포함하기 때문에 파일 크기가 상대적으로 크며, 백엔드 실행 엔진이 직접 해석하기에는 부적절한 구조를 가지고 있다 [1, 3, 15]. 반면 API Format은 UI 메타데이터를 제거하고 노드 입력 내에 링크 정보를 직접 임베딩하여 실행 최적화에 집중한다 [1, 16, 17].
3. 상호 운용성 및 한계
이미지 기반 로딩: PNG 이미지에 포함된 메타데이터를 통해 워크플로우를 즉시 복구할 수 있으나, 이미지 편집기나 소셜 미디어 플랫폼을 거치면서 메타데이터가 손실될 위험이 있다 [9, 11, 18].
버전 호환성: ComfyUI는 지속적으로 업데이트되므로, 구버전의 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다 [18].
종속성 문제: JSON 파일 자체에는 모델 가중치나 커스텀 노드의 코드가 포함되지 않으므로, 로컬 환경에 해당 노드나 모델이 없을 경우 'Red Box' 오류가 발생한다 [19, 20].
⚖️ 모순 및 업데이트 (Contradictions & updates)
파일 확장자 혼용: 소스에 따라 API 전용 포맷을 workflow_api.json으로, 프론트엔드 포맷을 workflow.json으로 명확히 구분하기도 하지만, 일반적인 대화에서는 모두 '워크플로우 JSON'으로 통칭되기도 한다 [1, 21].
메타데이터 취약성: PNG에 임베딩된 JSON은 압축 소프트웨어나 네트워크 전송 시 소실될 수 있다는 점이 지속적으로 지적된다 [11, 18].
🛠️ 적용 사례 (Applied in summary)
comfyui-workflow-to-api-converter-endpoint: 클라이언트 측의 자바스크립트 로직을 파이썬으로 변환하여, 프론트엔드 형식의 JSON을 API 형식으로 서버 사이드에서 변환하는 기능을 제공한다 (커밋 bc85382 참조) [15, 22, 23].
ComfyUI-to-Python-Extension: 프론트엔드 워크플로우 메타데이터를 포함한 스크립트를 생성하여, 저장된 이미지에서 워크플로우를 재임포트할 수 있도록 지원한다 [24, 25].
ComfyUI-WorkflowGenerator: LLM을 통해 생성된 논리적 구조를 최종적으로 실행 가능한 Frontend JSON 또는 API JSON 포맷으로 빌드하는 WorkflowBuilder 노드를 포함한다 [26, 27].
✅ 검증 상태 및 신뢰도
상태: draft
검증 단계: conceptual (공식 문서 및 다수의 오픈소스 프로젝트에서 핵심 규격으로 사용됨)
출처 신뢰도: B (공식 문서 및 기술 블로그, GitHub 리포지토리를 통한 교차 검증 완료)
