From 94b61a7901c45968b3c968a3a948fdf996ca21df Mon Sep 17 00:00:00 2001 From: g1nation Date: Tue, 19 May 2026 18:08:09 +0900 Subject: [PATCH] Update Wiki 2nd --- .../Comfyui/API Format (workflow_api.json).md | 107 ++++++++ 10_Wiki/Comfyui/API Format.md | 103 ++++++++ 10_Wiki/Comfyui/API JSON.md | 67 +++++ 10_Wiki/Comfyui/Comfy CLI.md | 91 +++++++ 10_Wiki/Comfyui/Comfy GPT.md | 102 ++++++++ 10_Wiki/Comfyui/ComfyUI API.md | 112 ++++++++ 10_Wiki/Comfyui/ComfyUI Backend Engine.md | 100 ++++++++ 10_Wiki/Comfyui/ComfyUI Manager.md | 94 +++++++ 10_Wiki/Comfyui/ComfyUI Workflow Extractor.md | 66 +++++ ...kflow JSON Generation and Serialization.md | 102 ++++++++ 10_Wiki/Comfyui/ComfyUI Workflow JSON.md | 115 +++++++++ 10_Wiki/Comfyui/ComfyUI Workspace Manager.md | 88 +++++++ 10_Wiki/Comfyui/ComfyUI-Manager.md | 89 +++++++ 10_Wiki/Comfyui/ComfyUI-WorkflowGenerator.md | 106 ++++++++ .../Comfyui/ComfyUI-to-Python-Extension.md | 66 +++++ .../Comfyui workflow json 생성 방법.md | 114 +++++++++ .../Custom Node Dependency Management.md | 102 ++++++++ 10_Wiki/Comfyui/Custom Node Registry.md | 103 ++++++++ 10_Wiki/Comfyui/Custom Nodes.md | 99 ++++++++ .../Comfyui/Directed Acyclic Graph (DAG).md | 95 +++++++ 10_Wiki/Comfyui/Execution Model Inversion.md | 94 +++++++ 10_Wiki/Comfyui/ExecutionCache.md | 60 +++++ .../Frontend Format (workflow.json).md | 70 +++++ 10_Wiki/Comfyui/Generative AI Pipeline.md | 67 +++++ 10_Wiki/Comfyui/JSON Schema v1.0.md | 109 ++++++++ .../Lazy Evaluation in Graph Theory.md | 100 ++++++++ 10_Wiki/Comfyui/Litegraph Standard.md | 97 +++++++ 10_Wiki/Comfyui/Litegraph.md | 58 +++++ 10_Wiki/Comfyui/Metadata Forensics.md | 61 +++++ 10_Wiki/Comfyui/Metadata Stripping.md | 98 +++++++ 10_Wiki/Comfyui/Model Hashing (SHA-256).md | 96 +++++++ 10_Wiki/Comfyui/Model Hashing.md | 91 +++++++ ...Natural Language to Workflow Generation.md | 69 +++++ 10_Wiki/Comfyui/PNG Metadata Chunks.md | 72 ++++++ ...Serialization Formats (Frontend vs API).md | 113 +++++++++ 10_Wiki/Comfyui/Serverless Deployment.md | 67 +++++ .../Comfyui/Steganography in Generative AI.md | 62 +++++ 10_Wiki/Comfyui/Subgraph.md | 62 +++++ .../Comfyui/Visual Programming Environment.md | 114 +++++++++ .../Workflow API JSON (Backend Format).md | 98 +++++++ 10_Wiki/Comfyui/Workflow API JSON.md | 103 ++++++++ 10_Wiki/Comfyui/Workflow JSON v1.0 Schema.md | 117 +++++++++ 10_Wiki/Comfyui/Workflow JSON.md | 111 ++++++++ .../Workflow.json (Frontend Format).md | 109 ++++++++ 10_Wiki/Comfyui/WorkflowExecutor.md | 94 +++++++ 10_Wiki/Comfyui/Workspace Packaging.md | 97 +++++++ 10_Wiki/Comfyui/exiftool.md | 58 +++++ 10_Wiki/Comfyui/workflow_api.json.md | 67 +++++ .../Comfyui/API Format (workflow_api.json).md | 107 ++++++++ 10_Wiki/Topics/Comfyui/API Format.md | 103 ++++++++ 10_Wiki/Topics/Comfyui/API JSON.md | 67 +++++ 10_Wiki/Topics/Comfyui/Comfy CLI.md | 91 +++++++ 10_Wiki/Topics/Comfyui/Comfy GPT.md | 102 ++++++++ 10_Wiki/Topics/Comfyui/ComfyUI API.md | 112 ++++++++ .../Topics/Comfyui/ComfyUI Backend Engine.md | 100 ++++++++ 10_Wiki/Topics/Comfyui/ComfyUI Manager.md | 94 +++++++ .../Comfyui/ComfyUI Workflow Extractor.md | 66 +++++ ...kflow JSON Generation and Serialization.md | 102 ++++++++ .../Topics/Comfyui/ComfyUI Workflow JSON.md | 115 +++++++++ .../Comfyui/ComfyUI Workspace Manager.md | 88 +++++++ 10_Wiki/Topics/Comfyui/ComfyUI-Manager.md | 89 +++++++ .../Comfyui/ComfyUI-WorkflowGenerator.md | 106 ++++++++ .../Comfyui/ComfyUI-to-Python-Extension.md | 66 +++++ .../Comfyui workflow json 생성 방법.md | 114 +++++++++ .../Custom Node Dependency Management.md | 102 ++++++++ .../Topics/Comfyui/Custom Node Registry.md | 103 ++++++++ 10_Wiki/Topics/Comfyui/Custom Nodes.md | 99 ++++++++ .../Comfyui/Directed Acyclic Graph (DAG).md | 95 +++++++ .../Comfyui/Execution Model Inversion.md | 94 +++++++ 10_Wiki/Topics/Comfyui/ExecutionCache.md | 60 +++++ .../Frontend Format (workflow.json).md | 70 +++++ .../Topics/Comfyui/Generative AI Pipeline.md | 67 +++++ 10_Wiki/Topics/Comfyui/JSON Schema v1.0.md | 109 ++++++++ .../Lazy Evaluation in Graph Theory.md | 100 ++++++++ 10_Wiki/Topics/Comfyui/Litegraph Standard.md | 97 +++++++ 10_Wiki/Topics/Comfyui/Litegraph.md | 58 +++++ 10_Wiki/Topics/Comfyui/Metadata Forensics.md | 61 +++++ 10_Wiki/Topics/Comfyui/Metadata Stripping.md | 98 +++++++ .../Topics/Comfyui/Model Hashing (SHA-256).md | 96 +++++++ 10_Wiki/Topics/Comfyui/Model Hashing.md | 91 +++++++ ...Natural Language to Workflow Generation.md | 69 +++++ 10_Wiki/Topics/Comfyui/PNG Metadata Chunks.md | 72 ++++++ ...Serialization Formats (Frontend vs API).md | 113 +++++++++ .../Topics/Comfyui/Serverless Deployment.md | 67 +++++ .../Comfyui/Steganography in Generative AI.md | 62 +++++ 10_Wiki/Topics/Comfyui/Subgraph.md | 62 +++++ .../Comfyui/Visual Programming Environment.md | 114 +++++++++ .../Workflow API JSON (Backend Format).md | 98 +++++++ 10_Wiki/Topics/Comfyui/Workflow API JSON.md | 103 ++++++++ .../Comfyui/Workflow JSON v1.0 Schema.md | 117 +++++++++ 10_Wiki/Topics/Comfyui/Workflow JSON.md | 111 ++++++++ .../Workflow.json (Frontend Format).md | 109 ++++++++ 10_Wiki/Topics/Comfyui/WorkflowExecutor.md | 94 +++++++ 10_Wiki/Topics/Comfyui/Workspace Packaging.md | 97 +++++++ 10_Wiki/Topics/Comfyui/exiftool.md | 58 +++++ 10_Wiki/Topics/Comfyui/workflow_api.json.md | 67 +++++ ...들고_거기에_react_기반으로_테트리스_게임_.json | 27 ++ ...w_script_test_ai로_새로운_비즈니스_저.json | 21 ++ ...-05-18_e_wiki_connectai_이_프로젝트야.json | 15 ++ ...026-05-18_지금_작업하고_있는거_취소해.json | 12 + 10_Wiki/Topics/memory/long_term.json | 240 ++++++++++++++++-- 101 files changed, 8960 insertions(+), 25 deletions(-) create mode 100644 10_Wiki/Comfyui/API Format (workflow_api.json).md create mode 100644 10_Wiki/Comfyui/API Format.md create mode 100644 10_Wiki/Comfyui/API JSON.md create mode 100644 10_Wiki/Comfyui/Comfy CLI.md create mode 100644 10_Wiki/Comfyui/Comfy GPT.md create mode 100644 10_Wiki/Comfyui/ComfyUI API.md create mode 100644 10_Wiki/Comfyui/ComfyUI Backend Engine.md create mode 100644 10_Wiki/Comfyui/ComfyUI Manager.md create mode 100644 10_Wiki/Comfyui/ComfyUI Workflow Extractor.md create mode 100644 10_Wiki/Comfyui/ComfyUI Workflow JSON Generation and Serialization.md create mode 100644 10_Wiki/Comfyui/ComfyUI Workflow JSON.md create mode 100644 10_Wiki/Comfyui/ComfyUI Workspace Manager.md create mode 100644 10_Wiki/Comfyui/ComfyUI-Manager.md create mode 100644 10_Wiki/Comfyui/ComfyUI-WorkflowGenerator.md create mode 100644 10_Wiki/Comfyui/ComfyUI-to-Python-Extension.md create mode 100644 10_Wiki/Comfyui/Comfyui workflow json 생성 방법.md create mode 100644 10_Wiki/Comfyui/Custom Node Dependency Management.md create mode 100644 10_Wiki/Comfyui/Custom Node Registry.md create mode 100644 10_Wiki/Comfyui/Custom Nodes.md create mode 100644 10_Wiki/Comfyui/Directed Acyclic Graph (DAG).md create mode 100644 10_Wiki/Comfyui/Execution Model Inversion.md create mode 100644 10_Wiki/Comfyui/ExecutionCache.md create mode 100644 10_Wiki/Comfyui/Frontend Format (workflow.json).md create mode 100644 10_Wiki/Comfyui/Generative AI Pipeline.md create mode 100644 10_Wiki/Comfyui/JSON Schema v1.0.md create mode 100644 10_Wiki/Comfyui/Lazy Evaluation in Graph Theory.md create mode 100644 10_Wiki/Comfyui/Litegraph Standard.md create mode 100644 10_Wiki/Comfyui/Litegraph.md create mode 100644 10_Wiki/Comfyui/Metadata Forensics.md create mode 100644 10_Wiki/Comfyui/Metadata Stripping.md create mode 100644 10_Wiki/Comfyui/Model Hashing (SHA-256).md create mode 100644 10_Wiki/Comfyui/Model Hashing.md create mode 100644 10_Wiki/Comfyui/Natural Language to Workflow Generation.md create mode 100644 10_Wiki/Comfyui/PNG Metadata Chunks.md create mode 100644 10_Wiki/Comfyui/Serialization Formats (Frontend vs API).md create mode 100644 10_Wiki/Comfyui/Serverless Deployment.md create mode 100644 10_Wiki/Comfyui/Steganography in Generative AI.md create mode 100644 10_Wiki/Comfyui/Subgraph.md create mode 100644 10_Wiki/Comfyui/Visual Programming Environment.md create mode 100644 10_Wiki/Comfyui/Workflow API JSON (Backend Format).md create mode 100644 10_Wiki/Comfyui/Workflow API JSON.md create mode 100644 10_Wiki/Comfyui/Workflow JSON v1.0 Schema.md create mode 100644 10_Wiki/Comfyui/Workflow JSON.md create mode 100644 10_Wiki/Comfyui/Workflow.json (Frontend Format).md create mode 100644 10_Wiki/Comfyui/WorkflowExecutor.md create mode 100644 10_Wiki/Comfyui/Workspace Packaging.md create mode 100644 10_Wiki/Comfyui/exiftool.md create mode 100644 10_Wiki/Comfyui/workflow_api.json.md create mode 100644 10_Wiki/Topics/Comfyui/API Format (workflow_api.json).md create mode 100644 10_Wiki/Topics/Comfyui/API Format.md create mode 100644 10_Wiki/Topics/Comfyui/API JSON.md create mode 100644 10_Wiki/Topics/Comfyui/Comfy CLI.md create mode 100644 10_Wiki/Topics/Comfyui/Comfy GPT.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI API.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI Backend Engine.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI Manager.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI Workflow Extractor.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON Generation and Serialization.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI Workspace Manager.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI-Manager.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI-WorkflowGenerator.md create mode 100644 10_Wiki/Topics/Comfyui/ComfyUI-to-Python-Extension.md create mode 100644 10_Wiki/Topics/Comfyui/Comfyui workflow json 생성 방법.md create mode 100644 10_Wiki/Topics/Comfyui/Custom Node Dependency Management.md create mode 100644 10_Wiki/Topics/Comfyui/Custom Node Registry.md create mode 100644 10_Wiki/Topics/Comfyui/Custom Nodes.md create mode 100644 10_Wiki/Topics/Comfyui/Directed Acyclic Graph (DAG).md create mode 100644 10_Wiki/Topics/Comfyui/Execution Model Inversion.md create mode 100644 10_Wiki/Topics/Comfyui/ExecutionCache.md create mode 100644 10_Wiki/Topics/Comfyui/Frontend Format (workflow.json).md create mode 100644 10_Wiki/Topics/Comfyui/Generative AI Pipeline.md create mode 100644 10_Wiki/Topics/Comfyui/JSON Schema v1.0.md create mode 100644 10_Wiki/Topics/Comfyui/Lazy Evaluation in Graph Theory.md create mode 100644 10_Wiki/Topics/Comfyui/Litegraph Standard.md create mode 100644 10_Wiki/Topics/Comfyui/Litegraph.md create mode 100644 10_Wiki/Topics/Comfyui/Metadata Forensics.md create mode 100644 10_Wiki/Topics/Comfyui/Metadata Stripping.md create mode 100644 10_Wiki/Topics/Comfyui/Model Hashing (SHA-256).md create mode 100644 10_Wiki/Topics/Comfyui/Model Hashing.md create mode 100644 10_Wiki/Topics/Comfyui/Natural Language to Workflow Generation.md create mode 100644 10_Wiki/Topics/Comfyui/PNG Metadata Chunks.md create mode 100644 10_Wiki/Topics/Comfyui/Serialization Formats (Frontend vs API).md create mode 100644 10_Wiki/Topics/Comfyui/Serverless Deployment.md create mode 100644 10_Wiki/Topics/Comfyui/Steganography in Generative AI.md create mode 100644 10_Wiki/Topics/Comfyui/Subgraph.md create mode 100644 10_Wiki/Topics/Comfyui/Visual Programming Environment.md create mode 100644 10_Wiki/Topics/Comfyui/Workflow API JSON (Backend Format).md create mode 100644 10_Wiki/Topics/Comfyui/Workflow API JSON.md create mode 100644 10_Wiki/Topics/Comfyui/Workflow JSON v1.0 Schema.md create mode 100644 10_Wiki/Topics/Comfyui/Workflow JSON.md create mode 100644 10_Wiki/Topics/Comfyui/Workflow.json (Frontend Format).md create mode 100644 10_Wiki/Topics/Comfyui/WorkflowExecutor.md create mode 100644 10_Wiki/Topics/Comfyui/Workspace Packaging.md create mode 100644 10_Wiki/Topics/Comfyui/exiftool.md create mode 100644 10_Wiki/Topics/Comfyui/workflow_api.json.md create mode 100644 10_Wiki/Topics/memory/episodes/ep_2026-05-15_tetris라는_폴더를_만들고_거기에_react_기반으로_테트리스_게임_.json create mode 100644 10_Wiki/Topics/memory/episodes/ep_2026-05-18_e_wiki_00_raw_script_test_ai로_새로운_비즈니스_저.json create mode 100644 10_Wiki/Topics/memory/episodes/ep_2026-05-18_e_wiki_connectai_이_프로젝트야.json create mode 100644 10_Wiki/Topics/memory/episodes/ep_2026-05-18_지금_작업하고_있는거_취소해.json diff --git a/10_Wiki/Comfyui/API Format (workflow_api.json).md b/10_Wiki/Comfyui/API Format (workflow_api.json).md new file mode 100644 index 00000000..b4c26dd8 --- /dev/null +++ b/10_Wiki/Comfyui/API Format (workflow_api.json).md @@ -0,0 +1,107 @@ +--- +id: api-format-(workflow_api.json) +title: "API Format (workflow_api.json)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Backend Format", "API JSON"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "API"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint/README.md", "comfy_api_simplified", "ComfyUI-to-Python-Extension", "Mystic pipeline code", "Replicate any-comfyui-workflow"] +github_commit: "" +--- + +# [[API Format (workflow_api.json)]] + +## 🎯 한 줄 통찰 (One-line insight) +UI 메타데이터를 제거하고 실행에 필수적인 노드 로직과 데이터 흐름만을 압축하여 서버 측 프로그래밍 및 `/prompt` 엔드포인트 실행에 최적화된 데이터 규격 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **실행 최적화 (Execution-centric):** 시각적 배치 정보가 아닌 백엔드 엔진이 프롬프트를 실행하는 데 필요한 최소한의 논리 그래프만 포함함 [1, 3]. +- **UI 메타데이터 제거 (Metadata Stripping):** 노드 위치(pos), 크기(size), 그룹, 색상 등 사용자 인터페이스와 관련된 모든 정보를 삭제하여 파일 크기를 경량화함 [1, 2, 4]. +- **내장형 링크 참조 (Embedded Linkage):** 별도의 링크 객체 배열 대신 노드 입력(inputs) 내에 소스 노드 ID와 출력 슬롯 인덱스를 직접 포함하는 구조를 가짐 [1, 5]. +- **개발자 모드 의존성 (Dev Mode Dependency):** 표준 환경에서는 숨겨져 있으며, 설정에서 'Dev mode Options'를 활성화해야만 생성 및 내보내기가 가능함 [6-8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **노드 식별 패턴:** 각 노드는 숫자 문자열(예: "5", "6") 형태의 고유 키를 가지며, 이는 그래프 내에서 기능적 매핑을 위한 식별자로 사용됨 [3, 9, 10]. +- **데이터 연결 패턴:** 특정 노드의 입력 필드에 `[노드ID, 출력슬롯번호]` 형태의 리스트(예: `[11, 12]`)를 할당하여 노드 간의 데이터 흐름을 정의함 [5]. +- **직렬화 구조:** 루트 레벨에서 노드 ID를 키로 하고, 그 값으로 `class_type`과 `inputs`를 포함하는 단일 JSON 객체 구조를 유지함 [10, 13]. + +## 📖 세부 내용 (Details) +### 1. 포맷의 정의와 목적 +API 포맷(`workflow_api.json`)은 ComfyUI 백엔드 엔진이 직접 해석할 수 있는 **평탄화된 실행 그래프(flattened execution graph)**입니다 [6]. 주로 외부 애플리케이션 통합, 자동화 스크립트 실행, 서버리스 배포 환경에서 프롬프트를 큐(queue)에 추가할 때 사용됩니다 [1, 9]. + +### 2. 기술적 구성 요소 +- **구조적 차이:** 프론트엔드 포맷(`workflow.json`)이 Litegraph 표준을 따르며 시각적 가독성을 중시하는 반면, API 포맷은 백엔드 엔진의 `/prompt` 엔드포인트 사양에 맞춰 설계되었습니다 [1, 9]. +- **노드 정의:** 각 노드 객체는 해당 노드의 클래스 이름을 나타내는 `class_type`과 실제 파라미터 및 연결 정보를 담은 `inputs` 딕셔너리로 구성됩니다 [2, 10]. +- **연결 방식:** 프론트엔드 포맷의 `links` 배열이 제거되고, 모든 연결 정보가 `inputs` 내에 직접 주입됩니다. 예를 들어 CLIP 텍스트 인코딩 노드의 `clip` 입력값은 연결된 소스 노드 정보를 리스트 형태로 보유합니다 [5]. + +### 3. 생성 및 변환 프로세스 +- **수동 생성:** 설정 메뉴에서 'Enable Dev mode Options'를 체크한 후, 제어판에 나타나는 **'Save (API Format)'** 버튼을 통해 추출합니다 [7, 8, 14]. +- **프로그래밍 방식 변환:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면 클라이언트 측 자바스크립트 로직 없이 서버 측에서 직접 프론트엔드 형식을 API 형식으로 변환할 수 있습니다 [15, 16]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가역성 문제 (Fragility):** API 포맷은 실행에는 완벽하지만 시각적 정보가 없으므로, 이를 다시 UI로 드래그하여 로드하면 노드 배치가 깨지거나 그룹 정보가 사라진 '스켈레톤(skeleton)' 상태로 나타나 편집이 매우 어렵습니다 [17, 18]. +- **버전 호환성:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드 의존성이 있는 경우 실행 실패 가능성이 높습니다 [19, 20]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 프론트엔드 워크플로우를 서버 측에서 API 포맷으로 즉시 변환하는 `/workflow/convert` 엔드포인트를 제공합니다 [15, 21]. +- **deimos-deimos/comfy_api_simplified:** API 포맷 워크플로우를 로드하여 파이썬 딕셔너리로 다루고, 노드 제목(title)을 기준으로 파라미터를 수정하여 큐에 추가하는 기능을 구현합니다 [22, 23]. +- **Mystic & Replicate:** 사용자 워크플로우를 서버리스 API로 배포할 때, 실행의 기본 단위로 `workflow_api.json`을 요구하거나 내부적으로 이를 사용하여 추론을 수행합니다 [14, 24, 25]. +- **ComfyUI-to-Python-Extension:** API 포맷의 JSON을 입력받아 독립적으로 실행 가능한 파이썬 스크립트(`.py`)로 변환하는 기능을 수행합니다 [26, 27]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 오픈소스 프로젝트 및 플랫폼에서 핵심 규격으로 활용됨) +- **출처 신뢰도:** B (Official Documentation / GitHub Repository README 및 소스 코드 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Frontend Format (workflow.json)]] + - 연결 이유: API 포맷과 대칭되는 시각적 편집용 데이터 규격임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 데이터 직렬화 시 UI 정보와 실행 정보의 분리 설계 방식. +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: API 포맷은 노드와 링크로 구성된 추상화된 그래프 구조를 표현함. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 의존성 및 실행 순서 결정 원리. + +#### [구현/활용 도구] +- [[ComfyUI API]] + - 연결 이유: API 포맷은 `/prompt` 엔드포인트 호출 시 전달되는 페이로드의 핵심 데이터임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 실제 서버 통신 및 작업 큐잉 프로세스. +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: API JSON을 파이썬 코드로 변환하여 독립 실행 환경을 구축함. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터가 실제 실행 코드로 치환되는 매핑 원리. + +### 심층 후속 질문 (Deeper Research Questions) +- 왜 ComfyUI는 시각적 정보와 실행 정보를 하나의 JSON에 통합하지 않고 두 가지 포맷으로 분리하여 관리하는가? [1] +- API 포맷에서 노드 ID가 문자열 형태의 숫자로 고정될 때, 워크플로우 편집 시 ID 충돌이나 누락을 방지하는 메커니즘은 무엇인가? [3, 28] +- `comfyui-workflow-to-api-converter-endpoint`는 클라이언트 측의 자바스크립트 변환 로직을 어떻게 파이썬 서버 측 로직으로 완벽하게 이식했는가? [15] +- 대규모 워크플로우(예: 200KB 이상)를 API 포맷으로 호출할 때 성능 저하나 데이터 누락이 발생할 가능성은 없는가? [16] +- `object_info.json`에 정의된 노드 스키마와 API 포맷의 `inputs` 데이터 구조 사이의 유효성 검사 과정은 어떻게 이루어지는가? [13] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬의 `json` 라이브러리를 사용하여 API JSON을 로드하고, 특정 노드 ID의 `inputs` 값을 변경하여 동적 프롬프트를 생성할 수 있음 [10, 29]. +- **System Design:** 프론트엔드 수정을 최소화하면서 백엔드 자동화를 구축하기 위해 서버 측에서 변환 엔드포인트를 활용하는 캐싱 전략을 수립할 수 있음 [17]. +- **Operation / Maintenance:** 커스텀 노드 업데이트 시 API 포맷 내의 `class_type` 명칭이 변경되지 않았는지 확인하여 서비스 중단을 방지해야 함 [19]. +- **Learning Path:** 노드 기반 UI에 익숙해진 후, 개발자 모드를 통해 추출된 API JSON의 구조를 분석하여 프로그래밍 방식의 자동화 단계로 진입함 [6]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: API JSON 내의 모델 파일 이름 불일치 문제를 해결하기 위한 고유 식별 기술 조사 [30]. +- [[Serverless Deployment]] + - 확장 방향: API 포맷을 클라우드 환경(Replicate, Mystic)에 배포하여 확장성 있는 AI 서비스를 구축하는 방법 [14, 31]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/API Format.md b/10_Wiki/Comfyui/API Format.md new file mode 100644 index 00000000..50e05a63 --- /dev/null +++ b/10_Wiki/Comfyui/API Format.md @@ -0,0 +1,103 @@ +--- +id: api-format +title: "API Format" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["API JSON", "workflow_api.json", "Backend Format"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "API", "JSON", "Automation"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint", "deimos-deimos/comfy_api_simplified", "pydn/ComfyUI-to-Python-Extension"] +github_commit: "bc85382" +--- + +# [[API Format]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI API 포맷은 시각적 메타데이터를 제거하고 노드 간의 논리적 연결과 입력값만을 보존하여 서버 측 실행 및 프로그래밍 방식의 자동화에 최적화된 경량화된 실행 그래프이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **실행 그래프 (Execution Graph):** UI 좌표, 노드 크기, 그룹화 정보 등 시각적 요소를 배제하고 백엔드 엔진이 프롬프트를 실행하는 데 필요한 순수 논리 구조만 포함한다 [1, 3, 4]. +- **임베디드 링크 (Embedded Links):** 별도의 링크 객체 배열을 사용하는 대신, 노드의 입력 필드(`inputs`) 내에 소스 노드 ID와 출력 슬롯 번호를 직접 참조(예: `[5, 6]`)하여 연결을 정의한다 [1, 2, 7]. +- **기능적 키 매핑 (Functional Key Mapping):** JSON 객체의 최상위 키가 노드 ID(문자열)이며, 각 값은 `class_type`과 `inputs`를 포함하는 딕셔너리 구조를 가진다 [8-10]. +- **개발자 모드 활성화 (Dev Mode Requirement):** 일반적인 저장 방식과 달리 ComfyUI 설정에서 'Enable Dev mode Options'를 활성화해야만 내보낼 수 있는 특수 포맷이다 [11-14]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **UI/백엔드 이원화 패턴:** 사용자 인터페이스용 `workflow.json`과 실행 전용 `workflow_api.json`을 분리하여 편집 효율성과 실행 속도를 동시에 확보한다 [1, 2, 15]. +- **메타데이터 캡슐화:** PNG 이미지의 `tEXt` 또는 `zTXt` 청크에 API 포맷(prompt) 데이터를 포함시켜 이미지 자체가 실행 가능한 소스 코드 역할을 하도록 설계한다 [16, 17]. +- **직접 딕셔너리 조작 패턴:** 개발자가 JSON을 로드하여 특정 노드 ID의 `inputs` 값을 파이썬 등으로 수정 후 `/prompt` 엔드포인트에 전송하는 동적 제어 방식을 지원한다 [8, 10, 18]. + +## 📖 세부 내용 (Details) +ComfyUI의 API 포맷은 주로 `workflow_api.json` 파일로 알려져 있으며, 서버리스 API 호출이나 외부 애플리케이션 통합 시 핵심적인 역할을 한다 [2, 15]. 이 포맷은 Litegraph 표준을 따르는 프론트엔드 포맷과 달리, 백엔드 엔진이 즉시 해석할 수 있도록 평탄화(Flattened)된 구조를 가진다 [1, 11]. + +구조적으로 API 포맷은 노드 ID를 키로 사용하는 단일 JSON 객체이다 [9]. 각 노드 정의에는 해당 노드의 클래스 이름인 `class_type`과 위젯 값 및 링크 정보를 포함하는 `inputs` 딕셔너리가 들어간다 [3, 8]. 예를 들어, `CLIPTextEncode` 노드의 경우 텍스트 입력값과 함께 연결된 CLIP 모델의 노드 정보를 `[노드ID, 슬롯번호]` 형태의 배열로 보유한다 [7, 10]. + +이 포맷은 데이터 용량이 작고 효율적이지만, 다시 ComfyUI 인터페이스로 드래그했을 때 시각적 레이아웃 정보가 없어 노드들이 겹치거나 연결 구조를 파악하기 힘든 '스켈레톤(Skeleton)' 상태로 로드된다는 특징이 있다 [19, 20]. 따라서 실무에서는 시각적 편집용 원본 워크플로를 별도로 보관하는 것이 권장된다 [20]. 또한, 최근에는 시각적 포맷을 API 포맷으로 실시간 변환해주는 서버측 엔드포인트 도구들이 개발되어 이 단점을 보완하고 있다 [19, 21]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가독성 vs 실행력:** API 포맷은 인간이 읽기에 간결하지만, 시각적 정보가 결여되어 있어 복잡한 워크플로를 이 포맷만으로 수동 편집하기에는 한계가 있다 [17, 20]. +- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 구버전의 JSON API 포맷이 최신 서버 환경에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [22]. +- **데이터 유실 위험:** 표준 이미지 편집기나 소셜 미디어를 거칠 경우 PNG 메타데이터에 포함된 API 포맷 정보가 삭제될 수 있어 전송 시 주의가 필요하다 [16]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 프론트엔드 워크플로를 API 포맷으로 변환하는 서버측 `/workflow/convert` 엔드포인트를 구현하였다 [19]. + - **Git 커밋:** `bc85382` (콤보 위젯 값의 대소문자 정규화 수정 포함) [23, 24]. +- **deimos-deimos/comfy_api_simplified:** 노드 제목(Title)을 기준으로 API 포맷의 파라미터를 수정하고 큐에 등록하는 파이썬 래퍼 기능을 제공한다 [25-27]. +- **pydn/ComfyUI-to-Python-Extension:** 저장된 API 포맷 JSON을 독립 실행 가능한 `.py` 스크립트로 변환하는 CLI 기능을 포함한다 [28-30]. +- **Mystic (Pipeline AI):** 사용자의 API JSON을 파이썬 엔드포인트 내에 주입하여 서버리스 환경에서 실행하는 템플릿을 제공한다 [14, 31]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual +- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 코드 기반) [23, 32] +- **중복 검사 결과:** 신규 생성 + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Frontend Format]] + - 연결 이유: API 포맷과 대조되는 시각적 편집용 데이터 구조임. [1, 2] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메타데이터 분리 전략 및 Litegraph 표준의 한계. [1, 33] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI 워크플로가 직렬화되는 근본적인 논리 구조임. [34] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 실행 순서와 데이터 흐름 제어 원리. [34, 35] + +#### [구현/활용 도구] +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: API JSON을 파이썬 코드로 변환하는 직접적인 도구임. [28] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 객체가 실제 파이썬 함수 호출로 매핑되는 과정. [29, 36] +- [[ComfyUI Manager]] + - 연결 이유: API 포맷 로드 시 발생하는 커스텀 노드 누락 문제를 해결하는 필수 도구임. [37, 38] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 종속성 관리 및 `class_type` 기반의 노드 복구 메커니즘. [37, 39] + +### 심층 후속 질문 (Deeper Research Questions) +- API 포맷에서 노드 ID가 단순한 숫자 문자열을 넘어 기능적 키(Functional Key)로 작동할 때, 대규모 워크플로에서 ID 충돌을 방지하는 내부 메커니즘은 무엇인가? [1, 2] +- `workflow_api.json`에 포함된 `_meta` 필드는 실행 엔진에서 어떤 구체적인 역할을 수행하며, 필수 요소인가? [9] +- 서브그래프(Subgraph)가 중첩된 워크플로를 API 포맷으로 내보낼 때, 내부 링크 ID와 외부 링크 ID의 충돌을 처리하는 알고리즘은 어떻게 설계되어 있는가? [40] +- API 포맷 내의 `inputs` 필드에서 위젯 값(`widgets_values`)과 동적 링크 연결을 구분하여 처리하는 구문 분석 로직은 무엇인가? [7, 41] +- `exiftool`과 같은 외부 CLI 도구를 사용하여 PNG에서 API JSON을 추출할 때, 메타데이터 손상을 복구하거나 검증할 수 있는 표준 스키마가 존재하는가? [42, 43] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬 `json` 라이브러리를 사용하여 API JSON 파일을 로드하고, 특정 노드 ID의 입력값을 수정한 뒤 서버의 `/prompt` 엔드포인트로 POST 요청을 보내 자동화를 구현한다 [8, 10, 18]. +- **System Design:** 프론트엔드 편집 도구와 백엔드 실행기를 분리하여, 사용자는 웹 UI에서 편집하고 실제 운영 환경에서는 경량화된 API JSON만 사용하여 리소스를 최적화한다 [1, 44]. +- **Operation / Maintenance:** API JSON에는 모델 체크포인트의 이름이 하드코딩되므로, 서버 간 모델 공유 시 파일명 불일치 문제를 해결하기 위해 모델 해싱(SHA-256) 기술과 함께 운용한다 [45, 46]. +- **Learning Path:** 먼저 GUI에서 워크플로를 완성한 후, 개발자 모드를 통해 API 포맷을 내보내고 그 구조를 분석하여 프로그래밍 방식의 제어 단계로 넘어가는 것이 표준 학습 경로이다 [14, 47]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Node Definitions]] + - 확장 방향: API 포맷 내 `class_type`이 참조하는 각 노드의 입력/출력 타입 정의 연구. [43] +- [[Execution Model Inversion]] + - 확장 방향: API JSON 전체 중 필요한 노드만 선택적으로 실행하는 백엔드 최적화 원리 이해. [32, 48] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. 기반 소스 18개 종합 분석 완료. [1-186] \ No newline at end of file diff --git a/10_Wiki/Comfyui/API JSON.md b/10_Wiki/Comfyui/API JSON.md new file mode 100644 index 00000000..16f5ffd1 --- /dev/null +++ b/10_Wiki/Comfyui/API JSON.md @@ -0,0 +1,67 @@ +--- +id: api-json +title: "API JSON" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["workflow_api.json", "Backend Format", "API Format"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI-WorkflowGenerator", "comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "comfy_api_simplified"] +github_commit: "" +--- + +# [[API JSON]] + +## 🎯 한 줄 통찰 (One-line insight) +API JSON은 ComfyUI의 시각적 인터페이스 요소를 배제하고 순수 실행 로직만을 추상화하여 백엔드 엔진의 프로그래밍적 제어와 자동화를 가능케 하는 핵심 데이터 규격이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **백엔드 실행 그래프 (Backend Execution Graph):** 노드 위치, 크기, 그룹 등 UI 관련 메타데이터를 제거하고 실행에 필요한 노드 타입과 입력값, 연결 관계만을 남긴 콤팩트한 형식이다 [1, 3]. +2. **임베딩된 참조 구조 (Reference-based Linking):** 별도의 링크 배열을 사용하는 프론트엔드 형식과 달리, 노드 입력 필드 내에 직접 소스 노드 ID와 출력 슬롯 인덱스를 배열 형태로 기술한다 [1, 3, 4]. +3. **개발자 모드 (Dev Mode) 활성화:** 표준 ComfyUI 환경에서 API JSON을 추출하기 위해 설정(Settings) 메뉴에서 반드시 선행 활성화해야 하는 옵션이다 [5-7]. +4. **프로그래밍적 엔드포인트 호환성:** `/prompt` 엔드포인트에 페이로드로 직접 전달되어 서버 측에서 즉시 실행될 수 있도록 최적화된 구조를 가진다 [8-10]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Bifurcation (이원화) 저장 패턴:** 사용자의 시각적 편집을 위한 `workflow.json`과 기계적 실행을 위한 `workflow_api.json`을 분리하여 각 용도에 최적화된 성능과 관리 편의성을 제공한다 [1, 8, 11]. +- **Metadata Chunk 중복 저장:** 생성된 PNG 파일의 tEXt 또는 zTXt 청크에 프론트엔드 워크플로우와 API 프롬프트를 모두 저장하여, 이미지 하나로 시각적 복원과 API 실행을 동시에 보장한다 [12, 13]. +- **Execution Model Inversion:** 엔진이 출력 노드에서부터 역방향으로 그래프를 탐색하여 결과 생성에 필요한 노드만 선별 실행함으로써 데이터 처리 효율을 극대화한다 [14]. + +## 📖 세부 내용 (Details) +### 1. 기술적 구조 및 사양 +API JSON은 루트 키가 **노드 ID(문자열)**로 구성된 단일 JSON 객체 구조를 취한다 [15, 16]. 각 노드 객체는 클래스 이름인 `class_type`과 사용자 입력 및 연결 정보를 포함하는 `inputs` 딕셔너리로 이루어진다 [3, 17]. 노드 간의 연결은 `inputs` 내에 `[노드_ID, 출력_슬롯_인덱스]` 형식의 배열로 표현되어 그래프 구조를 형성한다 [4, 18]. 이는 Litegraph 표준을 따르는 프론트엔드 포맷보다 훨씬 파일 크기가 작고 처리가 빠르다 [8]. + +### 2. 수동 생성 및 추출 방법 +가장 기본적인 생성 방법은 ComfyUI 웹 인터페이스를 이용하는 것이다. 설정 메뉴에서 **"Enable Dev mode Options"**를 체크하면 컨트롤 패널에 **"Save (API Format)"** 버튼이 노출되며, 이를 통해 즉시 다운로드 가능하다 [5, 6, 19, 20]. 또한, 이미 생성된 PNG 이미지에서 `exiftool`과 같은 CLI 도구를 사용해 메타데이터에 숨겨진 API JSON(Prompt) 데이터를 추출할 수도 있다 [21, 22]. + +### 3. 자동화 및 프로그래밍적 생성 +- **LLM 기반 생성:** `ComfyUI-WorkflowGenerator`는 자연어 지시를 해석하여 논리적 합성, 의미론적 검증, 그래프 컴파일 단계를 거쳐 실행 가능한 API JSON을 자동으로 구축한다 [23-25]. +- **동적 변환:** `comfyui-workflow-to-api-converter-endpoint` 커스텀 노드는 서버측에서 `/workflow/convert` 엔드포인트를 제공하여, 시각적 정보가 포함된 표준 JSON을 실시간으로 API 포맷으로 변환해준다 [10, 26, 27]. +- **Python 래퍼 및 확장:** `comfy_api_simplified`나 `ComfyUI-to-Python-Extension`은 API JSON을 로드하여 특정 노드의 파라미터(시드, 프롬프트 등)를 동적으로 수정한 후 큐잉하거나, 전체 워크플로우를 독립 실행형 Python 스크립트로 변환하는 기능을 제공한다 [28-30]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 제한:** ComfyUI는 업데이트가 매우 잦아 이전 버전에서 생성된 API JSON이 최신 버전의 노드 레지스트리나 스키마와 충돌하여 작동하지 않을 가능성이 상존한다 [31]. +- **데이터 파괴 위험:** 표준 이미지 편집기나 소셜 미디어 플랫폼을 통해 이미지를 공유할 경우, API JSON이 포함된 메타데이터 청크가 자동으로 삭제되어 워크플로우 정보가 영구 손실될 수 있다 [12, 31]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Mystic Python SDK 연동:** `workflow_api.json`을 사용하여 텍스트-투-비디오 워크플로우를 서버리스 엔드포인트로 배포하며, Python 스크립트에서 입력 프롬프트를 동적으로 주입한다 [32, 33]. +- **Replicate API 호출:** `fofr/any-comfyui-workflow` 모델을 통해 API JSON을 직접 입력받아 원격 GPU에서 워크플로우를 실행한다 [7, 34]. +- **ComfyUI-to-Python-Extension:** CLI를 통해 `workflow_api.json`을 입력 파일로 받아 실행 가능한 `.py` 스크립트를 생성하며, 이때 `--input_file` 플래그로 API JSON 경로를 지정한다 [35, 36]. +- **Lou@blog Python 코드:** `urllib`와 `websocket`을 사용하여 API JSON의 특정 노드 ID(예: #37 TextInput)의 `inputs.text` 값을 교체한 후 서버에 요청을 보내는 구조를 구현하였다 [16, 37]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견됨에 따라 추후 applied/validated 승격 가능) +- **출처 신뢰도:** B (공식 문서 및 실제 오픈소스 프로젝트의 README/구현 코드를 바탕으로 함) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Comfy CLI.md b/10_Wiki/Comfyui/Comfy CLI.md new file mode 100644 index 00000000..ebe6a3ae --- /dev/null +++ b/10_Wiki/Comfyui/Comfy CLI.md @@ -0,0 +1,91 @@ +--- +id: comfy-cli +title: "Comfy CLI" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["comfy-cli"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["Comfy-Org/comfy-cli Issue #341"] +github_commit: "" +--- + +# [[Comfy CLI]] + +## 🎯 한 줄 통찰 (One-line insight) +GUI의 한계를 넘어 터미널 환경에서 워크플로우의 대량 관리, 메타데이터 복구 및 자동화된 실행을 지원하는 ComfyUI 생태계의 통합 명령줄 인터페이스 도구이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **헤드리스 자동화 (Headless Automation):** 웹 인터페이스 없이 명령줄에서 직접 워크플로우를 관리하고 실행할 수 있는 환경을 제공한다 [3, 4]. +2. **메타데이터 가공 및 복구:** 이미지 파일(PNG, WebP)이나 영상 파일(MP4)에 포함된 워크플로우 JSON을 추출, 삽입, 복사하는 기능을 통해 데이터의 영속성을 보장한다 [2]. +3. **배치 처리 (Batch Processing):** 대규모 이미지 저장소에서 워크플로우를 일괄적으로 추출하거나 관리하기 위한 효율적인 수단을 제공한다 [1, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **메타데이터 분리 전략:** `exiftool`과 같은 하위 수준 도구를 호출하거나 전용 CLI 라이브러리를 통해 이미지의 `tEXt` 또는 `zTXt` 청크에서 JSON 데이터를 격리하는 패턴을 사용한다 [1, 5, 6]. +- **통합 지원 구조:** 개별적으로 흩어진 `Workflow Extractor`, `Python API Converter` 등의 기능을 하나의 통합된 CLI(comfy-cli)로 수렴하여 관리 효율성을 극대화한다 [2]. + +## 📖 세부 내용 (Details) +Comfy CLI는 ComfyUI의 강력한 노드 기반 시스템을 터미널 및 프로그래밍 환경으로 확장하기 위해 설계되었습니다. + +- **워크플로우 추출 및 관리:** CLI 도구는 특히 대량의 이미지 파일에서 워크플로우를 복구하는 데 유용합니다. 사용자는 `exiftool -b -workflow input.png > workflow.json`과 같은 명령을 통해 시각적 메타데이터를 JSON 파일로 추출할 수 있으며, `Comfy_UI_prompt_extractor`와 같은 전문 CLI 도구는 긍정적 프롬프트, API 그래프, UI 레이아웃을 분리하여 생성하는 기능을 제공합니다 [1, 5]. +- **이미지 메타데이터 복원 기능:** GIMP와 같은 표준 이미지 편집기나 소셜 미디어 플랫폼은 파일 크기 최적화를 위해 메타데이터를 삭제하는 경우가 많습니다. CLI는 유실된 워크플로우 데이터를 다시 이미지에 삽입(Insert)하거나 다른 이미지로 복사(Copy)하는 기능을 지원하여 워크플로우의 이동성을 유지합니다 [2, 5, 6]. +- **워크플로우 전환 지원:** CLI 환경에서 [[Workflow JSON (Frontend Format)]]을 [[Workflow API JSON (Backend Format)]]으로 변환하거나, 아예 독립적으로 실행 가능한 Python 스크립트로 내보내는 기능을 결합하여 외부 애플리케이션과의 연동을 용이하게 합니다 [7, 8]. +- **설치 및 시스템 관리:** Comfy CLI는 ComfyUI 설치 가이드의 주요 항목으로 포함되어 있으며, 시스템 상태 확인(GPU VRAM, Python 버전 등) 및 노드 카탈로그 업데이트를 위한 도구로도 활용됩니다 [9-11]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **메타데이터 손상 주의:** 수동 드래그 앤 드롭 방식과 달리 CLI 도구는 대량 처리에 유리하지만, 압축 소프트웨어나 네트워크 전송 과정에서 메타데이터가 영구적으로 제거된 경우에는 CLI로도 복구가 불가능하다는 한계가 소스에서 지적됩니다 [6, 12]. +- **기능 통합 진행형:** 현재 `comfy-cli`는 이미지에서 워크플로우를 추출, 삽입, 복사하는 기능을 포함하도록 개발 및 제안 단계에 있으며, 이는 기존의 여러 개별 CLI 도구들을 대체하거나 통합하려는 시도로 분석됩니다 [2, 5]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Comfy-Org/comfy-cli Issue #341:** 이미지, WebP, MP4 등 지원되는 모든 매체에서 워크플로우를 추출, 삽입, 복사할 수 있는 기능을 `comfy-cli`에 포함시키기 위한 기능 제안 및 논의가 진행되었습니다 [2, 13]. +- **배치 워크플로우 복구:** 대규모 AI 아트 라이브러리에서 디지털 포렌식 기법을 사용하여 생성 기술을 유지하고 검색 가능한 라이브러리를 구축하는 데 활용되었습니다 [1]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 및 개발자 커뮤니티의 기능 제안을 기반으로 작성됨) +- **출처 신뢰도:** B (Official Documentation / GitHub Issue Discussion) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처 및 기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: CLI를 통해 JSON 워크플로우를 생성 및 관리하는 상위 주제임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: GUI 이외의 워크플로우 획득 경로. +- [[Workflow API JSON (Backend Format)]] + - 연결 이유: CLI 도구가 최종적으로 실행을 위해 변환하거나 추출해야 하는 타겟 형식임. + +#### [구현 및 활용 도구] +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: CLI 명령을 통해 워크플로우를 Python 코드로 변환하는 유사한 터미널 기반 도구임. +- [[ComfyUI-Manager]] + - 연결 이유: CLI에서 누락된 커스텀 노드를 감지하고 종속성을 해결할 때 상호 보완적으로 작동함. + +### 심층 후속 질문 (Deeper Research Questions) +- `comfy-cli`가 이미지 외에 영상(MP4) 메타데이터에서 워크플로우를 추출할 때 사용하는 구체적인 태그 구조는 무엇인가? +- `exiftool`을 이용한 수동 추출 방식과 `comfy-cli` 전용 명령어를 통한 추출 방식 사이의 데이터 무결성 차이는 존재하는가? +- CLI 환경에서 [[Workflow JSON (Frontend Format)]]을 거치지 않고 직접 API 전용 JSON을 이미지에 삽입하는 것이 가능한가? +- 대규모 배치 처리 시 노드 ID의 충돌이나 종속성 문제를 CLI에서 어떻게 자동으로 해결하는가? +- CLI 도구가 외부 이미지 편집기(GIMP 등)에 의해 삭제된 메타데이터를 복구하기 위한 'Shadow Backup' 전략을 가지고 있는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `comfyui-to-python` CLI를 사용하여 반복적인 생성 작업을 자동화하는 쉘 스크립트 작성 [8]. +- **System Design:** 서버 사이드에서 사용자로부터 업로드된 이미지를 받아 워크플로우를 자동 추출하여 데이터베이스화하는 파이프라인 설계 [1, 2]. +- **Operation / Maintenance:** ComfyUI 업데이트 시 `UpdateNodeCatalog` CLI 명령을 통해 노드 호환성을 일괄 점검 [10]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Metadata Extraction]] + - 확장 방향: AI 생성 이미지 내에 숨겨진 프롬프트 및 파라미터 데이터 보호 및 분석 기술. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source references 6, 33, 136, 170, 171, 182) \ No newline at end of file diff --git a/10_Wiki/Comfyui/Comfy GPT.md b/10_Wiki/Comfyui/Comfy GPT.md new file mode 100644 index 00000000..58de13e2 --- /dev/null +++ b/10_Wiki/Comfyui/Comfy GPT.md @@ -0,0 +1,102 @@ +--- +id: comfy-gpt +title: "Comfy GPT" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyGPT", "ComfyUI-WorkflowGenerator"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "LLM", "Automation"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["DanielPFlorian/ComfyUI-WorkflowGenerator", "xiatianzs/resources", "ComfyUI/models/LLM/"] +github_commit: "82df278" +--- + +# [[Comfy GPT]] + +## 🎯 한 줄 통찰 (One-line insight) +Comfy GPT는 자연어 설명을 실행 가능한 ComfyUI 노드 그래프(JSON)로 변환하여 '비주얼 프로그래밍'을 '대화형 프로그래밍'으로 격상시키는 다단계 AI 합성 프레임워크이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **자연어 기반 워크플로우 생성 (Natural Language Generation):** 사용자의 의도(예: "SDXL을 사용한 텍스트-이미지 워크플로우 생성")를 해석하여 복잡한 노드 연결 구조를 자동 생성한다 [2]. +2. **3단계 합성 파이프라인 (Three-stage Pipeline):** 논리적 구조 생성(Generator), 노드 이름 및 호환성 검증(Validator), 최종 실행 파일 컴파일(Builder)의 단계적 공정을 거친다 [3, 4]. +3. **의미론적 노드 검증 (Semantic Node Validation):** 생성된 노드가 로컬 환경에 존재하는지 확인하고, 임베딩 모델을 통해 가장 유사한 실제 노드로 자동 교정한다 [4-6]. +4. **도메인 특화 미세 조정 모델 (Fine-tuned Models):** ComfyUI의 내부 노드 레지스트리와 스키마 사양에 최적화된 LLM(예: Qwen2.5-14B)을 중추로 활용한다 [1, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **구조적 논리 합성 패턴:** 자연어 입력을 바로 JSON으로 변환하는 것이 아니라, 중간 단계의 논리적 그래프 구조를 먼저 형성한 후 컴파일한다 [4, 6]. +- **로컬 환경 동기화 패턴:** `UpdateNodeCatalog` 노드를 통해 사용자의 로컬 ComfyUI에 설치된 네이티브 및 커스텀 노드를 스캔하여 검증 기준(Catalog)을 최신화한다 [7, 8]. +- **하이브리드 검증 전략:** 속도를 위한 '의미론적 검색' 모드와 정확도를 위한 'LLM 정밀 교정' 모드를 선택적으로 사용하여 유효성을 확보한다 [6]. + +## 📖 세부 내용 (Details) +Comfy GPT는 **"ComfyGPT: A Self-Optimizing Multi-Agent System for Comprehensive ComfyUI Workflow Generation"** 연구에 기반한 기술적 구현체이다 [4]. 이 시스템은 전문적인 노드 지식이 없는 사용자도 대화를 통해 복잡한 생성 AI 파이프라인을 구축할 수 있게 돕는다 [2]. + +- **작동 메커니즘:** + - **Generator:** Qwen2.5-14B 기반 모델이 입력된 자연어를 분석하여 노드 간의 데이터 흐름(DAG)을 정의하는 논리적 JSON 문자열을 출력한다 [5, 6]. + - **NodeValidator:** 생성된 노드 이름이 실제 설치된 노드 클래스 명칭과 일치하는지 검사한다 [6]. 일치하지 않을 경우 `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` 모델을 사용한 의미론적 검색으로 가장 적합한 노드를 제안하거나, LLM이 문맥을 통해 이름을 수정한다 [5, 6]. + - **WorkflowBuilder:** 최종 검증된 구조를 ComfyUI 실행 엔진이 이해할 수 있는 표준 [[Workflow JSON]] v1.0 규격으로 변환하고 파일로 저장한다 [3, 8, 9]. +- **기술적 특징:** GGUF 양자화 모델(q8_0)을 지원하여 효율적인 VRAM 관리가 가능하며, CUDA 및 Metal 환경에서 가속화된 추론을 제공한다 [5, 10, 11]. 또한, JSON 파일은 생성 의도와 실행 로직 사이의 '중간 바이트코드' 역할을 수행하게 된다 [3]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정적 모델의 한계:** 미세 조정된 모델은 훈련 데이터 컷오프 시점 이후에 출시된 새로운 커스텀 노드나 아키텍처에 대해서는 기본적으로 알지 못하는 '동결된(Frozen)' 상태라는 점이 한계로 지적된다 [12, 13]. +- **할루시네이션 관리:** 모델이 존재하지 않는 노드 연결을 생성할 위험이 있으므로, 향후에는 정적 미세 조성을 넘어선 실시간 적응형 아키텍처로의 진화가 필요하다고 명시되어 있다 [13, 14]. + +## 🛠️ 적용 사례 (Applied in summary) +- **GitHub 프로젝트:** `DanielPFlorian/ComfyUI-WorkflowGenerator`가 ComfyGPT 연구를 로컬 노드 수트로 구현한 독립적 사례로 확인된다 [2, 15]. +- **Git 커밋 기록:** `82df278` 커밋에서 드롭다운의 중복 모델 노출 문제가 수정되었으며, `config`, `generators`, `nodes` 등의 디렉토리 구조로 관리된다 [15]. +- **모델 경로 사양:** 사용자는 GGUF 모델과 토크나이저를 `ComfyUI/models/LLM/` 경로에 배치하여 시스템을 구동한다 [7]. +- **저장 로직:** 생성된 워크플로우 JSON은 기본적으로 `comfyUI/output` 폴더에 저장되어 즉시 로드하거나 공유할 수 있다 [16]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 GitHub 프로젝트와 연구 논문이 존재하며 구현 가이드가 소스에 포함됨) [2, 4] +- **출처 신뢰도:** B (Official Documentation / GitHub Repository README via NotebookLM) [2] +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: Comfy GPT가 해결하고자 하는 근본적인 루트 주제. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 수동 생성 방식과 자동 생성 방식의 차이점. +- [[Workflow JSON]] + - 연결 이유: Comfy GPT 파이프라인의 최종 출력물 규격. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: v1.0 스키마 제약 사항 준수의 중요성. + +#### [구현/활용 도구] +- [[Workflow API JSON]] + - 연결 이유: 생성된 JSON이 API 호출에 사용될 때의 스트림라인 포맷. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각 정보가 제거된 실행 전용 그래프 구조. +- [[ComfyUI Manager]] + - 연결 이유: 생성된 워크플로우의 커스텀 노드 의존성을 해결하는 핵심 도구. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 'Red Nodes' 오류 발생 시의 복구 메커니즘. + +### 심층 후속 질문 (Deeper Research Questions) +- 훈련 데이터 컷오프 이후 출시된 최신 커스텀 노드에 대한 할루시네이션을 `NodeValidator`가 어느 정도 수준까지 교정할 수 있는가? [12] +- `UpdateNodeCatalog` 노드가 로컬의 `INPUT_TYPES`를 스캔하여 LLM에게 전달하는 컨텍스트 주입 방식은 구체적으로 어떻게 설계되어 있는가? [8] +- GGUF 양자화 모델 사용 시, q8_0와 q4_0 간의 워크플로우 논리 합성 정확도 차이가 유의미하게 발생하는가? [10] +- 3단계 파이프라인 중 `Generator`가 생성한 '논리적 그래프'와 최종 '실행용 JSON' 사이의 데이터 유실 가능성은 없는가? [6, 8] +- LLM 기반 생성 시 복잡한 `ControlNet`의 다중 레이어 연결이나 `IPAdapter` 설정의 세밀한 파라미터 제어가 가능한가? [2, 16] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `Workflow Generator Pipeline` 노드를 추가하고 자연어 지침을 입력하여 즉시 실행 가능한 그래프를 생성함 [7, 16]. +- **System Design:** 사용자의 로컬 환경에 맞춰진 `Node Catalog`를 기반으로 맞춤형 유효성 검사 루프를 구축함 [8]. +- **Operation / Maintenance:** 새로운 커스텀 노드 설치 후 반드시 `Update Node Catalog`를 실행하여 시스템의 지식 베이스를 동기화해야 함 [17]. +- **Learning Path:** 복잡한 노드 이름을 외우는 대신, 자연어로 기능을 설명하며 워크플로우 구축 원리를 학습하는 도구로 활용 가능 [2, 18]. + +### 인접 주변 주제 (Adjacent Topics) +- [[ComfyUI Custom Scripts]] + - 확장 방향: 자동 생성된 워크플로우를 시각적 이미지(PNG/SVG)로 내보내어 관리하는 방법 연구 [19, 20]. +- [[Executing ComfyUI Workflows as Standalone Scripts]] + - 확장 방향: LLM이 생성한 JSON을 서버리스 환경에서 즉시 Python 스크립트로 실행하는 자동화 파이프라인 구축 [21, 22]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [23] \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI API.md b/10_Wiki/Comfyui/ComfyUI API.md new file mode 100644 index 00000000..3beb658f --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI API.md @@ -0,0 +1,112 @@ +--- +id: comfyui-api +title: "ComfyUI API" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["API Format", "workflow_api.json"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "automation", "API"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: + - "comfyui-workflow-to-api-converter-endpoint (bc85382)" + - "ComfyUI-WorkflowGenerator (82df278)" + - "ComfyUI-to-Python-Extension (6cdcc23)" +github_commit: "" +--- + +# [[ComfyUI API]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI API는 노드 기반의 비주얼 워크플로를 **실행 가능한 데이터 구조(JSON)**로 직렬화하여, 창의적 프로세스를 자동화된 프로덕션 파이프라인으로 전환하는 핵심 인터페이스이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **API Format (workflow_api.json):** 사용자 인터페이스(UI) 메타데이터(노드 위치, 크기, 그룹 등)를 제거하고 오직 백엔드 엔진의 실행에 필요한 노드 유형과 입력 연결 정보만을 포함하는 간소화된 그래프 포맷이다 [3-5]. +- **Dev Mode Options:** API 포맷으로 워크플로를 내보내기 위해 반드시 활성화해야 하는 설정으로, 활성화 시 'Save (API format)' 버튼이 노출된다 [6-8]. +- **Serialization & Mapping:** 노드망을 JSON 형식의 딕셔너리로 변환하며, 각 노드는 고유한 numeric ID(예: "37")를 키로 사용하여 `class_type`과 `inputs` 값을 정의한다 [9-11]. +- **Prompt Endpoint (/prompt):** 생성된 API JSON 페이로드를 ComfyUI 서버의 `/prompt` 엔드포인트로 POST 요청을 보내 실제 실행을 트리거한다 [10, 12]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Execution Model Inversion:** 엔진이 모든 노드를 실행하는 대신 'Save Image'와 같은 출력 노드에서 역방향으로 탐색하여 최종 결과에 필요한 의존성 노드만 식별하고 실행한다 [13]. +- **Bifurcation of Formats:** 시각적 편집을 위한 Frontend 포맷(`workflow.json`)과 프로그래밍적 실행을 위한 Backend 포맷(`workflow_api.json`)을 분리하여 운영 효율성을 극대화한다 [3, 14]. +- **Metadata Recovery:** PNG 파일의 `tEXt` 또는 `zTXt` 청크에 숨겨진 워크플로 JSON 데이터를 `exiftool`이나 전용 추출기를 통해 복구하여 공유 및 재사용하는 패턴이 발견된다 [15-17]. + +## 📖 세부 내용 (Details) + +### 1. API JSON 생성 및 구조적 특징 +API 포맷 JSON은 백엔드 실행 최적화를 위해 설계되었다. +- **데이터 구조:** 루트 키는 노드 ID(문자열)이며, 각 값은 `class_type`과 `inputs` 딕셔너리를 포함한다 [10, 18]. +- **연결 표현:** 노드 간의 링크는 별도의 배열이 아닌 노드 입력 내에서 `[origin_node_id, output_slot_index]` 형태의 참조로 직접 임베딩된다 [3, 19]. +- **위젯 값 전환:** GUI에서 사용자가 입력한 위젯 값(시드, 텍스트 등)은 API JSON의 `inputs` 필드로 직접 매핑되어 고정된 값이 된다 [19]. + +### 2. 프로그래밍적 조작 및 자동화 +개발자는 템플릿화된 API JSON을 Python 등을 통해 동적으로 수정하여 대량 생성을 자동화할 수 있다. +- **입력값 교체:** `json` 라이브러리를 사용하여 특정 노드 ID의 `inputs` 필드(예: 프롬프트 텍스트, 시드 값)를 런타임에 변경한다 [10, 20]. +- **이미지 주입:** 외부 이미지를 API로 전달할 때는 `Load Image (Base64)` 노드를 사용하거나 이미지를 서버의 `input` 디렉토리에 업로드한 후 파일명으로 참조한다 [21, 22]. +- **결과 수신:** 생성 진행 상황과 결과 이미지는 WebSocket 통신을 통해 실시간으로 모니터링하며, `SaveImageWebsocket` 노드를 사용하여 바이너리 데이터를 직접 수신할 수 있다 [22]. + +### 3. 고도화된 생성 도구 +- **ComfyUI-to-Python-Extension:** JSON 워크플로를 독립적으로 실행 가능한 `.py` 스크립트로 변환하여 서버 없이도 헤드리스 환경에서 실행 가능하게 한다 [23, 24]. +- **Comfy API Simplified:** 노드 ID 대신 사용자가 지정한 노드 제목(title)으로 파라미터를 설정할 수 있게 하여 워크플로 수정 시 코드의 파손을 방지한다 [23, 25]. +- **LLM 기반 생성:** 자연어 설명을 입력하면 Qwen2.5와 같은 모델이 이를 해석하여 유효한 노드 그래프 구조를 자동으로 생성하고 빌드한다 [26, 27]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **하위 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [28]. +- **포맷의 비가역성:** API 포맷 JSON은 실행 효율은 높으나, 이를 다시 GUI로 드래그하여 로드할 경우 시각적 레이아웃(노드 위치 등)이 유실된 '스켈레톤' 상태로 나타나 편집이 어렵다 [12, 29]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드의 JS 로직을 Python으로 변환하여 서버 측에서 일반 JSON을 API JSON으로 즉시 변환하는 엔드포인트를 구현함 (커밋: bc85382) [12, 30]. +- **ComfyUI-WorkflowGenerator:** 자연어 프롬프트를 기반으로 3단계 파이프라인(생성-검증-빌드)을 거쳐 실행 가능한 워크플로를 생성하는 시스템 (커밋: 82df278) [27, 31]. +- **ComfyUI-to-Python-Extension:** 워크플로를 Python 코드로 번역하여 자동화 및 반복 생성에 최적화된 스크립트를 제공함 (커밋: 6cdcc23) [24, 32]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (다수의 GitHub 프로젝트를 통해 실용성 입증됨) +- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 README 기반) +- **중복 검사 결과:** 신규 생성 + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow JSON]] + - 연결 이유: API 데이터의 근간이 되는 스키마 규격 + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 속성 및 링크 스키마 v1.0의 기술적 제약 사항 [33]. + +#### [구현/활용 도구] +- [[API Format]] + - 연결 이유: ComfyUI 서버 통신을 위한 필수 데이터 포맷 + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 메타데이터 제거 및 실행 최적화 로직 [5]. +- [[ComfyUI-Manager]] + - 연결 이유: API 실행 시 누락된 커스텀 노드 의존성 해결 도구 + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 `class_type`을 기반으로 한 자동 노드 설치 프로세스 [34]. + +### 심층 후속 질문 (Deeper Research Questions) +- API JSON의 `inputs` 필드에서 노드 참조 시 사용되는 슬롯 인덱스의 정확한 매핑 규칙은 무엇인가? [35] +- `Execution Model Inversion`이 대규모 워크플로에서 실제 성능(VRAM/연산)에 미치는 정량적 영향은 어느 정도인가? [13] +- LLM 기반 워크플로 생성 시 `NodeValidator`가 사용하는 시맨틱 임베딩 방식은 커스텀 노드의 정확도를 어떻게 보장하는가? [36, 37] +- PNG 메타데이터가 손상된 경우, `exiftool` 외에 바이너리 수준에서 워크플로를 복구할 수 있는 대안적 방법이 있는가? [17, 38] +- `comfyui-workflow-to-api-converter`가 처리하는 1MB 요청 제한의 기술적 근거와 대규모 워크플로(Flux 등) 대응 방안은 무엇인가? [39, 40] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `/prompt` 엔드포인트에 전송할 JSON 페이로드를 생성하기 위해 GUI의 'Dev mode'를 활용하여 템플릿을 확보한다 [8]. +- **System Design:** 프로덕션 환경에서는 사용자의 입력을 수신하는 미들웨어를 구축하고, 템플릿 JSON의 특정 노드 ID 값을 동적으로 치환하여 ComfyUI 인스턴스에 전달한다 [22, 41]. +- **Operation / Maintenance:** 워크플로 변경 시 노드 ID가 변할 수 있으므로, 유지보수성을 위해 `comfy_api_simplified`와 같이 노드 제목 기반으로 접근하는 래퍼 사용을 권장한다 [23, 25]. +- **Learning Path:** 기본 UI 사용법 숙지 → Dev mode 활성화 및 API JSON 구조 분석 → Python `requests` 및 `websocket`을 이용한 원격 제어 순으로 학습한다 [42, 43]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Comfy GPT]] + - 확장 방향: AI 에이전트가 직접 노드를 조립하고 디버깅하는 자가 최적화 시스템 연구 [27, 44]. +- [[Model Hashing]] + - 확장 방향: 파일명 대신 해시값을 사용하여 API 호출 시 모델 불일치 문제를 해결하는 기술 [45]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI Backend Engine.md b/10_Wiki/Comfyui/ComfyUI Backend Engine.md new file mode 100644 index 00000000..58667332 --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI Backend Engine.md @@ -0,0 +1,100 @@ +--- +id: comfyui-backend-engine +title: "ComfyUI Backend Engine" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI API Engine", "ComfyUI Execution Layer"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes/comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "WorkflowExecutor", "ExecutionCache"] +github_commit: "bc85382" +--- + +# [[ComfyUI Backend Engine]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI Backend Engine은 복잡한 노드 그래프(DAG)를 실행 가능한 [[API 포맷]]으로 직렬화하고, 역방향 의존성 추적을 통해 최적화된 상태로 머신러닝 워크플로우를 처리하는 핵심 실행 계층이다. [1-3] + +## 🧠 핵심 개념 (Core concepts) +1. **API JSON (Backend Format):** UI 메타데이터(좌표, 크기 등)를 제거하고 노드 클래스(class_type)와 입력(inputs) 간의 논리적 연결만 포함된 정제된 실행 데이터 구조이다. [2, 4, 5] +2. **Execution Model Inversion:** 최종 출력 노드(예: Save Image)에서 시작하여 필요한 의존성만 역방향으로 탐색해 실행함으로써 불필요한 노드 연산을 배제하는 최적화 기법이다. [3] +3. **Standalone Script Execution:** 웹 서버와 UI 계층을 분리하여 워크플로우를 독립적인 Python 스크립트나 헤드리스(Headless) 파이프라인으로 구동하는 메커니즘이다. [6-8] +4. **Dynamic Prompting:** API 엔드포인트(/prompt)에 JSON 페이로드를 전송할 때 노드 ID나 타이틀을 기반으로 파라미터를 실시간으로 수정하여 동적 워크플로우를 생성한다. [9-11] + +## 🧩 추출된 패턴 (Extracted patterns) +- **Serialization Bifurcation (직렬화 이원화):** 시각적 편집을 위한 'Frontend 포맷'과 서버 실행을 위한 'Backend API 포맷'으로 워크플로우를 구분하여 관리한다. [2, 12] +- **Backward Dependency Traversal:** 그래프 전체를 순차 실행하는 대신, 결과값 도출에 필수적인 노드들만 선별하여 실행 순서를 결정한다. [3] +- **Target Node Overriding:** JSON 내부의 특정 노드 ID를 키값으로 활용하여 시드(Seed), 프롬프트, 모델 경로 등의 값을 프로그래밍 방식으로 교체한다. [10, 13, 14] + +## 📖 세부 내용 (Details) + +ComfyUI의 백엔드 엔진은 워크플로우를 **유향 비순환 그래프(DAG)**로 처리하며, 이를 직렬화(Serialization)하여 기기 간 이식성과 프로그래밍 자동화를 지원한다. [1] 워크플로우를 API로 실행하기 위해서는 표준 JSON 포맷이 아닌 'API 전용 포맷'이 필수적이며, 이는 ComfyUI 설정 메뉴에서 **"Dev mode Options"**를 활성화해야 내보내기가 가능하다. [15-17] + +### 1. JSON 포맷의 구조적 차이 +- **Frontend JSON (workflow.json):** `nodes` 배열 안에 위치 정보(`pos`), 크기(`size`), 그룹 정보 등 UI 레이아웃 메타데이터가 포함된다. 연결은 별도의 `links` 배열에서 관리된다. [18-20] +- **API JSON (workflow_api.json):** 노드 ID가 루트 키인 딕셔너리 구조이며, UI 관련 정보가 모두 제거된다. 링크 정보는 노드 입력값 내에 직접 참조(예: `[node_id, output_slot]`) 형태로 포함되어 훨씬 컴팩트하다. [4, 18, 21, 22] + +### 2. 실행 및 최적화 메커니즘 +백엔드 엔진은 **/prompt 엔드포인트**를 통해 수신된 JSON을 분석한다. [13, 18] 엔진의 **Execution Model Inversion** 아키텍처는 그래프에 수십 개의 노드가 있더라도 최종 결과 노드에 연결되지 않은 노드는 완전히 무시하여 자원을 최적화한다. [3] 또한, `WorkflowExecutor`와 `ExecutionCache` 같은 클래스를 활용하면 서버 환경 없이도 독립적인 Python 환경에서 워크플로우를 실행할 수 있다. [9, 23] + +### 3. 프로그래밍적 확장성 +개발자는 Python의 `json` 라이브러리를 사용하여 로드된 워크플로우 객체의 특정 노드 값을 변경한 뒤 API 서버로 전송할 수 있다. [13, 24] 이 과정에서 노드 ID가 고정되지 않아 발생하는 유지보수 문제는 **Comfy API Simplified**와 같은 래퍼 라이브러리를 사용하여 노드의 제목(Title)으로 접근함으로써 해결할 수 있다. [11, 25] 최근에는 LLM을 활용해 자연어를 이 API 형식의 JSON으로 변환해주는 **ComfyUI-WorkflowGenerator** 기술도 도입되고 있다. [26, 27] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **포맷 호환성 이슈:** 표준 JSON 파일을 API 엔드포인트로 직접 보내면 에러가 발생하며, 반드시 API 포맷으로 변환해야 한다. [28] +- **API 포맷의 역변환 한계:** API 포맷 JSON을 UI로 불러오면 노드의 시각적 정보(위치, 크기 등)가 누락되어 분석 및 편집이 어려운 '스켈레톤' 상태로 로드된다. [29] +- **버전 호환성:** ComfyUI는 업데이트가 매우 빈번하여, 구버전 JSON이 최신 버전 백엔드에서 작동하지 않을 수 있으므로 주의가 필요하다. [30] + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측 JavaScript 로직을 Python으로 변환하여 서버사이드에서 non-API 포맷을 API 포맷으로 자동 변환해주는 엔드포인트(/workflow/convert)를 제공한다. [28, 31] +- **ComfyUI-to-Python-Extension:** 워크플로우를 실행 가능한 `.py` 스크립트로 변환하여 헤드리스 환경에서 실행할 수 있게 한다. [7, 8] +- **WorkflowExecutor & ExecutionCache:** 소스 코드 레벨에서 ComfyUI 워크플로우의 실행과 결과 캐싱을 관리하는 핵심 클래스 구현체이다. [9, 23] +- **P-Reinforce 관련:** LLM 기반 자동 워크플로우 생성 파이프라인(Generator -> Validator -> Builder)에서 최종 실행 객체로 활용된다. [32, 33] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견됨) +- **출처 신뢰도:** B (공식 문서 및 GitHub 기술 문서를 기반으로 합성됨) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[API JSON]] + - 연결 이유: 백엔드 엔진이 직접적으로 해석하고 실행하는 유일한 데이터 포맷이다. [4] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 데이터 흐름의 실제 직렬화 방식. [2, 21] + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 백엔드 엔진 실행 시 누락된 커스텀 노드 의존성을 해결하는 필수 도구이다. [34, 35] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내부의 class_type 정보를 기반으로 한 종속성 관리 메커니즘. [34] + +### 심층 후속 질문 (Deeper Research Questions) +- Execution Model Inversion이 복잡한 순환 구조(실제로는 DAG지만 복잡한 경우)에서 어떻게 성능을 최적화하는가? +- API 포맷 JSON에서 사용자 정의 노드(Custom Nodes)의 버전 관리 정보를 포함할 수 있는 방법은 무엇인가? [36] +- Standalone 실행 시 `ExecutionCache`가 GPU VRAM 자원을 효율적으로 해제하거나 재사용하는 구체적인 로직은 무엇인가? [23] +- `workflow_api.json` 내의 노드 ID를 수동 조작하지 않고 프로그래밍적으로 매핑할 수 있는 가장 안정적인 라이브러리는 무엇인가? [25] +- LLM 기반 생성기에서 `NodeValidator`가 지원하지 않는 새로운 커스텀 노드를 인식하게 하는 방법은 무엇인가? [37] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 웹 서비스 백엔드에서 사용자가 입력한 프롬프트를 JSON에 주입하고 ComfyUI API로 요청을 보내 이미지 생성 결과를 받아오는 데 활용된다. [24, 38] +- **System Design:** 헤드리스 렌더링 서버나 CI/CD 파이프라인에서 생성 AI 워크플로우를 자동 테스트하는 용도로 설계된다. [7, 8] +- **Operation / Maintenance:** ComfyUI Manager를 통해 백엔드에서 필요한 모델과 노드를 자동 설치하여 배포 프로세스를 간소화한다. [34] +- **Learning Path:** GUI를 통한 실험 단계에서 JSON 스키마를 이해하고, 이후 Python API를 통한 대량 생성 자동화 단계로 넘어가는 핵심 관문이다. [10, 39] + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: 백엔드에서 파일명 대신 해시값을 통해 정확한 모델 가중치를 로드하는 안정성 확보 방안 연구. [40] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Ref: [1-4, 9, 28]) \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI Manager.md b/10_Wiki/Comfyui/ComfyUI Manager.md new file mode 100644 index 00000000..f8e37eea --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI Manager.md @@ -0,0 +1,94 @@ +--- +id: comfyui-manager +title: "ComfyUI Manager" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI-Manager"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes/ComfyUI-Manager"] +github_commit: "" +--- + +# [[ComfyUI Manager]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우의 **의존성 자동 해결** 및 **중앙 집중식 자원 관리**를 통해 JSON 워크플로우의 이식성과 재현성을 보장하는 핵심 확장 도구 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **의존성 해결 (Dependency Resolution):** 외부에서 로드된 JSON 파일을 분석하여 누락된 커스텀 노드 패키지를 식별하고 설치를 지원함 [1]. +- **커스텀 노드 및 모델 관리 (Nodes & Models Management):** 수천 개의 커스텀 노드와 체크포인트, LoRA, VAE 등 모델 가중치를 GUI 환경에서 검색하고 원클릭으로 설치 및 업데이트함 [2, 3]. +- **워크플로우 발견 (Workflow Discovery):** 관리자 인터페이스 내에서 ComfyWorkflows, OpenArt 등의 플랫폼과 연동하여 워크플로우를 탐색하고 직접 다운로드함 [4]. +- **보안 및 환경 설정 (Security & Config):** 서버 보안 수준에 따른 실행 제한 관리 및 터미널 로그 확인 등 시스템 유틸리티 기능을 제공함 [5, 6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **누락 노드 복구 패턴 (Red Box Recovery):** 외부 워크플로우(JSON/PNG) 로드 시 빨간색 상자가 나타나면 "Install Missing Custom Nodes" 기능을 통해 필요한 노드를 일괄 설치한 후 서버를 재시작하여 복구함 [1, 7]. +- **의존성 명시 패턴 (Dependency Marking):** 특정 노드(예: Workflow to API Converter)는 '마커 노드'를 워크플로우에 포함시켜 ComfyUI Manager가 해당 워크플로우의 의존성을 더 정확하게 감지하도록 유도함 [8, 9]. +- **모델 검색 및 해싱 패턴:** 파일명 대신 모델의 SHA-256 해시를 사용하여 서로 다른 시스템 간의 모델 경로 및 이름 불일치 문제를 해결함 [10]. + +## 📖 세부 내용 (Details) +ComfyUI Manager는 `ltdrdata`가 개발한 커스텀 노드로, ComfyUI 생태계의 복잡한 노드 간 연결과 모델 의존성을 관리하는 중추적인 역할을 수행합니다 [2]. + +- **설치 및 구조:** 사용자는 `ComfyUI/custom_nodes` 디렉토리에 해당 저장소를 `git clone` 하여 설치할 수 있으며, 설치 후 UI에 관리 메뉴가 통합됩니다 [2]. +- **JSON 워크플로우와의 관계:** ComfyUI는 노드 기반의 비순환 유향 그래프(DAG)를 JSON으로 직렬화하여 공유하는데, 이때 제작자와 사용자의 환경이 다를 경우 발생하는 노드 누락 문제를 해결하는 것이 Manager의 주된 임무입니다 [1, 11]. +- **기능 인터페이스:** + - **Install Custom Nodes:** 사용 가능한 모든 커스텀 노드 목록을 조회하고 설치합니다 [2]. + - **Install Models:** 모델 체크포인트, ControlNet, LoRA 등을 카테고리별로 검색하여 다운로드할 수 있습니다 [3]. + - **Update/Fetch:** ComfyUI 자체 및 설치된 노드들의 최신 버전을 유지합니다 [2]. +- **고급 유틸리티:** 사용자 설정 메뉴에서 "Enable Dev mode Options"를 활성화하면 API 포맷의 JSON 내보내기가 가능해지며, Manager는 이 과정에서 의존성 정보를 포함하거나 누락된 요소를 진단하는 보조 도구로 활용됩니다 [12, 13]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **보안 오류:** ComfyUI Manager 사용 시 보안 설정 수준에 따라 'This action is not allowed' 오류가 발생할 수 있으며, 이는 환경 설정 파일 수정을 통한 해결이 필요합니다 [5, 6]. +- **노드 관리 방식의 변화:** 새로운 노드 매니저(기본 Windows 빌드 포함)에서는 일부 레거시 커스텀 노드 매니저가 보이지 않을 수 있으며, 필요시 레거시 모드를 활성화해야 합니다 [14]. + +## 🛠️ 적용 사례 (Applied in summary) +- **실제 파일 경로:** `ComfyUI/custom_nodes/ComfyUI-Manager` 경로에 위치하며 시스템이 시작될 때 로드됩니다 [2]. +- **워크플로우 진단:** 외부 플랫폼(Civitai, MimicPC 등)에서 다운로드한 JSON 워크플로우를 분석하여 로컬 환경에 없는 노드를 식별하는 과정에 적용됩니다 [1, 12]. +- **의존성 보증:** `comfyui-workflow-to-api-converter-endpoint` 프로젝트에서 Manager가 해당 노드의 의존성을 탐지할 수 있도록 "Workflow to API Converter (Marker)" 노드를 제공하는 사례가 확인됩니다 [8, 9]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual +- **출처 신뢰도:** B (Official Documentation / ComfyUI-Wiki / Primary YouTube Tutorials) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 + +### 상위/유사 개념 +- [[Workflow.json (Frontend Format)]] + - 연결 이유: Manager가 분석하고 누락된 요소를 채워 넣는 주된 대상 파일 포맷입니다 [1, 15]. +- [[Custom Nodes]] + - 연결 이유: Manager가 관리하는 핵심 객체이며, 워크플로우의 기능을 확장하는 단위입니다 [2, 16]. +- [[Workflow API JSON]] + - 연결 이유: API 실행을 위해 UI 메타데이터를 제거한 최적화된 JSON 형태이며, Manager는 이 과정에서의 의존성을 확인합니다 [1, 17]. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI Manager가 JSON 파일을 파싱하여 누락된 노드의 GitHub 저장소 주소를 정확히 찾아내는 메커니즘은 무엇인가? +- 모델 해싱(SHA-256)을 통한 모델 관리 방식은 파일명 기반 관리와 비교했을 때 이식성 측면에서 구체적으로 어떤 이점을 제공하는가? [10] +- 'Terminal Log (Manager)' 노드는 실시간 디버깅 및 JSON 실행 오류 분석에서 어떤 데이터를 제공하는가? [6] +- Manager의 보안 수준(Security Level)이 'This action is not allowed' 오류를 유발하는 구체적인 임계 조건은 무엇인가? [6] +- 워크플로우 패키징 기능(`comfy-pack`)과 Manager의 의존성 해결 기능은 상호 보완적인가 아니면 독립적인 대안인가? [10, 18] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `git clone`을 통해 `custom_nodes` 폴더에 설치 후, UI의 "Manager" 버튼을 통해 모든 조작을 수행합니다 [2]. +- **System Design:** 외부 API 서버 구축 시 필요한 모든 커스텀 노드와 모델이 사전에 설치되었는지 확인하는 검증 도구로 활용합니다 [1, 19]. +- **Operation / Maintenance:** ComfyUI 및 커스텀 노드들의 업데이트를 주기적으로 체크하여 환경의 안정성을 유지합니다 [2]. +- **Learning Path:** 초보자가 복잡한 워크플로우를 분석하기 전, 누락된 노드 문제를 해결하는 첫 번째 단계로 학습합니다 [7]. + +### 인접 주변 주제 (Adjacent Topics) +- [[ComfyUI Workspace Manager]] + - 확장 방향: 워크플로우를 시각적으로 조직하고 백업하는 특화된 관리 기능을 제공합니다 [20]. +- [[Comfy CLI]] + - 확장 방향: 명령줄 인터페이스를 통해 워크플로우 추출 및 의존성 관리를 수행하는 도구입니다 [21]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine.--- \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI Workflow Extractor.md b/10_Wiki/Comfyui/ComfyUI Workflow Extractor.md new file mode 100644 index 00000000..2210ef68 --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI Workflow Extractor.md @@ -0,0 +1,66 @@ +--- +id: comfyui-workflow-extractor +title: "ComfyUI Workflow Extractor" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["SethRobinson/comfyui-workflow-to-api-converter-endpoint (bc85382)", "Comfy-Org/comfy-cli issue #341", "exiftool CLI implementation"] +github_commit: "bc85382" +--- + +# [[ComfyUI Workflow Extractor]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 생성 이미지의 메타데이터(PNG Chunks)에 내장된 워크플로우 논리를 추출하여 유실된 노드 그래프를 복구하고 재사용 가능한 JSON으로 변환하는 필수 기술. [1-3] + +## 🧠 핵심 개념 (Core concepts) +- **메타데이터 임베딩 (Metadata Embedding):** ComfyUI의 'Save Image' 노드는 실행 시 전체 노드 그래프, 레이아웃, 설정 및 프롬프트를 PNG 파일의 숨겨진 메타데이터에 주입함. [4, 5] +- **PNG 청크 분석 (PNG Chunk Analysis):** 주로 `tEXt` 또는 `zTXt` 청크를 사용하여 워크플로우(Frontend 형식)와 프롬프트(API 형식)라는 두 가지 고유한 문자열을 저장함. [2] +- **데이터 복구 및 변환 (Data Recovery & Conversion):** 이미지 편집기나 소셜 미디어 플랫폼에 의해 제거될 수 있는 취약한 메타데이터를 독립적인 JSON 파일로 추출하여 공유 및 백업 가능성을 확보함. [1, 2] +- **추출 도구 생태계 (Extraction Tool Ecosystem):** 웹 기반 인터페이스부터 명령줄 도구(CLI), Python 라이브러리 및 하이 레벨 스크립트에 이르기까지 다양한 복구 경로가 존재함. [3, 6] + +## 🧩 추출된 패턴 (Extracted patterns) +- **바이너리 태그 격리 패턴:** `exiftool`과 같은 유틸리티를 사용하여 미디어 파일 내의 특정 바이너리 태그(`-workflow`)만을 분리하여 표준 JSON 파일로 출력하는 전략을 취함. [3, 6] +- **드래그 앤 드롭 로딩 메커니즘:** 추출 프로세스를 수동으로 수행하는 대신, 메타데이터가 포함된 이미지를 ComfyUI 캔버스에 직접 드롭하여 즉각적으로 노드 레이아웃을 재구성함. [4, 7, 8] +- **자동화된 배치 처리:** 대량의 이미지 저장소에서 워크플로우를 대규모로 수집하기 위해 디렉토리 전체를 스캔하고 API 그래프와 UI 레이아웃을 별도의 JSON으로 생성하는 배치 프로세싱 패턴이 발견됨. [3] + +## 📖 세부 내용 (Details) +ComfyUI Workflow Extractor는 이미지 파일 내에 직렬화된 데이터 구조를 파싱하는 전문화된 도구 모음을 의미함. ComfyUI에서 생성된 거의 모든 PNG 파일은 그 자체가 워크플로우의 운반체 역할을 하며, 이는 'Save Image' 노드가 실행될 때 최종 이미지와 함께 전체 노드 그래프를 인젝션하기 때문임. [4, 5] + +이 기술의 핵심은 PNG 규격 내의 비필수 메타데이터 영역을 활용하는 것임. 구체적으로 `tEXt` 또는 `zTXt` 청크에 두 가지 형식의 데이터를 저장하는데, 하나는 시각적 배치를 포함한 **Frontend 워크플로우**이고, 다른 하나는 실행을 위한 최적화된 **Backend API 프롬프트**임. [2] 이러한 데이터는 매우 취약하여 이미지 압축 소프트웨어나 소셜 네트워크 서비스를 거칠 경우 유실될 가능성이 높으므로, 워크플로우 추출기는 이러한 유실이 발생하기 전 혹은 저장된 라이브러리로부터 지식을 추출하는 데 중요함. [1, 2, 7] + +전문적인 추출 방법으로는 다음과 같은 것들이 존재함: +- **CLI 기반 도구:** `exiftool -b -workflow input.png > workflow.json`과 같은 명령어를 통해 바이너리 데이터를 직접 추출하거나, `ComfyUI_prompt_extractor`와 같은 전용 스크립트를 사용하여 긍정적 프롬프트와 API 그래프를 분리함. [3, 6] +- **웹 인터페이스 도구:** 'Weird Wonderful AI Art'에서 제공하는 추출기와 같이 사용자가 이미지를 업로드하면 서버 측 처리 없이(또는 보안 처리 후) 즉시 JSON 데이터를 반환하는 방식임. [1, 9] +- **통합 확장 도구:** `ComfyUI-to-Python-Extension`과 같은 도구는 추출된 워크플로우를 실행 가능한 Python 스크립트로 변환하여 헤드리스 환경에서 자동화할 수 있게 함. [10, 11] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **데이터 무결성 문제:** PNG 이미지 드래그 방식은 간편하지만, 새로 추가된 노드나 특정 커스텀 노드가 메타데이터에 올바르게 포함되지 않아 복구 시 일부 정보가 누락될 수 있다는 경고가 소스에서 확인됨. [5] +- **형식 간 충돌:** 추출 도구는 'Frontend JSON'과 'API JSON'을 구분해야 함. API 포맷은 시각적 정보(노드 위치, 크기 등)가 제거된 상태이므로 이를 다시 ComfyUI UI로 드래그하면 시각적으로 불완전한 상태로 로드될 수 있음. [12, 13] +- **메타데이터 파괴성:** 많은 표준 이미지 편집기(GIMP 등)는 이미지 저장 시 비표준 메타데이터 청크를 제거하므로, 원본 워크플로우를 유지하려면 전용 삽입/복사 도구가 필요함이 제기됨. [14] + +## 🛠️ 적용 사례 (Applied in summary) +- **SethRobinson/comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측의 자바스크립트 논리를 파이썬으로 변환하여 서버 측에서 비-API 워크플로우 형식을 API 형식으로 변환하는 `/workflow/convert` 엔드포인트를 구현함 (Commit: `bc85382`). [15, 16] +- **Comfy-Org/comfy-cli Issue #341:** 이미지뿐만 아니라 webp, mp4 등 지원되는 모든 미디어에서 워크플로우를 추출, 삽입, 복사하는 기능을 `comfy-cli`에 추가하려는 논의와 `exiftool` 활용 사례가 기록됨. [6, 14, 17] +- **WeirdWonderfulAI.Art:** 약 21,460개 이상의 워크플로우를 추출한 통계를 보유한 웹 기반 추출 도구 서비스를 운영 중임. [9] +- **exiftool CLI:** `exiftool -b -workflow` 명령을 통해 PNG에서 바이너리 워크플로우 데이터를 격리하는 표준적인 디지털 포렌식 기법으로 활용됨. [3, 6] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견으로 검증 가능성 높음) +- **출처 신뢰도:** B (Official Documentation / GitHub Issue / Technical Guides) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI Workflow JSON Generation and Serialization.md b/10_Wiki/Comfyui/ComfyUI Workflow JSON Generation and Serialization.md new file mode 100644 index 00000000..c3d80749 --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI Workflow JSON Generation and Serialization.md @@ -0,0 +1,102 @@ +--- +id: comfyui-workflow-json-generation-and-serialization +title: "ComfyUI Workflow JSON Generation and Serialization" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI Workflow JSON 생성 및 직렬화"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "ComfyUI API", "Serialization"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint", "comfyui_to_python.py", "WorkflowGenerator Pipeline", "/workflow/convert endpoint", "comfy_api_simplified"] +github_commit: "bc85382" +--- + +# [[ComfyUI Workflow JSON Generation and Serialization]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우 직렬화는 시각적 노드 그래프를 실행 가능한 계층적 JSON 구조(Frontend vs. API)로 변환하여 생성 AI 파이프라인의 이식성, 자동화 및 프로그래밍적 제어를 가능케 하는 핵심 메커니즘이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **JSON 포맷의 이분화 (Frontend vs. API)**: 시각적 편집과 레이아웃 정보를 포함하는 '프론트엔드 포맷(workflow.json)'과 실행 엔진에 최적화되어 UI 메타데이터가 제거된 '백엔드/API 포맷(workflow_api.json)'으로 나뉜다 [2, 3]. +- **메타데이터 임베딩 (Steganography)**: 워크플로우 데이터를 PNG, WebP 등의 이미지 파일 내부 텍스트 청크(tEXt/zTXt)에 숨겨 이미지 자체가 워크플로우 소스 코드 역할을 하게 한다 [4-6]. +- **JSON v1.0 스키마 표준**: 노드 ID, 클래스 타입, 위젯 값, 슬롯 기반 링크 연결 등을 정의하는 기술적 제약 조건 모음이다 [7, 8]. +- **실행 모델 역전 (Execution Model Inversion)**: 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색함으로써 필요한 의존성만 식별하여 실행을 최적화한다 [9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **수동 내보내기 프로토콜**: 설정 메뉴에서 'Dev mode Options'를 활성화하여 API 전용 JSON을 추출하거나, 표준 저장을 통해 UI 포함 JSON을 생성한다 [10-12]. +- **프로그래밍적 매개변수 변조**: JSON을 딕셔너리 객체로 로드한 후 특정 노드 ID의 `inputs` 값을 수정하여 시드(seed)나 프롬프트를 동적으로 변경한다 [13, 14]. +- **3단계 LLM 파이프라인**: 자연어 지시를 받아 '논리적 합성(Generator) -> 시맨틱 검증(Validator) -> 그래프 컴파일(Builder)' 과정을 거쳐 워크플로우를 자동 생성한다 [15-17]. +- **서버측 포맷 변환**: 클라이언트 자바스크립트 없이 서버 내부 노드 레지스트리를 참조하여 비 API 포맷을 API 포맷으로 변환하는 `/workflow/convert` 엔드포인트 패턴이다 [18, 19]. + +## 📖 세부 내용 (Details) +ComfyUI는 생성 프로세스를 **유향 비순환 그래프(DAG)**로 취급하며, 이를 JSON으로 직렬화하는 과정은 크게 두 가지 경로로 진행된다 [1]. + +첫째, **프론트엔드 JSON(workflow.json)**은 Litegraph 표준을 따르며 노드의 좌표, 크기, 그룹화 정보와 같은 시각적 메타데이터를 포함한다 [2, 20]. 이는 주로 사용자 인터페이스에서의 편집과 공유를 목적으로 한다 [3]. + +둘째, **API JSON(workflow_api.json)**은 실제 실행에 필요한 논리만을 남긴 스트림라인화된 그래프이다 [2]. 여기서는 링크가 별도의 객체가 아니라 노드 입력 내부에 직접 삽입된 참조 형태(`[origin_node_id, output_slot_index]`)로 표현된다 [2, 21]. + +기술적으로 **JSON v1.0 스키마**는 `nodes` 배열 내의 각 객체가 `id`, `type`, `pos`, `size`, `widgets_values`, `mode` 등의 속성을 가질 것을 요구한다 [7]. 특히 연결(Connectivity)은 입력 슬롯과 출력 슬롯의 고유 인덱스를 통해 정의되며, 이는 VAE Loader와 같이 여러 출력을 가진 노드에서 정확한 데이터 흐름을 보장하는 데 필수적이다 [22]. + +최근에는 **ComfyGPT** 연구를 기반으로 한 LLM 중심 생성 방식이 도입되어, Qwen2.5-14B와 같은 미세 조정된 모델이 자연어 설명을 실행 가능한 노드 그래프로 번역한다 [15, 23]. 또한 **ComfyUI-to-Python-Extension**과 같은 도구는 JSON 워크플로우를 순수 파이썬 스크립트로 변환하여 헤드리스(headless) 환경에서의 독립적 실행을 지원한다 [24, 25]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **JSON 버전 호환성**: ComfyUI가 빈번하게 업데이트됨에 따라 이전 버전의 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [26]. +- **메타데이터 손실 위험**: 이미지 파일에 포함된 워크플로우 메타데이터는 소셜 미디어 플랫폼이나 이미지 압축 소프트웨어에 의해 제거될 수 있으며, 이 경우 JSON 추출이 불가능해진다 [6, 26]. +- **API 포맷의 가독성**: API 포맷은 실행에는 효율적이지만 인간이 읽기 어렵고 노드 좌표가 없어 UI로 다시 불러올 때 노드들이 겹쳐 보이거나 뼈대만 남는 문제가 발생한다 [18, 27]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint**: `bc85382` 커밋에서 대소문자가 틀린 콤보 위젯 값을 정규화하는 기능이 수정되었으며, `/workflow/convert` 엔드포인트를 통해 비 API 포맷을 변환한다 [28-30]. +- **ComfyUI-to-Python-Extension**: `comfyui_to_python.py` 및 `comfyui_to_python_utils.py` 파일을 통해 JSON 워크플로우를 파이썬 코드로 변환하는 로직이 구현되어 있다 [31]. +- **DanielPFlorian/ComfyUI-WorkflowGenerator**: 자연어를 통한 워크플로우 생성을 위해 `Workflow Generator Pipeline` 노드를 제공하며, 내부적으로 `UpdateNodeCatalog`를 통해 로컬 노드 정보를 카탈로그화한다 [32-34]. +- **Mystic Pipeline**: `pipeline.yaml`과 `new_pipeline.py`를 사용하여 ComfyUI 워크플로우를 서버리스 엔드포인트로 배포할 때 API JSON 포맷이 사용된다 [35, 36]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 오픈소스 프로젝트와 공식 문서의 포맷 명세를 통해 기술적 구조 확인됨) +- **출처 신뢰도:** B (공식 문서 및 실제 구현체 GitHub 소스 코드 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI의 워크플로우 구조 자체가 DAG를 기반으로 설계됨 [1]. +- [[Litegraph Standard]] + - 연결 이유: 프론트엔드 JSON 포맷이 따르는 시각적 노드 그래프 라이브러리 표준 [2, 20]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 로드 시 발생하는 'Missing Custom Node' 오류를 해결하는 핵심 의존성 관리 도구 [37]. +- [[ComfyUI API]] + - 연결 이유: 생성된 JSON(API format)이 실제로 소모되는 최종 인터페이스 [38, 39]. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI의 'Execution Model Inversion'은 순방향 그래프 탐색 방식과 비교했을 때 대규모 워크플로우에서 어느 정도의 리소스 절감 효과를 가지는가? [9] +- 이미지 메타데이터(tEXt/zTXt) 외에 WebP나 MP4와 같은 다른 미디어 포맷에서 워크플로우 JSON을 안전하게 유지하는 표준 방식은 무엇인가? [40] +- LLM 기반 생성기에서 발생하는 '할루시네이션(노드 오연결)'을 방지하기 위한 Semantic Validator의 구체적인 임베딩 비교 알고리즘은 무엇인가? [23, 41] +- `object_info.json`을 사용하여 실시간으로 노드 스키마를 검증하는 것과 정적 카탈로그를 사용하는 방식의 성능 차이는 어떠한가? [42, 43] +- 복합적인 서브그래프(Subgraph)가 포함된 워크플로우를 API 포맷으로 직렬화할 때 노드 ID 충돌을 방지하는 내부 슬롯 매핑 전략은 무엇인가? [44] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬 `json` 라이브러리를 사용하여 로드된 워크플로우 딕셔너리의 `inputs` 키를 조작함으로써 자동화된 배치 생성을 구현할 수 있다 [13, 45]. +- **System Design:** API 전용 포맷을 사용하여 UI 오버헤드를 줄인 서버리스 추론 엔드포인트(Mystic, Replicate)를 구축한다 [39, 46]. +- **Operation / Maintenance:** ComfyUI Manager를 통해 외부에서 공유된 JSON의 커스텀 노드 누락 문제를 자동 진단하고 해결한다 [37, 47]. +- **Learning Path:** 기본 워크플로우(Default workflow)를 JSON으로 내보내 구조를 분석한 후, 점진적으로 커스텀 노드를 추가하며 스키마 변화를 관찰하는 학습이 권장된다 [48, 49]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: 워크플로우 JSON의 이식성을 위해 파일 이름 대신 모델의 해시값을 사용하여 의존성을 해결하는 기술 [50]. +- [[Steganography in Generative AI]] + - 확장 방향: 이미지 파일에 생성 파라미터를 숨기는 방식의 보안 및 데이터 보존 관련 연구 [6]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI Workflow JSON.md b/10_Wiki/Comfyui/ComfyUI Workflow JSON.md new file mode 100644 index 00000000..0f553ae4 --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI Workflow JSON.md @@ -0,0 +1,115 @@ +--- +id: comfyui-workflow-json +title: "ComfyUI Workflow JSON" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["워크플로우 JSON", "workflow_api.json"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "ComfyUI", "JSON"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: + - "DanielPFlorian/ComfyUI-WorkflowGenerator/README.md" + - "comfyui-workflow-to-api-converter-endpoint/README.md" + - "pydn/ComfyUI-to-Python-Extension/README.md" +github_commit: "82df278, bc85382, 6cdcc23" +--- + +# [[ComfyUI Workflow JSON]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI Workflow JSON은 복잡한 노드 기반 생성 AI 프로세스를 직렬화하여 가시적인 UI 레이아웃과 프로그램적 실행 로직 간의 상호 운용성을 보장하는 핵심 청사진이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **포맷의 이분화 (Bifurcation):** 사용자의 시각적 편집을 위한 '프런트엔드 포맷(workflow.json)'과 서버 실행에 최적화된 '백엔드/API 포맷(workflow_api.json)'으로 나뉜다 [3-6]. +2. **메타데이터 임베딩 (Metadata Embedding):** 생성된 PNG 이미지의 tEXt/zTXt 청크 내에 워크플로우 데이터를 숨겨 저장함으로써 이미지 자체가 백업 및 공유 수단이 된다 [7-9]. +3. **노드 레지스트리 기반 스키마:** 각 노드는 고유 ID, 클래스 타입, 입력/출력 슬롯 및 연결 정보를 담고 있으며, 이는 JSON Schema v1.0 규격을 따른다 [10-12]. +4. **프로그램적 제어 (Programmatic Automation):** JSON 구조를 직접 수정하거나 전용 라이브러리를 통해 워크플로우를 동적으로 생성 및 실행할 수 있다 [13-15]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **실행 모델 역전 (Execution Model Inversion):** 엔진은 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색하며 필요한 의존성만 식별하여 실행한다 [16]. +- **3단계 생성 파이프라인 (LLM):** 자연어 설명을 기반으로 논리적 구조 합성(Generator), 노드 이름 검증(Validator), 실행 가능한 JSON 컴파일(Builder) 순으로 워크플로우를 자동 생성한다 [17-19]. +- **헤드리스 변환 패턴:** 시각적 노드 그래프를 순수 Python 스크립트(.py)로 변환하여 GUI 없이 독립적으로 실행하는 구조를 가진다 [20, 21]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우는 AI 이미지 생성 프로세스를 설명하는 노드 네트워크를 직렬화한 데이터이다 [22, 23]. 주요 생성 및 관리 방법은 다음과 같다. + +**1. 포맷별 특성 및 생성** +* **프런트엔드 JSON:** 노드 위치, 크기, 그룹, 색상 등 시각적 정보를 포함하며 Litegraph 표준을 따른다 [3, 5, 24]. 일반적인 'Save' 버튼이나 `Ctrl+S`로 생성한다 [8, 25]. +* **API JSON:** UI 메타데이터를 제거하고 실행 로직(노드 타입, 입력값, 연결 관계)만 남긴 효율적인 포맷이다 [3, 6, 26]. 설정에서 'Dev mode Options'를 활성화한 후 'Save (API Format)'를 통해 추출할 수 있다 [27-30]. + +**2. 이미지 메타데이터 활용 및 추출** +ComfyUI에서 생성된 모든 이미지는 워크플로우 데이터를 내부 메타데이터에 포함한다 [31, 32]. 사용자는 PNG 파일을 캔버스에 드래그 앤 드롭하여 워크플로우를 즉시 복원할 수 있다 [7, 33, 34]. 대량의 이미지에서 JSON을 추출하기 위해 `exiftool`이나 전용 CLI 도구, 웹 기반 추출기(`Weird Wonderful AI Art` 등)가 사용된다 [35-37]. + +**3. 자동화 및 변환 도구** +* **Python API 연동:** `json` 라이브러리를 사용하여 시드, 프롬프트 등 특정 노드 파라미터를 직접 수정하고 `/prompt` 엔드포인트로 전송할 수 있다 [13, 15]. +* **변환 엔드포인트:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드는 비-API 포맷을 API 포맷으로 서버 측에서 변환하는 기능을 제공한다 [38, 39]. +* **코드 변환:** `ComfyUI-to-Python-Extension`은 JSON 워크플로우를 독립 실행 가능한 Python 코드로 번역하여 자동화 및 실험의 효율성을 높인다 [14, 21]. + +**4. LLM 기반 동적 생성** +`ComfyUI-WorkflowGenerator`는 Qwen2.5와 같은 거대언어모델을 활용하여 "SDXL을 이용한 텍스트 투 이미지 워크플로우 생성"과 같은 자연어 명령을 즉시 노드 그래프로 구축한다 [40-42]. 이 과정에서 로컬 노드 카탈로그를 스캔하여 유효성을 검증한다 [43, 44]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +* **버전 호환성:** ComfyUI의 잦은 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [33]. +* **메타데이터 소실:** 압축 소프트웨어나 소셜 미디어 플랫폼을 통해 이미지를 전송할 경우 임베딩된 워크플로우 정보가 삭제될 수 있다 [9, 33]. +* **API 포맷의 단점:** API 포맷으로만 저장된 파일은 UI 정보를 포함하지 않아 캔버스에 로드 시 노드가 겹치거나 시각적 구조가 무너진 '스켈레톤' 상태로 나타난다 [45]. + +## 🛠️ 적용 사례 (Applied in summary) +* **DanielPFlorian/ComfyUI-WorkflowGenerator:** LLM을 이용해 자연어 설명을 실행 가능한 워크플로우 JSON으로 변환하는 파이프라인 구현 (커밋: `82df278`) [19, 42, 46]. +* **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드 자바스크립트 로직을 파이썬으로 이식하여 `/workflow/convert` 엔드포인트를 통해 JSON 포맷을 변환 (커밋: `bc85382`) [38, 39, 47]. +* **pydn/ComfyUI-to-Python-Extension:** JSON 워크플로우를 `.py` 파일로 내보내어 단독 실행 가능한 스크립트 생성 환경 구축 (커밋: `6cdcc23`) [48, 49]. +* **Mystic Pipeline:** 사용자의 커스텀 워크플로우 JSON을 서버리스 엔드포인트에 배포하여 API 형태로 서빙 [50, 51]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (다양한 오픈소스 프로젝트 및 공식 문서에서 적용 사례 확인됨) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Nodes]] + - 연결 이유: 워크플로우 JSON의 기본 구성 단위 [22, 52]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간의 링크 연결 방식 및 데이터 흐름 구조 [23, 53]. +- [[Litegraph]] + - 연결 이유: 프런트엔드 JSON 포맷의 시각적 직렬화 표준 [3, 5]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 캔버스 레이아웃과 노드 좌표 관리 원리 [4]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 로드 시 누락된 커스텀 노드를 감지하고 설치하는 도구 [54-56]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 워크플로우 공유 시 발생하는 의존성 해결 방법 [55]. +- [[Comfy GPT]] + - 연결 이유: LLM 기반 워크플로우 생성의 원형이 되는 연구 [19, 40]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 자연어-그래프 변환 알고리즘의 발전 방향 [57]. + +### 심층 후속 질문 (Deeper Research Questions) +- 프런트엔드 JSON과 API JSON 간의 구조적 차이가 실제 서버 실행 성능에 미치는 정량적 차이는 무엇인가? [3, 4] +- PNG 외에 WebP나 MP4 메타데이터에 워크플로우를 효율적으로 내장하고 추출하는 기술적 표준은 어떻게 정의되는가? [58] +- 'Execution Model Inversion'이 복잡한 루프 구조를 가진 워크플로우에서도 일관된 순서를 보장하는가? [16] +- LLM 기반 생성기에서 새로운 커스텀 노드 출현 시 실시간으로 카탈로그를 업데이트하고 반영하는 효율적인 전략은 무엇인가? [57, 59] +- `.cpack.zip`과 같은 워크플로우 패키징 방식이 기존 JSON 방식의 모델 경로 문제를 어떻게 완전히 해결할 수 있는가? [60] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `/prompt` 엔드포인트를 호출할 때 API JSON의 특정 노드 ID 값을 가로채어 동적으로 파라미터를 삽입함 [13, 15]. +- **System Design:** 시각적 편집 환경(프런트엔드)과 배포 환경(백엔드)을 분리하여 효율적인 AI 프로덕션 파이프라인 구축 [3, 50, 61]. +- **Operation / Maintenance:** `ComfyUI Manager`를 통해 외부 공유 워크플로우의 커스텀 노드 누락 문제를 모니터링하고 해결 [54, 55]. +- **Learning Path:** 기본 워크플로우 템플릿 로드에서 시작하여, 메타데이터 추출을 통한 타인 워크플로우 분석, 최종적으로 API 기반 자동화 단계로 발전 [62-64]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Custom Nodes]] + - 확장 방향: JSON 내 `class_type`이 참조하는 실제 기능 구현체 및 의존성 관리 [8, 55, 65]. +- [[Model Hashing]] + - 확장 방향: JSON 파일 내 하드코딩된 모델 경로 문제를 SHA-256 해시를 이용해 해결하는 방법 [66]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source indices: [1-186]) \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI Workspace Manager.md b/10_Wiki/Comfyui/ComfyUI Workspace Manager.md new file mode 100644 index 00000000..d031eef7 --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI Workspace Manager.md @@ -0,0 +1,88 @@ +--- +id: comfyui-workspace-manager +title: "ComfyUI Workspace Manager" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Workspace Manager"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI 루트 디렉토리"] +github_commit: "" +--- + +# [[ComfyUI Workspace Manager]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우를 시각적으로 조직화하고 루트 디렉토리 기반의 안전한 저장 및 자산 관리 기능을 제공하는 파워 유저용 워크스페이스 최적화 도구 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **시각적 워크플로우 조직화 (Visual Organization):** 버튼 클릭 한 번으로 워크플로우를 시각적으로 확인하고 관리할 수 있는 세련된 사용자 인터페이스를 제공함 [2]. +2. **루트 디렉토리 보호 저장 (Root Directory Storage):** 워크플로우를 ComfyUI의 루트 디렉토리에 저장하여, 향후 업데이트 시 파일이 실수로 덮어씌워지는 것을 방지하고 안전한 백업 및 공유를 지원함 [2]. +3. **통합 자산 획득 (Integrated Asset Acquisition):** 관리 인터페이스 내에서 체크포인트 모델, LoRA 및 기타 필요한 파일들을 직접 다운로드할 수 있는 기능을 포함함 [3]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **업데이트 내성 저장 패턴:** 시스템 업데이트와 사용자 데이터를 분리하기 위해 워크플로우를 고정된 루트 디렉토리 구조에 보관하여 데이터 영속성을 보장함 [2]. +- **중앙 집중식 관리 패턴:** 워크플로우 파일(JSON) 관리와 모델 자산(Weights) 관리를 단일 시각 인터페이스로 통합하여 작업 흐름의 단절을 최소화함 [2, 3]. + +## 📖 세부 내용 (Details) +ComfyUI Workspace Manager는 기본 ComfyUI의 저장 및 로드 기능을 넘어선 고도의 관리 기능을 원하는 사용자들을 위한 커스텀 노드이다 [1]. 이 도구는 단순히 JSON 파일을 저장하는 것에 그치지 않고, 사용자가 보유한 수많은 워크플로우를 시각적으로 탐색하고 분류할 수 있는 전용 브라우저 역할을 수행한다 [2]. + +특히 **데이터 안전성** 측면에서 강력한 이점을 가지는데, 모든 워크플로우 데이터를 ComfyUI 설치 폴더의 루트 디렉토리에 체계적으로 보관함으로써 소프트웨어의 핵심 바이너리가 업데이트되더라도 사용자의 소중한 워크플로우 자산이 손실되지 않도록 설계되었다 [2]. 또한, 사용자는 이 인터페이스를 통해 필요한 모델이나 LoRA를 즉시 검색하고 내려받을 수 있어, 워크플로우 구성 중 발생하는 리소스 부족 문제를 도구 내에서 즉각 해결할 수 있다 [3]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +기존의 [[ComfyUI Custom Scripts]]가 저장/로드 버튼 아래에 드롭다운 메뉴를 생성하여 경로 기반 접근을 제공하는 것과 달리, Workspace Manager는 별도의 독립적이고 시각적인 인터페이스를 제공하는 상급 대안으로 분류된다 [1, 2]. 소스 데이터 내에서 기능적 모순은 발견되지 않으며, 파워 유저를 위한 편의성 확장 도구로서의 성격이 강조된다 [1]. + +## 🛠️ 적용 사례 (Applied in summary) +- **저장 위치:** 이 도구를 통해 관리되는 모든 워크플로우는 **ComfyUI의 루트 디렉토리**에 저장되어 안전하게 관리된다 [2]. +- **기능 활용:** 사용자는 인터페이스를 통해 워크플로우 관리뿐만 아니라 **모델 및 LoRA 다운로드**를 수행하여 작업 환경을 구축한다 [3]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Primary Source via NotebookLM / User Guides) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [워크플로우 관리 체계] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: Workspace Manager가 관리하는 핵심 대상인 JSON 파일의 생성 원리임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 관리 도구가 JSON의 어떤 메타데이터를 활용하여 시각화하는지 이해할 수 있음. +- [[ComfyUI Custom Scripts]] + - 연결 이유: 워크플로우의 저장 및 로드 편의성을 개선하는 유사한 목적의 도구임 [1]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 경로 기반 관리와 시각적 관리 방식의 차이점을 비교할 수 있음. + +#### [자산 및 의존성 관리] +- [[ComfyUI Manager]] + - 연결 이유: 누락된 노드 설치 및 모델 관리를 수행하는 상호보완적 도구임 [4]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: Workspace Manager의 모델 다운로드 기능과의 통합 활용법을 파악할 수 있음. + +### 심층 후속 질문 (Deeper Research Questions) +- Workspace Manager가 루트 디렉토리에 워크플로우를 저장할 때 내부적인 폴더 구조화 규칙은 무엇인가? +- 시각적 인터페이스에서 워크플로우의 썸네일이나 메타데이터를 추출하여 표시하는 메커니즘은 어떠한가? +- 루트 디렉토리에 저장된 워크플로우가 Git 등의 버전 관리 시스템과 연동될 때의 이점은 무엇인가? +- 모델 다운로드 기능이 ComfyUI Manager의 DB와 동기화되어 작동하는가, 아니면 독자적인 소스를 사용하는가? +- 대규모 워크플로우(예: 200KB 이상의 복잡한 노드 그래프) 처리 시 인터페이스의 성능 한계는 존재하는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 다수의 프로젝트별 워크플로우를 시각적으로 구분하여 관리해야 하는 제작 환경에 도입. +- **System Design:** 업데이트가 잦은 개발 환경에서 워크플로우 자산을 안전하게 보존하기 위한 저장 전략으로 채택. +- **Operation / Maintenance:** 워크플로우와 필요한 모델(Weights)을 한 곳에서 관리하여 팀 내 공유 및 인수인계 효율화. + +### 인접 주변 주제 (Adjacent Topics) +- [[Workflow JSON]] + - 확장 방향: 관리 도구가 제어하는 데이터 형식의 상세 스펙 이해 [5]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI-Manager.md b/10_Wiki/Comfyui/ComfyUI-Manager.md new file mode 100644 index 00000000..be2f0464 --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI-Manager.md @@ -0,0 +1,89 @@ +--- +id: comfyui-manager +title: "ComfyUI-Manager" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ltdrdata/ComfyUI-Manager", "Comfy-Org/ComfyUI-Manager/issues/719"] +github_commit: "" +--- + +# [[ComfyUI-Manager]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI-Manager는 워크플로우 JSON의 종속성을 동적으로 해석하고 누락된 커스텀 노드와 모델을 자동 설치하여, 정적인 파일 상태의 지식을 실행 가능한 파이프라인으로 전환하는 핵심 관리 엔진이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +1. **종속성 자동 해결 (Dependency Resolution):** 외부에서 가져온 JSON 파일을 로드할 때 발생하는 "Red Box(누락된 노드)" 오류를 분석하여 필요한 커스텀 노드 패키지를 식별하고 원클릭 설치를 지원함 [1, 2]. +2. **통합 리소스 허브 (Resource Hub):** 커스텀 노드뿐만 아니라 체크포인트, LoRA, ControlNet 등 다양한 AI 모델(Weights)의 검색 및 설치를 GUI 내에서 통합 관리함 [3, 4]. +3. **워크플로우 브라우징:** Comfy Workflows 및 OpenArt와 같은 플랫폼과 직접 연결되어 워크플로우 JSON을 다운로드하기 전에 미리 보고 즉시 로드할 수 있는 통로 역할을 함 [5]. +4. **보안 및 상태 관리:** 노드 설치 시의 보안 수준(Security Level) 설정 및 서버 업데이트, 터미널 로그 확인 등 시스템 전반의 유지보수 기능을 수행함 [6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Scan-Parse-Install 패턴:** 사용자가 JSON을 로드하면 시스템이 `class_type`을 스캔하고, 로컬 레지스트리와 대조하여 누락된 항목을 파싱한 뒤, 해당 Git 리포지토리를 찾아 설치를 제안하는 일련의 흐름 [2]. +- **마커 노드 활용 패턴:** `Workflow to API Converter (Marker)`와 같은 특정 노드를 워크플로우에 포함시켜, Manager가 해당 워크플로우의 특정 종속성을 더 정확하게 감지하도록 유도하는 전략 [7, 8]. +- **중앙 집중형 업데이트 전략:** 개별적으로 `git pull`을 수행하는 대신, Manager를 통해 설치된 모든 커스텀 노드의 업데이트 상태를 일괄 확인하고 갱신함 [3, 9]. + +## 📖 세부 내용 (Details) +ComfyUI-Manager는 **ltdrdata**에 의해 개발된 커스텀 노드로, ComfyUI 생태계의 복잡한 노드 종속성 문제를 해결하기 위해 설계되었다 [3]. 사용자가 Civitai나 GitHub에서 공유된 JSON 워크플로우를 로드했을 때, 로컬 환경에 해당 커스텀 노드가 없으면 화면에 붉은색 상자가 표시된다 [2]. 이때 Manager는 JSON 내의 노드 정보를 분석하여 "Install Missing Custom Nodes" 기능을 통해 누락된 패키지를 자동으로 찾아 설치하고 서버를 재시작함으로써 워크플로우를 즉시 복구한다 [1, 2]. + +또한, 워크플로우 생성에 필수적인 **모델 관리** 기능도 강력하다. "Install Models" 메뉴를 통해 SDXL, Realistic Vision 등 주요 모델뿐만 아니라 특정 커스텀 노드에 필요한 ControlNet 모델까지 검색하여 적절한 폴더 경로에 자동으로 배치한다 [4, 10, 11]. + +설치 방법은 매우 간단하여, ComfyUI의 `custom_nodes` 디렉토리 내에서 `git clone https://github.com/ltdrdata/ComfyUI-Manager` 명령을 실행하는 것만으로 활성화된다 [3]. 최근에는 워크플로우를 API용 JSON으로 변환할 때 종속성을 명시하기 위한 'Marker' 노드 등을 제공하여, 다른 사용자와 워크플로우를 공유할 때의 호환성을 높이는 역할도 수행하고 있다 [7, 8]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **보안 수준 갈등:** Manager를 통한 자동 설치 시 'This action is not allowed'와 같은 보안 레벨 오류가 발생할 수 있으며, 이는 설정 메뉴에서의 별도 조치가 필요하다 [6]. +- **모델 명칭 불일치:** 동일한 모델임에도 파일명이 다를 경우(예: `sd_xl_base_v10.safetensors` vs `sdxl_base.safetensors`) Manager가 이를 해결하기 위해 모델 해싱(SHA-256) 기술을 활용하거나 검색 기능을 강화하고 있다 [12, 13]. +- **특정 노드 누락:** IP-Adapter와 같은 일부 복잡한 커스텀 노드의 경우 Manager를 통해서도 해결되지 않는 종속성 문제가 보고되어 지속적인 수정이 이루어지고 있다 [14]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ltdrdata/ComfyUI-Manager 리포지토리:** `ComfyUI/custom_nodes/ComfyUI-Manager` 경로에 설치되어 전체 노드 관리 시스템으로 작동 [3]. +- **Workflow to API Converter (Marker) 노드:** 워크플로우 공유 시 Manager가 종속성을 감지할 수 있도록 돕는 마커로 실제 JSON 구조 내에 포함됨 [7, 8]. +- **Issue #719 (ComfyUI-Manager):** IP-Adapter 및 누락된 모델/커스텀 노드에 대한 커뮤니티 차원의 수정 및 기여 시도가 기록됨 [14]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual +- **출처 신뢰도:** B (Official Wiki 및 튜토리얼 소스 기반 합성) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: Manager는 생성된 JSON을 타 환경에서 복구하고 실행하는 데 필수적인 도구임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 파일의 이식성(Portability) 확보 원리. +- [[Workflow API JSON (Backend Format)]] + - 연결 이유: API 형식의 JSON에서도 종속성을 추적하기 위해 Manager의 마커 기능을 사용함 [7]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 정보가 없는 API 환경에서의 노드 복구 전략. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI-Manager가 JSON의 `class_type`을 기반으로 정확한 Git 리포지토리를 매핑하는 내부 레지스트리 업데이트 알고리즘은 무엇인가? +- 모델 해싱(SHA-256) 기술이 Manager의 모델 검색 엔진에 어떻게 통합되어 파일명 불일치 문제를 해결하는가? +- 보안 레벨 설정(`Security Level Error`)이 노드 설치 권한에 미치는 구체적인 영향과 해결 방안은 무엇인가? +- `Workflow to API Converter (Marker)` 노드가 JSON 메타데이터에 기록되는 방식과 Manager가 이를 인식하는 로직은 무엇인가? +- 서브그래프(Subgraph)나 중첩된 워크플로우 구조 내에서 Manager의 종속성 감지 성능은 어떻게 보장되는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 커스텀 노드 개발 시 `INPUT_TYPES`를 정확히 정의하여 Manager의 레지스트리와 호환되도록 설계해야 함 [15]. +- **System Design:** 워크플로우 배포 시 Manager가 인식 가능한 'Marker' 노드를 포함하여 사용자 경험을 개선함 [7, 8]. +- **Operation / Maintenance:** 정기적으로 Manager를 통해 설치된 모든 패키지의 업데이트 상태를 점검하여 최신 모델 지원 환경을 유지함 [3, 9]. +- **Learning Path:** 초보 사용자가 "Red Box" 오류를 해결하고 다양한 모델을 안전하게 설치하는 첫 번째 단계로 학습함 [1, 3]. + +### 인접 주변 주제 (Adjacent Topics) +- [[ComfyUI Workspace Manager]] + - 확장 방향: Manager가 설치를 담당한다면, Workspace Manager는 설치된 노드들을 활용한 워크플로우의 시각적 조직화와 백업에 집중함 [16, 17]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI-WorkflowGenerator.md b/10_Wiki/Comfyui/ComfyUI-WorkflowGenerator.md new file mode 100644 index 00000000..ac89a087 --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI-WorkflowGenerator.md @@ -0,0 +1,106 @@ +--- +id: comfyui-workflowgenerator +title: "ComfyUI-WorkflowGenerator" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["DanielPFlorian/ComfyUI-WorkflowGenerator", "catalog/", "cataloging/", "config/", "generators/", "nodes/", "tests/", "utils/", "wiki/", "workflows/"] +github_commit: "82df278" +--- + +# [[ComfyUI-WorkflowGenerator]] + +## 🎯 한 줄 통찰 (One-line insight) +자연어 설명을 기반으로 복잡한 노드 그래프 논리를 추론하고, 실행 가능한 [[Workflow API JSON]] 형식으로 자동 변환하는 LLM 기반의 지능형 워크플로우 합성 엔진 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **자연어-노드 그래프 변환 (Natural Language to Node Graph Conversion):** 사용자의 의도(예: "SDXL 기반 텍스트 투 이미지 생성")를 분석하여 적절한 노드 구성과 데이터 흐름을 정의하는 논리적 연결망을 생성함 [1-3]. +- **3단계 생성 파이프라인 (Three-stage Pipeline):** 논리적 합성(Generator), 시맨틱 검증(Validator), 그래프 컴파일(Builder) 과정을 거쳐 최종 결과물을 도출하는 구조적 아키텍처 [3-5]. +- **미세 조정된 전문 모델 (Fine-tuned Specialist LLM):** ComfyUI의 내부 노드 레지스트리 및 스키마 사양을 학습한 Qwen2.5-14B 기반 모델을 핵심 엔진으로 사용함 [1, 6]. +- **로컬 노드 동기화 (Local Node Synchronization):** 'Update Node Catalog' 기능을 통해 현재 환경에 설치된 네이티브 및 커스텀 노드를 스캔하여 모델의 지식 공백을 보완함 [7, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **시맨틱 검증 및 교정 패턴 (Semantic Validation & Correction):** LLM이 생성한 가상의 노드 이름을 로컬에 설치된 실제 노드 클래스 이름과 대조하여 자동 수정하거나 대체 노드를 제안함 [3, 4, 9]. +- **모듈형 단계별 개입 (Modular Step-wise Intervention):** 생성-검증-구축 과정을 개별 노드로 분리하여 사용자가 중간 결과물(논리 다이어그램 등)을 직접 검토하고 수정할 수 있도록 설계됨 [10, 11]. +- **환경 적응형 지식 확장 (Environment-adaptive Knowledge Expansion):** 학습 데이터의 컷오프(Cutoff) 한계를 극복하기 위해 로컬 노드 리스트를 동적으로 임베딩하여 검증에 활용하는 휴리스틱을 적용함 [7, 8, 12]. + +## 📖 세부 내용 (Details) +ComfyUI-WorkflowGenerator는 **ComfyGPT 연구**를 기반으로 구현된 독립적인 시스템으로, 사용자가 노드를 직접 배치하는 "시각적 프로그래밍" 단계에서 언어로 의도를 전달하는 "대화형 프로그래밍"으로의 전환을 목표로 한다 [2-4]. + +- **아키텍처 구조:** + 1. **Generator (논리 합성):** LLM이 자연어 지시를 해석하여 노드 종류와 연결 관계를 정의하는 추상적 JSON 구조를 생성한다 [3, 5, 9]. + 2. **Validator (시맨틱 검증):** 'Semantic search' 전용 모드 또는 'LLM refinement' 모드를 통해 생성된 노드 이름의 유효성을 검사하고 로컬 환경과의 호환성을 보장한다 [3, 9]. + 3. **Builder (그래프 컴파일):** 검증된 추상 구조를 ComfyUI 실행 엔진이 인식할 수 있는 **v1.0 스키마** 준수 워크플로우 JSON으로 최종 변환한다 [3, 8]. + +- **모델 및 실행 환경:** + - **핵심 모델:** Qwen2.5-14B를 기반으로 미세 조정되었으며, 효율성을 위해 **GGUF 양자화(q8_0)** 형식을 주로 사용한다 [6]. + - **필수 의존성:** GGUF 모델 구동을 위해 `llama-cpp-python` 라이브러리가 필요하며, 시맨틱 검색을 위해 별도의 임베딩 모델(`paraphrase-multilingual-MiniLM-L12-v2`)을 활용한다 [6, 13]. + - **카탈로그 관리:** `UpdateNodeCatalog` 노드를 실행하면 현재 설치된 모든 커스텀 노드를 스캔하여 임베딩 및 카탈로그 파일을 최신화하며, 이는 생성된 워크플로우의 정확도를 결정하는 핵심 요소이다 [7, 8]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정적 학습 데이터 vs 동적 생태계:** 미세 조정된 모델은 학습 시점 이후에 출시된 최신 커스텀 노드에 대해서는 본질적으로 지식이 없는 "동결(frozen)" 상태이다. 이를 해결하기 위해 로컬 노드 스캔(Update Catalog)을 통한 보완책이 강조된다 [12, 14]. +- **논리적 생성 vs 물리적 실행:** 모델이 논리적으로 올바른 노드 연결을 생성하더라도, 로컬 환경에 해당 체크포인트 모델이나 특정 커스텀 노드가 물리적으로 부재할 경우 최종 워크플로우는 실행 실패(Red Nodes)로 이어질 수 있다 [3, 14, 15]. + +## 🛠️ 적용 사례 (Applied in summary) +- **GitHub 프로젝트:** `DanielPFlorian/ComfyUI-WorkflowGenerator` 저장소에 전체 소스 코드와 노드 아키텍처가 공개되어 있다 [16]. +- **주요 파일 구조:** + - `nodes/`: WorkflowGenerator, NodeValidator, WorkflowBuilder 등 핵심 노드 구현체 포함 [11, 16]. + - `catalog/`: 로컬 노드 정보를 저장하고 검색하기 위한 카탈로그 관리 폴더 [8, 16]. + - `generators/`: LLM을 통한 워크플로우 논리 생성 엔진 포함 [16]. +- **특이 사항:** 6개월 전 커밋(`82df278`)을 통해 드롭다운 메뉴의 중복 모델 표시 문제가 수정된 기록이 발견된다 [16]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 논문 ComfyGPT의 아키텍처를 기반으로 하며, 실제 GitHub 구현체가 존재함) +- **출처 신뢰도:** B (GitHub Repository 및 기술 문서 기반 정보) +- **중복 검사 결과:** 신규 생성 (New discovery) + +--- + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow API JSON]] + - 연결 이유: WorkflowGenerator의 최종 출력물이자 백엔드 실행을 위한 필수 규격임 [8, 17, 18]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 메타데이터가 배제된 실행 최적화 그래프 구조. +- [[ComfyGPT]] + - 연결 이유: WorkflowGenerator의 이론적 토대가 된 다중 에이전트 워크플로우 생성 연구임 [2, 3]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: LLM이 노드 그래프를 이해하고 구성하는 원천 논리. + +#### [구현/활용 도구] +- [[ComfyUI-Manager]] + - 연결 이유: 생성된 JSON에서 누락된 커스텀 노드 의존성을 해결하는 핵심 사후 관리 도구임 [15, 19]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 외부 공유 워크플로우의 실행 가능성 확보 프로세스. + +### 심층 후속 질문 (Deeper Research Questions) +- LLM의 학습 데이터 컷오프 이후에 출시된 새로운 아키텍처(예: Wan 2.2)를 `UpdateNodeCatalog` 정보만으로 정확히 구성할 수 있는가? [12] +- Semantic Validation 단계에서 'LLM refinement'를 사용할 때 발생하는 토큰 소모량과 추론 시간 대비 정확도 향상 비율은 어느 정도인가? [9] +- 생성된 워크플로우의 `order` 및 `mode` 속성을 결정할 때 WorkflowBuilder가 사용하는 우선순위 알고리즘은 무엇인가? [8, 20] +- GGUF 양자화 강도(q4_0 vs q8_0)가 노드 간의 복잡한 연결(Link) 논리 보존력에 미치는 영향이 존재하는가? [21] +- 다중 ControlNet과 같이 중첩된 조건부 연결을 자연어만으로 완벽하게 제어하기 위한 프롬프트 엔지니어링 표준은 무엇인가? [4, 5] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `llama-cpp-python[cuda]`를 설치하여 저사양 VRAM 환경에서도 LLM 기반 워크플로우 생성이 가능하도록 최적화할 수 있음 [13, 22]. +- **System Design:** 사용자의 요구사항을 바이트코드 형태의 JSON으로 변환하는 추상화 계층으로 활용하여 전문 지식 없는 사용자의 접근성을 높임 [4, 23]. +- **Operation / Maintenance:** 커스텀 노드 대량 추가 시 반드시 `UpdateNodeCatalog`를 재실행하여 시스템의 지식 베이스를 동기화해야 함 [7, 8]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Comfy Nodekit]] + - 확장 방향: 파이썬 코드를 통해 워크플로우를 프로그래밍 방식으로 구축하는 정적 생성 방식과의 비교 연구 [24]. +- [[Litegraph]] + - 확장 방향: 워크플로우 JSON의 시각적 요소(위치, 크기)가 정의되는 프론트엔드 표준 규격 이해 [17, 25]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/ComfyUI-to-Python-Extension.md b/10_Wiki/Comfyui/ComfyUI-to-Python-Extension.md new file mode 100644 index 00000000..27c01d50 --- /dev/null +++ b/10_Wiki/Comfyui/ComfyUI-to-Python-Extension.md @@ -0,0 +1,66 @@ +--- +id: comfyui-to-python-extension +title: "ComfyUI-to-Python-Extension" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Save As Script"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui_to_python.py", "comfyui_to_python_utils.py", "install.py", "init.py", "ComfyUI/custom_nodes"] +github_commit: "6cdcc23" +--- + +# [[ComfyUI-to-Python-Extension]] + +## 🎯 한 줄 통찰 (One-line insight) +시각적인 **ComfyUI 노드 그래프 워크플로우를 별도의 서버 없이 독립적으로 실행 가능한 파이썬(.py) 코드로 변환**하여 자동화 및 실험의 반복성을 극대화하는 강력한 확장 도구이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **Save As Script (UI Export):** ComfyUI 웹 인터페이스의 메뉴를 통해 현재 워크플로우를 즉시 파이썬 스크립트로 다운로드하는 기능이다 [2, 3]. +- **CLI Exporter:** 저장된 API 포맷의 JSON 파일을 명령줄 인터페이스에서 파이썬 코드로 일괄 변환하는 도구이다 [2, 4]. +- **Runtime Dependency:** 생성된 스크립트는 실행을 위해 반드시 **ComfyUI 런타임 환경(PyTorch 등)**과 코드베이스에 대한 접근 권한이 필요하다 [5, 6]. +- **Metadata Preservation:** 생성된 스크립트를 통해 저장된 이미지는 원본 워크플로우 메타데이터를 포함하므로, 다시 ComfyUI로 드래그 앤 드롭하여 복구가 가능하다 [5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Workflow-to-Script Serialization:** 시각적 DAG(Directed Acyclic Graph) 구조를 순차적인 파이썬 함수 호출 및 클래스 인스턴스화 코드로 직렬화하는 패턴을 따른다 [2, 7]. +- **Headless Execution Pattern:** 웹 서버나 프론트엔드 없이도 워크플로우를 실행할 수 있게 하여, 독립형 소프트웨어 프로젝트나 자동화 파이프라인에 통합하기 용이한 구조를 제공한다 [8, 9]. +- **Lifecycle Management:** 생성된 스크립트의 `main()` 함수 내에서 모델 및 캐시 정리를 수행하는 `finally` 블록을 포함하여 자원 관리를 최적화한다 [6]. + +## 📖 세부 내용 (Details) +- **주요 기능 및 사용법:** + - **웹 UI 확장:** `File -> Save As Script` 메뉴를 통해 `workflow_api.py` 파일로 워크플로우를 내보낸다 [3]. + - **CLI 변환:** `python comfyui_to_python.py --input_file workflow_api.json` 명령을 통해 기존 JSON 파일을 스크립트로 변환할 수 있으며, `--queue_size` 옵션으로 실행 횟수를 지정할 수 있다 [4]. + - **환경 설정:** 실행 환경에 따라 `COMFYUI_PATH`를 설정하여 ComfyUI 코드베이스 위치를 명시해야 한다 [6, 10]. +- **기술적 특징:** + - **독립 실행형 러너:** 생성된 스크립트는 프롬프트 서버가 아닌 **단발성 워크플로우 실행기(single-shot runner)**로 동작한다 [6]. + - **인자 처리:** ComfyUI의 런타임 인자 파서를 재사용하므로, `--highvram`, `--cpu`와 같은 메모리 관리 플래그를 스크립트 실행 시 직접 전달할 수 있다 [5]. + - **파이썬 버전 요구사항:** 안정적인 동작을 위해 **Python 3.12 이상**의 버전을 권장한다 [2]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **동적 워크플로우의 한계:** 한 소스에서는 이 도구가 중간 변환 단계가 필요하기 때문에 **동적인 워크플로우(Dynamic workflows)**를 실행하기에 어려움이 있다는 비판적 시각을 제시한다 [9]. +- **메뉴 위치 변동성:** 프론트엔드 버전에 따라 `Save As Script` 메뉴의 위치가 달라질 수 있다는 점이 명시되어 있다 [3, 6]. +- **최신성 유지:** 정적 데이터셋으로 훈련된 LLM 기반 생성 도구와 달리, 이 익스텐션은 로컬의 노드 레지스트리를 활용하려는 시도를 보이지만, 여전히 수동 변환 과정이 수반된다 [4, 11]. + +## 🛠️ 적용 사례 (Applied in summary) +- **pydn/ComfyUI-to-Python-Extension:** 해당 개념이 구현된 핵심 프로젝트 저장소이다 [1]. +- **comfyui_to_python.py / comfyui_to_python_utils.py:** 워크플로우를 파이썬 코드로 변환하는 로직이 담긴 실제 소스 파일들이다 [12]. +- **install.py:** 익스텐션 설치 및 의존성 관리를 위한 스크립트로 적용되어 있다 [12]. +- **Save As Script 메뉴:** ComfyUI의 `File` 메뉴 하단에 실제 인터페이스 요소로 구현되어 적용되었다 [3]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Comfyui workflow json 생성 방법.md b/10_Wiki/Comfyui/Comfyui workflow json 생성 방법.md new file mode 100644 index 00000000..9e30877b --- /dev/null +++ b/10_Wiki/Comfyui/Comfyui workflow json 생성 방법.md @@ -0,0 +1,114 @@ +--- +id: comfyui-workflow-json-생성-방법 +title: "Comfyui workflow json 생성 방법" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI Workflow Serialization", "ComfyUI API JSON Generation"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "ComfyUI", "Workflow", "JSON", "API"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["bc85382", "82df278", "DanielPFlorian/ComfyUI-WorkflowGenerator", "SethRobinson/comfyui-workflow-to-api-converter-endpoint", "pydn/ComfyUI-to-Python-Extension"] +github_commit: "bc85382" +--- + +# [[Comfyui workflow json 생성 방법]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우 JSON은 시각적 그래프(Frontend)와 실행 가능한 로직(API) 사이를 연결하는 **직렬화된 소스 코드**이며, 수동 내보내기부터 LLM 기반 합성까지 다층적인 생성 경로를 제공한다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **형식의 이분화 (Bifurcation):** 시각적 메타데이터를 포함한 **Frontend JSON**(사용자 편집용)과 이를 제거하고 실행 로직만 남긴 **API JSON**(서버/프로그램 호출용)으로 구분된다 [4-7]. +- **메타데이터 임베딩 (Metadata Embedding):** 생성된 PNG/WebP 이미지의 tEXt 또는 zTXt 청크 내에 워크플로우 데이터를 숨겨 저장함으로써 이미지 자체가 워크플로우 백업 역할을 수행한다 [8, 9]. +- **실행 모델 역전 (Execution Model Inversion):** 최종 출력 노드에서 시작하여 필요한 의존성만 역방향으로 탐색해 실행 리스트를 구성하는 구조적 특성을 가진다 [10, 11]. +- **LLM 기반 합성 (LLM-driven Synthesis):** 자연어 설명을 세 단계(생성 → 검증 → 빌드)의 파이프라인을 거쳐 실행 가능한 노드 그래프로 자동 변환하는 최신 접근법이다 [12-14]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **개발자 모드 활성화 패턴:** API 전용 JSON을 추출하기 위해서는 설정 메뉴에서 **'Enable Dev mode Options'**를 활성화해야만 'Save (API format)' 버튼이 노출된다 [2, 15-17]. +- **노드 ID 고정화 전략:** API 환경에서 워크플로우를 제어할 때, 가변적인 노드 ID 대신 **노드 제목(Title)**이나 **사용자 정의 키**를 기반으로 파라미터를 수정하는 래퍼(Wrapper) 사용 패턴이 발견된다 [18-20]. +- **의존성 자동 해결 패턴:** 외부 JSON 로드 시 발생하는 'Missing Custom Node' 오류(빨간색 박스)를 해결하기 위해 **ComfyUI Manager**가 JSON을 파싱하여 누락된 패키지를 설치하도록 유도한다 [21-23]. + +## 📖 세부 내용 (Details) + +### 1. GUI를 통한 수동 생성 방법 +가장 기본적이고 흔한 방법으로, ComfyUI 웹 인터페이스의 컨트롤 패널을 사용한다. +- **Frontend 포맷 (workflow.json):** 캔버스 레이아웃, 노드 좌표, 그룹, 색상 등 시각적 정보를 모두 포함한다 [4, 24]. **Ctrl + S** (또는 Cmd + S) 단축키로 현재 상태를 바로 다운로드할 수 있다 [24]. +- **API 포맷 (workflow_api.json):** 서버 실행에 불필요한 UI 데이터를 제거한 정제된 그래프이다 [4, 7]. 설정에서 개발자 모드를 켠 후 생성되는 **'Save (API format)'** 버튼을 통해 추출하며, `/prompt` 엔드포인트 호출에 필수적이다 [2, 25, 26]. + +### 2. 이미지 메타데이터로부터의 추출 +이미 생성된 결과물 파일에서 워크플로우 로직을 복구하는 방법이다. +- **드래그 앤 드롭:** 워크플로우 정보가 포함된 PNG 파일을 캔버스에 떨어뜨리면 즉시 노드 구성이 복원된다 [8, 27-29]. +- **추출 도구 활용:** `ExifTool`을 사용하여 바이너리 태그를 추출하거나(`exiftool -b -workflow input.png > workflow.json`), 전문 웹 사이트(Weird Wonderful AI Art) 및 CLI 도구를 통해 벌크 추출이 가능하다 [30-33]. + +### 3. 프로그래밍 및 자동화 생성 +개발 환경에서 워크플로우를 동적으로 생성하거나 변환한다. +- **Python 딕셔너리 조작:** JSON은 기본적으로 중첩된 딕셔너리 구조이므로, `json` 라이브러리를 통해 시드, 프롬프트, 모델 경로 등의 특정 노드 입력을 직접 수정하여 다시 저장하거나 API로 보낼 수 있다 [34, 35]. +- **형식 변환 엔드포인트:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면, 일반 Frontend JSON을 서버 사이드에서 즉시 API 포맷으로 변환해주는 `/workflow/convert` API를 활용할 수 있다 [26, 36]. +- **Python 스크립트 변환:** `ComfyUI-to-Python-Extension`은 JSON 워크플로우를 순수 파이썬 코드(.py)로 변환하여 독립적인 실행 스크립트로 만들어준다 [18, 37, 38]. + +### 4. LLM 기반 자연어 생성 (AI 합성) +- **파이프라인 구조:** `ComfyUI-WorkflowGenerator`는 사용자의 자연어 명령(예: "SDXL을 사용한 텍스트-투-이미지 워크플로우 생성")을 입력받아 **Generator**(논리 구조 생성) → **Validator**(노드 이름 검증) → **Builder**(실행 가능 JSON 빌드) 과정을 거친다 [13, 14]. +- **기반 모델:** Qwen2.5-14B와 같이 미세 조정된 대규모 언어 모델을 활용하여 노드 간의 유효한 연결 관계를 추론한다 [39]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **JSON 호환성 이슈:** ComfyUI의 빈번한 업데이트로 인해 이전 버전의 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [23, 28]. +- **메타데이터 손실 위험:** 온라인 공유나 압축 과정에서 이미지의 메타데이터(JSON 정보 포함)가 제거될 수 있으며, 이 경우 드래그 앤 드롭을 통한 복구가 불가능하다 [9, 28, 40]. +- **Reroute 노드 처리:** 최근 업데이트(V2.2.0)에서는 변환기들이 새로운 'reroute' 노드를 무시하거나 적절히 처리하도록 로직이 수정되었다 [41]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Git 커밋 bc85382:** `comfyui-workflow-to-api-converter-endpoint` 프로젝트에서 대소문자 구분 오류(True vs true)를 수정하고 콤보 위젯 값을 정규화하는 로직이 적용됨 [41, 42]. +- **Git 커밋 82df278:** `ComfyUI-WorkflowGenerator`에서 드롭다운 메뉴의 중복 모델 표시 문제를 해결함 [43]. +- **/workflow/convert 엔드포인트:** Seth A. Robinson에 의해 개발된 커스텀 노드로, 비 API 포맷을 API 포맷으로 서버 측에서 변환하는 기능을 구현함 [26, 44]. +- **Save As Script 메뉴:** `pydn/ComfyUI-to-Python-Extension` 설치 시 ComfyUI의 'File' 메뉴에 추가되어 워크플로우를 파이썬 코드로 내보낼 수 있게 함 [45, 46]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 및 다수의 오픈소스 구현 사례 확인됨) +- **출처 신뢰도:** B (공식 개발 문서, 메이저 커스텀 노드 개발자의 기술 노트 및 튜토리얼 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 + +#### [아키텍처/기반 기술] +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON 형식이 기반하고 있는 시각적 그래프 표준 [4, 6]. +- [[Execution Model Inversion]] + - 연결 이유: JSON 데이터가 실제로 처리되는 백엔드 엔진의 핵심 알고리즘 [10]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 생성된 JSON의 노드 의존성을 관리하고 누락된 요소를 복구하는 필수 도구 [21, 22]. +- [[ComfyUI API]] + - 연결 이유: 생성된 API JSON이 최종적으로 소비되는 인터페이스 엔드포인트 [47, 48]. + +### 심층 후속 질문 (Deeper Research Questions) +- 왜 ComfyUI는 Frontend와 API 포맷을 분리하여 설계했으며, 이로 인해 얻는 성능적 이득은 구체적으로 무엇인가? [4, 5] +- PNG 메타데이터 청크(tEXt/zTXt)를 넘어서는 대용량 워크플로우를 이미지에 안전하게 포함시키는 대안 기술은 무엇이 있는가? [9] +- LLM 기반 생성 시, 학습 데이터에 없는 최신 커스트 노드와의 연결을 위해 RAG(검색 증강 생성)를 어떻게 결합할 수 있는가? [49] +- `Execution Model Inversion` 구조에서 사용되지 않는 노드가 JSON에 포함되었을 때 실제 실행 효율에 미치는 영향은 어떠한가? [10] +- 모델 해싱(SHA-256)을 이용해 서로 다른 환경의 JSON 내 모델 파일 경로 불일치 문제를 해결하는 표준 프로세스는 무엇인가? [50] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `/workflow/convert` 엔드포인트를 활용하여 클라이언트 앱에서 워크플로우 수정 후 즉시 실행 가능한 API 호출 생성 [26]. +- **System Design:** 워크플로우를 Git으로 관리하고, 배포 시에는 API 포맷만 추출하여 서버리스 환경(Replicate, Mystic 등)에 업로드 [16, 17, 51]. +- **Operation / Maintenance:** `object_info.json`을 사용하여 실행 전 노드 입출력 유효성을 검사함으로써 런타임 오류 방지 [52, 53]. +- **Learning Path:** 기본 워크플로우 템플릿부터 시작하여 수동 내보내기를 익힌 후, `ComfyUI-to-Python`을 통해 자동화 단계로 진입 [38, 54]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: 워크플로우 이식성 강화를 위한 모델 식별 기술 [50]. +- [[Custom Node Registry]] + - 확장 방향: JSON 내 `class_type`이 참조하는 실제 노드 구현 저장소 관리 [55]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source synthesis from 18 documents) [1-188] \ No newline at end of file diff --git a/10_Wiki/Comfyui/Custom Node Dependency Management.md b/10_Wiki/Comfyui/Custom Node Dependency Management.md new file mode 100644 index 00000000..ee81db71 --- /dev/null +++ b/10_Wiki/Comfyui/Custom Node Dependency Management.md @@ -0,0 +1,102 @@ +--- +id: custom-node-dependency-management +title: "Custom Node Dependency Management" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["커스텀 노드 의존성 관리", "Missing Custom Nodes Resolution"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Dependency Management"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes/ComfyUI-Manager", "comfyui-workflow-to-api-converter-endpoint (V2.05)", "UpdateNodeCatalog Node"] +github_commit: "" +--- + +# [[Custom Node Dependency Management]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI의 워크플로우 이식성은 **JSON 메타데이터 내 `class_type` 분석**과 **ComfyUI Manager를 통한 자동 의존성 해결** 메커니즘에 의해 보장된다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **Red Node Detection:** 워크플로우 로드 시 로컬 레지스트리에 존재하지 않는 노드를 시각적 경고(빨간색 박스)로 식별하는 메커니즘 [1, 3, 4]. +2. **Node Registry (object_info.json):** 현재 실행 중인 ComfyUI 인스턴스에서 사용 가능한 모든 노드의 입력/출력 스키마 및 클래스 정보를 담고 있는 통합 카탈로그 [5, 6]. +3. **Class Type Mapping:** JSON 파일의 `class_type` 속성을 기반으로 커스텀 노드 패키지를 역추적하여 필요한 기능을 식별하는 프로세스 [1, 7]. +4. **Automated Resolution (ComfyUI Manager):** 미설치 노드를 파싱하여 해당 패키지를 원클릭으로 설치하고 서버를 재시작할 수 있게 하는 관리 도구 [3, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Dependency Detection Marker:** 워크플로우 공유 시 ComfyUI Manager가 의존성을 더 쉽게 감지할 수 있도록 전용 '마커 노드'를 포함시키는 전략 [9]. +- **Semantic Validation Pipeline:** LLM을 사용하여 자연어 명령에서 생성된 노드 이름이 실제 설치된 노드와 일치하는지 시맨틱 임베딩으로 검증하고 교정하는 패턴 [10, 11]. +- **Model Weight Hashing:** 파일명 불일치 문제를 해결하기 위해 SHA-256 해시를 사용하여 모델 의존성을 관리하는 고급 직렬화 방식 [4, 12]. + +## 📖 세부 내용 (Details) +ComfyUI의 의존성 관리는 워크플로우 JSON이 단순한 그래픽 레이아웃이 아니라 **실행 가능한 논리 구조(DAG)**라는 점에서 핵심적인 위치를 차지한다 [2, 13]. + +**의존성 식별 및 해결 프로세스** +사용자가 외부에서 생성된 JSON 워크플로우를 가져올 때, ComfyUI 인터페이스는 각 노드의 `class_type`을 로컬 노드 레지스트리와 대조한다 [1]. 이 과정에서 노드를 찾을 수 없는 경우 해당 노드는 캔버스에 빨간색 박스로 표시된다 [3, 14]. **ComfyUI Manager**는 이 JSON을 다시 파싱하여 누락된 커스텀 노드 패키지를 식별하며, "Install Missing Custom Nodes" 기능을 통해 자동 설치를 지원한다 [3, 8]. + +**데이터 무결성 및 레지스트리** +의존성 관리의 근간은 `object_info.json` 파일이다. 이 파일은 인스턴스 내 모든 노드의 입력/출력 유형, 기본값, 툴팁 등 상세 스키마를 포함하고 있어 도구 개발 및 입력 유효성 검사에 필수적이다 [6, 15]. 또한, 자연어 기반 워크플로우 생성 도구인 **WorkflowGenerator**는 `UpdateNodeCatalog` 노드를 통해 로컬 및 커스텀 노드를 정기적으로 스캔하여 최신 카탈로그를 유지한다 [16, 17]. + +**환경 간 불일치 해결** +로컬 경로가 하드코딩된 이미지나 모델의 경우, 타 시스템으로 워크플로우를 이동할 때 경로 오류가 발생하기 쉽다 [4]. 이를 해결하기 위해 모델 해싱을 사용하거나, `Comfy API Simplified`와 같이 노드 ID 대신 '타이틀'을 기준으로 파라미터를 설정하는 래퍼 라이브러리를 사용하여 워크플로우의 유연성을 높인다 [12, 18]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **JSON 버전 호환성:** ComfyUI는 빈번하게 업데이트되므로, 구버전의 JSON 파일이 최신 버전에서 의존성 문제 없이 완벽하게 작동한다는 보장이 없으며 수동 수정이 필요할 수 있다 [19]. +- **정적 모델의 한계:** 특정 시점에 학습된 LLM 기반 워크플로우 생성기는 학습 이후에 출시된 새로운 커스텀 노드의 존재나 의존성 관계를 알 수 없는 '동결(frozen)' 상태의 한계를 가진다 [20]. +- **보안 이슈:** 의존성 관리의 핵심인 `Impact-Pack` 플러그인 등에서 채굴 바이러스가 발견되는 등 커스텀 노드 생태계의 보안 취약점이 보고된 바 있다 [21]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI/custom_nodes/ComfyUI-Manager:** 의존성 관리 및 커스텀 노드 설치를 위한 표준 디렉토리 경로 [22]. +- **comfyui-workflow-to-api-converter-endpoint (V2.05):** 워크플로우 의존성 감지를 강화하기 위한 "Marker Node" 기능 구현 [9, 23]. +- **UpdateNodeCatalog 노드:** 가용 노드(네이티브 및 커스텀)를 스캔하여 의존성 유효성 검사에 필요한 카탈로그 파일 업데이트 [16, 17]. +- **NodeValidator:** LLM 기반 생성 워크플로우에서 노드 이름을 실제 로컬 설치 노드와 비교하여 교정하는 검증 노드 [10, 11]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (주요 도구 및 레지스트리 구조 확인됨) +- **출처 신뢰도:** B (공식 문서 및 주요 오픈소스 프로젝트 리드미 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow JSON - ComfyUI]] + - 연결 이유: 의존성 정보가 저장되는 데이터 구조의 표준. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: `class_type` 필드의 중요성. +- [[API JSON (Backend Format)]] + - 연결 이유: 시각 데이터가 제거된 순수 실행 그래프에서의 의존성 정의 방식. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 실질적인 의존성 해결 및 자동 설치 도구. +- [[object_info.json]] + - 연결 이유: 모든 노드 의존성 및 스키마의 런타임 데이터 소스. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI Manager는 서로 다른 리포지토리에서 동일한 `class_type`을 가질 경우 우선순위를 어떻게 결정하는가? [소스에 관련 정보가 부족합니다.] +- SHA-256 모델 해싱이 파일명 불일치를 해결하는 구체적인 알고리즘적 워크플로우는 무엇인가? [12] +- LLM 기반 `NodeValidator`가 오인식(Hallucination) 없이 커스텀 노드를 정확히 매핑하기 위한 프롬프트 최적화 전략은? [10, 20] +- `object_info`를 원격 서버에서 호출할 때 보안 인증이 의존성 정보 노출에 미치는 영향은? [24] +- 의존성 감지를 위한 'Marker Node'가 JSON 구조 내에서 차지하는 데이터 가중치는 어느 정도인가? [9] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 커스텀 노드 개발 시 `INPUT_TYPES`를 정확히 정의하여 `object_info.json`에 반영되도록 설계해야 함 [25]. +- **System Design:** 다중 사용자 환경에서 워크플로우를 배포할 때, 누락된 노드로 인한 빨간색 박스 오류를 방지하기 위해 ComfyUI Manager 호환성을 고려해야 함 [1]. +- **Operation / Maintenance:** 새로운 커스텀 노드 설치 후에는 `UpdateNodeCatalog`를 실행하여 의존성 레지스트리를 갱신해야 함 [17]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: 모델 파일 관리의 일관성 보장 기술. +- [[Retrieval-Augmented Generation (RAG) for Nodes]] + - 확장 방향: 미래의 동적 의존성 탐색 기술 [26]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [27] \ No newline at end of file diff --git a/10_Wiki/Comfyui/Custom Node Registry.md b/10_Wiki/Comfyui/Custom Node Registry.md new file mode 100644 index 00000000..29b50533 --- /dev/null +++ b/10_Wiki/Comfyui/Custom Node Registry.md @@ -0,0 +1,103 @@ +--- +id: custom-node-registry +title: "Custom Node Registry" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Node Catalog", "Node Schema Registry"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/models/LLM/", "ComfyUI/custom_nodes/ComfyUI-WorkflowGenerator", "/object_info endpoint", "/workflow/convert endpoint"] +github_commit: "" +--- + +# [[Custom Node Registry]] + +## 🎯 한 줄 통찰 (One-line insight) +Custom Node Registry는 ComfyUI의 유연한 확장성을 지탱하는 핵심 데이터베이스로, JSON 워크플로의 추상화된 노드 타입을 실제 Python 실행 로직 및 스키마와 연결하는 권위 있는 원천이다. [1-3] + +## 🧠 핵심 개념 (Core concepts) +- **Node Mapping (class_type):** 워크플로 JSON 내의 `type` 또는 `class_type` 문자열을 로컬 환경에 설치된 실제 Python 클래스 기능과 매핑한다. [2, 4, 5] +- **Schema Discovery (object_info):** 실행 중인 ComfyUI 인스턴스에서 모든 노드의 입력/출력 유형, 필수 여부, 허용 범위를 동적으로 카탈로그화하여 제공한다. [3, 6] +- **Dependency Tracking:** 외부에서 유입된 JSON 워크플로를 로컬 레지스트리와 대조하여 누락된 커스텀 노드 패키지를 식별하고 관리한다. [7, 8] +- **Semantic Validation:** 자연어 기반 워크플로 생성 시, 생성된 노드 이름이 실제 로컬 레지스트리에 존재하는지 검증하고 교정하는 기준점이 된다. [9-11] + +## 🧩 추출된 패턴 (Extracted patterns) +- **Scan-and-Catalog 패턴:** 새로운 커스텀 노드를 설치하거나 업데이트한 후 `UpdateNodeCatalog` 노드 등을 실행하여 로컬 노드 환경을 최신화하고 카탈로그 파일을 생성한다. [11-13] +- **Runtime Resolution 패턴:** 백엔드 엔진은 실행 시점에 JSON의 `class_type`을 레지스트리에서 찾아 기능을 호출하며, 시각적 데이터가 제거된 API 포맷에서 이 매핑이 특히 중요하다. [2, 5, 14] +- **Schema Inversion 패턴:** `/object_info` 엔드포인트를 통해 레지스트리를 외부로 노출함으로써, 외부 앱이 ComfyUI 내부 로직을 모르더라도 노드 인터페이스를 동적으로 구성할 수 있게 한다. [3, 15] + +## 📖 세부 내용 (Details) +Custom Node Registry는 ComfyUI 워크플로 생성 및 직렬화의 근간을 이룬다. 워크플로가 JSON으로 저장될 때, 각 노드는 레지스트리에 등록된 고유한 **class_type**을 기반으로 식별된다. [2, 4] 이는 프론트엔드에서 사용하는 시각적 ID와는 별개의 기능적 키 값이다. [2, 16] + +**주요 구성 요소 및 역할:** +1. **스키마 정의 (object_info.json):** 이 레지스트리는 각 노드가 요구하는 `required` 및 `optional` 입력값, 데이터 타입, 도구 설명(tooltips) 등을 상세히 포함한다. [3] 개발자는 이를 활용해 입력값을 검증하거나 동적으로 워크플로 수정 도구를 빌드할 수 있다. [3, 15, 17] +2. **의존성 해결 및 관리:** ComfyUI Manager는 외부에서 로드된 JSON의 노드 클래스를 로컬 레지스트리와 교차 검증한다. [7] 일치하는 항목이 없을 경우 "Missing Custom Node" 에러(빨간색 박스)를 발생시키고, 레지스트리 정보를 바탕으로 자동 설치를 지원한다. [7, 18] +3. **API 변환 및 검증:** `Workflow to API Converter`와 같은 도구는 정확한 변환을 위해 ComfyUI의 실제 노드 레지스트리를 직접 참조하여 리스트, 딕셔너리 위젯, 서브그래프 등을 처리한다. [19] +4. **LLM 기반 생성의 준거 집단:** 자연어 설명을 워크플로로 변환하는 시스템(`ComfyUI-WorkflowGenerator`)은 레지스트리 데이터를 기반으로 학습되거나, 생성 단계에서 레지스트리와의 시맨틱 매칭을 통해 유효한 그래프 구조를 보장한다. [9, 10, 20] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정적 모델과 동적 레지스트리의 간극:** 고정된 데이터로 학습된 LLM 모델은 학습 시점 이후에 출시된 새로운 커스텀 노드를 레지스트리에서 인식하지 못하는 한계가 있으며, 이를 극복하기 위해 실시간 카탈로그 스캔이 필수적이다. [21-23] +- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 노드 레지스트리 내의 클래스 이름이나 구조가 변경될 수 있으며, 이로 인해 과거 버전의 JSON 파일이 최신 레지스트리에서 제대로 작동하지 않을 수 있다. [24] + +## 🛠️ 적용 사례 (Applied in summary) +- **UpdateNodeCatalog:** 사용자가 설치한 모든 네이티브 및 커스텀 노드를 스캔하여 로컬 카탈로그를 갱신하는 기능이 구현되어 있다. [11, 12] +- **ComfyUI Manager:** JSON 내의 `class_type`을 파싱하여 레지스트리에 없는 패키지를 탐지하고 설치 인터페이스를 제공한다. [7, 8] +- **Workflow to API Converter Endpoint:** 클라이언트 측 JS 로직을 Python으로 변환하여 서버 사이드에서 노드 레지스트리를 참조해 비-API 포맷을 API 포맷으로 변환한다. [19, 25] +- **object_info 엔드포인트:** `/object_info` 경로를 통해 현재 인스턴스의 전체 노드 스키마 레지스트리를 JSON 형태로 배포한다. [15] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례가 소스 코드 및 공식 문서 내 엔드포인트 형태로 다수 발견됨) [7, 15, 19] +- **출처 신뢰도:** B (Official Documentation / GitHub Repository README / API Docs 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow API JSON (Backend Format)]] + - 연결 이유: API 포맷은 시각적 메타데이터 없이 오직 레지스트리의 기능적 키에만 의존하여 실행된다. [2, 26] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터가 백엔드 실행 로직으로 변환되는 방식. [2, 5] +- [[JSON Schema v1.0]] + - 연결 이유: 레지스트리에 정의된 노드 객체들이 준수해야 할 구조적 제약 조건을 정의한다. [4] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 ID, 타입, 위젯 값 등의 기술적 사양. [4, 27] + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 레지스트리 불일치 문제를 해결하고 의존성을 관리하는 가장 보편적인 도구이다. [7, 18] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 누락된 노드 설치 및 패키지 관리 프로세스. [7, 28] +- [[ComfyUI-WorkflowGenerator]] + - 연결 이유: 자연어를 레지스트리에 존재하는 유효한 노드 그래프로 변환하는 파이프라인을 제공한다. [10, 29] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 레지스트리 데이터를 활용한 AI 기반 자동화 방법론. [9, 20, 30] + +### 심층 후속 질문 (Deeper Research Questions) +- 서로 다른 커스텀 노드 패키지 간에 클래스 이름(`class_type`)이 충돌할 경우 레지스트리는 어떤 우선순위로 이를 처리하는가? +- 수백 개의 커스텀 노드가 설치된 환경에서 동적 카탈로그 스캔(`UpdateNodeCatalog`)이 시스템 성능 및 로딩 시간에 미치는 영향은 무엇인가? +- `object_info.json`의 스키마 데이터를 활용하여 외부 웹 대시보드에서 실시간으로 ComfyUI 노드 UI를 완벽하게 재현할 수 있는가? +- 노드 레지스트리의 변경 사항(필드 추가/삭제)이 기존에 직렬화된 JSON 워크플로의 하위 호환성에 미치는 영향과 그 대응 전략은 무엇인가? +- `.cpack.zip`과 같은 워크스페이스 패키징 방식은 레지스트리 의존성 문제를 어떻게 영구적으로 해결하는가? [31] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 외부 애플리케이션 개발 시 `/object_info`를 호출하여 사용자 입력값이 노드 레지스트리 규격에 맞는지 클라이언트 사이드에서 즉시 검증할 수 있다. [3, 15] +- **System Design:** Python 스크립트에서 워크플로를 동적으로 생성할 때 노드 ID 대신 레지스트리의 타이틀이나 클래스 명을 참조하는 래퍼 라이브러리를 사용하여 유지보수성을 높일 수 있다. [32] +- **Operation / Maintenance:** 워크플로 공유 시 `Workflow to API Converter (Marker)` 노드를 추가하여 타인이나 매니저가 레지스트리 의존성을 쉽게 식별하도록 돕는다. [8] +- **Learning Path:** 노드 메뉴얼을 읽는 대신 `object_info` 데이터를 분석하여 특정 노드의 모든 가능한 입력 조합과 데이터 흐름을 기술적으로 파악할 수 있다. [3] + +### 인접 주변 주제 (Adjacent Topics) +- [[Execution Model Inversion]] + - 확장 방향: 레지스트리의 전체 노드 중 최종 출력에 필요한 노드만 선택적으로 실행하는 백엔드 최적화 원리. [33] +- [[Model Hashing]] + - 확장 방향: 노드 정의 외에도 레지스트리에서 참조하는 모델 파일의 일관성을 보장하는 기술. [34] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [Source 26, 28, 37, 41, 133, 151 기반 합성] \ No newline at end of file diff --git a/10_Wiki/Comfyui/Custom Nodes.md b/10_Wiki/Comfyui/Custom Nodes.md new file mode 100644 index 00000000..9a374fbf --- /dev/null +++ b/10_Wiki/Comfyui/Custom Nodes.md @@ -0,0 +1,99 @@ +--- +id: custom-nodes +title: "Custom Nodes" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["커스텀 노드", "확장 노드"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes", "GitHub: DanielPFlorian/ComfyUI-WorkflowGenerator", "GitHub: SethRobinson/comfyui-workflow-to-api-converter-endpoint", "GitHub: pydn/ComfyUI-to-Python-Extension"] +github_commit: "bc85382" +--- + +# [[Custom Nodes]] + +## 🎯 한 줄 통찰 (One-line insight) +커스텀 노드는 ComfyUI의 모듈형 아키텍처를 무한히 확장하는 핵심 동력이지만, 워크플로우 JSON의 이식성과 실행 가능성을 결정짓는 가장 큰 종속성 변수이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **생태계 확장성 (Ecosystem Extensibility):** 기본 노드 세트(Core nodes) 외에 전 세계 개발자들이 공유하는 기능을 추가하여 Stable Diffusion뿐만 아니라 비디오, 오디오, 3D 생성 등 모든 유형의 미디어 자산을 생성할 수 있게 한다 [2, 3]. +- **클래스 타입 매핑 (Class_type Mapping):** JSON 워크플로우 파일 내에서 각 노드는 `class_type` 속성을 통해 식별되며, 실행 시 로컬의 커스텀 노드 레지스트리와 대조된다 [4, 5]. +- **종속성 관리 (Dependency Management):** 외부 워크플로우를 불러올 때 해당 시스템에 특정 커스텀 노드가 없으면 'Red Boxes' 에러가 발생하며, 이를 해결하기 위해 ComfyUI Manager와 같은 도구가 필수적이다 [5, 6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **누락 노드 복구 패턴:** 외부 JSON 로드 시 발생하는 'Red Boxes'를 감지하고 ComfyUI Manager를 통해 "Install Missing Custom Nodes"를 실행하여 서버를 재시작하는 복구 흐름이 정형화되어 있다 [5, 6]. +- **마커 노드 활용 패턴:** 워크플로우 공유 시 ComfyUI Manager가 종속성을 더 쉽게 감지할 수 있도록 "Workflow to API Converter (Marker)"와 같은 특정 마커 노드를 의도적으로 포함시킨다 [7]. +- **LLM 기반 자동 검색 패턴:** `Update Node Catalog` 노드를 사용하여 현재 설치된 모든 커스텀 노드를 스캔하고, 이를 LLM이 자연어를 JSON으로 변환할 때 참조하는 데이터베이스로 활용한다 [8, 9]. + +## 📖 세부 내용 (Details) +커스텀 노드는 ComfyUI의 `custom_nodes` 디렉토리에 설치되며, 주로 Git 클론을 통해 추가된다 [10, 11]. 워크플로우 JSON 생성 시, 커스텀 노드의 정보는 다음과 같이 처리된다. + +- **JSON 내 기록:** 워크플로우가 저장될 때 각 커스텀 노드의 설정, 위젯 값, 연결 관계가 JSON의 `nodes` 배열에 포함된다 [12, 13]. API 포맷인 경우 비주얼 메타데이터가 삭제된 `class_type`과 `inputs` 정보만 남는다 [4, 14]. +- **주요 커스텀 노드 예시:** + - **ComfyUI-Manager:** 노드 및 모델 설치/관리의 중추 [10]. + - **Efficiency Nodes:** 여러 노드를 하나로 결합하여 워크플로우를 간소화함 [15, 16]. + - **AnimateDiff Evolved & VideoHelperSuite:** 비디오 생성을 위한 필수 확장 [15, 16]. + - **IPAdapter Plus & ControlNet Aux:** 정밀한 이미지 제어를 위한 노드군 [16, 17]. +- **개발자 도구와의 통합:** `Comfy Nodekit`과 같은 Python 라이브러리는 서버의 커스텀 노드 레지스트리와 자동으로 동기화되어, 프로그래밍 방식으로 워크플로우를 생성할 때 타입 안정성을 제공한다 [18]. 또한 `ComfyUI-to-Python-Extension`은 이러한 커스텀 노드가 포함된 그래프를 순수 Python 스크립트로 변환하여 독립 실행을 지원한다 [19]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 문제:** ComfyUI가 빈번하게 업데이트됨에 따라, 과거에 생성된 JSON 파일 내의 커스텀 노드 구성이 최신 버전의 노드와 충돌하여 제대로 작동하지 않을 수 있다는 경고가 존재한다 [20, 21]. +- **데이터 증발 위험:** 일반적인 이미지 편집기나 소셜 미디어 플랫폼에서 이미지를 처리할 때, 커스텀 노드 정보가 담긴 메타데이터(JSON)가 삭제될 수 있어 전용 추출 도구 사용이 권장된다 [22, 23]. + +## 🛠️ 적용 사례 (Applied in summary) +- **설치 위치:** `ComfyUI/custom_nodes` 디렉토리 하위에 각 노드 패키지가 배치됨 [10, 11]. +- **GitHub 프로젝트:** + - `DanielPFlorian/ComfyUI-WorkflowGenerator`: LLM을 통해 커스텀 노드를 포함한 워크플로우를 자동 생성하는 노드 구현 [24, 25]. + - `SethRobinson/comfyui-workflow-to-api-converter-endpoint`: (커밋 `bc85382`) 비 API 포맷의 커스텀 노드 워크플로우를 API 포맷으로 변환하는 서버 사이드 로직 구현 [26, 27]. +- **의사결정 기록:** ComfyUI Manager의 "Install Missing Custom Nodes" 기능은 커스텀 노드 부재로 인한 워크플로우 실행 실패를 해결하는 표준 운영 절차(SOP)로 확립됨 [5, 6]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (다수의 GitHub 프로젝트 및 공식 튜토리얼을 통해 실무 적용 확인됨) +- **출처 신뢰도:** B (공식 문서 및 주요 개발자 리포지토리 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처 및 기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: 커스텀 노드는 JSON 파일의 내용을 구성하는 가장 동적인 요소임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 `class_type`이 어떻게 실제 기능으로 매핑되는지 이해 가능. +- [[Workflow API JSON]] + - 연결 이유: API 실행 시 커스텀 노드의 입출력 구조가 이 포맷에 맞춰 최적화됨. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 없는 환경에서의 커스텀 노드 호출 메커니즘. + +#### [구현 및 관리 도구] +- [[ComfyUI Manager]] + - 연결 이유: 커스텀 노드의 설치, 업데이트, 누락 복구를 담당하는 전용 도구임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 복잡한 종속성 문제를 자동화하는 방법. + +### 심층 후속 질문 (Deeper Research Questions) +- 커스텀 노드의 `class_type`이 중복될 경우 ComfyUI는 어떤 우선순위로 노드를 로드하는가? +- `Update Node Catalog` 노드는 어떤 방식으로 로컬에 설치되지 않은 원격 커스텀 노드의 정보를 수집할 수 있는가? [9] +- 커스텀 노드 내에서 정의된 `INPUT_TYPES`가 JSON Schema v1.0 규격과 충돌할 때 발생하는 예외 처리 메커니즘은 무엇인가? [28] +- `comfy-pack`과 같은 도구에서 모델 해싱(SHA-256)을 사용할 때 커스텀 노드 내부의 모델 경로 의존성은 어떻게 해결되는가? [29] +- LLM 기반 워크플로우 생성기에서 학습 데이터에 없는 최신 커스텀 노드를 인식시키기 위한 RAG(Retrieval-Augmented Generation) 적용 방안은 무엇인가? [30] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 새로운 기능을 개발할 때 `ComfyUI/custom_nodes`에 Python 클래스를 정의하고 이를 JSON에서 호출 가능한 형태로 등록함 [3, 10]. +- **System Design:** API 서버 구축 시 모든 필요한 커스텀 노드가 사전 설치된 Docker 이미지를 준비해야 함 [31]. +- **Operation / Maintenance:** 워크플로우 공유 시 "Red Box" 발생을 최소화하기 위해 필수 커스텀 노드 목록을 별도로 제공하거나 마커 노드를 포함함 [6, 7]. +- **Learning Path:** 기본 워크플로우 숙지 후, `Efficiency Nodes`나 `Manager` 설치를 통해 고급 워크플로우 설계 단계로 진입함 [15, 32]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: 커스텀 노드가 사용하는 특정 모델 파일의 이름 불일치 문제를 해결하는 보완 기술 [29]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source identifiers: [1, 3, 5, 6, 10, 19, 25, 26]) \ No newline at end of file diff --git a/10_Wiki/Comfyui/Directed Acyclic Graph (DAG).md b/10_Wiki/Comfyui/Directed Acyclic Graph (DAG).md new file mode 100644 index 00000000..798afeea --- /dev/null +++ b/10_Wiki/Comfyui/Directed Acyclic Graph (DAG).md @@ -0,0 +1,95 @@ +--- +id: directed-acyclic-graph-(dag) +title: "Directed Acyclic Graph (DAG)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["유향 비순환 그래프", "실행 그래프"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["workflow_api.json", "Execution Model Inversion", "WorkflowExecutor", "validate_prompt"] +github_commit: "bc85382, 82df278" +--- + +# [[Directed Acyclic Graph (DAG)]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI의 워크플로우 아키텍처는 노드와 링크를 통해 데이터 흐름을 정의하며, 순환하지 않는 방향성을 가진 **Directed Acyclic Graph(DAG)** 구조를 핵심 실행 모델로 채택한다 [1]. + +## 🧠 핵심 개념 (Core concepts) +- **Node-based Connectivity:** 프로그램 객체인 노드들이 서로 연결되어 네트워크(그래프)를 형성하며, 각 노드는 모델 로더, 샘플러, 인코더 등의 특정 기능을 수행한다 [1-3]. +- **Directional Data Flow:** 데이터는 링크를 통해 한 노드의 출력 슬롯에서 다른 노드의 입력 슬롯으로 정해진 방향에 따라 흐른다 [1, 4]. +- **Acyclicity (비순환성):** 그래프 내에서 경로가 자기 자신으로 돌아오지 않는 비순환 구조를 가져 실행의 시작과 끝이 명확하다 [1]. +- **Serialization:** 복잡한 DAG 네트워크는 JSON 형식으로 직렬화되어 이식성, 버전 관리 및 프로그래밍 방식의 자동화를 가능하게 한다 [1]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Execution Model Inversion (실행 모델 역전):** 모든 노드를 순차 실행하는 대신, 'Save Image'와 같은 최종 출력 노드에서 시작하여 그래프를 역방향으로 추적, 필요한 종속성만 식별하여 실행하는 최적화 패턴이다 [5]. +- **Bifurcation of Formats (형식의 이분화):** 시각적 레이아웃을 포함하는 **Frontend Format**과 순수 실행 논리(DAG)만을 남긴 **Backend/API Format**으로 구분되어 관리된다 [6, 7]. +- **Slot-based Indexing:** 연결은 단순히 노드 간의 결합이 아니라, 특정 출력 슬롯(예: VAE Loader의 VAE 슬롯)에서 특정 입력 슬롯으로 정밀하게 매핑되는 인덱싱 구조를 따른다 [4]. + +## 📖 세부 내용 (Details) +ComfyUI는 스테이블 디퓨전과 같은 복잡한 생성형 AI 프로세스를 절차적 프레임워크로 추상화하기 위해 DAG를 활용한다 [1]. 워크플로우 자체가 DAG와 동의어로 사용되며, 이는 3D 프로그램의 '씬 그래프'나 영상 편집 프로그램의 '프로젝트 파일'과 유사한 역할을 수행한다 [8]. + +그래프의 구조적 무결성은 **JSON Schema v1.0** 규격에 의해 검증된다 [9]. 각 노드는 고유 ID, 클래스 타입(type), 그리고 위젯 값을 포함하며, `inputs` 배열은 유입되는 링크의 ID를 기록하고 `outputs` 배열은 해당 데이터를 소비하는 하위 노드들의 링크 ID 리스트를 유지한다 [4, 9]. API 형식의 JSON에서는 시각적 메타데이터가 제거되고, 링크가 별도의 배열 대신 노드 입력 내부에 직접 삽입되어 실행 효율성을 극대화한다 [6, 10]. + +실행 단계에서 엔진은 DAG의 특성을 이용해 불필요한 계산을 배제한다. 최종 출력에 기여하지 않는 노드들이 그래프에 포함되어 있더라도, 역방향 그래프 탐색(Backward Traversal)을 통해 이를 무시함으로써 성능 저하 없이 복잡한 워크플로우를 구성할 수 있다 [5]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **데이터 보존의 취약성:** DAG 구조를 PNG 메타데이터(tEXt/zTXt 청크)에 저장할 수 있으나, 일반적인 이미지 편집기나 소셜 미디어 플랫폼을 거치면 이 메타데이터가 유실되어 그래프 구조가 파괴될 수 있다는 점이 주의사항으로 언급된다 [11]. +- **형식 간의 불완전한 호환성:** API 형식으로 저장된 그래프(DAG 최적화본)를 다시 UI로 불러올 경우, 시각적 레이아웃 정보가 없어 노드들이 겹치거나 뼈대만 남는 현상이 발생할 수 있다 [12]. + +## 🛠️ 적용 사례 (Applied in summary) +- **workflow_api.json:** 시각적 요소가 제거된 순수 DAG 형태의 실행 파일 형식으로, 서버 측 처리 및 API 호출에 최적화되어 적용됨 [6, 13]. +- **Execution Model Inversion:** ComfyUI 서버 아키텍처에서 노드 실행 우선순위를 결정하고 효율성을 확보하기 위한 핵심 알고리즘으로 적용됨 [5, 14]. +- **WorkflowExecutor 클래스:** Python 스크립트에서 워크플로우 JSON을 `ExecutionList`로 변환하고 각 노드를 순회하며 실행하는 로직에 적용됨 [15]. +- **validate_prompt 함수:** 워크플로우를 실행하기 전 DAG의 유효성을 검증하는 내부 함수로 활용됨 [15]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (ComfyUI 공식 문서 및 아키텍처 분석 자료 기반) +- **출처 신뢰도:** B (Official Documentation / Technical Architectures via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: DAG 구조를 지속 가능한 파일 형태로 변환하는 상위 프로세스. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 기반 시스템의 직렬화 메커니즘. + +#### [실무 구현 도구] +- [[API Format (workflow_api.json)]] + - 연결 이유: DAG의 실행 논리만이 정제된 최종 데이터 포맷. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 메타데이터와 실행 그래프의 차이점. +- [[Execution Model Inversion]] + - 연결 이유: DAG 구조를 효율적으로 처리하기 위한 엔진의 핵심 알고리즘. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 그래프 탐색 및 최적화 원리. + +### 심층 후속 질문 (Deeper Research Questions) +- DAG 구조 내에서 의도적인 순환(Looping)이 필요한 경우(예: 반복 개선) ComfyUI는 이를 어떤 방식으로 우회하거나 처리하는가? +- Execution Model Inversion이 중첩된 [[Subgraph]] 구조를 만났을 때, 그래프 탐색의 깊이 제한이나 우선순위는 어떻게 관리되는가? [16, 17] +- 노드 ID가 중복되거나 유실된 손상된 DAG 구조를 복구하기 위한 알고리즘적 전략이 소스 데이터에 존재하는가? +- LLM 기반의 워크플로우 생성기([[ComfyUI-WorkflowGenerator]])는 DAG의 논리적 타당성을 어떤 의미론적 검증 과정을 통해 확보하는가? [18] +- `object_info.json`에 정의된 스키마가 DAG의 연결 가능성을 제한하는 제약 조건으로 어떻게 작용하는가? [19] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬의 `json` 라이브러리를 사용하여 API JSON의 노드 ID를 추적하고 `inputs` 값을 동적으로 수정하여 대량의 이미지를 생성할 수 있다 [20, 21]. +- **System Design:** 서버리스 환경(Mystic, Replicate 등)에 배포할 때, DAG 구조에서 불필요한 시각적 데이터를 제거한 API 형식을 사용해야 통신 효율성이 높아진다 [22, 23]. +- **Operation / Maintenance:** 'Red Nodes'(누락된 노드) 오류 발생 시, DAG 스키마를 파싱하여 필요한 커스텀 노드 패키지를 식별하고 설치하는 것이 필수적이다 [24]. +- **Learning Path:** 복잡한 워크플로우를 이해하려면 출력 노드에서 거꾸로 입력을 찾아가는 역방향 추적 방식을 익히는 것이 효과적이다 [5]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Litegraph]] + - 확장 방향: ComfyUI 프론트엔드에서 DAG를 시각적으로 렌더링하기 위해 사용하는 표준 포맷 연구. [6, 25] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Execution Model Inversion.md b/10_Wiki/Comfyui/Execution Model Inversion.md new file mode 100644 index 00000000..5e04bb1c --- /dev/null +++ b/10_Wiki/Comfyui/Execution Model Inversion.md @@ -0,0 +1,94 @@ +--- +id: execution-model-inversion +title: "Execution Model Inversion" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["역방향 실행 모델", "Output-Driven Traversal"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Architecture"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI Server Documentation"] +github_commit: "" +--- + +# [[Execution Model Inversion]] + +## 🎯 한 줄 통찰 (One-line insight) +최종 출력 노드에서 시작하여 필요한 의존성만을 역추적해 실행함으로써, 워크플로 내 불필요한 노드가 성능에 미치는 영향을 완전히 배제하는 ComfyUI의 최적화 아키텍처 [1]. + +## 🧠 핵심 개념 (Core concepts) +- **출력 기반 역방향 탐색 (Output-Driven Traversal):** 실행 엔진이 모든 노드를 순차적으로 처리하는 대신, 'Save Image'와 같은 최종 출력 노드에서 시작하여 그래프를 거꾸로 거슬러 올라가며 필요한 노드만 식별함 [1]. +- **의존성 자동 식별 (Dependency Identification):** 최종 결과물에 기여하는 노드들만 실행 목록(Execution List)에 포함시키고, 연결되어 있더라도 결과에 영향을 주지 않는 노드는 무시함 [1, 2]. +- **성능 격리 (Performance Isolation):** 생성된 JSON 내에 수십 개의 미사용 노드가 포함되어 있더라도 백엔드에서 이를 실행하지 않으므로 실행 성능에 무리가 가지 않음 [1]. +- **DAG(유향 비순환 그래프) 기반 논리:** 워크플로를 방향성이 있고 순환하지 않는 그래프 구조로 취급하여 논리적인 역추적을 가능케 함 [1, 3]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **의존성 체인 검증 패턴:** `WorkflowExecutor`가 `validate_prompt` 함수를 사용하여 워크플로의 유효성을 검사하고 이를 `ExecutionList`로 변환하는 구조 [2]. +- **결과 중심 데이터 흐름:** 데이터가 모델 로더에서 시작하여 샘플러를 거쳐 출력으로 흐르지만, 실행 제어는 그 반대 방향인 출력에서 시작됨 [1, 3]. + +## 📖 세부 내용 (Details) +Execution Model Inversion은 ComfyUI의 아키텍처에서 가장 정교한 개념 중 하나로, 워크플로가 처리되는 방식을 최적화하는 핵심 기제이다 [1]. + +- **작동 원리:** 엔진은 그래프의 모든 노드를 실행하는 대신 'Save Image'와 같은 출력 노드에서 시작한다 [1]. 여기서부터 그래프를 역방향으로 탐색하여 최종 출력에 도달하기 위해 반드시 실행되어야 하는 상위 노드(의존성)들을 계층적으로 파악한다 [1]. +- **JSON 설계와의 관계:** 이 모델 덕분에 사용자는 복잡하고 큰 규모의 워크플로 JSON을 생성하면서도 성능 저하를 걱정할 필요가 없다 [1]. 백엔드 엔진은 최종 출력에 기여하지 않는 모든 노드를 지능적으로 무시하기 때문이다 [1]. +- **API 효율성:** 특히 **API Format(workflow_api.json)**으로 변환된 워크플로를 실행할 때, 이 모델은 최소한의 필수 연산만을 보장하여 서버 자원을 효율적으로 관리할 수 있게 한다 [1, 4]. +- **캐싱 메커니즘과의 연계:** `ExecutionCache`와 결합하여, 역방향 탐색 중 이미 계산된 결과가 있는 노드의 경우 실행을 건너뛰고 캐시된 데이터를 즉시 반환함으로써 효율을 극대화한다 [5]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **전체 실행 vs 부분 실행:** 전통적인 파이프라인 방식이 모든 단계를 순차적으로 실행하는 것과 달리, ComfyUI는 출력 노드에 도달하기 위한 최소 경로만을 실행하는 "Lazy Evaluation"과 유사한 특성을 보인다 [1]. +- **JSON의 유연성:** 소스에 따르면 워크플로 파일 내에 사용하지 않는 노드가 많아도 시스템에 무리가 가지 않는다는 점은 일반적인 소프트웨어 최적화 상식(리소스 최소화)과는 다른 ComfyUI만의 설계적 특징이다 [1]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI Server 공식 가이드:** 공식 문서의 'ComfyUI Server' 섹션 내에 "Execution Model Inversion Guide"라는 명칭의 기술 문서로 상세히 다루어지고 있음 [6]. +- **WorkflowExecutor 구현:** 독립 실행형 스크립트 실행 시 `WorkflowExecutor` 클래스가 `validate_prompt`를 통해 실행 목록을 생성하는 과정에 이 논리가 내재되어 있음 [2]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 가이드라인 존재 확인 [6]) +- **출처 신뢰도:** B (Official Documentation 및 전문 분석 리포트 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: Execution Model Inversion이 작동하기 위한 구조적 토대임 [3]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 링크가 어떻게 논리적 흐름을 형성하는지 파악 가능. +- [[ComfyUI Backend Engine]] + - 연결 이유: 역방향 탐색과 실행 목록 생성을 담당하는 주체임 [1, 2]. + +#### [구현/활용 도구] +- [[API Format (workflow_api.json)]] + - 연결 이유: UI 정보가 제거된 실행 중심의 JSON 포맷으로, 이 모델에 최적화되어 있음 [1, 4]. +- [[WorkflowExecutor]] + - 연결 이유: 역방향 탐색 논리를 실제 실행 코드로 구현한 클래스임 [2]. + +### 심층 후속 질문 (Deeper Research Questions) +- Execution Model Inversion 환경에서 'Bypass'된 노드는 역추적 과정에서 어떻게 처리되는가? [7] +- 여러 개의 출력 노드가 존재할 경우, 엔진은 각 출력별로 독립적인 역방향 탐색을 수행하는가? +- `ExecutionCache`가 역방향 탐색 경로에 있는 특정 노드의 실행 여부를 결정하는 구체적인 임계값은 무엇인가? [5] +- 사용자가 명시적으로 모든 노드를 강제 실행(Force Execute)하도록 설정할 수 있는 우회 방법이 존재하는가? +- 자연어 기반 워크플로 생성 도구인 `ComfyUI-WorkflowGenerator`는 이 실행 모델을 고려하여 노드 연결을 생성하는가? [8, 9] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** API 서버 구축 시 워크플로에 테스트용 노드가 섞여 있더라도 성능 영향을 최소화하며 배포 가능 [1]. +- **System Design:** 대규모 자동화 배너 광고 시스템 등에서 다양한 변종 워크플로를 하나의 JSON 템플릿으로 관리할 때 유리함 [10]. +- **Operation / Maintenance:** 워크플로 디버깅 시 실행되지 않는 노드를 식별하여 의존성 연결 오류를 파악하는 지표로 활용 가능 [11]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Lazy Evaluation in Graph Theory]] + - 확장 방향: 컴퓨터 과학 관점에서의 계산 최적화 기법 비교. +- [[Workflow JSON v1.0 Schema]] + - 확장 방향: 역방향 탐색에 필수적인 `id`, `inputs`, `links` 속성의 기술적 명세 이해 [12, 13]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on Source [1], [6]) \ No newline at end of file diff --git a/10_Wiki/Comfyui/ExecutionCache.md b/10_Wiki/Comfyui/ExecutionCache.md new file mode 100644 index 00000000..7e8ef662 --- /dev/null +++ b/10_Wiki/Comfyui/ExecutionCache.md @@ -0,0 +1,60 @@ +--- +id: executioncache +title: "ExecutionCache" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["Standalone Execution Script (GitHub Gist)"] +github_commit: "" +--- + +# [[ExecutionCache]] + +## 🎯 한 줄 통찰 (One-line insight) +독립형 스크립트 환경에서 ComfyUI 워크플로우를 실행할 때 노드 출력 및 UI 데이터를 통합 관리하여 중복 계산을 방지하고 성능을 최적화하는 핵심 캐시 관리 클래스 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **통합 캐시 관리 (Unified Cache Management):** 노드 출력, UI 데이터, 객체 인스턴스의 캐싱을 중앙에서 처리하여 워크플로우 실행 효율을 높임 [2]. +- **성능 최적화 (Performance Optimization):** 불필요하고 중복되는 계산을 줄여 독립형 실행 환경의 오버헤드를 최소화함 [2]. +- **HierarchicalCache 기반 구조:** ComfyUI의 기본 계층적 캐시(HierarchicalCache) 메커니즘 위에 구축되어 노드 객체와 결과 데이터를 구조적으로 저장함 [2]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **독립형 실행 아키텍처 패턴:** 워크플로우 실행을 조율하는 `WorkflowExecutor`와 데이터 영속성을 관리하는 `ExecutionCache`가 결합되어 서버 없이도 워크플로우를 실행하는 구조를 형성함 [1, 3]. +- **데이터 캡슐화 패턴:** 노드 객체(node object), 출력 데이터(output data), UI 데이터를 하나의 캐시 단위 내에 보관하여 ComfyUI와의 호환성을 유지함 [2]. + +## 📖 세부 내용 (Details) +ExecutionCache는 ComfyUI 워크플로우를 서버 기반의 웹 인터페이스 없이 **독립형 파이썬 스크립트**로 실행하기 위해 설계된 핵심 컴포넌트임 [1, 4]. 이 클래스는 워크플로우 실행 과정에서 발생하는 다양한 데이터를 효율적으로 관리하는 역할을 수행함. + +주요 기능은 다음과 같음: +1. **데이터 저장 및 관리:** 각 노드의 실행 결과인 출력 데이터뿐만 아니라, UI 관련 데이터 및 생성된 객체 인스턴스 정보를 캐시에 저장함 [2]. +2. **중복 계산 방지:** 동일한 입력에 대해 이미 계산된 결과가 캐시에 존재할 경우 이를 재사용함으로써 실행 시간을 단축하고 컴퓨팅 자원을 절약함 [2]. +3. **호환성 유지:** ComfyUI 내부의 `HierarchicalCache`를 기반으로 동작하도록 설계되어, 서버 환경에서의 실행 로직과 최대한 유사한 동작 방식을 보장함 [2, 3]. + +이 클래스는 `WorkflowExecutor`와 함께 사용되며, `WorkflowExecutor`가 노드를 실행(`_execute_node`)할 때 필요한 입력 데이터를 조회하거나 실행 결과를 저장하는 저장소 역할을 담당함 [1, 2]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **독립형 실행의 한계:** ExecutionCache를 포함한 독립형 스크립트 방식은 ComfyUI 서버와 웹 UI가 밀접하게 연결된 기본 구조를 우회하려는 시도이나, 여전히 ComfyUI의 런타임 환경(torch 등)에 의존함 [5-7]. +- **캐시 생명주기:** 서버 환경의 Web UI 프롬프트/결과 캐싱과 달리, 이를 활용한 생성된 스크립트는 일반적으로 단발성 실행(single-shot)으로 동작하며 실행 종료 시 모델/캐시 정리를 수행함 [8]. + +## 🛠️ 적용 사례 (Applied in summary) +- **독립형 실행 스크립트 (Standalone Execution Script):** SDXL Turbo 워크플로우 등을 API JSON 형식에서 파이썬 스크립트로 직접 실행하기 위한 `WorkflowExecutor` 시스템의 일부로 구현됨 [1, 3, 4]. 해당 코드는 특정 GitHub Gist를 통해 공유되고 있음 [1, 4]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (전문 개발자 블로그 및 기술 분석 자료 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Frontend Format (workflow.json).md b/10_Wiki/Comfyui/Frontend Format (workflow.json).md new file mode 100644 index 00000000..8a90a033 --- /dev/null +++ b/10_Wiki/Comfyui/Frontend Format (workflow.json).md @@ -0,0 +1,70 @@ +--- +id: frontend-format-(workflow.json) +title: "Frontend Format (workflow.json)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "RunComfy Serverless API"] +github_commit: "" +--- + +# [[Frontend Format (workflow.json)]] + +## 🎯 한 줄 통찰 (One-line insight) +Frontend Format(`workflow.json`)은 ComfyUI의 **Litegraph 표준**을 따르며, 노드 간의 실행 로직뿐만 아니라 캔버스상의 시각적 레이아웃과 그룹 정보를 모두 보존하는 **인간 중심의 공유 및 편집용 블루프린트**이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **시각적 메타데이터(UI Metadata) 포함**: 노드의 위치(`pos`), 크기(`size`), 색상, 그룹화 구조 및 노드의 축소(collapsed) 또는 고정(pinned) 여부와 같은 시각적 상태 정보를 모두 포함한다 [1, 4, 5]. +- **Litegraph 표준 준수**: 웹 인터페이스에서의 시각적 렌더링 및 조작에 최적화된 데이터 구조를 따른다 [1, 2]. +- **명시적 링크 표현 (Explicit Links)**: 연결을 노드 내부에 매핑하는 대신, 별도의 `links` 배열 내에서 고유 ID를 가진 명시적인 연결 객체로 관리한다 [2, 4, 6]. +- **가역성(Reversibility)**: 생성된 이미지 메타데이터에 포함되어 드래그 앤 드롭만으로 원본 노드 그래프를 완벽하게 재구성할 수 있게 한다 [7-9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **포맷의 이분화(Bifurcation)**: ComfyUI는 사용자의 시각적 편집을 위한 'Frontend 포맷'과 서버의 실행 효율성을 위한 'Backend/API 포맷'을 엄격히 구분하여 운영한다 [1, 10]. +- **메타데이터 임베딩(Metadata Embedding)**: 생성된 PNG/WebP 파일의 `tEXt` 또는 `zTXt` 청크에 프론트엔드 워크플로우를 저장하여 이미지가 곧 소스 코드가 되는 패턴을 형성한다 [8, 9, 11]. +- **의존성 기반 노드 ID 할당**: 각 노드는 생성 순서 또는 사용자 정의에 따라 고유한 숫자형 문자열 ID(예: "37")를 부여받아 그래프 탐색의 키로 활용된다 [4, 5, 12]. + +## 📖 세부 내용 (Details) +프론트엔드 포맷은 ComfyUI 웹 인터페이스에서 **기본 저장(Ctrl+S)** 시 생성되는 표준 규격이다 [13]. 이는 사용자 경험을 유지하기 위해 설계되었으며, 워크플로우를 재로드했을 때 모든 노드가 정확한 좌표에 나타나도록 보장한다 [13, 14]. + +**JSON 스키마 v1.0 구성 요소 [5, 6, 15]**: +- **nodes**: 개별 노드 객체의 배열로 구성된다. + - `id`: 그래프 탐색을 위한 고유 식별자. + - `type`: 노드 레지스트리에 매핑된 클래스 이름. + - `pos`/`size`: 캔버스 좌표 및 시나리오 렌더링 크기. + - `widgets_values`: 슬라이더, 텍스트 박스, 토글 등 사용자 입력값의 배열. + - `order`: 실행 또는 렌더링 권장 순서. + - `mode`: 노드의 활성/비활성/바이패스 상태. +- **links**: 노드 간의 연결을 정의하는 상위 레벨 배열로, `[origin_id, origin_slot, target_id, target_slot, type]` 등의 정보를 포함하는 6개 항목 배열 또는 구조화된 객체 형태를 띤다 [6]. + +이 포맷은 **API 포맷과 대조**적이다. API 포맷은 시각적 메타데이터를 제거하고 실행에 필요한 로직만 남긴 '스트림라인' 버전으로, 프론트엔드 파일을 API 엔드포인트에 직접 보낼 경우 오류가 발생할 수 있다 [1, 14, 16]. 따라서 전문적인 자동화 환경에서는 프론트엔드 포맷을 원본(Source of truth)으로 관리하고, 실행 직전에 API 포맷으로 변환하는 프로세스가 권장된다 [17, 18]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 문제**: ComfyUI의 잦은 업데이트로 인해 구버전에서 생성된 프론트엔드 JSON 파일이 최신 버전에서 제대로 작동하지 않거나 시각적으로 깨지는 현상이 발생할 수 있다 [19]. +- **데이터 유실 위험**: 이미지에 포함된 프론트엔드 메타데이터는 소셜 미디어나 이미지 편집기(GIMP 등)를 거칠 경우 파일 크기 최적화 또는 개인정보 보호를 이유로 제거되는 경우가 많아 가역성이 파괴될 수 있다 [9, 20]. +- **API 실행 불가**: 프론트엔드 JSON은 `/prompt` 엔드포인트에서 직접 실행할 수 없으며, 반드시 API 포맷으로의 변환 과정이 선행되어야 한다 [16, 17]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint**: `workflow.json`(프론트엔드 포맷)을 입력받아 서버 측에서 API 포맷으로 자동 변환해 주는 커스텀 노드 프로젝트에 적용됨 [16, 18, 21]. +- **ComfyUI-to-Python-Extension**: 프론트엔드 메타데이터를 유지하여 생성된 Python 스크립트로 만든 이미지가 다시 ComfyUI로 드래그 앤 드롭될 때 워크플로우를 복구할 수 있도록 구현됨 [11]. +- **RunComfy Serverless**: 배포 시 사용자가 업로드한 `workflow.json`에서 레이아웃 정보를 추출하고 시각화 가이드로 활용함 [3, 10]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견으로 applied 단계로 승격 가능) +- **출처 신뢰도:** B (Official Documentation 및 전문 개발자 기술 문서 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. 본 문서는 소스 데이터의 기술적 명세(v1.0 스키마)와 운영 패턴(포맷 이분화)을 중심으로 합성됨. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Generative AI Pipeline.md b/10_Wiki/Comfyui/Generative AI Pipeline.md new file mode 100644 index 00000000..8f06eb68 --- /dev/null +++ b/10_Wiki/Comfyui/Generative AI Pipeline.md @@ -0,0 +1,67 @@ +--- +id: generative-ai-pipeline +title: "Generative AI Pipeline" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI Workflow JSON Serialization"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint/README.md", "DanielPFlorian/ComfyUI-WorkflowGenerator", "pydn/ComfyUI-to-Python-Extension", "ComfyUI/custom_nodes", "ComfyUI/models/LLM/"] +github_commit: "bc85382, 82df278, 6cdcc23" +--- + +# [[Generative AI Pipeline]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로 JSON은 복잡한 생성형 AI 파이프라인을 방향성 비순환 그래프(DAG) 형태로 직렬화하여 시각적 디자인과 프로그래밍적 실행 간의 가교 역할을 하는 핵심 청사진이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **형식의 이분화 (Bifurcation of Formats):** 시각적 레이아웃과 메타데이터를 포함한 '프론트엔드 형식(workflow.json)'과 실행에 필요한 필수 논리만 남긴 'API 형식(workflow_api.json)'으로 구분된다 [2, 4, 5]. +- **메타데이터 임베딩 (Metadata Embedding):** 생성된 PNG 이미지의 tEXt 또는 zTXt 청크 내에 JSON 워크플로 데이터를 숨겨 저장함으로써 이미지 자체가 워크플로 백업 역할을 수행하게 한다 [6-8]. +- **LLM 기반 합성 (LLM-Driven Synthesis):** 자연어 설명을 통해 노드 그래프를 자동 생성하는 다단계 파이프라인(생성-검증-구축)을 통해 비기술자도 복잡한 파이프라인을 구축할 수 있게 한다 [9-11]. +- **실행 모델 역전 (Execution Model Inversion):** 최종 출력 노드에서 시작하여 필요한 의존성만 역추적하여 실행함으로써 그래프 내 미사용 노드의 성능 영향을 최소화한다 [12]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **데이터 복구 및 추출 패턴:** 전용 도구(exiftool)나 온라인 추출기를 사용하여 온라인 플랫폼에서 제거되기 쉬운 이미지 메타데이터 내의 JSON 워크플로를 복구한다 [13-15]. +- **API 정규화 패턴:** 프론트엔드 형식에서 링크 객체를 제거하고 노드 입력값 내에 직접 소스 노드 ID와 슬롯 번호를 임베딩하여 실행 그래프를 간소화한다 [2, 16, 17]. +- **동적 파라미터 주입:** Python 스크립트나 래퍼 라이브러리를 통해 JSON 딕셔너리를 직접 조작하여 시드(Seed), 프롬프트 등을 동적으로 변경하며 대량 생성을 자동화한다 [18-20]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로 JSON 생성은 사용자의 목적에 따라 수동 내보내기, 이미지 메타데이터 추출, 프로그래밍적 생성 및 LLM 기반 합성의 네 가지 경로로 나뉜다. + +**1. 수동 및 시각적 생성:** 사용자는 ComfyUI 웹 인터페이스에서 노드를 연결하여 파이프라인을 설계한다. `Ctrl + S` 또는 메뉴의 'Export' 기능을 통해 프론트엔드 형식의 JSON을 생성할 수 있으며, 이는 노드 위치, 크기, 그룹화 정보 등 캔버스 레이아웃 메타데이터를 모두 포함한다 [21, 22]. API 호출을 위해서는 설정에서 'Dev mode'를 활성화한 후 'Save (API format)'를 선택해야 한다 [23, 24]. + +**2. 이미지 기반 워크플로 추출:** ComfyUI에서 생성된 모든 PNG 이미지는 기본적으로 워크플로 데이터를 포함한다 [25]. 사용자는 이미지를 캔버스에 드래그 앤 드롭하거나 `exiftool -b -workflow input.png > workflow.json` 명령어를 사용하여 JSON을 추출할 수 있다 [14, 26]. 다만, 이미지 편집기나 SNS 업로드 시 메타데이터가 삭제될 수 있으므로 주의가 필요하다 [8, 27]. + +**3. 프로그래밍적 및 API 기반 생성:** 개발자는 Python의 `json` 라이브러리를 사용하여 워크플로 템플릿의 특정 노드 ID와 입력값(inputs)을 수정할 수 있다 [18]. `Comfy API Simplified`와 같은 래퍼는 숫자 ID 대신 노드 제목으로 접근할 수 있게 하여 유지보수성을 높이며, `ComfyUI-to-Python-Extension`은 JSON을 직접 실행 가능한 `.py` 스크립트로 변환한다 [19, 28]. + +**4. LLM 기반 자연어 생성:** `ComfyUI-WorkflowGenerator`와 같은 최신 시스템은 Qwen2.5-14B와 같은 미세 조정된 모델을 사용하여 사용자의 의도를 해석한다 [9, 29]. 이 과정은 1) 논리적 그래프 구조 생성(Generator), 2) 로컬 노드 레지스트리와의 이름 일치 여부 검증(Validator), 3) 실행 가능한 JSON으로 컴파일(Builder)하는 3단계 파이프라인을 거친다 [10, 11]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 문제:** ComfyUI의 잦은 업데이트로 인해 이전 버전의 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다는 점이 지적되었다 [30]. +- **API 형식의 불완전성:** API 형식의 JSON은 실행에는 최적화되어 있으나 시각적 데이터가 제거되어 있어, 이를 다시 UI로 불러올 경우 워크플로의 구조가 파괴된 '스켈레톤' 상태로 나타나는 한계가 있다 [27, 31]. +- **의존성 오류:** 외부 소스에서 로드한 JSON은 'Missing Custom Nodes' 오류(빨간색 박스)를 일으킬 수 있으며, 이는 ComfyUI Manager를 통한 설치 및 서버 재시작으로 해결해야 한다 [32, 33]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 서버 측에서 프론트엔드 형식을 API 형식으로 변환하는 `/workflow/convert` 엔드포인트를 제공한다 (Commit `bc85382`) [31, 34, 35]. +- **ComfyUI-WorkflowGenerator:** 사용자의 자연어 명령(예: "Create a text-to-image workflow using SDXL")을 받아 `ComfyUI/models/LLM/` 내의 모델을 사용하여 워크플로를 자동 생성한다 [11, 36, 37]. +- **ComfyUI-to-Python-Extension:** 워크플로 JSON을 독립형 Python 스크립트로 변환하여 `COMFYUI_PATH` 환경 변수 설정을 통해 서버 없이도 실행 가능한 환경을 구축한다 [28, 38]. +- **P-Reinforce 적용 위치:** `ComfyUI/custom_nodes/` 디렉토리에 설치되는 다양한 커스텀 노드 패키지들에서 JSON 규격 v1.0에 맞춘 직렬화 로직이 구현되어 있다 [39-41]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/JSON Schema v1.0.md b/10_Wiki/Comfyui/JSON Schema v1.0.md new file mode 100644 index 00000000..d01ce5f0 --- /dev/null +++ b/10_Wiki/Comfyui/JSON Schema v1.0.md @@ -0,0 +1,109 @@ +--- +id: json-schema-v1.0 +title: "JSON Schema v1.0" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI Workflow JSON v1.0"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "JSON Schema"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["/specs/workflow_json"] +github_commit: "" +--- + +# [[JSON Schema v1.0]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우 JSON v1.0은 Draft-07 사양을 준수하며, 노드 기반의 생성형 AI 파이프라인을 시각적 메타데이터와 실행 논리로 이원화하여 직렬화하는 표준 규격이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **Draft-07 Specification:** ComfyUI 워크플로우 JSON의 구조적 무결성을 보장하는 최신 공식 스키마 표준이다 [2]. +- **데이터 이원화 (Bifurcation):** 사용자 인터페이스용 'Frontend Format'과 서버 실행용 'API Format'으로 나뉘어 관리된다 [1, 3]. +- **노드 객체 속성 (Node Object Properties):** 각 노드는 ID, 유형, 위치(pos), 크기(size), 위젯 값(widgets_values) 등의 필수 및 선택적 속성을 정의해야 한다 [2, 4]. +- **슬롯 및 링크 연결성 (Slot & Link Connectivity):** 노드 간의 데이터 흐름은 고유한 링크 ID와 입력/출력 슬롯 인덱싱을 통해 정의된다 [5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **실행 모델 반전 (Execution Model Inversion):** 엔진이 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색, 필요한 의존성만 식별하여 실행하는 최적화 패턴을 따른다 [6]. +- **메타데이터 임베딩 (Metadata Embedding):** PNG 파일의 tEXt 또는 zTXt 청크에 Frontend와 API 포맷의 JSON 데이터를 동시에 저장하여 시각적 편집과 프로그래밍적 재실행을 모두 지원한다 [7-9]. +- **버전 호환성 제약:** 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 ComfyUI 버전에서 정상 작동하지 않을 수 있는 패턴이 관찰된다 [10]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우 JSON v1.0은 복잡한 노드 네트워크를 이식 가능하고 사람이 읽을 수 있는 형태의 데이터로 변환하는 핵심 메커니즘이다 [11, 12]. + +**1. 노드 객체의 기술적 구성** +- **필수 속성:** `id`(그래프 탐색용 고유 식별자), `type`(노드 레지스트리의 클래스 이름 매핑), `pos` 및 `size`(UI 렌더링용 좌표 및 크기), `order`(실행 또는 렌더링 순서), `mode`(활성/바이패스 상태)가 포함된다 [2]. +- **선택적 속성:** 사용자가 입력한 슬라이더, 텍스트 박스 등의 값을 저장하는 `widgets_values`가 존재한다 [2]. + +**2. 포맷별 구조적 차이** +- **Frontend JSON (workflow.json):** 시각적 편집을 위해 Litegraph 표준을 따르며, 노드 위치, 그룹 구조, 색상 등 모든 시각적 메타데이터를 포함한다 [1, 3, 13]. +- **API JSON (workflow_api.json):** 서버 사이드 처리에 최적화된 스트림라인 실행 그래프이다 [1]. 시각적 데이터를 제거하고 노드 입력 내에 링크를 직접 임베딩하여 효율성을 극대화한다 [1, 3, 14]. + +**3. 연결 메커니즘** +- 연결은 `links` 배열 내에서 정의되며, 각 항목은 일반적으로 `origin_id`, `origin_slot`, `target_id`, `target_slot`을 정의하는 6개 항목 배열 또는 구조화된 객체이다 [5]. +- 슬롯 인덱싱은 매우 엄격하여, 특정 노드의 여러 출력 슬롯 중 정확히 어떤 데이터가 다운스트림 노드에 소비되는지 명시해야 한다 [5]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **JSON 포맷의 취약성:** PNG 메타데이터에 포함된 JSON은 표준 이미지 편집기나 소셜 미디어 플랫폼에서 압축/편집 시 삭제되기 쉬운 취약점이 있다 [9]. +- **버전 간 비호환성:** 소스에 따르면 ComfyUI의 빈번한 업데이트로 인해 구버전 JSON이 최신 버전에서 작동하지 않을 수 있으며, 이를 해결하기 위해 ComfyUI Manager 등의 도구가 의존성을 해결해야 한다 [10, 15]. +- **필드 명칭 차이:** Frontend 포맷에서는 `type`을 사용하지만 API 포맷에서는 `class_type`이라는 명칭을 사용하여 노드를 식별한다 [3, 16]. + +## 🛠️ 적용 사례 (Applied in summary) +- **공식 문서 경로:** `/specs/workflow_json` 위치에 JSON Schema v1.0 명세가 정의되어 있다 [17]. +- **버전 관리:** 현재 가장 최신 규격은 Version 1.0이며, 이전 버전인 0.4와 구분되어 관리된다 [18]. +- **유효성 검사 도구:** `comfyui-workflow-to-api-converter-endpoint` 커스텀 노드는 서버 사이드에서 비-API 워크플로우를 v1.0 API 포맷으로 변환하는 기능을 구현하고 있다 [19, 20]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 명세 및 개발 문서 기반으로 구조화됨) [2, 21] +- **출처 신뢰도:** B (공식 문서 및 기본 소스 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Draft-07 Specification]] + - 연결 이유: JSON Schema v1.0이 기반으로 삼고 있는 기술 표준이다 [2]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터의 유효성 검사 규칙 및 구조적 제약 조건. +- [[Node-based Visual Programming]] + - 연결 이유: JSON Schema가 표현하고자 하는 추상화된 프로그래밍 모델이다 [11, 22]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드와 링크가 실제 프로그램 논리로 변환되는 원리. + +#### [구현/활용 도구] +- [[API JSON (workflow_api.json)]] + - 연결 이유: v1.0 스키마가 실제로 실행 환경에서 가장 많이 활용되는 형태이다 [1, 14]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 서버리스 배포 및 API 호출 시의 데이터 최적화 방법. +- [[Frontend JSON (workflow.json)]] + - 연결 이유: v1.0 스키마의 시각적 메타데이터를 포함하는 전체 데이터셋이다 [1, 13]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 사용자 인터페이스 상에서의 워크플로우 재구성과 공유. + +### 심층 후속 질문 (Deeper Research Questions) +- v1.0 스키마에서 Draft-07 규격이 구체적으로 어떤 유효성 검사 과정을 거쳐 노드 실행 전 오류를 방지하는가? [2] +- Frontend JSON의 시각적 메타데이터(pos, size)가 실제 백엔드 실행 엔진에 전혀 영향을 주지 않는 구조적 이유는 무엇인가? [1, 3] +- 링크 데이터 표현 방식(6개 항목 배열)에서 각 인덱스가 담고 있는 기술적 의미는 무엇인가? [5] +- [[Execution Model Inversion]] 패턴이 적용될 때, JSON 내에서 사용되지 않는 노드는 어떤 과정을 통해 무시되는가? [6] +- API 포맷에서 `class_type`이 아닌 `inputs` 내에 링크 정보가 포함되는 방식이 실행 속도에 미치는 영향은 무엇인가? [1, 3] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** Python의 `json` 라이브러리를 사용하여 노드 ID를 추적하고 `widgets_values`를 동적으로 수정하여 자동화된 이미지 생성을 구현할 수 있다 [23, 24]. +- **System Design:** 외부 애플리케이션에서 ComfyUI를 호출할 때, `workflow_api.json` 형식을 사용하여 불필요한 UI 데이터를 배제하고 전송 효율을 높인다 [1, 25]. +- **Operation / Maintenance:** `ComfyUI Manager`를 통해 JSON 내의 `class_type`을 파싱하여 누락된 커스텀 노드를 자동으로 설치하고 관리할 수 있다 [15]. +- **Learning Path:** 시각적 워크플로우를 먼저 이해한 후, 개발자 모드를 활성화하여 API 전용 JSON 포맷의 데이터 구조를 분석하는 단계로 학습이 진행된다 [26, 27]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Object_info.json]] + - 확장 방향: 실행 중인 ComfyUI 인스턴스의 노드 스키마 카탈로그를 이해하여 JSON을 동적으로 생성하는 도구 제작 [28, 29]. +- [[Metadata Stripping]] + - 확장 방향: 이미지 파일 공유 시 발생하는 워크플로우 데이터 손실 방지 및 복구 전략 [9, 19]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Lazy Evaluation in Graph Theory.md b/10_Wiki/Comfyui/Lazy Evaluation in Graph Theory.md new file mode 100644 index 00000000..60dad65b --- /dev/null +++ b/10_Wiki/Comfyui/Lazy Evaluation in Graph Theory.md @@ -0,0 +1,100 @@ +--- +id: lazy-evaluation-in-graph-theory +title: "Lazy Evaluation in Graph Theory" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Execution Model Inversion"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["Execution Model Inversion"] +github_commit: "" +--- + +# [[Lazy Evaluation in Graph Theory]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI는 **실행 모델 역전(Execution Model Inversion)** 아키텍처를 통해 출력 노드로부터 역방향으로 그래프를 추적하여 최종 결과에 필요한 노드만 선택적으로 실행함으로써 효율성을 극대화한다 [1]. + +## 🧠 핵심 개념 (Core concepts) +- **유향 비순환 그래프 (Directed Acyclic Graph, DAG):** ComfyUI 워크플로우의 근간으로, 노드 간의 링크가 데이터의 흐름을 정의하며 순환하지 않는 구조를 형성한다 [2]. +- **실행 모델 역전 (Execution Model Inversion):** 그래프의 모든 노드를 순차적으로 실행하는 대신, '출력' 노드에서 시작하여 필요한 의존성만 역추적하는 방식이다 [1]. +- **의존성 식별 (Dependency Identification):** 백엔드 엔진이 최종 결과(예: Save Image)에 기여하지 않는 노드를 무시하고 실행 목록(Execution List)을 구성하는 프로세스이다 [1, 3]. +- **백엔드 실행 그래프 최적화:** API 포맷(workflow_api.json)은 시각적 메타데이터를 제거하고 실행에 필수적인 논리적 연결성만을 포함하여 처리 속도를 높인다 [4, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **역방향 트리거링 패턴:** 사용자나 시스템이 특정 출력 노드를 요청하면, 해당 노드에 연결된 입력 경로를 따라 상위 노드들이 활성화되는 구조를 가진다 [1]. +- **불필요한 계산 배제:** 생성된 JSON 내에 수십 개의 미사용 노드가 포함되어 있더라도 최종 출력에 기여하지 않는다면 성능에 영향을 주지 않는다 [1]. +- **동적 프롬프트 변환:** JSON 워크플로우를 유효성 검사 후 `DynamicPrompt` 및 `ExecutionList`로 변환하여 노드 실행 순서를 최적화한다 [3, 6]. + +## 📖 세부 내용 (Details) +ComfyUI의 지연 평가(Lazy Evaluation)적 접근법은 **그래프 이론의 DAG 구조**를 기반으로 한 **실행 모델 역전** 아키텍처에서 구체화된다 [1, 2]. 전통적인 선형 파이프라인과 달리, ComfyUI 엔진은 'Save Image'와 같은 출력 지점에서부터 그래프를 거꾸로 횡단(Traverse)한다 [1]. 이 과정에서 엔진은 최종 결과물을 생성하기 위해 실행되어야 할 노드와 그 순서를 식별하며, 결과에 기여하지 않는 노드는 백엔드에서 완전히 무시된다 [1]. + +이러한 방식은 대규모 워크플로우를 JSON으로 관리할 때 큰 이점을 제공한다. 사용자는 단일 JSON 파일 내에 다양한 실험적 노드 구성을 유지할 수 있으며, 실제 실행 시에는 필요한 경로만 활성화되므로 성능 저하 없이 유연한 작업이 가능하다 [1]. + +프로그래밍적 관점에서, 이러한 실행 로직은 `WorkflowExecutor` 클래스 등에 의해 캡슐화될 수 있다 [3]. 워크플로우 JSON이 로드되면 `validate_prompt` 함수를 통해 검증되고, 최종적으로 노드별 입력 데이터 검색(`get_input_data`)과 출력 데이터 생성(`get_output_data`)을 거치는 실행 목록으로 변환된다 [3, 6]. 결과적으로 JSON 파일은 단순한 데이터 저장소가 아닌, 실행 엔진이 읽고 최적화할 수 있는 **지시문(Blueprint)** 역할을 수행하게 된다 [7]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **메타데이터의 취약성:** JSON 데이터는 PNG 이미지의 메타데이터(tEXt/zTXt 청크)에 저장되지만, 이미지 편집기나 소셜 미디어 플랫폼을 거치면 이 정보가 손실될 수 있어 데이터의 영속성이 보장되지 않는다 [8]. +- **포맷 간의 괴리:** 시각적 편집용인 'Frontend Format'과 실행용인 'API Format'이 이원화되어 있어, API 포맷 파일을 UI로 다시 불러올 경우 시각적 레이아웃(노드 위치 등)이 누락되는 문제가 존재한다 [4, 9, 10]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Execution Model Inversion:** ComfyUI 공식 백엔드 로직에 적용되어 출력 노드 중심의 역방향 그래프 횡단을 구현함 [1]. +- **WorkflowExecutor:** Python 기반 독립 실행 스크립트 구현 시 워크플로우를 `ExecutionList`로 변환하고 실행하는 핵심 컴포넌트로 제안됨 [3, 6]. +- **ComfyUI-WorkflowGenerator:** LLM을 이용해 자연어 설명을 논리적 그래프 구조(JSON)로 합성하고 이를 실행 가능한 빌더로 전달하는 3단계 파이프라인에서 활용됨 [11, 12]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI 워크플로우의 구조적 근간 [2]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 데이터 흐름의 방향성과 노드 간의 위계적 연결 방식. +- [[Execution Model Inversion]] + - 연결 이유: 지연 평가를 가능하게 하는 핵심 메커니즘 [1]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 백엔드 엔진이 실행 효율성을 높이는 구체적인 알고리즘. + +#### [구현/활용 도구] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: 그래프 구조가 직렬화되어 파일로 저장되는 대상 [2, 7]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 ID, 유형, 입력값 등이 JSON 내에서 어떻게 매핑되는지. +- [[workflow_api.json]] + - 연결 이유: 지연 평가 로직이 적용되는 최종 실행용 파일 포맷 [4, 13]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각 메타데이터가 제거된 순수 실행 그래프의 구조. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI 백엔드에서 역방향 횡단 시 캐싱(Caching)은 중복 계산을 어떻게 방지하는가? [6] +- `DynamicPrompt`가 `ExecutionList`로 변환되는 과정에서 노드의 실행 우선순위(Order)는 어떻게 결정되는가? [3, 14] +- 노드가 'Bypass' 상태일 때 그래프 이론 측면에서 링크 연결성은 어떻게 처리되는가? [15] +- 특정 노드에만 실행을 제한하는 'Partial Execution' 기능은 지연 평가 모델과 어떻게 상호작용하는가? [16, 17] +- LLM 기반 워크플로우 생성기에서 논리적 합성(Logical Synthesis) 결과가 그래프 이론의 유효성을 만족하는지 검증하는 구체적인 알고리즘은 무엇인가? [12, 18] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 독립 실행형 스크립트를 작성할 때 `WorkflowExecutor`를 활용하여 JSON 워크플로우를 직접 제어할 수 있다 [3]. +- **System Design:** API 호출 시 필요한 노드만 포함된 `workflow_api.json`을 사용하여 네트워크 페이로드와 서버 부하를 최소화할 수 있다 [4, 5]. +- **Operation / Maintenance:** 워크플로우 수정 시 미사용 노드를 삭제하지 않고 남겨두더라도 실제 실행 성능에는 영향을 주지 않으므로 유지보수가 용이하다 [1]. +- **Learning Path:** 노드 기반 인터페이스의 시각적 로직을 이해하는 것이 곧 시스템의 실행 논리를 학습하는 과정이 된다 [19]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: 워크플로우 포터빌리티 확보를 위해 파일명 대신 해시를 이용한 모델 식별 방법 [20]. +- [[Natural Language to Workflow Generation]] + - 확장 방향: LLM을 통해 대화형으로 그래프 구조를 생성하는 미래 지향적 방식 [11, 21]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine.--- \ No newline at end of file diff --git a/10_Wiki/Comfyui/Litegraph Standard.md b/10_Wiki/Comfyui/Litegraph Standard.md new file mode 100644 index 00000000..2bcf7987 --- /dev/null +++ b/10_Wiki/Comfyui/Litegraph Standard.md @@ -0,0 +1,97 @@ +--- +id: litegraph-standard +title: "Litegraph Standard" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Litegraph Format", "Frontend JSON Format"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Litegraph", "Frontend"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-frontend-package/src/scripts/metadata", "ComfyUI Settings/Lite Graph"] +github_commit: "" +--- + +# [[Litegraph Standard]] + +## 🎯 한 줄 통찰 (One-line insight) +Litegraph Standard는 ComfyUI의 시각적 워크플로우를 구성하는 노드의 배치, 크기, 그룹 등 **UI 메타데이터를 포함한 그래프 구조를 정의하는 프론트엔드 직렬화 규격**이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **Frontend JSON (workflow.json):** 사용자 상호작용 및 시각화를 위해 설계된 포맷으로, Litegraph 표준을 준수하여 노드의 좌표와 레이아웃 정보를 보존한다 [1, 3]. +- **Visual Metadata:** 노드의 위치(pos), 크기(size), 색상, 그룹 구조, 노드의 축소(collapsed) 또는 고정(pinned) 상태와 같은 시각적 속성을 포함한다 [1, 4]. +- **Explicit Link Objects:** 노드 간의 연결을 별도의 배열 내에서 명시적인 연결 객체(link ID)로 표현하여 그래프 시각화를 용이하게 한다 [1, 3, 5]. +- **Node-Based Interface Compatibility:** Maya, Blender, Unreal Engine 등 타 시각적 프로그래밍 환경과 유사한 그래프 시각화 및 조작 패러다임을 제공한다 [6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **형식의 이분화 (Serialization Bifurcation):** 워크플로우를 저장할 때 시각적 편집을 위한 Litegraph 기반 '프론트엔드 포맷'과 실행 효율을 위한 'API 포맷'으로 구분하여 관리하는 패턴이 발견된다 [1]. +- **스키마 제약 조건 (Schema Constraints):** JSON v1.0 규격에 따라 노드 객체는 고유 ID, 클래스 타입, 좌표, 크기, 실행 순서(order), 모드 등을 반드시 정의해야 한다 [4]. +- **메타데이터 임베딩 (Metadata Embedding):** PNG 파일의 tEXt 또는 zTXt 청크에 Litegraph 형식의 워크플로우 데이터를 삽입하여 이미지 자체가 백업 및 공유 수단이 되도록 설계한다 [7, 8]. + +## 📖 세부 내용 (Details) +Litegraph 표준은 ComfyUI 워크플로우의 **'소스 코드' 역할을 수행하는 프론트엔드 JSON 포맷**의 기술적 근간이다 [1, 9]. 이 표준은 노드 기반의 시각적 프로그래밍 환경에서 노드 간의 데이터 흐름뿐만 아니라, 사용자가 구성한 캔버스 상의 시각적 질서를 보존하는 데 중점을 둔다 [1, 10]. + +주요 기술적 특성은 다음과 같다: +- **데이터 구조:** 루트 레벨에서 `nodes` 배열과 `links` 배열을 포함하며, 각 노드는 캔버스 상의 X, Y 좌표(`pos`)와 너비, 높이(`size`) 정보를 보유한다 [4, 5]. +- **연결 방식:** 노드 내부의 `inputs`와 `outputs`는 단순한 참조가 아닌, 전역 `links` 배열에 정의된 고유한 링크 ID를 통해 상호 연결된다 [5]. 이는 API 포맷에서 입력값에 소스 노드 정보를 직접 내장하는 방식과 대조적이다 [1]. +- **사용자 경험 지원:** 그룹화 기능 및 노드 상태(Active, Bypassed 등)를 지원하여 복잡한 워크플로우의 가독성을 높인다 [4]. +- **호환성 및 확장:** ComfyUI 설정 메뉴에는 'Lite Graph' 관련 전용 설정 카테고리가 존재하며, 이를 통해 인터페이스 동작을 제어할 수 있다 [11, 12]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **실행 호환성 문제:** Litegraph 표준 기반의 JSON(workflow.json)은 노드 좌표 등 불필요한 메타데이터가 많아 백엔드 엔진이 직접 해석하기에 비효율적이며, 종종 `/prompt` 엔드포인트에서 오류를 발생시킨다 [1, 9, 13]. 따라서 서버 실행을 위해서는 이를 API 포맷으로 변환해야 한다 [14]. +- **데이터 취약성:** PNG 이미지에 포함된 Litegraph 메타데이터는 표준 이미지 편집기나 소셜 미디어 플랫폼에서 압축/편집 시 쉽게 손실될 수 있다는 점이 지적된다 [7, 8]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-frontend-package:** 프론트엔드 자바스크립트 컨텍스트 내의 `src/scripts/metadata` 경로에서 공식적인 메타데이터 파싱 로직으로 적용됨 [15]. +- **ComfyUI 설정 메뉴:** 인터페이스 내 Settings > Lite Graph 섹션을 통해 관련 기능이 구현되어 있음 [11]. +- **workflow.json 내보내기:** ComfyUI 제어판의 'Export' 기능을 통해 생성되는 모든 표준 워크플로우 파일의 규격으로 사용됨 [16, 17]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 및 아키텍처 분석을 통해 확인됨) +- **출처 신뢰도:** B (Official Documentation 및 기술 블로그 분석 결과) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[ComfyUI Workflow JSON Generation and Serialization]] + - 연결 이유: Litegraph 표준이 직렬화 프로세스의 핵심 구성 요소임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 프론트엔드와 API 포맷 간의 기술적 차이점. +- [[Visual Programming Environment]] + - 연결 이유: Litegraph가 지향하는 사용자 인터페이스 패러다임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 기반 시스템의 범용적 설계 원리. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: Litegraph JSON을 파싱하여 누락된 커스텀 노드를 식별하고 관리함. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 워크플로우 종속성 해결 메커니즘. + +### 심층 후속 질문 (Deeper Research Questions) +- Litegraph 표준에서 정의하는 `links` 배열의 6가지 인덱스 값은 각각 구체적으로 어떤 데이터를 의미하는가? [5] +- API 포맷(workflow_api.json)으로 변환 시 Litegraph의 어떤 데이터가 가장 먼저 폐기되는가? [1, 3] +- `comfyui-frontend-package`의 자바스크립트 로직은 Litegraph 데이터를 어떻게 검증(Validation)하는가? [15] +- 노드 상태(`mode`) 중 'Bypassed' 처리가 Litegraph 직렬화 결과에 미치는 영향은 무엇인가? [18] +- 0.4 버전에서 1.0 버전으로의 Litegraph 스키마 변경 시 주요 차이점은 무엇인가? [19, 20] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 커스텀 노드 개발 시 `INPUT_TYPES`를 Litegraph 규격에 맞춰 정의하여 UI 상에서 올바르게 렌더링되도록 함 [21]. +- **System Design:** 워크플로우 관리 시스템 설계 시, 시각적 편집용 데이터와 실행 전용 데이터를 분리하여 저장하는 구조를 채택함 [1]. +- **Learning Path:** 초보자가 워크플로우 구조를 이해하기 위해 JSON 파일을 직접 열어 노드 ID와 연결 관계를 추적하는 학습 도구로 활용 가능함 [22]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Directed Acyclic Graph (DAG)]] + - 확장 방향: Litegraph가 시각적으로 표현하는 데이터 흐름의 수학적 모델. +- [[Metadata Stripping]] + - 확장 방향: 이미지 공유 과정에서 Litegraph 정보가 소실되는 보안 및 기술적 이유 분석. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Litegraph.md b/10_Wiki/Comfyui/Litegraph.md new file mode 100644 index 00000000..3bade50a --- /dev/null +++ b/10_Wiki/Comfyui/Litegraph.md @@ -0,0 +1,58 @@ +--- +id: litegraph +title: "Litegraph" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI Settings Menu", "workflow.json"] +github_commit: "" +--- + +# [[Litegraph]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 프론트엔드 워크플로우의 시각적 레이아웃과 노드 연결 구조를 정의하는 핵심 직렬화 표준 규격 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **프론트엔드 JSON 포맷의 근간:** ComfyUI의 시각적 편집 도구인 `workflow.json` 파일이 따르는 표준으로, 노드 기반 그래프의 시각화 및 조작을 위해 설계됨 [1, 2]. +2. **시각적 메타데이터 저장:** 노드의 좌표(`pos`), 크기(`size`), 그룹 구성, 노드의 축소(collapsed) 또는 고정(pinned) 상태와 같은 UI 전용 정보를 포함함 [1, 3]. +3. **명시적 링크 시스템 (Explicit Links):** 노드 간의 연결을 별도의 `links` 배열 내에서 고유 식별자를 가진 객체로 관리하며, 이는 백엔드 실행용 API 포맷과 차별화되는 지점임 [1, 4, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **이분법적 직렬화 구조:** 사용자 인터페이스를 위한 Litegraph 기반의 '프론트엔드 포맷'과 서버 실행을 위한 'API 포맷'을 엄격히 구분하여 운영함 [1, 4, 6]. +- **캔버스 상태 복원 패턴:** Litegraph 규격을 준수함으로써 워크플로우 로드 시 사용자가 마지막으로 작업했던 좌표와 노드 배치를 정확하게 재생성함 [7, 8]. + +## 📖 세부 내용 (Details) +- **기술적 구성 요소:** Litegraph 표준에 따라 노드 객체는 `id`(고유 번호), `type`(노드 클래스명), `pos`(캔버스 내 x, y 좌표), `size`(너비 및 높이), `order`(실행/렌더링 순서) 등 필수 속성을 가짐 [3, 9]. +- **데이터 흐름 정의:** 연결성은 `inputs`와 `outputs` 배열을 통해 정의되며, 각 입력은 고유한 링크 ID를 참조하여 데이터의 기원(origin_id)과 슬롯(origin_slot)을 식별함 [5]. +- **비주얼 프로그래밍 환경:** Maya, Blender, Unreal Engine 등 전문적인 노드 기반 소프트웨어와 유사한 '절차적 프레임워크'를 제공하여 사용자가 복잡한 수학이나 코드 이해 없이도 AI 시스템을 설계할 수 있게 함 [10, 11]. +- **메타데이터 임베딩:** ComfyUI는 Litegraph 규격의 JSON 데이터를 생성된 PNG 파일의 메타데이터(tEXt/zTXt 청크)에 삽입하여, 이미지 파일을 캔버스로 드래그했을 때 워크플로우가 즉시 복구되도록 지원함 [12, 13]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 간 호환성 제약:** ComfyUI의 빈번한 업데이트로 인해 이전 버전의 Litegraph 기반 JSON 파일이 최신 환경에서 제대로 로드되지 않거나 위젯이 사라지는 현상이 발생할 수 있음 [14, 15]. +- **실행 엔진과의 괴리:** Litegraph 포맷은 시각적 정보가 비대하여 백엔드 API 요청 시 오류를 유발할 수 있으므로, 반드시 'Dev mode'를 통한 API 포맷 변환 과정이 필요함 [8, 16]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI 설정(Settings) 메뉴:** 인터페이스 내 설정 창에 'Lite Graph' 섹션이 별도로 존재하여 관련 시각 옵션을 조정할 수 있음 [17, 18]. +- **워크플로우 내보내기(Export):** 사용자가 인터페이스 메뉴에서 'Export'를 선택할 때 생성되는 `workflow.json` 파일이 이 규격을 직접적으로 사용함 [7, 9]. +- **MetaData Parsing Logic:** ComfyUI 프론트엔드 패키지 내의 자바스크립트 컨텍스트(`src/scripts/metadata`)에서 Litegraph 기반의 메타데이터 파싱이 공식적으로 수행됨 [19]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (ComfyUI 공식 문서 및 기술 사양을 통해 규격 확인됨) +- **출처 신뢰도:** B (Official Documentation / Technical Architecture Review via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Metadata Forensics.md b/10_Wiki/Comfyui/Metadata Forensics.md new file mode 100644 index 00000000..4417162c --- /dev/null +++ b/10_Wiki/Comfyui/Metadata Forensics.md @@ -0,0 +1,61 @@ +--- +id: metadata-forensics +title: "Metadata Forensics" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Workflow Extraction", "Metadata Extraction"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Metadata", "Forensics"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-frontend-package/src/scripts/metadata", "exiftool -b -workflow input.png > workflow.json"] +github_commit: "" +--- + +# [[Metadata Forensics]] + +## 🎯 한 줄 통찰 (One-line insight) +Metadata Forensics는 이미지 파일 내부에 은닉된 생성형 AI의 실행 로직(JSON)을 역공학적으로 추출하여 생성 기원의 투명성과 워크플로우 재현성을 확보하는 핵심 기술이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +1. **Metadata Injection (메타데이터 주입):** ComfyUI의 `Save Image` 노드가 실행될 때, 최종 이미지 파일의 헤더에 전체 노드 그래프, 레이아웃, 설정 및 프롬프트 정보를 자동으로 삽입하는 프로세스이다 [4, 5]. +2. **tEXt/zTXt Chunks:** PNG 파일 형식 내에서 워크플로우(Frontend 형식)와 프롬프트(API 형식)라는 두 가지 상이한 문자열 데이터를 저장하는 특수 데이터 영역이다 [3]. +3. **Data Fragility (데이터 취약성):** 내장된 메타데이터는 표준 이미지 편집기, 소셜 미디어 플랫폼, 또는 파일 압축 유틸리티에 의해 제거되기 쉬운 "비필수적" 정보로 취급되어 소실될 위험이 높다 [3, 6]. +4. **Algorithmic Extraction (알고리즘 추출):** 전용 도구나 CLI 유틸리티를 사용하여 이미지의 바이너리 태그를 분석하고, 그 안에 포함된 직렬화된 JSON 데이터를 분리해내는 기술적 절차이다 [7, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **이중 형식 저장 패턴:** ComfyUI는 시각적 편집을 위한 'Frontend JSON'과 실행을 위한 'API JSON'을 이미지 내에 동시에 저장하여 사용자 편의성과 프로그램적 재실행 가능성을 모두 충족시킨다 [3]. +- **드래그 앤 드롭 복구 전략:** 사용자가 이미지 파일을 ComfyUI 캔버스에 직접 끌어다 놓으면 내장된 메타데이터를 즉시 파싱하여 원래의 노드 구성을 복원하는 직관적인 워크플로우 로드 방식이다 [1, 4]. + +## 📖 세부 내용 (Details) +ComfyUI에서 생성된 미디어 파일(PNG, WebP 등)은 단순한 시각적 데이터 이상의 정보를 포함하고 있다 [4, 9]. 워크플로우가 종료되는 `Save Image` 노드는 이미지 생성 시점의 **전체 노드 그래프와 설정을 파일의 숨겨진 메타데이터에 주입**한다 [4, 5]. 구체적으로 PNG 파일의 경우 `tEXt` 또는 `zTXt` 청크를 활용하여 시각적 레이아웃 정보를 담은 Frontend 형식의 JSON과 실제 백엔드 실행에 필요한 API 형식의 JSON(Prompt)을 저장한다 [3]. + +이러한 메타데이터는 워크플로우의 백업 역할을 수행하며, 다른 사용자와 생성 기법을 공유하는 효율적인 수단이 된다 [1, 9]. 그러나 **데이터의 영속성 측면에서 취약점**이 존재한다. 소셜 미디어 플랫폼이나 파일 압축 과정에서 파일 크기 절감을 위해 이러한 메타데이터를 제거하는 경우가 빈번하며, GIMP와 같은 이미지 편집기로 수정할 경우에도 원본 메타데이터가 손실될 수 있다 [3, 6, 8]. + +실무적인 포렌식 및 추출을 위해 다양한 도구가 사용된다. `exiftool`과 같은 범용 도구를 사용하여 특정 태그(`-workflow`)를 지정해 JSON을 추출할 수 있으며, `ComfyUI Workflow Extractor`와 같은 웹 기반 도구나 `comfyui_extractor.py`와 같은 전문 스크립트는 배치 프로세싱을 통해 수천 개의 이미지에서 워크플로우를 대량으로 복구할 수 있게 해준다 [2, 7, 10]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **공유 편의성 vs. 데이터 보존:** 이미지를 통한 워크플로우 공유는 가장 쉬운 방법으로 추천되지만, 네트워크 전송이나 압축 과정에서 메타데이터가 손실될 수 있으므로 **중요한 워크플로우는 별도의 JSON 파일로 저장하는 것이 권장**된다 [3, 5, 6]. +- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해, 메타데이터에서 추출한 이전 버전의 JSON 파일이 최신 버전의 인터페이스에서 정상적으로 작동하지 않을 수 있는 호환성 리스크가 존재한다 [6]. + +## 🛠️ 적용 사례 (Applied in summary) +- **파일 경로:** `comfyui-frontend-package/src/scripts/metadata` (공식 메타데이터 파싱 로직이 구현된 위치) [11]. +- **CLI 명령:** `exiftool -b -workflow input.png > workflow.json` (PNG 메타데이터 청크에서 직렬화된 JSON을 격리하는 표준 명령) [7]. +- **전문 도구:** `Comfy_UI_prompt_extractor`, `comfyui_extractor.py`, `comfyui-workflow-extractor` (AI 아트의 디지털 포렌식 및 기술 라이브러리 유지를 위한 추출 도구들) [7, 10]. +- **설계 결정:** PNG 파일 내에 `workflow`(Frontend)와 `prompt`(API) 정보를 중복 저장하여 시각적 편집과 자동화 실행을 동시에 지원함 [3]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Metadata Stripping.md b/10_Wiki/Comfyui/Metadata Stripping.md new file mode 100644 index 00000000..e7db7d6c --- /dev/null +++ b/10_Wiki/Comfyui/Metadata Stripping.md @@ -0,0 +1,98 @@ +--- +id: metadata-stripping +title: "Metadata Stripping" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["메타데이터 제거", "Metadata Loss"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["GIMP", "Social Media Platforms", "File Compression Utilities"] +github_commit: "" +--- + +# [[Metadata Stripping]] + +## 🎯 한 줄 통찰 (One-line insight) +메타데이터 스트리핑은 이미지 파일에 내장된 워크플로우 데이터를 외부 환경(소셜 미디어, 편집기 등)이 데이터 최적화나 개인정보 보호를 목적으로 제거하여 결과물의 재현성을 파괴하는 현상이다. [1, 2] + +## 🧠 핵심 개념 (Core concepts) +- **데이터 취약성 (Data Fragility):** 이미지 내 메타데이터(tEXt/zTXt 청크)는 표준 이미지 편집기나 압축 소프트웨어에 의해 쉽게 손실될 수 있는 비필수적 데이터로 간주됨. [2] +- **청크 기반 저장 (Chunk-based Storage):** ComfyUI는 PNG 파일의 tEXt 또는 zTXt 청크를 사용하여 워크플로우(Frontend)와 프롬프트(API) JSON 문자열을 저장함. [2] +- **최적화 사이드 이펙트:** 소셜 미디어 플랫폼이나 전송 네트워크가 파일 크기를 줄이기 위해 비이미지 데이터를 자동 제거하는 과정에서 발생함. [2, 3] +- **추출 및 복구 (Extraction & Recovery):** 손실된 메타데이터를 대체하기 위해 별도의 JSON 파일을 보존하거나, 특화된 추출 도구를 사용하여 잔존 데이터를 회수하는 행위. [1, 4] + +## 🧩 추출된 패턴 (Extracted patterns) +- **플랫폼 기반 손실 패턴:** 워크플로우가 포함된 PNG를 소셜 미디어에 게시할 경우, 대부분의 플랫폼은 용량 최적화를 위해 내장된 JSON 데이터를 스트리핑함. [1, 2] +- **도구 기반 제거 패턴:** GIMP와 같은 일반적인 이미지 편집기로 파일을 수정하고 저장할 때, 사용자 정의 메타데이터가 보존되지 않고 삭제됨. [4] +- **전송 매체 종속성:** 압축 소프트웨어를 사용하거나 네트워크를 통해 파일을 전송할 때 메타데이터 정보가 누락될 가능성이 높음. [3] + +## 📖 세부 내용 (Details) +ComfyUI는 생성된 이미지 내부에 전체 노드 그래프와 설정을 주입하는 방식을 취하지만, 이 메타데이터는 매우 **불안정(fragile)**한 상태로 존재한다. [2] + +- **저장 메커니즘:** 워크플로우 정보는 주로 `Save Image` 노드가 실행될 때 최종 이미지의 숨겨진 메타데이터에 주입된다. [5, 6] 구체적으로 PNG 파일 구조 내의 `tEXt` 또는 `zTXt` 청크를 활용하여 시각적 레이아웃(Frontend format)과 실행 로직(API format)을 동시에 저장한다. [2] +- **스트리핑의 주요 원인:** + - **소셜 미디어 및 웹 플랫폼:** 이미지 게시 시 파일 크기를 줄이거나 업로더의 프라이버시를 보호하기 위해 비필수 메타데이터를 모두 제거한다. [1, 2] + - **이미지 편집 소프트웨어:** GIMP 등의 도구로 이미지를 편집하면 원본에 포함되어 있던 사용자 정의 청크 정보가 유실된다. [4] + - **파일 압축 및 전송:** 압축 유틸리티나 특정 네트워크 전송 프로토콜은 이미지 데이터 외의 부가 정보를 정리하는 경향이 있다. [2, 3] +- **영향 및 대안:** 메타데이터가 스트리핑된 이미지는 ComfyUI 캔버스로 드래그 앤 드롭해도 워크플로우를 복원할 수 없다. [3, 6] 이를 방지하기 위해 복잡한 워크플로우는 반드시 **JSON 파일** 형태로 별도 저장 및 공유하는 것이 권장된다. [6] 이미 스트리핑이 우려되는 환경에서는 `exiftool`이나 전문 추출기(Workflow Extractor)를 사용하여 데이터 유무를 확인하거나 미리 추출해 두어야 한다. [1, 7] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **이미지 vs JSON 저장의 신뢰성:** 초기에는 이미지 드래그 앤 드롭이 가장 쉬운 방법으로 소개되지만, 소스에서는 새로운 노드나 커스텀 노드가 누락될 수 있는 문제와 메타데이터 손실 위험 때문에 **JSON 파일 저장**을 최종적으로 더 강력히 권장한다. [6] +- **재삽입 요구사항:** 단순 추출을 넘어 유실된 메타데이터를 다시 이미지에 삽입(Insert)하거나 복사(Copy)하는 기능에 대한 요구가 커뮤니티에서 지속적으로 제기되고 있다. [4] + +## 🛠️ 적용 사례 (Applied in summary) +- **GIMP 편집 환경:** 사용자가 pythongosssss 워크플로우 이미지를 제작한 후 GIMP에서 수정 시 메타데이터가 삭제되어 재삽입 기능이 필요해진 사례가 보고됨. [4] +- **소셜 미디어 게시물:** 온라인에 게시된 PNG 파일들에서 일반적으로 JSON 데이터가 제거되어 있어, 이를 해결하기 위한 `Weird Wonderful AI Art` 등의 전용 추출 도구가 개발됨. [1] +- **Comfy-CLI 도구:** 이미지, webp, mp4 등 지원되는 미디어에서 워크플로우를 추출, 삽입, 복사하는 기능을 `comfy-cli`에 포함시키려는 개선 제안(Issue #341)이 진행 중임. [4, 8] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 유실 사례 및 대응 도구 존재 확인됨) +- **출처 신뢰도:** B (공식 문서 및 개발자 커뮤니티 이슈 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow JSON]] + - 연결 이유: 스트리핑되는 데이터의 실체이자 표준 규격임. [9, 10] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON의 구조적 특성이 메타데이터 청크에 어떻게 인코딩되는지 이해 가능. +- [[PNG Metadata Chunks]] + - 연결 이유: 데이터가 물리적으로 저장되는 tEXt/zTXt 위치를 정의함. [2] + +#### [구현/활용 도구] +- [[ComfyUI Workflow Extractor]] + - 연결 이유: 스트리핑되지 않은 데이터를 이미지에서 회수하는 도구임. [1] +- [[exiftool]] + - 연결 이유: 명령줄 기반으로 이미지 메타데이터를 직접 추출하거나 조작하는 표준 도구임. [7, 11] + +### 심층 후속 질문 (Deeper Research Questions) +- PNG 외에 WebP나 MP4 포맷에서도 동일한 메타데이터 스트리핑 패턴이 발생하는가? [4] +- 메타데이터 손실을 방지하면서 이미지를 압축할 수 있는 무손실 전송 규격이 존재하는가? [2, 3] +- 스트리핑된 데이터를 복구하기 위해 AI 가 이미지의 특성을 분석하여 역으로 워크플로우를 추론하는 것이 가능한가? +- 특정 소셜 미디어 플랫폼 중 메타데이터를 보존하는 예외적인 사례가 있는가? [1] +- `exiftool`을 사용하여 정의되지 않은(unregistered) 태그에 워크플로우를 강제로 삽입할 때 발생하는 호환성 문제는 무엇인가? [11] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 워크플로우 공유 시 이미지 파일만 전달하지 말고 JSON 파일을 병행 제공하여 데이터 유실에 대비해야 함. [3, 6] +- **System Design:** API 서버 구축 시 외부에서 입력된 이미지의 메타데이터 존재 여부를 검증하는 로직이 필요함. [12] +- **Operation / Maintenance:** 커뮤니티 배포용 이미지는 메타데이터를 유지하는 전용 툴(예: pythongosssss workflow image)을 사용하여 생성하는 것이 안전함. [4] +- **Learning Path:** 워크플로우 저장 방식을 익힐 때 단순 'Save'와 'Export'의 차이, 그리고 이미지 내장 방식의 한계를 먼저 파악해야 함. [6, 13] + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: 메타데이터 유실뿐만 아니라, 워크플로우 내 모델 파일명 불일치 문제를 해결하는 보완 기술임. [14] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [Source 3, 14, 18, 32, 170] \ No newline at end of file diff --git a/10_Wiki/Comfyui/Model Hashing (SHA-256).md b/10_Wiki/Comfyui/Model Hashing (SHA-256).md new file mode 100644 index 00000000..489f3956 --- /dev/null +++ b/10_Wiki/Comfyui/Model Hashing (SHA-256).md @@ -0,0 +1,96 @@ +--- +id: model-hashing-(sha-256) +title: "Model Hashing (SHA-256)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["SHA-256 Model Verification", "Content-based Model Identification"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfy-pack", ".cpack.zip"] +github_commit: "" +--- + +# [[Model Hashing (SHA-256)]] + +## 🎯 한 줄 통찰 (One-line insight) +모델 해싱은 가변적인 파일 이름 대신 고유한 SHA-256 지문을 통해 모델 가중치를 식별함으로써, 서로 다른 환경 간의 워크플로 이식성과 재현성을 보장하는 핵심 기술이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **SHA-256 알고리즘:** 모델 가중치 데이터로부터 고유한 고정 길이 식별자를 생성하여 데이터의 무결성을 검증하고 식별하는 표준 해시 함수이다 [1]. +2. **이식성 및 재현성 (Portability):** 제작자와 사용자의 환경에서 모델 파일 이름(예: `sd_xl_base.safetensors` vs `sdxl_v10.safetensors`)이 다르더라도 동일한 모델임을 인식하게 한다 [1, 2]. +3. **메타데이터 통합:** 워크플로 JSON 또는 관련 아카이브 파일 내에 해시 정보를 포함시켜 시스템이 로컬 파일 시스템에서 올바른 모델을 자동으로 찾도록 지원한다 [1, 2]. +4. **의존성 해결 (Dependency Resolution):** ComfyUI Manager와 같은 도구가 누락된 모델을 검색하거나 대체 모델을 제안할 때 기준점으로 활용된다 [2]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **콘텐츠 기반 식별 (Content-Addressable Identification):** 파일 경로가 아닌 실제 데이터의 내용을 기반으로 자원을 식별하여 "Model Not Found" 오류를 방지하는 설계 패턴이다 [1]. +- **워크스페이스 패키징 (Workspace Packaging):** 단순 JSON 배포에서 벗어나 JSON, 모델 해시, 커스텀 노드 버전을 `.cpack.zip`과 같은 단일 아티팩트로 묶어 관리하는 추세가 발견된다 [2]. + +## 📖 세부 내용 (Details) +모델 해싱은 ComfyUI 워크플로의 고질적인 문제인 **모델 경로 및 이름 불일치**를 해결하기 위한 고급 직렬화 기법이다 [1]. 일반적으로 워크플로는 제작자의 로컬 경로를 참조하지만, 타인의 환경에서는 파일 이름이 다를 가능성이 높다 [1]. + +이를 해결하기 위해 **comfy-pack**과 같은 도구는 모델 가중치의 **SHA-256 해시**를 계산하여 저장한다 [1, 2]. 시스템은 실행 시 파일 이름 대신 이 해시값을 대조하여, 파일명이 다르더라도 가중치가 일치하는 로컬 파일을 찾아 연결한다 [1]. + +최근에는 워크플로 JSON 외에도 모델 해시 정보를 포함하는 **아티팩트 기반 배포**가 도입되고 있으며, 이는 향후 워크플로가 업데이트되거나 특정 노드가 더 이상 지원되지 않더라도 실행 가능성을 유지하는 기술적 토대가 된다 [2]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **최신 트렌드:** 기존의 원시(raw) JSON 의존 방식에서 모델 해시와 노드 버전 정보를 포함한 **.cpack.zip** 기반의 패키징 방식으로 진화하고 있다 [2]. +- **수동 해결의 한계:** 수동으로 모델을 다시 선택하는 방식은 대규모 자동화나 API 환경에서 비효율적이므로, 해싱을 통한 자동 검색(Comfy Manager search)이 권장되는 해결책으로 제시된다 [2]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfy-pack:** 워크플로 직렬화 시 모델 가중치의 SHA-256 해시를 생성하고 활용하는 도구로 명시됨 [1, 2]. +- **.cpack.zip (Workspace Packaging):** 워크플로 JSON과 함께 모델 해시 정보를 포함하여 배포하는 표준화된 패키지 형식에 적용됨 [2]. +- **ComfyUI Manager:** 모델 경로가 깨졌을 때 해시 정보를 바탕으로 모델을 검색하고 복구하는 기능에 활용됨 [2]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 도구인 comfy-pack과 연계된 개념으로 applied 수준에 근접함) +- **출처 신뢰도:** B (Official Documentation 및 기술 분석 자료 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[ComfyUI Workflow JSON]] + - 연결 이유: 모델 해시 정보가 저장되는 근본적인 데이터 구조임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 모델 참조 방식의 변화. +- [[Serialization Formats (Frontend vs API)]] + - 연결 이유: API 자동화 시 모델 해싱을 통한 경로 해결이 필수적임. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 누락된 모델을 해시 기반으로 찾고 설치하는 주체임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 실무적인 의존성 관리 전략. +- [[Workspace Packaging]] + - 연결 이유: 해시를 포함한 아카이브 배포의 최상위 개념임. + +### 심층 후속 질문 (Deeper Research Questions) +- SHA-256 해시 계산이 수 기가바이트(GB) 규모의 모델 파일을 로드할 때 발생하는 성능 오버헤드는 어느 정도인가? +- 모델 파일의 일부(예: 메타데이터)가 수정되었을 때 해시값이 변경되어 발생하는 위양성(False Negative) 문제를 어떻게 관리하는가? +- 서로 다른 체크포인트 병합(Merging) 모델에 대해 SHA-256 해싱이 제공하는 고유 식별의 신뢰도는 어떠한가? +- 클라우드 기반 API 환경(Replicate, Mystic 등)에서 로컬 모델 해시를 기반으로 가중치를 동적 로딩하는 메커니즘은 무엇인가? +- 모델 해싱 정보를 JSON 스키마 v1.0 내에 공식적으로 표준화하려는 RFC 논의가 존재하는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `comfy-pack`을 사용하여 워크플로를 내보낼 때 자동으로 해시값을 생성하도록 설정함 [1]. +- **System Design:** 워크플로 배포 시 파일명 대신 해시를 식별자로 사용하는 인벤토리 관리 시스템 구축 [2]. +- **Operation / Maintenance:** 모델 파일명 변경 시에도 API 호출이 끊기지 않도록 해시 기반의 모델 매핑 레이어 운영 [2]. +- **Learning Path:** 초보자가 외부 워크플로를 로드할 때 발생하는 "Model Not Found" 오류의 원인과 해시를 통한 해결 원리를 학습함 [1, 2]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Custom Node Dependency Management]] + - 확장 방향: 모델뿐만 아니라 커스텀 노드 버전의 일관성을 유지하는 방법으로 확장. + + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on Source [1, 2]) \ No newline at end of file diff --git a/10_Wiki/Comfyui/Model Hashing.md b/10_Wiki/Comfyui/Model Hashing.md new file mode 100644 index 00000000..e5054c59 --- /dev/null +++ b/10_Wiki/Comfyui/Model Hashing.md @@ -0,0 +1,91 @@ +--- +id: model-hashing +title: "Model Hashing" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["SHA-256 Model Identification"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "portability", "serialization"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfy-pack", ".cpack.zip"] +github_commit: "" +--- + +# [[Model Hashing]] + +## 🎯 한 줄 통찰 (One-line insight) +모델 가중치의 고유한 디지털 지문(SHA-256)을 생성하여 파일명이나 경로의 불일치에 관계없이 워크플로우의 이식성과 재현성을 보장하는 핵심 기술 [1]. + +## 🧠 핵심 개념 (Core concepts) +1. **SHA-256 기반 식별:** 모델 파일의 가중치를 해싱하여 중복되지 않는 고유 식별자를 부여함 [1]. +2. **파일명 독립성 (Filename Independence):** 서로 다른 시스템에서 모델 파일명이 다르더라도(예: `sd_xl_base_v10` vs `sdxl_base`) 동일 모델임을 인식 가능하게 함 [1]. +3. **고급 직렬화 (Advanced Serialization):** 표준 JSON 포맷을 넘어 모델 해시를 포함한 아티팩트 중심의 워크플로우 패키징을 지향함 [1, 2]. +4. **의존성 무결성:** 워크플로우 실행 시 필요한 정확한 모델 버전을 확인하여 "Model Not Found" 오류를 근본적으로 해결함 [1, 2]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **콘텐츠 중심 참조 패턴:** 하드코딩된 '파일 경로' 대신 파일의 '내용(Hash)'을 기준으로 리소스를 조회하는 참조 전략 [1]. +- **워크스페이스 패키징 패턴:** JSON 워크플로우, 모델 해시, 커스텀 노드 버전을 하나의 아카이브(`.cpack.zip`)로 묶어 배포하는 표준화 패턴 [2]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우의 이식성에서 가장 큰 장애물 중 하나는 **모델 파일의 명명 규칙과 경로의 불일치**이다 [1]. 제작자의 컴퓨터에서는 `sd_xl_base_v10.safetensors`로 저장된 파일이 사용자의 환경에서는 `sdxl_base.safetensors`로 존재할 수 있으며, 이 경우 표준 JSON 워크플로우는 해당 모델을 찾지 못해 실행에 실패한다 [1, 2]. + +이를 해결하기 위해 `comfy-pack`과 같은 고급 직렬화 도구는 **SHA-256 해시**를 활용한다 [1]. 워크플로우 생성 시 모델 가중치의 해시값을 계산하여 메타데이터에 포함시키면, 시스템은 파일명 대신 해시값을 검색하여 로컬 저장소에서 일치하는 모델을 찾아낼 수 있다 [1]. + +이 기술은 단순한 오류 수정을 넘어, 향후 **워크스페이스 패키징**의 핵심 요소로 자리 잡고 있다 [2]. `.cpack.zip` 포맷은 워크플로우 JSON과 함께 모델 해시 정보를 담아, 개별 커스텀 노드가 업데이트되거나 삭제되더라도 생성 시점의 논리를 그대로 재현할 수 있는 '아티팩트 기반 배포'를 가능하게 한다 [2]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **표준 vs 확장:** 기본 ComfyUI의 "Save" 또는 "Save (API)" 기능은 현재 모델 해싱을 기본적으로 포함하지 않으며, 이는 `comfy-pack`과 같은 별도의 고급 도구나 향후 도입될 표준 포맷에서 지원되는 기능이다 [1, 2]. +- **성능 오버헤드:** 대용량 모델 파일에 대한 SHA-256 계산은 리소스를 소모할 수 있으나, 소스에서는 이를 워크플로우 안정성을 위한 필수적인 비용으로 간주한다 [1]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfy-pack:** 모델 가중치의 SHA-256 해시를 사용하여 경로 및 파일명 문제를 해결하는 직렬화 도구로 명시됨 [1]. +- **.cpack.zip (워크스페이스 패키징):** 워크플로우 JSON, 모델 해시, 커스텀 노드 버전을 통합하여 미래에도 작동 가능한 배포 단위를 생성하는 포맷에 적용됨 [2]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (comfy-pack 등 실제 도구에서 사용 중임을 확인) +- **출처 신뢰도:** B (전문 아키텍처 기술 문서 및 공식 문서 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow API JSON]] + - 연결 이유: 해시 정보가 삽입되거나 참조되는 기본 실행 구조체 [3]. +- [[Serialization Formats]] + - 연결 이유: JSON 포맷을 넘어선 데이터 보존 전략의 일부 [1, 4]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 모델 검색 및 누락된 의존성 해결 시 해시 정보를 활용할 수 있는 도구 [2]. +- [[Workspace Packaging]] + - 연결 이유: 모델 해싱이 실제 구현되는 최상위 배포 단위 [2]. + +### 심층 후속 질문 (Deeper Research Questions) +- `comfy-pack`에서 SHA-256 해시를 계산할 때 대용량 모델(예: 10GB+)에 대한 계산 속도 최적화 방법은 무엇인가? +- 모델 해시가 일치하지만 파일명이 다를 때, ComfyUI 내부적으로 자동으로 연결을 매핑하는 로직은 어떻게 구현되는가? +- 향후 `.cpack.zip` 표준이 확정될 때, 모델 해시 외에 환경(Python 버전 등)에 대한 해싱도 포함될 계획이 있는가? +- 모델 가중치의 일부가 변경(Fine-tuning 등)되었을 때, 해시 변화에 따른 의존성 관리 전략은 무엇인가? +- 외부 API 서비스(Replicate, Mystic 등)에서 모델 해싱을 통한 프리로드(Pre-load) 최적화가 가능한가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `comfy-pack` 라이브러리를 사용하여 모델 의존성이 포함된 패키지를 생성할 때 해싱 로직을 호출함 [1]. +- **System Design:** 다수의 머신에서 동일한 워크플로우를 실행해야 하는 서버리스 환경에서 모델 이름 불일치 문제를 방지함 [2]. +- **Operation / Maintenance:** 모델 라이브러리의 파일명이 변경되더라도 기존 워크플로우의 작동 여부를 검증하는 무결성 체크용으로 활용함 [1]. +- **Learning Path:** 단순한 UI 저장을 넘어 아키텍처 수준의 워크플로우 자동화 및 배포를 이해하는 단계에서 학습함 [5]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Metadata Stripping]] + - 확장 방향: 이미지 배포 시 해시 정보 등 메타데이터가 손실되는 문제와 그 방지책 [6]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Natural Language to Workflow Generation.md b/10_Wiki/Comfyui/Natural Language to Workflow Generation.md new file mode 100644 index 00000000..0bb5054e --- /dev/null +++ b/10_Wiki/Comfyui/Natural Language to Workflow Generation.md @@ -0,0 +1,69 @@ +--- +id: natural-language-to-workflow-generation +title: "Natural Language to Workflow Generation" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Natural Language to Workflow", "LLM-based Workflow Generation"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["DanielPFlorian/ComfyUI-WorkflowGenerator", "ComfyGPT research"] +github_commit: "82df278" +--- + +# [[Natural Language to Workflow Generation]] + +## 🎯 한 줄 통찰 (One-line insight) +자연어 설명을 대규모 언어 모델(LLM)을 통해 ComfyUI의 실행 가능한 노드 그래프(JSON)로 자동 변환함으로써 시각적 프로그래밍의 진입 장벽을 제거하고 생성 속도를 혁신적으로 높이는 기술이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **3단계 파이프라인 (Multi-stage Pipeline):** 논리 생성(Generator), 시맨틱 검증(Validator), 그래프 구축(Builder)의 순차적 과정을 통해 자연어를 워크플로우로 변환한다 [3, 4]. +- **노드 카탈로깅 (Node Cataloging):** 로컬에 설치된 네이티브 및 커스텀 노드를 스캔하고 색인화하여 LLM이 실제 존재하는 노드만을 사용하도록 보장한다 [5, 6]. +- **특화 LLM 미세조정 (Fine-tuned LLMs):** Qwen2.5와 같은 모델을 ComfyUI 스키마 및 노드 레지스트리 데이터로 미세 조정하여 워크플로우 구조에 최적화된 출력을 생성한다 [1, 7]. +- **시맨틱 임베딩 (Semantic Embedding):** 자연어 설명과 실제 노드 클래스 명칭 사이의 의미적 유사성을 계산하여 정확한 노드 매핑을 수행한다 [7, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **합성-검증-컴파일 루프:** LLM이 논리적 구조를 먼저 설계(Logical Synthesis)하고, 이를 로컬 노드 레지스트리와 대조(Semantic Validation)한 뒤, 최종 JSON으로 변환(Graph Compilation)하는 구조적 설계 패턴이 관찰된다 [3]. +- **로컬 환경 접지(Local Grounding):** 모델의 지식이 훈련 시점에 고정되는 한계를 극복하기 위해, 실행 전 "Update Node Catalog" 노드를 실행하여 현재 시스템의 노드 정보를 동기화하는 패턴을 사용한다 [5, 9]. + +## 📖 세부 내용 (Details) +자연어 기반 워크플로우 생성은 사용자가 "SDXL을 사용한 텍스트-투-이미지 워크플로우 생성"과 같은 지시어를 입력하면 시스템이 이를 분석하여 노드 간의 연결 관계를 정의하는 JSON 파일을 생성하는 과정이다 [2]. + +**1. 생성 단계 (Generator):** +이 단계에서는 fine-tuned된 모델(예: Qwen2.5-14B)이 지시어의 의도를 해석하여 논리적 그래프 구조를 생성한다 [3, 7]. 모델은 노드 간의 데이터 흐름(예: CLIP Text Encode에서 KSampler로의 연결)을 이해하고 이를 추상적인 JSON 형태로 출력한다 [8]. + +**2. 검증 단계 (Validator):** +생성된 논리 구조의 노드 명칭이 실제 시스템에 존재하는지 확인한다 [3, 4]. `sentence-transformers`와 같은 임베딩 모델을 사용하여 의미적으로 가장 유사한 실제 노드를 찾아 수정하며, 이 과정을 통해 LLM의 환각(Hallucination) 현상을 방지한다 [7, 8]. + +**3. 구축 단계 (Builder):** +검증된 구조를 ComfyUI 실행 엔진이 인식할 수 있는 최종 .json 포맷으로 변환한다 [3, 10]. 이 과정에서 노드의 위치(pos), 크기(size), 위젯 값(widgets_values) 등 UI 메타데이터와 실행 순서(order)가 할당된다 [10, 11]. + +**주요 기술적 사양:** +- **모델 구조:** GGUF 포맷으로 양자화된 Qwen2.5 모델군이 주로 사용되며, 효율적인 추론을 위해 llama-cpp-python 라이브러리가 요구된다 [7, 12]. +- **데이터 한계:** 정적 미세 조정을 거친 모델은 훈련 이후에 출시된 새로운 커스텀 노드에 대한 지식이 부족할 수 있으므로 지속적인 카탈로그 업데이트와 사용자의 감독이 권장된다 [9, 13]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +과거의 워크플로우 생성 방식이 수동적인 노드 연결과 JSON 편집에 의존했다면, 최신 기술인 **ComfyGPT** 아키텍처는 이를 '대화형 프로그래밍' 패러다임으로 전환하고 있다 [3]. 소스에 따르면, 정적 모델은 실시간으로 변화하는 커스텀 노드 생태계를 따라잡기 어렵다는 문제점이 제기되었으며, 이를 해결하기 위해 향후에는 정적 미세 조정을 넘어선 동적 아키텍처로의 진화가 필요함이 명시되어 있다 [9]. + +## 🛠️ 적용 사례 (Applied in summary) +- **DanielPFlorian/ComfyUI-WorkflowGenerator:** 자연어 설명을 통해 워크플로우를 생성하는 실제 커스텀 노드 구현체이다 [2, 14]. +- **핵심 노드 구성:** `Workflow Generator Pipeline`, `WorkflowGenerator`, `NodeValidator`, `WorkflowBuilder`, `UpdateNodeCatalog` 등의 노드가 실제 프로젝트 파일 구조(`nodes/`, `generators/`) 내에 구현되어 있다 [6, 8, 10, 14, 15]. +- **수정 이력:** Git 커밋 `82df278`에서 드롭다운 메뉴의 중복 모델 표시 문제가 해결된 기록이 발견된다 [14]. +- **연구 기반:** 이 기술은 "ComfyGPT: A Self-Optimizing Multi-Agent System..." 연구의 아키텍처를 로컬 ComfyUI 환경에 맞게 구현한 것이다 [2, 4]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 구현체인 ComfyUI-WorkflowGenerator 프로젝트 확인됨) +- **출처 신뢰도:** B (Official Documentation 및 GitHub 저장소 데이터 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/PNG Metadata Chunks.md b/10_Wiki/Comfyui/PNG Metadata Chunks.md new file mode 100644 index 00000000..af2e142f --- /dev/null +++ b/10_Wiki/Comfyui/PNG Metadata Chunks.md @@ -0,0 +1,72 @@ +--- +id: png-metadata-chunks +title: "PNG Metadata Chunks" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-frontend-package/src/scripts/metadata", "exiftool -b -workflow"] +github_commit: "" +--- + +# [[PNG Metadata Chunks]] + +## 🎯 한 줄 통찰 (One-line insight) +PNG 이미지의 표준 데이터 블록에 워크플로우의 시각적 구조와 실행 로직을 동시에 내장하여, 이미지 파일 자체를 **휴대 가능한 독립적 실행 스크립트**로 변모시키는 핵심 메커니즘 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **tEXt 및 zTXt 청크 (Chunks):** ComfyUI가 워크플로우 데이터를 저장하기 위해 활용하는 PNG 표준의 텍스트 데이터 보관 영역이다 [2]. +- **메타데이터 주입 (Metadata Injection):** `Save Image` 노드가 실행될 때, 최종 이미지 데이터와 함께 전체 노드 그래프, 레이아웃 설정, 프롬프트를 파일의 숨겨진 영역에 주입하는 프로세스다 [1, 4]. +- **데이터 이원화 (Bifurcation):** 하나의 이미지 내에 시각적 편집을 위한 'Frontend 포맷(workflow)'과 프로그래밍 방식의 실행을 위한 'API 포맷(prompt)' 정보를 중복 저장하여 호환성을 확보한다 [2]. +- **데이터 취약성 (Data Fragility):** 표준 이미지 편집기, 소셜 미디어 플랫폼, 또는 파일 압축 유틸리티를 거칠 경우 비필수적인 메타데이터 청크가 제거되어 워크플로우 정보가 유실될 위험이 크다 [2, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **종단 노드 자동 기록 패턴:** 거의 모든 워크플로우가 `Save Image` 노드에서 종료되며, 이 노드가 실행되는 순간 현재 캔버스의 모든 상태를 이미지 메타데이터에 자동으로 동기화한다 [1]. +- **드래그 앤 드롭 복구 패턴:** 사용자가 PNG 파일을 ComfyUI 캔버스로 드래그하면, 시스템이 메타데이터 청크를 파싱하여 즉시 노드 레이아웃과 설정을 재현한다 [1, 5, 6]. +- **CLI 기반 벌크 추출 패턴:** 다수의 이미지에서 수동 조작 없이 워크플로우를 대량으로 회수하기 위해 `exiftool`과 같은 명령줄 도구를 활용하여 특정 청크 데이터를 추출한다 [7, 8]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우는 전형적인 시각적 프로그래밍의 결과물로, 이를 PNG 파일의 **메타데이터 청크**에 저장함으로써 이동성과 재현성을 극대화한다 [1, 9]. + +- **청크의 기술적 구성:** + - 주로 **tEXt** 또는 압축된 형태인 **zTXt** 청크를 사용하여 두 가지 주요 문자열을 저장한다 [2]. + - 하나는 사용자 인터페이스(UI) 상의 노드 위치, 크기, 그룹화 정보를 포함한 **Frontend JSON** 데이터다 [2, 10]. + - 다른 하나는 서버 백엔드에서 즉시 실행 가능한 형태인 **API JSON(Prompt)** 데이터로, 시각적 정보가 제거된 압축된 실행 그래프다 [2, 10, 11]. + +- **워크플로우 추출 및 분석:** + - 이미지에서 워크플로우를 추출하기 위해 전용 웹 도구나 Python 라이브러리가 사용되기도 한다 [8, 12]. + - 명령줄 도구인 `exiftool`을 사용할 경우, `-workflow` 태그를 지정하여 바이너리 데이터를 JSON 파일로 분리해낼 수 있다 [7, 8]. + - 공식적인 메타데이터 파싱 로직은 ComfyUI 프론트엔드 패키지의 자바스크립트 컨텍스트 내에서 관리된다 [13]. + +- **장점 및 한계:** + - 별도의 JSON 파일을 관리할 필요 없이 이미지 하나로 모든 생성 정보를 공유할 수 있다는 점이 가장 큰 장점이다 [14]. + - 그러나 파일이 온라인에 게시되거나 재가공될 때 메타데이터가 삭제(Stripped)되는 경우가 빈번하며, 매우 복잡하거나 최신 커스텀 노드가 포함된 경우 간혹 일부 노드 정보가 유실될 수 있다는 기술적 한계가 보고되었다 [2, 4, 12]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **저장 안정성 논란:** 첫 번째 저장 방식인 '이미지 메타데이터' 방식은 가장 간편하지만, 소스에 따르면 복잡한 노드나 특정 커스텀 노드를 누락할 가능성이 있어, 보다 확실한 백업을 위해서는 두 번째 방식인 **수동 JSON 파일 저장**이 권장된다 [4]. +- **포맷 호환성 이슈:** ComfyUI의 빈번한 업데이트로 인해, 과거 이미지 메타데이터에 내장된 구버전 JSON 형식이 최신 버전의 인터페이스에서 정상적으로 작동하지 않을 수 있다는 점이 지적되었다 [5]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Exiftool 추출 명령:** `exiftool -b -workflow input.png > workflow.json` 명령어를 통해 PNG의 메타데이터 청크에서 워크플로우 JSON을 격리하여 저장하는 사례가 확인된다 [7, 8]. +- **Frontend 파싱 위치:** 공식적인 메타데이터 파싱 로직은 `comfyui-frontend-package` 내부의 `src/scripts/metadata` 경로에서 구현 및 관리되고 있다 [13]. +- **커스텀 노드 연동:** `pythongosssss`의 워크플로우 이미지 생성 노드 등을 통해 워크플로우 정보가 포함된 이미지를 생성하고, 이를 다시 `workflow_templates`로 활용하기 위해 JSON을 추출하는 작업 흐름이 존재한다 [15]. +- **온라인 추출 도구:** `weirdwonderfulai.art` 등에서 제공하는 워크플로우 추출기는 사용자가 드롭한 PNG의 메타데이터 청크를 분석하여 JSON 파일로 다운로드할 수 있게 한다 [12, 16]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Serialization Formats (Frontend vs API).md b/10_Wiki/Comfyui/Serialization Formats (Frontend vs API).md new file mode 100644 index 00000000..08877a47 --- /dev/null +++ b/10_Wiki/Comfyui/Serialization Formats (Frontend vs API).md @@ -0,0 +1,113 @@ +--- +id: serialization-formats-(frontend-vs-api) +title: "Serialization Formats (Frontend vs API)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Frontend JSON", "API JSON", "workflow.json", "workflow_api.json"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Serialization", "API"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint (bc85382)", "ComfyUI-to-Python-Extension", "Mystic Pipeline (new_pipeline.py)"] +github_commit: "bc85382" +--- + +# [[Serialization Formats (Frontend vs API)]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI는 인간 중심의 시각적 편집을 위한 **Frontend Format**과 기계 중심의 효율적 실행을 위한 **API Format**으로 직렬화 규격을 이원화하여 관리한다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **Frontend Format (workflow.json):** 사용자와의 상호작용 및 시각화를 위해 설계된 포맷으로, Litegraph 표준을 따르며 노드 좌표, 크기, 그룹화 정보 등 모든 UI 메타데이터를 포함한다 [1, 3, 4]. +- **Backend/API Format (workflow_api.json):** 서버 사이드 처리에 최적화된 스트림라인 실행 그래프로, 시각적 메타데이터를 제거하고 실행에 필요한 노드 유형과 입력값, 연결 관계만을 유지한다 [1, 5]. +- **Metadata Stripping:** API 포맷 생성 과정에서 불필요한 UI 속성을 제거하여 파일 크기를 압축하고 실행 효율성을 극대화하는 전략이다 [1, 2]. +- **Link Embedding:** API 포맷에서는 링크가 별도의 객체가 아니라 노드 입력 내부에 `[origin_node_id, output_slot_index]` 형태의 참조값으로 직접 포함된다 [1, 6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Bifurcation Pattern:** 동일한 워크플로우를 사용 목적에 따라 시각적 레이아웃(Frontend)과 논리적 실행 순서(API)로 분리하여 저장 및 관리한다 [1]. +- **Execution Model Inversion:** 엔진 실행 시 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색함으로써, JSON 내에 미사용 노드가 있더라도 실행 성능에 영향을 주지 않도록 설계되었다 [7]. +- **Metadata Injection:** 생성된 이미지(PNG/WebP)의 텍스트 청크(tEXt/zTXt)에 두 포맷을 모두 주입하여, 이미지 자체가 실행 논리의 컨테이너 역할을 수행하도록 한다 [8, 9]. + +## 📖 세부 내용 (Details) +ComfyUI의 직렬화 구조는 크게 두 가지 운영 맥락으로 나뉜다. + +**1. Frontend JSON (workflow.json)의 구조와 역할** +이 형식은 사용자가 웹 인터페이스에서 워크플로우를 편집하고 공유할 때 사용된다 [2]. 주요 특징은 다음과 같다: +- **시각적 메타데이터:** `pos`(좌표), `size`(크기), `flags`(노드 상태), `groups`(그룹 구조)와 같은 캔버스 레이아웃 정보를 완벽하게 보존한다 [1, 10]. +- **링크 표현:** 노드 간의 연결이 별도의 `links` 배열 내에서 명시적인 연결 객체로 관리된다 [2, 11]. +- **호환성:** 웹 인터페이스에서 드래그 앤 드롭을 통해 워크플로우를 원상복구하는 데 필수적이다 [3, 12]. + +**2. API JSON (workflow_api.json)의 구조와 역할** +서버리스 배포나 외부 애플리케이션 연동 시 사용되는 실행 전용 포맷이다 [2, 13]. +- **효율성 최적화:** 모든 UI 관련 정보를 제거하여 파일 용량을 줄이고 처리 속도를 높인다 [2]. +- **노드 식별:** 노드는 고유한 기능적 키(주로 숫자 문자열)로 식별되며, `class_type`과 `inputs` 필드가 핵심을 이룬다 [2, 14]. +- **연결 방식:** 별도의 링크 객체 없이, 노드의 입력 필드 내에 소스 노드와 슬롯 번호를 직접 기입하는 방식을 취한다 [1, 2]. + +**3. 포맷 간 전환 및 생성** +기본적으로 ComfyUI 설정의 'Dev mode Options'를 활성화해야 'Save (API format)' 버튼이 노출된다 [15, 16]. 일부 도구는 Frontend 포맷을 서버 사이드에서 API 포맷으로 변환하는 기능을 제공하여 개발자가 UI 버전만 관리할 수 있도록 돕기도 한다 [17, 18]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가독성 vs 실행력:** API JSON은 실행에는 최적화되어 있으나, 다시 UI로 불러올 경우 시각적 레이아웃이 파괴된 'Skeleton' 상태로 나타나 편집이 매우 어렵다는 한계가 있다 [18]. +- **데이터 유실 위험:** PNG 이미지에 포함된 메타데이터는 SNS 업로드나 압축 과정에서 쉽게 제거될 수 있으며, 이 경우 워크플로우 복구가 불가능해진다 [9, 19]. +- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라, 이전 버전에서 생성된 JSON 파일이 최신 엔진에서 정상적으로 동작하지 않을 수 있는 모순이 존재한다 [19]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드의 변환 로직을 Python으로 구현하여 `/workflow/convert` 엔드포인트를 통해 비 API 포맷을 API 포맷으로 변환한다 (Git Commit: `bc85382`) [17, 20, 21]. +- **ComfyUI-to-Python-Extension:** API JSON 포맷을 읽어 실행 가능한 순수 Python 스크립트(`.py`)로 변환하며, `workflow_api.py`라는 기본 파일명을 사용한다 [22, 23]. +- **Mystic Pipeline:** `workflow.json`을 포함한 디렉토리 구조에서 `new_pipeline.py`를 통해 입력 프롬프트를 JSON에 주입하고 실행하는 파이프라인 아키텍처를 구성한다 [24, 25]. +- **Replicate fofr/any-comfyui-workflow:** API JSON 블록을 직접 입력받아 GPU 환경에서 실행하고 결과물을 반환하는 프로덕션 모델로 활용된다 [26, 27]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (다양한 커스텀 노드 및 확장 도구에서 적용 사례 확인됨) +- **출처 신뢰도:** B (Official Documentation / GitHub Source Code README / Expert Tutorials) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[ComfyUI Workflow JSON 생성 방법]] + - 연결 이유: 본 주제의 루트 주제로서 전체적인 생성 맥락을 제공함. +- [[Litegraph Standard]] + - 연결 이유: Frontend 포맷의 시각적 레이아웃 규격을 결정하는 핵심 기술임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 좌표 및 링크 객체 처리 방식의 원리. + +#### [구현/활용 도구] +- [[Dev Mode Options]] + - 연결 이유: API 포맷을 추출하기 위해 반드시 선행되어야 하는 UI 설정임. +- [[ComfyUI-Manager]] + - 연결 이유: JSON 로드 시 발생하는 종속성(Custom Node) 문제를 해결하는 필수 도구임 [28]. +- [[Load Image (Base64)]] + - 연결 이유: API 요청 시 외부 이미지 파일을 JSON 내부에 직렬화하여 포함하는 주요 방식임 [29]. + +### 심층 후속 질문 (Deeper Research Questions) +- Frontend JSON의 `links` 배열 구조와 API JSON의 `inputs` 내 임베디드 참조 방식 간의 변환 알고리즘은 구체적으로 어떻게 작동하는가? +- 이미지 메타데이터(tEXt/zTXt)에 두 가지 포맷을 동시에 저장할 때 발생하는 오버헤드와 실제 처리 우선순위는 무엇인가? +- `object_info.json`은 API JSON을 동적으로 생성하거나 검증하는 과정에서 어떤 데이터 스키마를 제공하는가? [13] +- 왜 ComfyUI는 API 포맷 노출을 기본적으로 숨기고 'Dev Mode'를 통해서만 접근하도록 설계했는가? [17] +- `ComfyUI-to-Python-Extension`이 변환한 파이썬 코드와 원본 API JSON 간의 실행 효율 차이는 존재하는가? +- 복잡한 서브그래프(Subgraph)가 포함된 워크플로우를 API 포맷으로 직렬화할 때의 제약 사항은 무엇인가? [30] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 외부 Python 앱에서 ComfyUI 서버로 프롬프트를 보낼 때는 반드시 API 포맷을 사용해야 하며, 프롬프트 내 특정 노드 ID의 값을 동적으로 변경하여 전송한다 [31, 32]. +- **System Design:** 프로덕션 환경에서는 사용자가 시각적으로 편집한 `workflow.json`을 저장하고, 시스템 내부적으로 이를 API 포맷으로 변환하여 큐에 삽입하는 아키텍처가 권장된다 [18]. +- **Operation / Maintenance:** 모델 파일명 변경이나 커스텀 노드 누락에 대비하여 JSON 내의 `class_type`과 실제 서버의 `object_info`를 대조하는 검증 로직이 필요하다 [33]. +- **Learning Path:** 초보자는 Frontend JSON을 통한 시각적 학습에 집중하고, 자동화 단계로 넘어갈 때 API 포맷의 노드 ID 및 입력 구조를 파악해야 한다 [34]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: JSON 파일 내의 하드코딩된 파일명 문제를 해결하기 위한 모델 식별 기술 [35]. +- [[Retrieval-Augmented Generation (RAG) for Nodes]] + - 확장 방향: LLM을 이용해 동적으로 최적의 노드 그래프를 생성하는 미래 기술 [36]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) \ No newline at end of file diff --git a/10_Wiki/Comfyui/Serverless Deployment.md b/10_Wiki/Comfyui/Serverless Deployment.md new file mode 100644 index 00000000..3ea7d637 --- /dev/null +++ b/10_Wiki/Comfyui/Serverless Deployment.md @@ -0,0 +1,67 @@ +--- +id: serverless-deployment +title: "Serverless Deployment" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["서버리스 배포", "API 배포"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["new_pipeline.py", "pipeline.yaml", "fofr/any-comfyui-workflow"] +github_commit: "bc85382" +--- + +# [[Serverless Deployment]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우의 서버리스 배포는 시각적 메타데이터를 제거하고 실행 로직만 남긴 **API 포맷 JSON(Backend Format)**을 통해 워크플로우를 독립적인 실행 가능한 프로그램으로 변환하는 과정이다 [1-4]. + +## 🧠 핵심 개념 (Core concepts) +1. **API 포맷 JSON (workflow_api.json):** 서버 사이드 실행에 최적화된 스트림라인드 그래프로, 노드 위치나 크기 같은 UI 메타데이터를 제외하고 오직 노드 타입, 입력값, 연결 정보만을 포함한다 [1, 4]. +2. **서버리스 엔드포인트 (Serverless Endpoint):** GPU 관리, 오토스케일링, 플랫폼 최적화가 포함된 확장 가능한 API 지점으로, 사용자는 인프라 관리 없이 워크플로우를 실행할 수 있다 [3]. +3. **입력 오버라이드 (Input Overrides):** 배포된 워크플로우를 호출할 때 프롬프트, 시드, 이미지 경로 등 특정 파라미터만을 동적으로 변경하여 전송하는 방식이다 [5, 6]. +4. **종속성 패키징 (Dependency Packaging):** 서버리스 환경에서 워크플로우가 작동하도록 필요한 커스텀 노드, 모델 가중치, Python 라이브러리를 도커 이미지나 YAML 설정으로 정의하는 과정이다 [7, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Bifurcation(이분화) 패턴:** 사용자 편집용 'Frontend JSON'과 실행 전용 'API JSON'을 분리하여 관리하며, API 요청 시에는 반드시 후자를 사용해야 한다 [1, 9, 10]. +- **Pipeline-as-Code:** 워크플로우 실행 로직을 Python 스크립트(`new_pipeline.py`)로, 환경 설정을 YAML(`pipeline.yaml`)로 작성하여 인프라를 코드로 관리한다 [7]. +- **Remote Asset Referencing:** 로컬 파일을 직접 사용하는 대신 URL 참조나 ZIP/TAR 압축 파일 업로드를 통해 서버리스 환경에 데이터를 공급한다 [11, 12]. + +## 📖 세부 내용 (Details) +* **API 포맷 획득 프로토콜:** 서버리스 배포를 위한 JSON을 얻으려면 ComfyUI 설정(Settings) 메뉴에서 **'Enable Dev mode Options'**를 활성화해야 한다 [2, 11, 13, 14]. 이후 제어판에 나타나는 **'Save (API format)'** 또는 **'Export (API)'** 버튼을 통해 추출할 수 있다 [2, 15]. +* **플랫폼별 배포 방식:** + * **Mystic:** `pipeline.yaml`에 CUDA 및 Python 의존성을 정의하고, `new_pipeline.py`에서 ComfyUI 서버 시작 및 워크플로우 로드 로직을 구현한다 [7, 8]. 도커 이미지를 빌드하여 Mystic 계정에 푸시하면 엔드포인트가 생성된다 [8, 16]. + * **Replicate:** `fofr/any-comfyui-workflow`와 같은 범용 모델을 활용하거나 전용 API 토큰을 사용하여 Python/JavaScript 클라이언트로 워크플로우 JSON을 전송한다 [17-19]. + * **RunComfy:** 워크플로우를 'Serverless API (ComfyUI)'로 배포하며, 플랫폼이 내부적으로 `workflow_api.json`을 저장하고 API 호출 시 오버라이드 값만 적용하여 효율적으로 실행한다 [4, 6, 20]. +* **데이터 처리 및 통신:** + * **입력:** 이미지 입력 시 `Load Image (Base64)` 노드를 사용하여 JSON 내에 데이터를 직접 포함하거나, URL을 통해 클라우드 저장소의 자원을 참조한다 [11, 21]. + * **출력:** 결과물 확인을 위해 `SaveImageWebsocket` 노드를 사용하여 웹소켓 통신으로 이미지 바이너리를 수신하거나, 서버리스 플랫폼의 출력 디렉토리에 저장된 파일을 반환받는다 [21, 22]. +* **자동화 및 변환 도구:** `comfyui-workflow-to-api-converter-endpoint`를 설치하면 `/workflow/convert` 엔드포인트를 통해 일반 `workflow.json`을 API 포맷으로 서버사이드에서 즉시 변환하여 실행할 수 있다 [10, 23, 24]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +* **호환성 문제:** 표준 `workflow.json`을 API 엔드포인트(`prompt`)에 직접 전송하면 백엔드 엔진이 시각적 메타데이터를 해석하지 못해 오류가 발생한다 [10, 13]. +* **가독성 손실:** API JSON은 노드 위치 정보가 제거되었으므로, 이를 다시 ComfyUI UI로 드래그하면 노드들이 겹쳐진 '뼈대만 남은' 상태가 되어 편집이 극도로 어렵다 [25]. 따라서 원본 'Full Workflow' JSON을 반드시 별도로 보관해야 한다 [25]. +* **종속성 취약점:** 배포된 환경에 필요한 커스텀 노드가 누락되면 'Red Boxes' 에러가 발생하며, 이를 해결하기 위해 `ComfyUI-Manager`를 통한 의존성 해결이나 도커 기반의 환경 구성이 필수적이다 [8, 26, 27]. + +## 🛠️ 적용 사례 (Applied in summary) +* **`new_pipeline.py`**: Mystic 플랫폼에서 서버리스 엔드포인트를 정의하는 핵심 파이썬 파일로, 입력 프롬프트를 JSON 워크플로우에 주입하고 실행하는 템플릿 역할을 한다 [7, 22]. +* **`pipeline.yaml`**: Mystic 배포 시 CUDA 버전, Python 라이브러리 종속성, 오토스케일링 설정을 포함하는 구성 파일이다 [7, 8]. +* **`fofr/any-comfyui-workflow`**: Replicate에서 어떤 API 포맷 JSON이든 수용하여 실행할 수 있도록 설계된 범용 서버리스 모델이다 [17, 19]. +* **GitHub Commit `bc85382`**: `comfyui-workflow-to-api-converter-endpoint`에서 콤보 위젯의 대소문자 표기 오류(예: True vs true)를 수정하여 유효성 검사 실패 문제를 해결한 기록이 확인된다 [28, 29]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Steganography in Generative AI.md b/10_Wiki/Comfyui/Steganography in Generative AI.md new file mode 100644 index 00000000..b8fa0a74 --- /dev/null +++ b/10_Wiki/Comfyui/Steganography in Generative AI.md @@ -0,0 +1,62 @@ +--- +id: steganography-in-generative-ai +title: "Steganography in Generative AI" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["메타데이터 은닉", "Metadata Embedding"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI-to-Python-Extension", "Comfy_UI_prompt_extractor", "comfyui_extractor.py", "exiftool"] +github_commit: "" +--- + +# [[Steganography in Generative AI]] + +## 🎯 한 줄 통찰 (One-line insight) +생성형 AI의 결과물(이미지) 내부에 실행 가능한 워크플로우 로직(JSON)을 메타데이터 형태로 은닉함으로써, 시각적 자산과 그 제작 절차를 결합하여 완벽한 재현성을 확보하는 기술 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **메타데이터 주입 (Metadata Injection):** ComfyUI의 'Save Image' 노드가 실행될 때, 최종 이미지 파일의 숨겨진 메타데이터 영역에 전체 노드 그래프, 설정 및 프롬프트를 자동으로 포함시키는 프로세스 [2, 4]. +- **PNG 청크 구조 (tEXt/zTXt Chunks):** PNG 파일 규격 내에서 텍스트 정보를 저장하기 위해 정의된 특정 영역으로, ComfyUI는 이곳에 'workflow'(프런트엔드 포맷)와 'prompt'(API 포맷)라는 두 가지 정보를 저장함 [5]. +- **데이터 프레절리티 (Metadata Fragility):** 소셜 미디어 플랫폼이나 일반 이미지 편집기(예: GIMP)를 거칠 경우, 파일 최적화나 개인정보 보호를 위해 비필수 메타데이터인 워크플로우 JSON이 제거되어 재현성이 소실되는 특성 [4-6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **드래그 앤 드롭 복구 패턴:** 이미지 파일을 ComfyUI 캔버스에 직접 끌어다 놓으면 내장된 JSON 데이터를 읽어 즉각적으로 노드 레이아웃을 복구하는 직관적 인터페이스 패턴 [2, 7]. +- **이중 직렬화 저장 전략:** PNG 메타데이터 내에 시각적 편집을 위한 '프런트엔드 포맷'과 실제 실행을 위한 'API/백엔드 포맷'을 동시에 저장하여 호환성을 높임 [5, 8]. +- **사후 추출 및 주입 패턴:** 메타데이터가 손실되었거나 대량의 이미지에서 로직을 추출해야 할 경우, `exiftool`이나 전용 CLI 도구를 사용하여 이진 태그에서 JSON을 분리해내는 패턴 [9, 10]. + +## 📖 세부 내용 (Details) +ComfyUI 생태계에서 스테가노그래피는 주로 생성된 이미지(PNG, WebP 등) 내부에 워크플로우의 "소스 코드"에 해당하는 JSON 데이터를 숨기는 방식으로 구현된다 [1, 2]. + +- **저장 메커니즘:** 대부분의 워크플로우는 `Save Image` 노드에서 종료되며, 이 노드가 구동될 때 생성된 이미지의 비가시적 메타데이터 영역에 전체 노드 레이아웃, 노드 간의 링크, 입력값, 모델 설정 등을 주입한다 [2, 4]. 이는 별도의 파일 없이 이미지 자체를 워크플로우의 백업 또는 공유 매체로 사용할 수 있게 한다 [4]. +- **데이터 구조의 세분화:** PNG 파일 내의 `tEXt` 또는 `zTXt` 청크를 활용하며, 여기에 두 가지 형태의 문자열이 저장된다. 하나는 UI 레이아웃 정보를 포함한 **Frontend Format(workflow.json)**이며, 다른 하나는 백엔드 엔진이 즉시 실행할 수 있도록 정제된 **API Format(prompt/workflow_api.json)**이다 [5]. +- **추출 기술:** 이미지에서 은닉된 로직을 복구하기 위해 `exiftool -b -workflow input.png > workflow.json`과 같은 명령어를 사용하여 이진 메타데이터 영역에서 JSON 스트링을 분리해낼 수 있다 [9]. 또한 `ComfyUI-to-Python-Extension`과 같은 도구는 생성된 스크립트가 저장하는 이미지에 프런트엔드 메타데이터를 포함시켜 다시 UI로 불러올 수 있도록 지원한다 [11]. +- **한계점:** 이러한 스테가노그래피 방식은 매우 편리하지만, 이미지 압축 소프트웨어나 온라인 플랫폼의 메타데이터 제거 정책에 취약하여 데이터가 유실될 위험이 상존한다 [5, 7]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정보의 불완전성:** 이미지 임베딩 방식(첫 번째 방법)은 간편하지만, 때때로 새롭게 추가된 노드나 커스텀 노드의 일부 정보를 누락하는 경우가 보고되어, 복잡한 워크플로우의 경우 별도의 JSON 파일 저장(두 번째 방법)이 권장된다 [4]. +- **버전 호환성:** ComfyUI의 빈번한 업데이트로 인해, 이미지 내부에 저장된 구버전의 JSON 메타데이터가 최신 버전의 ComfyUI에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [7]. + +## 🛠️ 적용 사례 (Applied in summary) +- **exiftool 기반 워크플로우 추출:** `exiftool -b -workflow input.png` 명령을 통해 이미지 내의 비표준 태그에 저장된 JSON을 파일로 출력함 [9, 10]. +- **ComfyUI-to-Python-Extension:** 생성된 .py 스크립트 실행 시 저장되는 이미지에 프런트엔드 워크플로우 메타데이터를 포함하도록 구현되어 있어, 결과 이미지를 다시 UI로 드래그 앤 드롭하여 재편집 가능 [11]. +- **Weird Wonderful AI Art (추출기):** 웹 브라우저 기반으로 PNG 파일에서 JSON 워크플로우 데이터를 분석하고 추출해주는 전용 서비스 도구 [12, 13]. +- **Comfy_UI_prompt_extractor:** 이미지에서 긍정 프롬프트, API 그래프, UI 레이아웃을 분리하여 별도의 JSON 파일로 일괄 생성하는 CLI 도구 [9, 10]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Subgraph.md b/10_Wiki/Comfyui/Subgraph.md new file mode 100644 index 00000000..a222cac9 --- /dev/null +++ b/10_Wiki/Comfyui/Subgraph.md @@ -0,0 +1,62 @@ +--- +id: subgraph +title: "Subgraph" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint"] +github_commit: "bc85382" +--- + +# [[Subgraph]] + +## 🎯 한 줄 통찰 (One-line insight) +Subgraph는 복잡한 ComfyUI 노드 그래프를 논리적으로 캡슐화하고 모듈화하여 관리 및 실행 효율성을 극대화하는 공식 기능이다. [1-3] + +## 🧠 핵심 개념 (Core concepts) +1. **그래프 캡슐화 (Encapsulation):** 복잡한 노드 연결 구조를 하나의 상위 노드 단위로 묶어 워크플로우 가독성을 높이고 관리 지점을 단순화한다. [2, 3] +2. **중첩 구조 지원 (Nested Support):** 서브그래프 내부에 또 다른 서브그래프를 포함하는 계층적 구조 설계가 가능하다. [3] +3. **입력 슬롯 매핑 (Slot Mapping):** 상위 노드의 입력 위치와 내부 서브그래프 정의 간의 데이터 흐름을 정확히 일치시키는 동기화 메커니즘을 포함한다. [4] +4. **실행 모델 통합:** 노드 실행 시 서브그래프 존재 여부를 감지하고, 이를 전체 실행 리스트(Execution List)의 일부로 처리한다. [5] + +## 🧩 추출된 패턴 (Extracted patterns) +- **링크 ID 충돌 방지 패턴:** 서브그래프 내부의 링크 ID가 전체 워크플로우의 링크 ID와 충돌하지 않도록 독립적인 ID 할당 체계를 유지해야 한다. [4] +- **API 변환 최적화:** 워크플로우를 API 전용 JSON으로 변환할 때, 서브그래프의 계층 구조를 보존하면서도 실행 가능한 형태의 노드 입력 참조 방식으로 스트림라이닝한다. [3, 4] + +## 📖 세부 내용 (Details) +- **공식 릴리스 및 인터페이스:** Subgraph는 ComfyUI의 공식 기능으로 릴리스되었으며, 사용자 인터페이스 가이드의 "Interface Guide" 섹션에서 주요 기능으로 다루어진다. [1, 2] +- **실행 엔진과의 상호작용:** 백엔드 실행 엔진은 `get_output_data` 함수를 통해 노드의 실행 결과 및 UI 관련 출력과 함께 서브그래프의 존재 여부에 대한 추가 정보를 반환한다. [5] +- **커스텀 노드 개발 활용:** 노드 개발자는 "Subgraph blueprints" 규격을 활용하여 특정 기능을 수행하는 서브그래프 기반의 커스텀 노드를 정의할 수 있다. [6] +- **JSON 변환 시의 기술적 처리:** + - 서브그래프 내부의 링크 ID가 외부 워크플로우와 충돌할 경우 입력 연결이 소실되는 문제가 발생할 수 있어, 이를 격리하여 처리하는 로직이 필수적이다. [4] + - 외부 노드의 슬롯 위치와 실제 서브그래프 정의 내의 입력 슬롯 위치가 다를 경우 이를 매핑하는 과정이 포함된다. [4] + - 중첩된 서브그래프를 처리하기 위해서는 재귀적인 변환 깊이 제한(예: 100회)을 두어 무한 루프를 방지하고 안정성을 확보한다. [3] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **API 호환성 이슈:** 초기에는 서브그래프가 포함된 워크플로우를 API 포맷으로 변환할 때 내부 링크 ID 충돌이나 슬롯 매핑 오류가 발생했으나, 이후 `comfyui-workflow-to-api-converter-endpoint`와 같은 툴을 통해 이러한 기술적 결함들이 해결되었다. [4, 7] +- **버전별 기능 차이:** V2.09 버전에서 서브그래프 입력 슬롯 매핑 방식이 개선되는 등 지속적인 스펙 업데이트가 이루어지고 있다. [4] + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint (V2.09):** 서브그래프 정의와 외부 노드 간의 입력 슬롯 매핑 위치가 불일치하는 문제를 해결했다. [4] +- **comfyui-workflow-to-api-converter-endpoint (V2.07):** 서브그래프 내부 링크 ID와 전체 워크플로우 링크 ID 간의 충돌로 인한 입력 연결 소실 문제를 수정했다. [4] +- **comfyui-workflow-to-api-converter-endpoint (V2.02):** 서브그래프 처리와 관련된 일반적인 버그를 수정했다. [7] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Visual Programming Environment.md b/10_Wiki/Comfyui/Visual Programming Environment.md new file mode 100644 index 00000000..a0b0ae12 --- /dev/null +++ b/10_Wiki/Comfyui/Visual Programming Environment.md @@ -0,0 +1,114 @@ +--- +id: visual-programming-environment +title: "Visual Programming Environment" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["시각적 프로그래밍 환경", "Node-based Interface"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Visual Programming"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: + - "ComfyUI/custom_nodes/ComfyUI-Manager" + - "ComfyUI-WorkflowGenerator (Commit: 82df278)" + - "comfyui-workflow-to-api-converter-endpoint (Commit: bc85382)" + - "comfyui_to_python.py" + - "/workflow/convert" + - "workflow_api.json" +github_commit: "82df278, bc85382" +--- + +# [[Visual Programming Environment]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI는 생성형 AI의 복잡한 파이프라인을 노드 기반의 유향 비순환 그래프(DAG)로 추상화하여, 코드 없이 로직을 설계하고 이를 JSON 형태로 직렬화하여 실행 및 공유할 수 있게 하는 고수준 시각적 프로그래밍 환경이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +1. **노드 기반 유향 비순환 그래프 (DAG):** 모델 로더, 샘플러, 인코더 등을 나타내는 노드들이 링크로 연결되어 데이터의 흐름을 정의하는 구조적 토대이다 [1, 4]. +2. **절차적 프레임워크 (Procedural Framework):** 정적인 메뉴 방식과 달리 알고리즘이나 절차를 통해 콘텐츠를 생성하며, 워크플로우 자체가 프로그램의 '소스 코드' 역할을 수행한다 [3, 5]. +3. **포맷의 이원화 (Bifurcation of Formats):** 시각적 편집을 위한 **Frontend JSON**과 서버 실행 및 API 호출에 최적화된 **API JSON**으로 구분되어 운영된다 [6-8]. +4. **실행 모델 역전 (Execution Model Inversion):** 그래프의 모든 노드를 실행하는 대신, 최종 출력 노드에서 거꾸로 추적하여 필요한 의존성 노드만 실행함으로써 성능을 최적화한다 [9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **메타데이터 임베딩 패턴:** 생성된 PNG 이미지의 tEXt 또는 zTXt 청크 내에 워크플로우 JSON을 삽입하여 이미지 자체가 실행 가능한 소스 코드가 되도록 설계한다 [10, 11]. +- **API 최적화 패턴:** 백엔드 실행 시 불필요한 좌표(pos), 크기(size), 그룹 등 UI 메타데이터를 제거하고 노드 간의 직접적인 참조로 그래프를 단순화한다 [6, 8, 12]. +- **의존성 해결 패턴:** 워크플로우 JSON 내 `class_type`을 로컬 레지스트리와 대조하여 누락된 커스텀 노드를 식별하고 자동으로 설치를 유도하는 구조를 가진다 [13, 14]. + +## 📖 세부 내용 (Details) +ComfyUI는 시각적 프로그래밍 환경으로서 사용자가 복잡한 수학적 이해나 프로그래밍 코드 작성 없이도 정교한 생성 AI 시스템을 설계할 수 있도록 돕는다 [2]. 이 환경의 핵심은 모든 작업 단위가 **노드(Node)**로 정의된다는 점이며, 이 노드들은 특정 슬롯(Slot)을 통해 데이터를 주고받는다 [4, 15]. + +**JSON 직렬화 아키텍처** +- **스키마 규격:** ComfyUI JSON Schema v1.0(Draft-07 사양)을 따르며, 각 노드는 `id`, `type`, `pos`, `size`, `widgets_values`, `inputs`, `outputs` 등의 속성을 필수적으로 포함한다 [16]. +- **워크플로우 생성 경로:** + - **수동 생성:** 웹 인터페이스에서 `Ctrl + S`를 통해 직렬화된 JSON 파일을 다운로드한다 [17]. + - **자동 추출:** 전용 도구(exiftool 등)를 사용하여 이미지 메타데이터에서 JSON을 복원한다 [18, 19]. + - **프로그래밍적 생성:** Python의 `json` 라이브러리를 사용해 딕셔너리 구조를 조작하거나 LLM을 통해 자연어 설명을 실행 가능한 그래프 구조로 변환한다 [20, 21]. + +**실행 환경의 분리** +프론트엔드 형식(Litegraph 표준 기반)은 캔버스 레이아웃 정보를 포함하여 인간의 협업과 시각적 편집에 적합하며, API 형식은 `/prompt` 엔드포인트에 즉시 전달 가능한 압축된 실행 그래프 형태를 띤다 [6, 12, 22, 23]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **메타데이터의 취약성:** 이미지 메타데이터에 워크플로우를 저장하는 방식은 편리하지만, 소셜 미디어나 표준 이미지 편집기에 의해 데이터가 제거(Stripped)될 위험이 크다 [11, 24]. +- **버전 호환성:** ComfyUI의 잦은 업데이트로 인해 이전 버전의 JSON 파일이 최신 환경에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [25]. +- **API 호환성 오류:** 표준 'Save'로 생성된 JSON을 API로 호출하면 오류가 발생하며, 반드시 'Dev mode'를 활성화하여 'Save (API Format)'으로 추출해야 한다 [26]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI/custom_nodes/ComfyUI-Manager:** 워크플로우 JSON을 분석하여 누락된 노드를 설치하고 관리하는 실제 구현체이다 [27, 28]. +- **ComfyUI-WorkflowGenerator (Commit: 82df278):** Qwen2.5 모델을 사용하여 자연어를 ComfyUI JSON으로 변환하는 파이프라인이 구현되어 있다 [29, 30]. +- **comfyui-workflow-to-api-converter-endpoint (Commit: bc85382):** 클라이언트 측의 JS 로직을 Python으로 변환하여 서버사이드에서 일반 JSON을 API 포맷으로 변환하는 `/workflow/convert` 엔드포인트를 제공한다 [26, 31]. +- **comfyui_to_python.py:** 시각적 워크플로우를 실행 가능한 독립적인 Python 스크립트로 변환하는 도구이다 [32]. +- **workflow_api.json:** RunComfy 등의 플랫폼에서 서버리스 API 호출의 기본 단위로 사용되는 직렬화 파일이다 [7]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견됨) +- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 분석 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI 워크플로우의 논리적 구조를 정의함 [1]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 데이터 흐름 및 의존성 관계. +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON 포맷의 시각적 메타데이터 규격을 결정함 [6, 23]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 위치, 크기 및 그룹 관리 방식. + +#### [구현/활용 도구] +- [[ComfyUI Workflow JSON]] + - 연결 이유: 시각적 환경의 설계를 저장하고 전달하는 중간 매개체임 [1, 33]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 수동/자동 생성 방법 및 스키마 구조. +- [[Execution Model Inversion]] + - 연결 이유: 그래프를 효율적으로 실행하기 위한 백엔드 최적화 기술임 [9]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 불필요한 노드 실행 방지 메커니즘. + +### 심층 후속 질문 (Deeper Research Questions) +- JSON v1.0 스키마에서 `widgets_values` 배열의 순서가 노드 실행 안정성에 미치는 영향은 무엇인가? [16] +- 이미지의 tEXt 청크 외에 SVG 포맷을 활용한 워크플로우 시각화 및 보존 전략은 어떻게 구현되는가? [34, 35] +- `object_info.json`을 활용하여 클라이언트 사이드에서 동적으로 노드 유효성을 검사하는 메커니즘은 무엇인가? [36] +- LLM 기반 생성 시 'Semantic Validation' 단계에서 발생하는 임베딩 유사도 검색의 정확도 한계는? [37, 38] +- 모델 해싱(SHA-256)을 통한 워크플로우 이식성(Portability) 해결 방식의 상세 아키텍처는? [39] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `/workflow/convert` 엔드포인트를 구축하여 프론트엔드 워크플로우를 실시간 API 포맷으로 변환 [26]. +- **System Design:** 워크플로우를 독립적인 Python 스크립트로 변환하여 헤드리스(Headless) 처리 파이프라인에 통합 [40, 41]. +- **Operation / Maintenance:** ComfyUI Manager를 통해 누락된 커스텀 노드(Red boxes)를 식별하고 복구 [13, 14]. +- **Learning Path:** 기본 예제 워크플로우를 로드하고 노드 연결 방식을 분석하여 시각적 프로그래밍 원리를 습득 [4, 42]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Generative AI Pipeline]] + - 확장 방향: 시각적 프로그래밍이 실제 AI 모델 실행 흐름으로 전환되는 전체 주기. +- [[Metadata Forensics]] + - 확장 방향: AI 생성 이미지에서 워크플로우를 추출하고 분석하는 디지털 포렌식 기술 [18]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. Drawing on sources [1-186]. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Workflow API JSON (Backend Format).md b/10_Wiki/Comfyui/Workflow API JSON (Backend Format).md new file mode 100644 index 00000000..025c2af9 --- /dev/null +++ b/10_Wiki/Comfyui/Workflow API JSON (Backend Format).md @@ -0,0 +1,98 @@ +--- +id: workflow-api-json-(backend-format) +title: "Workflow API JSON (Backend Format)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["API JSON", "Backend Format JSON"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI-WorkflowGenerator", "ComfyUI-to-Python-Extension", "comfyui-workflow-to-api-converter-endpoint", "comfy_api_simplified"] +github_commit: "" +--- + +# [[Workflow API JSON (Backend Format)]] + +## 🎯 한 줄 통찰 (One-line insight) +시각적 레이아웃 정보를 제거하고 노드 간의 실행 로직과 데이터 흐름만을 정제하여, ComfyUI 백엔드 엔진의 `/prompt` 엔드포인트에서 즉각 실행 가능한 최적화된 그래프 데이터 형식이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **UI 메타데이터의 박리 (Stripping UI Metadata):** 노드 위치, 크기, 그룹화 정보, 색상 등 캔버스 시각화를 위한 모든 데이터를 제외하여 파일 크기를 축소하고 처리 효율성을 높인다 [1-4]. +- **임베디드 링크 구조 (Embedded Link Representation):** 별도의 연결 객체 배열을 사용하는 대신, 노드 입력 필드 내에 소스 노드 ID와 출력 슬롯 번호를 직접 참조(예: `[5, 6]`)하여 관계를 정의한다 [1, 2, 7, 8]. +- **기능적 키 매핑 (Functional Key Mapping):** 각 노드는 고유한 문자열 키(ID)로 식별되며, `class_type`과 `inputs`를 핵심 속성으로 보유하여 백엔드 노드 레지스트리와 직접 매핑된다 [2, 9-11]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **개발자 모드 전환 패턴:** 수동 생성 시 설정 메뉴에서 'Enable Dev mode Options'를 활성화하여 'Save (API Format)' 버튼을 노출시키는 것이 필수 절차이다 [3, 12-15]. +- **동적 파라미터 주입 패턴:** 생성된 JSON 템플릿을 로드한 후, 특정 노드 ID의 `inputs` 딕셔너리에 접근하여 시드(Seed), 프롬프트, 이미지 경로 등을 프로그래밍 방식으로 수정하여 재전송한다 [9, 11, 16-18]. +- **데이터 인라인화 (Self-containment):** 외부 파일 참조 대신 "Load Image (Base64)" 노드 등을 통해 이미지 데이터를 Base64 문자열로 JSON 내부에 직접 포함시켜 자가 포함된 요청을 구성한다 [19, 20]. + +## 📖 세부 내용 (Details) +Workflow API JSON은 ComfyUI의 두 가지 주요 직렬화 형식 중 하나로, 주로 **프로그램 방식의 실행 및 API 호출**을 위해 설계되었다 [1, 2]. 이 형식은 Litegraph 표준을 따르는 프런트엔드 형식(`workflow.json`)과 달리 백엔드 엔진이 프롬프트를 처리하기 위해 예상하는 평면화된 실행 그래프(Flattened execution graph)를 제공한다 [1, 12]. + +기술적으로 API JSON은 루트 키가 노드 ID이고 값이 노드 정의인 단일 JSON 객체 구조를 갖는다 [10]. 각 노드 정의에는 `class_type`, `inputs`, 그리고 선택적인 `_meta` 데이터가 포함된다 [10]. 연결(Link)은 입력 리스트 내에서 `[소스_노드_ID, 소스_슬롯_인덱스]` 형태의 배열로 표현되며, 이는 특정 슬롯(예: VAE Loader의 VAE 출력 슬롯)을 명확하게 지정하는 데 중요하다 [7, 8]. + +실행 시 ComfyUI 백엔드는 이 JSON을 수신하여 '실행 모델 역전(Execution Model Inversion)' 방식을 적용한다 [21]. 즉, 'Save Image'와 같은 출력 노드에서 시작하여 그래프를 역방향으로 추적하며 필요한 의존성만 식별하여 실행한다 [21]. 이 과정 덕분에 JSON 내에 실행과 무관한 노드가 포함되어 있어도 성능에 영향을 주지 않는다 [21]. 또한, API JSON은 모델 가중치와 독립적이므로 크기가 매우 작아 버전 관리와 아카이빙에 유리하다 [22, 23]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가독성 및 편집성:** API JSON은 실행에는 최적화되어 있으나, ComfyUI UI로 다시 드래그 앤 드롭할 경우 노드 위치 정보 등이 없어 로직만 남은 '뼈대' 상태로 로드되어 시각적 편집이 어렵다는 단점이 지적된다 [24, 25]. +- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 이전 버전의 API JSON 형식이 최신 버전의 백엔드 엔진에서 정상적으로 작동하지 않을 수 있는 호환성 문제가 존재한다 [26]. +- **메타데이터 취약성:** PNG 이미지에 임베드된 API JSON 데이터는 이미지 편집기나 소셜 미디어 플랫폼을 거치면서 손실되기 쉽다 [27]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 프런트엔드 포맷을 백엔드 API 포맷으로 서버 측에서 변환하는 `/workflow/convert` 엔드포인트를 제공한다 [28, 29]. +- **ComfyUI-to-Python-Extension:** API 포맷의 JSON을 독립 실행 가능한 Python 스크립트로 변환하는 기능을 지원한다 [30, 31]. +- **comfy_api_simplified:** 노드 타이틀을 기준으로 API JSON의 파라미터를 수정하고 큐에 추가할 수 있는 Python 래퍼 라이브러리이다 [16, 18]. +- **Replicate 및 RunComfy 플랫폼:** 사용자가 업로드한 API JSON을 기반으로 서버리스 환경에서 워크플로를 실행하고 결과를 반환하는 시스템 아키텍처를 보유하고 있다 [4, 32, 33]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처 및 데이터 표준] +- [[Workflow JSON (Frontend Format)]] + - 연결 이유: API JSON의 원형이 되는 시각적 작업 데이터 포맷이다 [1, 34]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 데이터 유무에 따른 두 포맷 간의 구조적 차이와 변환 필요성 [2]. +- [[Litegraph Standard]] + - 연결 이유: ComfyUI 프런트엔드가 채택하고 있는 그래프 시각화 표준이다 [1, 34]. + +#### [구현 및 자동화 도구] +- [[ComfyUI API Integration]] + - 연결 이유: API JSON이 실제로 활용되는 최종 목적지이다 [12, 35]. +- [[ComfyUI Manager]] + - 연결 이유: API JSON 로드 시 발생하는 커스텀 노드 의존성 문제를 해결하는 핵심 도구이다 [36, 37]. + +### 심층 후속 질문 (Deeper Research Questions) +- 시각적 레이아웃이 없는 API JSON을 다시 UI용 프런트엔드 JSON으로 복원할 때, 노드 배치 알고리즘은 어떻게 작동하는가? +- 노드 ID가 동적으로 변경될 수 있는 환경에서, 특정 노드를 타이틀(Title) 기반으로 안정적으로 식별하여 값을 수정하는 최적의 휴리스틱은 무엇인가? [16, 18] +- Execution Model Inversion 가이드에 명시된 백엔드 엔진의 노드 순회 알고리즘은 순환 참조를 어떻게 방지하는가? [21] +- 이미지 내 메타데이터에 포함된 API JSON이 손실되었을 때, 픽셀 정보를 분석하여 워크플로를 추론하는 기술적 가능성이 존재하는가? +- 대규모 배치 처리 환경에서 API JSON의 `_meta` 필드를 활용하여 실행 로그와 결과를 추적하는 방법은 무엇인가? [10] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 자동화 스크립트 작성 시 `json` 라이브러리를 사용해 API JSON의 특정 노드 `inputs` 값을 덮어씌워 서버에 POST 요청을 보낸다 [9, 20]. +- **System Design:** 서버리스 AI 서비스 구축 시, 사용자의 의도를 LLM으로 해석하여 API JSON 구조를 동적으로 생성하는 파이프라인을 설계한다 [38-40]. +- **Operation / Maintenance:** ComfyUI Manager를 통해 JSON 내에 정의된 `class_type`을 기반으로 누락된 커스텀 노드를 자동 설치하여 환경을 동기화한다 [36, 41]. +- **Learning Path:** 기본 텍스트-투-이미지 워크플로를 API 형식으로 내보내고, Python에서 시드값을 바꿔가며 실행해보는 것부터 시작한다 [20, 42]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: JSON 내 모델 파일 이름 불일치 문제를 해결하기 위한 모델 고유 식별 기술 [43]. +- [[Base64 Image Encoding]] + - 확장 방향: API 요청 시 파일 업로드 없이 데이터를 JSON에 직렬화하여 전달하는 방식 [19, 20]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source references 29, 30, 32, 37, 38, 42, 43, 44, 45, 46, 71, 85, 86, 116, 124, 143, 144, 151, 152, 161, 162, 174, 192, 196 등 활용) [1-4, 7-16, 18-21, 24, 28, 30, 31, 36, 43] \ No newline at end of file diff --git a/10_Wiki/Comfyui/Workflow API JSON.md b/10_Wiki/Comfyui/Workflow API JSON.md new file mode 100644 index 00000000..e0154463 --- /dev/null +++ b/10_Wiki/Comfyui/Workflow API JSON.md @@ -0,0 +1,103 @@ +--- +id: workflow-api-json +title: "Workflow API JSON" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["workflow_api.json", "Backend Format"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.95 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["SethRobinson/comfyui-workflow-to-api-converter-endpoint", "pydn/ComfyUI-to-Python-Extension", "DanielPFlorian/ComfyUI-WorkflowGenerator", "deimos-deimos/comfy_api_simplified"] +github_commit: "" +--- + +# [[Workflow API JSON]] + +## 🎯 한 줄 통찰 (One-line insight) +Workflow API JSON은 시각적 메타데이터를 제거하고 노드 간의 순수 실행 로직과 연결성만을 최적화하여 제공하는 ComfyUI의 서버 측 실행 인터페이스용 핵심 데이터 규격이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **백엔드 실행 최적화 (Backend Optimization):** 프론트엔드용 시각적 정보(위치, 크기, 색상)를 제외하고 오직 `/prompt` 엔드포인트 실행에 필요한 데이터만 포함한다 [1-3]. +- **노드-슬롯 연결성 (Node-Slot Connectivity):** 별도의 연결 객체 대신 노드 입력(inputs) 내에 직접 [원본 노드 ID, 출력 슬롯 인덱스] 형식으로 연결 정보를 임베딩한다 [1, 4, 5]. +- **고유 식별자 체계 (Unique ID System):** 각 노드는 고유한 숫자형 문자열 키(예: "5", "6")로 식별되며, 이는 실행 그래프 내에서 데이터 흐름을 추적하는 기준이 된다 [1, 3, 6]. +- **직렬화 유연성 (Serialization Flexibility):** 사람이 읽을 수 있는 JSON 형식을 취하며, 대규모 모델 가중치와 별개로 워크플로우 로직의 배포, 버전 관리 및 자동화를 가능하게 한다 [7-9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **UI 메타데이터 스트리핑 (Metadata Stripping):** 시각적 편집용 `workflow.json`에서 API 호출용 `workflow_api.json`으로 전환 시 `pos`, `size`, `groups`와 같은 필드를 제거하여 파일 크기를 축소하고 처리 효율을 높인다 [1, 2, 5]. +- **실행 모델 인버전 (Execution Model Inversion):** 엔진이 'Save Image'와 같은 출력 노드에서 역방향으로 그래프를 탐색하여 필수 종속성만 실행하고 불필요한 노드는 무시하는 구조를 취한다 [10]. +- **입력 데이터 인젝션 (Input Injection):** 자동화 시 JSON 내의 특정 노드 ID를 찾아 시드(seed), 프롬프트(prompt), 또는 Base64 인코딩된 이미지 데이터를 동적으로 교체하여 실행한다 [6, 11-13]. + +## 📖 세부 내용 (Details) +ComfyUI의 워크플로우 직렬화 형식은 크게 **프론트엔드 포맷**과 **백엔드(API) 포맷**으로 이분화된다 [1, 2, 14]. API JSON은 서버 측 엔진이 프롬프트를 실행하는 데 필요한 최소한의 논리 그래프를 나타내며, `Litegraph` 표준을 따르는 프론트엔드 포맷과 달리 매우 간결한 구조를 갖는다 [1, 3, 15]. + +- **생성 방법:** 사용자는 설정 메뉴에서 "Dev mode Options"를 활성화해야 하며, 이후 제어판에 나타나는 "Save (API Format)" 또는 "Export (API)" 버튼을 통해 이 파일을 생성할 수 있다 [16-20]. +- **구조적 특징:** 루트 키는 노드 ID이며, 각 값은 `class_type`과 `inputs`를 포함하는 객체이다 [6, 20]. 예를 들어, 특정 노드의 입력 필드에 `[ "20", 1 ]`과 같은 배열이 있다면 이는 20번 노드의 2번 슬롯(인덱스 1) 출력이 연결되었음을 의미한다 [4]. +- **메타데이터 임베딩:** ComfyUI에서 생성된 PNG 또는 WebP 이미지에는 프론트엔드 워크플로우와 API 프롬프트(JSON 형식)가 모두 메타데이터(tEXt 또는 zTXt 청크)로 저장되어 있어, 이미지 자체를 인터페이스로 드래그하여 로직을 복구할 수 있다 [21-24]. +- **프로그래밍 방식의 조작:** 파이썬의 `json` 라이브러리를 사용하여 딕셔너리 구조를 직접 수정하거나, `comfy_api_simplified`와 같은 래퍼 라이브러리를 통해 노드 제목 기반으로 파라미터를 동적으로 변경하여 대량의 이미지를 자동 생성할 수 있다 [6, 25-27]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가독성 vs 편집성:** API 포맷은 실행에는 효율적이나, 시각적 정보가 결여되어 있어 다시 ComfyUI 인터페이스로 불러올 경우 노드들이 겹쳐 보이거나 구조 파악이 어려운 '스켈레톤' 상태가 된다 [28-30]. +- **파일 포맷 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 구버전의 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있는 호환성 문제가 존재한다 [31, 32]. +- **커스텀 노드 의존성:** JSON 자체에는 로직만 포함되므로, 워크플로우 생성자가 사용한 동일한 커스텀 노드가 로컬 환경에 설치되어 있지 않으면 'Red Box' 오류가 발생하며 실행이 불가능하다 [33, 34]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드 JS 로직을 파이썬으로 변환하여 서버 측에서 일반 워크플로우를 API 포맷으로 즉시 변환하는 엔드포인트를 제공한다 [28, 35]. +- **ComfyUI-to-Python-Extension:** `.json` 워크플로우를 독립 실행 가능한 `.py` 스크립트로 변환하여 헤드리스(headless) 환경에서 실행할 수 있게 한다 [25, 36]. +- **ComfyUI-WorkflowGenerator:** LLM(Qwen2.5 등)을 사용하여 자연어 설명을 실행 가능한 API JSON 그래프로 합성하고 유효성을 검증한다 [37-39]. +- **fofr/any-comfyui-workflow (Replicate):** 클라우드 환경에서 JSON 블롭(blob)을 입력받아 API를 통해 워크플로우를 실행하고 결과를 반환한다 [40, 41]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 및 오픈소스 프로젝트 코드를 통해 데이터 규격 및 생성 방식 확인됨) [42, 43] +- **출처 신뢰도:** B (Official Documentation / GitHub Repository / Expert Tutorial) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Litegraph Standard]] + - 연결 이유: ComfyUI 프론트엔드 JSON이 시각적 표현을 위해 채택한 기반 표준임 [1, 15]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: API 포맷으로 전환 시 제거되는 UI 메타데이터의 구조적 근거 [1, 2]. +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI 워크플로우의 근본적인 데이터 흐름 구조임 [7, 44]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 연결성과 실행 순서가 결정되는 논리적 원리 [7, 10]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 로드 시 발생하는 누락된 노드 및 모델 문제를 해결하는 필수 도구임 [33, 34, 45]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 워크플로우 배포 시 발생하는 의존성 관리 전략 [34, 46]. +- [[/prompt endpoint]] + - 연결 이유: API 포맷 JSON이 최종적으로 전송되어 처리되는 목적지임 [2, 16, 28]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 클라이언트-서버 간의 실제 통신 메커니즘 [12, 13]. + +### 심층 후속 질문 (Deeper Research Questions) +- API JSON 내에서 링크 정보를 별도 배열이 아닌 노드 입력(inputs) 내에 직접 임베딩하는 방식이 실행 효율성에 미치는 영향은 무엇인가? [1, 4] +- LLM 기반의 워크플로우 생성 모델은 학습 데이터 이후에 출시된 새로운 커스텀 노드의 I/O 스키마를 어떻게 동적으로 학습하고 반영할 수 있는가? [44, 47, 48] +- `object_info.json`을 활용하여 동적으로 생성된 API JSON의 유효성을 런타임에 검증하는 구체적인 알고리즘은 어떻게 설계되는가? [20, 49] +- 실행 모델 인버전(Execution Model Inversion) 과정에서 조건부 분기나 반복 루프가 포함된 복잡한 그래프의 종속성을 어떻게 추적하는가? [10] +- 모델 해싱(Model Hashing)을 통해 하드코딩된 파일 경로 문제를 해결할 때, 서로 다른 머신 간의 모델 버전 일관성을 보장하는 방법은 무엇인가? [32, 46] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 배너 광고 자동 생성 시스템 구축 시, 템플릿 JSON의 특정 노드(예: CLIPTextEncode)를 파이썬 스크립트로 수정하여 자동화할 수 있음 [12, 50]. +- **System Design:** 서버리스 환경(Mystic, Replicate 등)에서 워크플로우를 배포할 때 UI 정보를 제거한 최적화된 API JSON을 기본 실행 단위로 설정함 [5, 19, 51]. +- **Operation / Maintenance:** `comfyui-workflow-to-api-converter-endpoint`를 사용하여 프론트엔드 워크플로우만 관리하고 실행 직전에 API 포맷으로 변환함으로써 관리 포인트의 이원화를 방지함 [29, 35]. +- **Learning Path:** 초보자는 시각적 그래프를 통해 로직을 이해하고, 숙련자는 개발자 모드를 통해 추출된 JSON의 노드 ID와 파라미터 구조를 분석하여 코딩 방식의 제어로 전이함 [52-54]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Base64 Image Encoding]] + - 확장 방향: API 요청 시 로컬 파일 경로 대신 이미지 데이터를 JSON에 직접 포함하는 기술적 구현 방법 [11, 13]. +- [[RAG (Retrieval-Augmented Generation)]] + - 확장 방향: 정적 모델의 한계를 극복하기 위해 실시간 노드 라이브러리를 검색하여 워크플로우를 생성하는 차세대 AI 에이전트 설계 [44]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) [1-200] \ No newline at end of file diff --git a/10_Wiki/Comfyui/Workflow JSON v1.0 Schema.md b/10_Wiki/Comfyui/Workflow JSON v1.0 Schema.md new file mode 100644 index 00000000..3598132b --- /dev/null +++ b/10_Wiki/Comfyui/Workflow JSON v1.0 Schema.md @@ -0,0 +1,117 @@ +--- +id: workflow-json-v1.0-schema +title: "Workflow JSON v1.0 Schema" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI JSON Schema", "Workflow v1.0 Specification"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Schema", "JSON"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: + - "/specs/workflow_json" + - "/src/scripts/metadata" + - "comfyui-workflow-to-api-converter-endpoint" + - "ComfyUI-to-Python-Extension" +github_commit: "bc85382" +--- + +# [[Workflow JSON v1.0 Schema]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우 JSON은 생성 로직을 **유도 비순환 그래프(DAG)**로 구조화하여 시각적 인터페이스와 실행 엔진 사이의 상호운용성을 보장하는 핵심 데이터 규격이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **이원적 직렬화 포맷 (Bifurcation of Formats):** 시각적 편집과 레이아웃 보존을 위한 **Frontend Format**(workflow.json)과 서버 측 실행에 최적화된 **Backend/API Format**(workflow_api.json)으로 구분된다 [3-5]. +- **Litegraph 표준 기반:** 프론트엔드 포맷은 노드 위치, 크기, 그룹화 등 시각적 메타데이터를 포함하는 Litegraph 표준을 따른다 [3, 6]. +- **슬롯 기반 연결성 (Slot-based Connectivity):** 노드 간 데이터 흐름은 고유한 입력/출력 슬롯 인덱스를 통해 정의되며, API 포맷에서는 이를 노드 내부에 인라인 참조로 내장한다 [3, 7, 8]. +- **JSON Schema v1.0 (Draft-07):** 기술적 무결성을 검증하기 위해 필수 속성과 데이터 타입을 규정하는 최신 공식 사양이다 [9-11]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Metadata Redundancy 패턴:** PNG 파일 내에 시각적 포맷(workflow)과 실행 포맷(prompt)을 동시에 내장하여, 이미지 한 장만으로 편집과 재실행이 모두 가능하도록 설계되었다 [12, 13]. +- **Execution Model Inversion:** 최종 출력 노드(Save Image 등)에서 역방향으로 그래프를 탐색하여 실행에 필요한 의존성 노드만 식별하고 불필요한 연산을 배제한다 [14]. +- **Node Functional Mapping:** API 포맷에서 링크 객체를 제거하고 `[노드ID, 슬롯번호]` 형태의 배열로 간소화하여 전송 효율과 파싱 속도를 극대화한다 [3, 15, 16]. + +## 📖 세부 내용 (Details) +### 1. 노드 객체 속성 (Node Object Properties) +v1.0 스키마에 정의된 노드 객체는 그래프 탐색 및 렌더링을 위해 다음과 같은 속성을 포함해야 한다 [8, 9]: +- **id:** 그래프 내 노드를 식별하는 고유 정수 또는 문자열 [9]. +- **type (또는 class_type):** 노드 레지스트리에 등록된 클래스 이름과 매핑되는 식별자 [9, 16]. +- **pos & size:** 캔버스상의 좌표 및 크기 정보를 담은 배열 (API 포맷에서는 제거됨) [9, 16]. +- **widgets_values:** 텍스트 박스, 슬라이더 등 사용자 입력값을 저장하는 배열 [9, 15]. +- **order & mode:** 실행/렌더링 우선순위 및 노드의 활성 상태(예: bypass)를 정의한다 [8, 9]. + +### 2. 그래프 연결 구조 (Link and Slot Connectivity) +- **연결 정의:** 노드의 `inputs` 배열은 유입되는 선의 ID를 참조하며, `outputs` 배열은 여러 하위 노드로 연결될 수 있는 링크 ID들의 배열을 포함한다 [7]. +- **슬롯 인덱싱:** 특정 노드의 출력(예: VAE Loader의 VAE 출력)이 정확히 어떤 슬롯에서 생성되어 소비되는지 명시하는 것이 필수적이다 [7]. +- **API 포맷의 특수성:** `workflow_api.json`은 시각적 링크 배열을 제거하고, 노드 입력 필드 내에 직접 `["노드ID", 슬롯_인덱스]` 값을 할당하여 실행 그래프를 평탄화(Flattening)한다 [3, 15]. + +### 3. 보조 스키마 (object_info.json) +- 실행 중인 ComfyUI 인스턴스의 모든 노드에 대한 스키마 카탈로그이다 [5, 17]. +- 각 노드가 허용하는 입력 유형, 범위, 출력 데이터 타입 및 툴팁 정보를 포함하여 외부 도구에서 JSON을 동적으로 생성하거나 검증할 때 사용된다 [17-19]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 문제:** 소스에 따르면 현재 v1.0이 최신이지만, ComfyUI의 잦은 업데이트로 인해 0.4 버전 등 이전 버전의 JSON 파일이 최신 환경에서 정상 작동하지 않을 수 있음이 지적된다 [10, 11, 20]. +- **데이터 파편화:** 이미지 메타데이터에서 추출한 JSON은 종종 커스텀 노드 정보를 누락할 수 있으며, 이 경우 캔버스에 'Red Boxes' 에러가 발생한다 [21-23]. +- **API 포맷의 가독성:** 실행 최적화된 API JSON은 시각적 정보가 모두 제거된 'Skeleton' 형태이므로, 이를 다시 ComfyUI 인터페이스로 드래그하여 편집하기에는 부적합하다 [24, 25]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI 공식 사양:** `/specs/workflow_json` 경로에서 v1.0 규격을 공식 관리한다 [10]. +- **프론트엔드 메타데이터 처리:** `ComfyUI_frontend/src/scripts/metadata`에서 자바스크립트 기반의 메타데이터 파싱 로직을 구현하고 있다 [26]. +- **comfyui-workflow-to-api-converter-endpoint:** 서버 측 파이썬 로직을 통해 Frontend JSON을 API JSON 규격으로 실시간 변환하며, `bc85382` 커밋에서 콤보 위젯 값의 정규화 이슈가 해결되었다 [24, 27-29]. +- **ComfyUI-to-Python-Extension:** JSON 워크플로우를 분석하여 동일한 로직의 `.py` 실행 스크립트를 생성할 때 v1.0 스키마 구조를 참조한다 [30, 31]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 기반의 스펙 정의 완료) +- **출처 신뢰도:** B (Official Documentation 및 전문 기술 블로그 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 + +### 상위/유사 개념 +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: 본 스키마가 생성 방법론의 기술적 기반이 됨. +- [[Dev mode Options]] + - 연결 이유: 스키마의 두 가지 형태(Frontend/API) 중 API 포맷을 내보내기 위한 필수 전제 조건임. + +#### [아키텍처/기반 기술] +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON의 데이터 구조와 렌더링 방식을 규정함. +- [[Execution Model Inversion]] + - 연결 이유: JSON 그래프를 해석하여 효율적으로 실행하는 백엔드 최적화 원리임. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 스키마 내의 `class_type`을 분석하여 누락된 커스텀 노드를 복구함. +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: JSON 워크플로우를 파이썬 코드로 이식하는 실제 사례임. + +### 심층 후속 질문 (Deeper Research Questions) +- API 포맷에서 링크를 노드 입력 내부에 인라인화하는 방식이 순환 참조(Circular Reference) 방지에 어떤 기여를 하는가? +- `object_info.json`의 스키마 데이터와 실제 노드의 `INPUT_TYPES` 메서드 사이의 동기화 실패 시 어떤 예외 처리가 발생하는가? +- v1.0 스키마에서 `widgets_values` 배열의 순서 기반 데이터 저장이 노드 업데이트로 인한 위젯 추가 시 어떤 호환성 문제를 일으키는가? +- PNG 파일의 `tEXt` 청크 용량 제한이 매우 거대한 워크플로우 JSON(예: 수백 개의 노드) 저장에 한계로 작용하는가? +- `comfy-pack`과 같은 도구에서 사용하는 모델 해싱 기술이 JSON 스키마 내에서 어떻게 표준화될 수 있는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 외부 애플리케이션(Unity, Web App 등)에서 ComfyUI 서버에 작업을 요청할 때 API JSON을 생성하고 전송해야 한다 [28, 32]. +- **System Design:** 워크플로우 자동화를 위해 JSON 내의 특정 노드 ID와 입력 필드(예: 프롬프트, 시드)를 동적으로 수정하는 로직을 설계할 수 있다 [33, 34]. +- **Operation / Maintenance:** 커스텀 노드 업데이트 시 JSON 내 `class_type` 명칭이 변경되면 워크플로우가 파손될 수 있으므로 버전 관리가 필요하다 [20, 35]. +- **Learning Path:** 노드 기반 인터페이스의 데이터 구조를 이해하면 시각적 툴 없이도 순수 코드로 생성 AI 파이프라인을 구축할 수 있다 [30, 36]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Custom Nodes]] + - 확장 방향: JSON 스키마에 새로운 노드 타입을 등록하고 관리하는 방법 연구. +- [[Metadata Stripping]] + - 확장 방향: 소셜 미디어 배포 시 이미지 내 메타데이터 손실 대응 방안 및 외부 JSON 저장 전략. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Workflow JSON.md b/10_Wiki/Comfyui/Workflow JSON.md new file mode 100644 index 00000000..0d8c3df6 --- /dev/null +++ b/10_Wiki/Comfyui/Workflow JSON.md @@ -0,0 +1,111 @@ +--- +id: workflow-json +title: "Workflow JSON" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Workflow API JSON", "Frontend JSON"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes/ComfyUI-Manager", "ComfyUI/custom_nodes/ComfyUI-WorkflowGenerator", "ComfyUI/models/LLM/", "workflow_api.py"] +github_commit: "82df278, bc85382" +--- + +# [[Workflow JSON]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI의 Workflow JSON은 노드 기반 비순환 유향 그래프(DAG)를 직렬화하여 복잡한 생성형 AI 파이프라인을 휴대 가능한 데이터로 변환하고, 이를 통해 시각적 편집과 프로그래밍적 자동화를 연결하는 핵심 매개체이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **이분화된 직렬화 포맷:** 사용자 인터페이스를 위한 **Frontend 포맷(workflow.json)**과 서버 측 실행에 최적화된 **API 포맷(workflow_api.json)**으로 나뉜다 [4-6]. +- **Litegraph 기반 스키마 (v1.0):** 노드 ID, 유형, 위치, 크기, 위젯 값 및 노드 간의 링크 배열을 포함하는 표준화된 기술 규격을 따른다 [7-9]. +- **메타데이터 임베딩 기술:** 생성된 PNG나 WebP 이미지의 tEXt/zTXt 청크 내에 JSON 데이터를 직접 삽입하여 이미지 파일 자체가 워크플로우 백업 역할을 수행하게 한다 [10, 11]. +- **실행 모델 반전 (Execution Model Inversion):** 최종 출력 노드(Save Image 등)로부터 역추적하여 필요한 의존성 노드만 실행하는 최적화 구조를 가진다 [12]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **UI-to-API 정제 패턴:** 시각적 메타데이터(좌표, 그룹, 색상)를 제거하고 노드 입력을 직접적인 노드 참조로 변환하여 파일 크기를 줄이고 실행 효율을 극대화한다 [4, 13]. +- **LLM 기반 3단계 생성 파이프라인:** 자연어 설명 해석(Logical Synthesis) → 노드 존재 여부 검증(Semantic Validation) → 실행 가능한 JSON 컴파일(Graph Compilation) 과정을 통해 워크플로우를 자동 생성한다 [14-16]. +- **의존성 복구 휴리스틱:** JSON 내 `class_type`을 로컬 레지스트리와 대조하여 누락된 커스텀 노드를 식별하고 ComfyUI Manager를 통해 일괄 설치를 제안한다 [17, 18]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우 JSON은 생성적 AI 프로세스를 절차적 프레임워크로 추상화한 결과물이다 [1, 19]. 이 데이터 구조는 인간이 읽을 수 있는 형식이며, 대용량 모델 가중치와 독립적으로 공유 및 버전 관리가 가능하다 [2]. + +**1. 주요 포맷 상세 비교** [4, 5, 13, 20-22]: +- **Frontend JSON:** Litegraph 표준을 따르며 노드의 캔버스 좌표(`pos`), 크기(`size`), 그룹 정보 등 시각적 레이아웃 데이터를 모두 보존한다. 주로 시각적 편집과 공유를 목적으로 사용된다. +- **API JSON:** `/prompt` 엔드포인트 호출을 위한 정제된 형태이다. 시각적 정보는 삭제되며, 노드 간 연결은 별도의 링크 배열이 아닌 각 노드 입력부에 `[노드_ID, 출력_슬롯_인덱스]` 형태로 직접 임베딩된다. + +**2. 생성 및 획득 방법** [23-27]: +- **수동 내보내기:** GUI의 제어판에서 `Ctrl + S`(Frontend)를 누르거나, 설정에서 'Dev mode' 활성화 후 'Save (API format)' 버튼을 클릭하여 생성한다. +- **이미지에서 추출:** 생성된 PNG 파일을 캔버스에 드래그 앤 드롭하면 내장된 JSON이 로드된다. 대량 추출 시 `exiftool`이나 `ComfyUI-Workflow-Extractor` 같은 CLI 도구를 사용하여 메타데이터 청크에서 직접 파싱할 수 있다. +- **LLM 생성:** `Qwen2.5-14B` 등 미세 조정된 모델을 사용하여 "SDXL용 텍스트-이미지 워크플로우 생성"과 같은 자연어 지시를 즉시 실행 가능한 JSON 그래프로 변환한다 [14, 28]. + +**3. 프로그래밍적 조작 및 자동화** [29-33]: +- 개발자는 Python의 `json` 라이브러리를 사용하여 노드 ID를 기반으로 프롬프트(`CLIPTextEncode`), 시드값, 체크포인트 이름 등을 동적으로 변경할 수 있다. +- `Comfy API Simplified`와 같은 래퍼 라이브러리는 숫자 ID 대신 노드 제목(Title)을 기준으로 파라미터를 설정할 수 있게 하여 코드 유지보수성을 높인다. +- 워크플로우 자체를 순수 Python 스크립트로 변환하여 서버리스 환경이나 단독 애플리케이션에서 실행할 수도 있다 [34]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성:** ComfyUI의 잦은 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [35]. +- **메타데이터 취약성:** 이미지 편집기, 소셜 미디어 플랫폼 등에서 파일 최적화 과정 중 워크플로우 정보가 포함된 메타데이터 청크를 삭제하는 경우가 많아 JSON 공유 시 주의가 필요하다 [10]. +- **노드 명칭 충돌:** 서로 다른 제작자가 만든 커스텀 노드가 동일한 제목을 가질 수 있어, 프로그래밍적 접근 시 숫자 ID나 고유 클래스 타입 확인이 필수적이다 [33]. + +## 🛠️ 적용 사례 (Applied in summary) +- **DanielPFlorian/ComfyUI-WorkflowGenerator:** LLM을 이용해 자연어로 JSON을 생성하는 프로젝트로, 커밋 `82df278`에서 모델 경로 해결 및 중복 드롭다운 수정이 이루어졌다 [36, 37]. +- **SethRobinson/comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측 JS 로직을 서버 측 Python으로 변환하여 Frontend JSON을 API 포맷으로 즉시 변환하는 엔드포인트를 구현했다 (커밋 `bc85382`) [38, 39]. +- **ComfyUI Manager:** JSON 내부의 노드 정의를 분석하여 `ComfyUI/custom_nodes` 디렉토리에 필요한 의존성을 자동 설치하는 매커니즘을 제공한다 [17, 40]. +- **Standalone Execution Scripts:** `sdxl_workflow_api.json`을 로드하여 독립적인 Python 환경에서 실행하는 `WorkflowExecutor` 사례가 확인되었다 [41, 42]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 오픈소스 프로젝트와 공식 문서의 구조가 일치함을 확인) +- **출처 신뢰도:** B (공식 문서 및 실제 구현 코드가 포함된 GitHub 저장소 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: 워크플로우의 노드 연결 구조를 정의하는 수학적 기반임 [1]. + - 이해 증진: 실행 순서 결정 및 의존성 해결 원리를 이해할 수 있음. +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON 포맷의 시각적 직렬화 규격임 [4, 20]. + - 이해 증진: 노드 위치, 크기 및 시각적 플래그 저장 방식을 파악할 수 있음. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 내 정의된 커스텀 노드 의존성을 해결하는 핵심 도구임 [17]. + - 이해 증진: 공유된 워크플로우의 실행 오류를 해결하는 프로세스를 이해할 수 있음. +- [[Large Language Models (LLM)]] + - 연결 이유: 자연어를 JSON으로 변환하는 최신 자동화 기술의 핵심임 [14, 37]. + - 이해 증진: '대화형 프로그래밍'으로의 진화 방향을 이해할 수 있음. + +### 심층 후속 질문 (Deeper Research Questions) +- Frontend JSON과 API JSON 사이의 변환 과정에서 손실되는 데이터가 실행 결과에 미치는 영향은 무엇인가? [4, 39] +- 이미지 메타데이터(tEXt/zTXt) 외에 워크플로우 정보를 보존하기 위한 더 견고한 아키텍처는 무엇인가? [10, 43] +- LLM 기반 생성기에서 '훈련 시점 이후 출시된 커스텀 노드'에 대한 환각(Hallucination) 문제를 어떻게 제어하는가? [44, 45] +- Execution Model Inversion이 대규모 복합 워크플로우에서 자원 효율성을 구체적으로 얼마나 개선하는가? [12] +- 모델 해싱(SHA-256)을 JSON 내에 포함시켜 파일명 불일치 문제를 해결하는 표준화된 방식은 무엇인가? [46] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** Python의 `urllib`과 `websocket`을 사용하여 `/prompt` 엔드포인트에 JSON 페이로드를 전송하고 결과를 실시간으로 수신함 [32]. +- **System Design:** 워크플로우를 JSON으로 관리함으로써 CI/CD 파이프라인을 통한 자동 테스트 및 버전 관리가 가능해짐 [47]. +- **Operation / Maintenance:** 모델 파일 경로가 다른 환경으로 이전 시 JSON 내부의 파일명을 로컬 환경에 맞춰 수정하거나 ComfyUI Manager의 검색 기능을 활용함 [43]. +- **Learning Path:** 기본 워크플로우 템플릿 로드 → 시각적 노드 연결 변경 → JSON 내보내기 및 구조 분석 순서로 학습 권장 [48]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: JSON 파일의 기기 간 이동 시 모델 파일명 불일치 문제를 해결하는 기술적 대안 [46]. +- [[Workspace Packaging (.cpack.zip)]] + - 확장 방향: JSON 단일 파일의 한계를 넘어 모델 해시와 노드 버전까지 패키징하는 미래 표준 [43]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [1, 6, 14, 24, 25, 29, 30, 32, 37, 41, 43, 49-52] \ No newline at end of file diff --git a/10_Wiki/Comfyui/Workflow.json (Frontend Format).md b/10_Wiki/Comfyui/Workflow.json (Frontend Format).md new file mode 100644 index 00000000..90ff47f5 --- /dev/null +++ b/10_Wiki/Comfyui/Workflow.json (Frontend Format).md @@ -0,0 +1,109 @@ +--- +id: workflow.json-(frontend-format) +title: "Workflow.json (Frontend Format)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Frontend JSON", "Full Workflow Export"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "ComfyUI-WorkflowGenerator"] +github_commit: "" +--- + +# [[Workflow.json (Frontend Format)]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI의 시각적 편집 상태와 노드 간의 논리적 연결을 **Litegraph 표준**에 따라 완벽하게 보존하여, 인간의 재편집과 기계적 실행 사이의 가교 역할을 수행하는 전제 상태(Full State) 스냅샷 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **Litegraph 표준 준수:** ComfyUI 웹 인터페이스의 캔버스 레이아웃을 정의하는 라이브러리인 Litegraph 형식을 따르며, 시각적 렌더링에 필요한 모든 데이터를 포함한다 [1, 2]. +2. **시각적 메타데이터(Visual Metadata):** 노드의 좌표(pos), 크기(size), 그룹 구성, 색상, 노드의 축소(collapsed) 또는 고정(pinned) 상태 등의 정보를 상세히 기록한다 [1, 3, 4]. +3. **명시적 링크 구조(Explicit Links):** 노드 간의 연결을 별도의 `links` 배열 내에서 고유 ID를 가진 명시적 객체로 관리하여 그래프의 시각적 연결성을 유지한다 [2, 3, 5]. +4. **노드 식별자(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 리포지토리를 통한 교차 검증 완료) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON 포맷의 구조적 근간이 되는 라이브러리 규격임 [1]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 배치 및 링크 렌더링 원리. +- [[Workflow.api.json (Backend Format)]] + - 연결 이유: Frontend JSON에서 UI 정보를 제거하고 실행 효율성을 극대화한 대응 포맷임 [1, 3]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 표현과 논리적 실행 구조의 분리. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 내의 `class_type`을 분석하여 누락된 커스텀 노드를 설치해주는 필수 관리 도구임 [20]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 종속성 관리 및 환경 복구 프로세스. +- [[Workflow Extractor]] + - 연결 이유: 이미지 메타데이터에 숨겨진 Frontend JSON을 추출하는 전문 도구임 [28, 29]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메타데이터 보존 및 데이터 복구 기술. + +### 심층 후속 질문 (Deeper Research Questions) +- Frontend JSON의 `order` 필드가 실제 백엔드의 실행 순서와 항상 일치하는가? [14] +- PNG 이미지의 `tEXt` 청크와 `zTXt` 청크 중 어느 방식이 워크플로우 데이터 저장에 더 유리한가? [11] +- `comfyui-workflow-to-api-converter-endpoint`는 서브그래프(Subgraph)가 포함된 복잡한 프론트엔드 JSON을 어떻게 처리하는가? [23, 30] +- 노드 ID가 문자열로 저장될 때와 숫자로 저장될 때의 시스템 처리 차이는 무엇인가? [4, 6] +- 모델 해싱(Model Hashing) 기술이 JSON의 포터빌리티(Portability) 문제를 어떻게 해결하는가? [31] +- LLM이 생성한 논리적 다이어그램을 표준 V1.0 스키마에 맞게 검증하는 구체적인 메커니즘은 무엇인가? [26, 32] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 커스텀 앱에서 워크플로우를 로드할 때, 우선 Frontend 포맷으로 불러와 사용자에게 시각적으로 보여준 뒤 실행 시점에만 API 포맷으로 변환하여 요청한다 [33]. +- **System Design:** 버전 관리 시스템(Git)에 워크플로우를 저장할 때, 시각적 변경 사항을 추적하기 위해 Frontend 포맷을 유지하는 것이 유리하다 [34]. +- **Operation / Maintenance:** 사용자가 공유한 이미지에서 워크플로우를 복원할 수 없는 경우, `exiftool` 등을 사용해 메타데이터 존재 여부를 선제적으로 확인한다 [29, 35]. +- **Learning Path:** 초보자는 시각적 노드 연결 방식을 통해 논리 구조를 익히고, 숙련자는 JSON의 `widgets_values`를 직접 수정하여 자동화 스크립트를 작성한다 [13, 36]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Custom Nodes]] + - 확장 방향: JSON 내의 `type` 필드가 실제 파이썬 클래스와 매핑되는 방식 연구. +- [[JSON Schema v1.0]] + - 확장 방향: 워크플로우 파일의 구조적 무결성을 검증하는 기술적 명세 확인 [14]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine based on 18 sources. \ No newline at end of file diff --git a/10_Wiki/Comfyui/WorkflowExecutor.md b/10_Wiki/Comfyui/WorkflowExecutor.md new file mode 100644 index 00000000..5161709f --- /dev/null +++ b/10_Wiki/Comfyui/WorkflowExecutor.md @@ -0,0 +1,94 @@ +--- +id: workflowexecutor +title: "WorkflowExecutor" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "applied" +canonical_id: "" +aliases: ["워크플로 실행기"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["GitHub Gist: Standalone execution script", "Quasilinear Musings: Executing ComfyUI Workflows as Standalone Scripts"] +github_commit: "" +--- + +# [[WorkflowExecutor]] + +## 🎯 한 줄 통찰 (One-line insight) +**[[WorkflowExecutor]]**는 ComfyUI의 웹 UI 및 서버 백엔드 종속성을 제거하여 워크플로를 독립적인 파이썬 스크립트 환경에서 실행할 수 있게 하는 핵심 오케스트레이션 엔진이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **독립적 실행 오케스트레이션**: 웹 기반 인터페이스 없이도 워크플로의 환경 초기화, 캐시 관리, 노드 실행을 총괄한다 [2]. +- **실행 그래프 구조화**: JSON 형식의 워크플로를 검증한 후 `DynamicPrompt`를 거쳐 순차적 실행이 가능한 `ExecutionList`로 변환한다 [2]. +- **노드 단위 데이터 처리**: 개별 노드의 입력 데이터를 조회(`get_input_data`)하고 연산을 수행하여 출력 데이터를 생성(`get_output_data`)하는 실행 단위를 제어한다 [3]. +- **캐시 통합 관리**: `ExecutionCache`와 연동하여 노드 출력 및 객체 인스턴스를 저장함으로써 중복 계산을 방지하고 성능을 최적화한다 [3, 4]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Backend-Only Execution Pattern**: 시각적 메타데이터가 포함된 Frontend JSON 대신, 노드 간의 직접적인 입력 참조를 포함하는 [[Workflow API JSON (Backend Format)]]만을 사용하여 실행 효율성을 극대화한다 [5, 6]. +- **Validation-to-Execution Pipeline**: 실행 전 `validate_prompt`를 통해 그래프의 무결성을 선제적으로 확인하고, 이를 동적 리스트로 컴파일하여 실행하는 단계적 파이프라인 구조를 따른다 [2]. + +## 📖 세부 내용 (Details) +**[[WorkflowExecutor]]**는 ComfyUI 워크플로를 서버리스 환경이나 독립형 애플리케이션으로 배포하고자 하는 개발자들을 위한 해결책으로 고안되었다 [1, 7]. 기본적으로 ComfyUI는 프론트엔드와 백엔드가 밀접하게 결합되어 있으나, 이 엔진은 해당 로직을 분리하여 헤드리스(Headless) 처리를 가능하게 한다 [1]. + +실행 과정은 크게 세 단계로 나뉜다. 첫째, 입력받은 API 형식의 JSON 워크플로를 ComfyUI 내부의 `validate_prompt` 함수를 사용하여 검증한다 [2]. 둘째, 검증된 데이터를 `DynamicPrompt` 객체로 구성하고, 이를 다시 실행 순서가 정의된 `ExecutionList`로 변환한다 [2]. 셋째, 이 리스트를 순회하며 개별 노드를 `_execute_node` 메서드를 통해 실행한다 [3]. + +노드 실행 시에는 `get_input_data`를 호출하여 이전 노드의 출력값이나 위젯 값을 수집하고, 이를 `get_output_data` 함수에 전달하여 실제 연산을 수행한다 [3]. 이 과정에서 생성된 결과물과 실행 상태는 **[[ExecutionCache]]**에 저장되어, 동일한 연산의 반복을 피하고 실행 속도를 높이는 데 기여한다 [3, 4]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **종속성 모순**: ComfyUI의 기본 아키텍처는 서버와 UI가 강하게 결합되어 있어 독립 실행이 불가능하다고 여겨졌으나, **[[WorkflowExecutor]]**는 내부 함수들을 직접 호출하는 방식으로 이 제약을 극복했다 [1, 4]. +- **형식 요구사항**: 일반적인 `workflow.json`은 시각적 메타데이터를 포함하므로 **[[WorkflowExecutor]]**에서 직접 사용할 수 없으며, 반드시 'Dev mode'에서 내보낸 [[Workflow API JSON (Backend Format)]]을 사용해야 한다 [5, 6]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Quasilinear Musings 프로젝트**: Timothy Lin이 제안한 "Executing ComfyUI Workflows as Standalone Scripts"의 핵심 구성 요소로 구현되었다 [7, 8]. +- **독립 실행 스크립트**: GitHub Gist에 공개된 소스 코드에서 `WorkflowExecutor` 클래스가 실제로 정의되어 있으며, SDXL Turbo 워크플로를 독립적인 `.py` 파일로 실행하는 데 성공적으로 적용되었다 [2, 4, 6]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** applied (GitHub Gist 및 기술 블로그를 통해 실제 구현 코드가 확인됨 [2, 8]) +- **출처 신뢰도:** B (전문 기술 블로그 및 오픈 소스 구현 사례 기반 [2, 7]) +- **중복 검사 결과:** 신규 생성 (기존 소스 내 독립 실행 엔진 개념 정의) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: 본 주제의 루트 주제이며 워크플로 데이터의 생성 기원을 정의함. +- [[Workflow API JSON (Backend Format)]] + - 연결 이유: **[[WorkflowExecutor]]**가 실행을 위해 반드시 필요로 하는 데이터 규격임 [5]. + +#### [구현/활용 도구] +- [[ExecutionCache]] + - 연결 이유: 실행 효율성을 위해 **[[WorkflowExecutor]]**와 함께 필수적으로 사용되는 캐시 시스템임 [3]. +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: 워크플로를 파이썬 코드로 변환하여 독립 실행한다는 목적을 공유하는 대안적 도구임 [1]. + +### 심층 후속 질문 (Deeper Research Questions) +- WorkflowExecutor가 `validate_prompt`를 수행할 때 커스텀 노드의 존재 여부를 어떻게 확인하는가? [2] +- `ExecutionList` 생성 시 순환 참조(Circular Reference)가 있는 그래프에 대한 방어 로직은 어떻게 작동하는가? [2] +- **[[ExecutionCache]]**가 메모리 한계에 도달했을 때의 데이터 축출 정책은 어떻게 정의되어 있는가? [3] +- 독립 실행 환경에서 `SaveImage` 노드와 같은 파일 출력 노드의 경로 지정 방식은 어떻게 처리되는가? [6] +- WorkflowExecutor를 통해 실행할 때와 표준 ComfyUI 서버를 통해 실행할 때의 VRAM 점유 효율 차이는 어느 정도인가? +- 대규모 배치 처리를 수행할 때 WorkflowExecutor의 병렬 실행 가능성은 어떻게 설계되어 있는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬 환경에서 ComfyUI 서버를 띄우지 않고 AI 생성 파이프라인을 자동화할 때 사용된다 [6]. +- **System Design:** 도커(Docker) 컨테이너 내에서 최소한의 오버헤드로 특정 워크플로를 실행하는 마이크로서비스 아키텍처에 적합하다 [1]. +- **Operation / Maintenance:** 서버 백엔드 업데이트 없이 특정 실행 로직만을 독립적으로 유지보수해야 할 때 유용하다 [1]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Execution Model Inversion]] + - 확장 방향: 출력 노드에서 시작하여 필요한 종속성만 실행하는 최적화 모델에 대한 심층 이해 [9]. +- [[ComfyUI Manager]] + - 확장 방향: 독립 실행 환경에서 누락된 커스텀 노드를 관리하고 설치하는 방법론 조사 [10]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/Workspace Packaging.md b/10_Wiki/Comfyui/Workspace Packaging.md new file mode 100644 index 00000000..17258612 --- /dev/null +++ b/10_Wiki/Comfyui/Workspace Packaging.md @@ -0,0 +1,97 @@ +--- +id: workspace-packaging +title: "Workspace Packaging" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [".cpack.zip", "Artifact-based Deployment"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfy-pack", ".cpack.zip"] +github_commit: "" +--- + +# [[Workspace Packaging]] + +## 🎯 한 줄 통찰 (One-line insight) +단순한 노드 그래프 직렬화를 넘어, 모델 해시와 커스텀 노드 버전 등 실행 의존성 전체를 하나의 아티팩트로 묶어 워크플로우의 영구적 재현성을 보장하는 차세대 배포 표준 [1]. + +## 🧠 핵심 개념 (Core concepts) +1. **아티팩트 기반 배포 (Artifact-based Deployment):** 원시 JSON 파일 대신 워크플로우 실행에 필요한 모든 컨텍스트를 포함하는 패키지 단위의 배포 방식 [1]. +2. **모델 가중치 해싱 (Model Weight Hashing):** 파일명에 의존하는 대신 SHA-256 해시를 사용하여 서로 다른 환경에서도 동일한 모델을 고유하게 식별하고 매핑 [1, 2]. +3. **버전 고정 (Version Locking):** 워크플로우 설계 당시 사용된 커스텀 노드의 특정 버전을 기록하여, 향후 노드 업데이트나 기능 중단(deprecation)으로 인한 오류를 방지 [1]. +4. **.cpack.zip 규격:** 워크플로우 JSON, 모델 해시 리스트, 커스텀 노드 버전 정보를 포함하도록 제안된 통합 패키지 형식 [1]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **불변성 확보 패턴 (Immutability Pattern):** JSON + SHA-256 Hash + Node Versioning을 결합하여 시간이 지나도 동일한 출력을 보장하는 '정적 실행 환경'을 구축함 [1]. +- **환경 독립적 식별 패턴 (Environment-Agnostic Identification):** 물리적 파일 경로(sd_xl_base.safetensors)가 아닌 데이터의 지문(Hash)을 통해 자원을 검색함으로써 이식성 문제를 해결함 [1, 2]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우는 기존에 PNG 메타데이터나 단순 JSON 파일로 공유되었으나, 이는 모델 파일명 불일치나 커스텀 노드 버전 차이로 인한 'Red Nodes' 오류에 취약한(fragile) 구조를 가짐 [1, 3, 4]. **Workspace Packaging**은 이러한 한계를 극복하기 위해 워크플로우를 고립된 실행 단위로 취급함 [1]. + +주요 구성 요소는 다음과 같음: +- **워크플로우 직렬화:** 표준 JSON v1.0 규격에 따른 노드 및 링크 데이터 포함 [1, 5]. +- **의존성 체크섬:** `comfy-pack`과 같은 도구를 사용하여 모델 가중치의 SHA-256 해시를 생성하며, 이를 통해 사용자의 로컬 환경에서 파일명이 다르더라도 올바른 모델을 찾아낼 수 있음 [1, 2]. +- **노드 컨텍스트:** 특정 시점의 커스텀 노드 코드 상태를 고정하여 시스템의 일관성을 유지함 [1]. + +이 방식은 특히 고도화된 생성형 AI 프로덕션 환경에서 워크플로우가 미래에도 정상 작동하도록 보장하는 '버전 관리 및 아카이빙'의 핵심 기술로 자리 잡고 있음 [1, 6]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **모순:** 현재 가장 널리 쓰이는 방식은 Metadata가 포함된 PNG이나, 이는 보안 소프트웨어나 소셜 미디어 플랫폼에 의해 데이터가 손실되기 쉬워(stripped) 신뢰도가 낮음 [3]. +- **업데이트:** 단순 JSON 저장 방식에서 시스템 전체 상태를 패키징하는 `.cpack.zip` 기반의 아티팩트 배포로 패러다임이 전환되고 있음 [1]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfy-pack:** 모델 가중치의 SHA-256 해시를 사용하여 물리적 경로가 아닌 논리적 식별자로 모델을 관리하는 기능이 구현됨 [1, 2]. +- **.cpack.zip:** 워크플로우 JSON, 모델 해시, 노드 버전 정보를 통합 저장하기 위한 미래형 아티팩트 파일 규격으로 제안됨 [1]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (미래 지향적 기술로 제안되었으며 comfy-pack 등 일부 도구에서 구현 시작) +- **출처 신뢰도:** B (Official Documentation 및 전문 아키텍처 분석 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[ComfyUI Workflow JSON]] + - 연결 이유: 패키징의 핵심이 되는 직렬화 데이터 형식. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 기반 데이터 구조의 표준화된 저장 방식. +- [[Model Hashing]] + - 연결 이유: 패키지 내에서 자원을 식별하는 유일한 기술적 수단. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 파일명 불일치 문제를 해결하는 SHA-256 기반 매핑 원리. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 패키지 내 명시된 누락 노드를 탐지하고 복구하는 역할을 수행. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 의존성 자동 해결 및 설치 프로세스. + +### 심층 후속 질문 (Deeper Research Questions) +- `.cpack.zip` 패키지 내에서 모델 파일 자체를 포함하지 않고 해시만으로 대용량 가중치를 효율적으로 확보하는 원격 저장소 연동 프로토콜은 무엇인가? +- 커스텀 노드 버전 고정이 Git 커밋 해시를 사용하는 방식과 시맨틱 버저닝(Semantic Versioning)을 사용하는 방식 중 어느 것이 더 높은 호환성을 제공하는가? +- Workspace Packaging 기술이 Replicate나 Mystic과 같은 서버리스 API 환경에서 콜드 스타트(Cold Start) 시간에 미치는 영향은 어떠한가? +- 수백 개의 커스텀 노드가 얽힌 복잡한 워크플로우에서 모든 의존성을 누락 없이 패키징하기 위한 검증 알고리즘은 어떻게 설계되는가? +- 패키징된 아티팩트의 무결성을 검증하기 위해 SHA-256 외에 디지털 서명(Digital Signature)을 결합하는 보안 모델의 가능성은? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `comfy-pack` 도구를 사용하여 프로젝트별 모델 해시 리스트를 생성하고 관리함 [2]. +- **System Design:** CI/CD 파이프라인에서 워크플로우 변경 시마다 `.cpack.zip` 아티팩트를 자동 생성하여 배포함 [1]. +- **Operation / Maintenance:** 특정 시점에 생성된 이미지를 재현해야 할 경우, 해당 패키지를 로드하여 노드 및 모델의 환경을 즉각 복원함 [1]. +- **Learning Path:** 단순 JSON 저장을 넘어 모델 해시의 중요성과 의존성 관리의 원리를 학습하는 고도화 단계임 [6]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Retrieval-Augmented Generation (RAG) for Nodes]] + - 확장 방향: 정적으로 고정된 패키지를 넘어 실시간으로 최신 노드 정보를 탐색하고 반영하는 기술. +- [[Execution Model Inversion]] + - 확장 방향: 패키징된 거대 그래프 내에서 실제 출력에 필요한 노드만 선별하여 실행하는 최적화 기법. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. 기초 아키텍처 및 .cpack.zip 규격 정의 포함. \ No newline at end of file diff --git a/10_Wiki/Comfyui/exiftool.md b/10_Wiki/Comfyui/exiftool.md new file mode 100644 index 00000000..ad920491 --- /dev/null +++ b/10_Wiki/Comfyui/exiftool.md @@ -0,0 +1,58 @@ +--- +id: exiftool +title: "exiftool" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI.config"] +github_commit: "" +--- + +# [[exiftool]] + +## 🎯 한 줄 통찰 (One-line insight) +`exiftool`은 미디어 파일의 메타데이터 청크 내에 임베딩된 ComfyUI 워크플로 JSON 데이터를 추출, 삽입 및 복구하기 위한 표준 명령줄 유틸리티이다. [1], [2] + +## 🧠 핵심 개념 (Core concepts) +1. **메타데이터 추출 (Metadata Extraction):** PNG 파일의 `tEXt` 또는 `zTXt` 청크와 같은 바이너리 태그에서 직렬화된 워크플로 JSON을 독립된 파일로 분리한다. [3], [1] +2. **워크플로 복구 (Workflow Recovery):** 이미지 편집기(예: GIMP) 사용으로 인해 삭제된 메타데이터를 원본 파일에서 추출하여 재삽입함으로써 워크플로의 무결성을 유지한다. [4], [2] +3. **비표준 태그 정의 (Non-standard Tag Definition):** ComfyUI 워크플로 데이터는 비표준 태그에 저장되므로, 쓰기 작업을 수행할 때는 해당 태그를 허용하는 구성 설정이 필요하다. [2] + +## 🧩 추출된 패턴 (Extracted patterns) +- **바이너리 출력 패턴:** `-b` 플래그를 사용하여 특정 태그(`-workflow`)의 원시 데이터를 캡처하고 리다이렉션(`>`)을 통해 JSON 파일로 저장하는 전략을 사용한다. [1], [2] +- **설정 기반 삽입 패턴:** `exiftool`이 등록되지 않은 태그 쓰기를 거부하는 문제를 해결하기 위해 `%unreg` 지시어를 포함한 설정 파일을 참조하여 비표준 태그에 데이터를 주입한다. [2] + +## 📖 세부 내용 (Details) +`exiftool`은 ComfyUI 워크플로 관리 및 디지털 포렌식에서 핵심적인 역할을 수행하는 도구이다. [1] ComfyUI는 이미지 생성 시 `Save Image` 노드를 통해 워크플로(Frontend 포맷)와 프롬프트(API 포맷) 정보를 PNG 메타데이터에 주입하는데, `exiftool`은 이러한 바이너리 태그를 읽고 쓰는 데 최적화되어 있다. [5], [3], [1] + +구체적인 기술적 상세는 다음과 같다: +- **추출 메커니즘:** 대규모 이미지 저장소에서 드래그 앤 드롭 방식의 수동 추출이 비효율적일 때, `exiftool -b -workflow input.png > workflow.json` 명령을 통해 워크플로를 일괄적으로 격리할 수 있다. [1] 이는 이미지 내부의 직렬화된 JSON 데이터를 보존하면서 파일 시스템으로 인출하는 표준적인 방법이다. [1] +- **삽입 및 복사:** 단순한 추출을 넘어, 한 이미지의 워크플로를 다른 미디어(PNG, WebP, MP4 등)로 복사하거나 재삽입하는 것이 가능하다. [4] 단, 워크플로 태그는 표준 규격이 아니므로, `exiftool`은 기본적으로 이 태그에 대한 수정을 거부할 수 있다. 이를 해결하기 위해 사용자는 태그를 미등록(`%unreg`) 상태로 정의하는 별도의 설정 파일을 활용해야 한다. [2] +- **대안 도구와의 관계:** `Comfy_UI_prompt_extractor`나 `comfymeta` 등 특정 목적을 가진 CLI 및 UI 도구들이 존재하지만, `exiftool`은 가장 원형적인 유틸리티로서 워크플로 삽입 및 복사 기능을 구현하는 기반 기술로 언급된다. [2] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **데이터 휘발성:** `exiftool`의 성능과 관계없이, 메타데이터 자체가 취약하다는 점이 지적된다. 소셜 미디어 플랫폼이나 표준 이미지 압축 유틸리티는 파일 크기 절감 및 프라이버시 보호를 위해 워크플로 JSON이 포함된 비필수 메타데이터를 제거하는 경우가 많으므로, 원본 파일이 아닐 경우 `exiftool`을 통한 추출이 불가능할 수 있다. [6], [7], [3] + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI.config 활용:** 워크플로 데이터를 비표준 태그에 추가하기 위해 `exiftool` 설정 파일에서 해당 태그를 `%unreg`로 정의하여 사용한 사례가 보고되었다. [2] +- **CLI 워크플로 추출:** `exiftool -b -workflow input.png > workflow.json` 명령어를 통해 PNG 파일에서 워크플로 데이터를 직접 추출하여 JSON 파일로 변환하는 방식이 표준으로 사용된다. [1], [2] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 명령어와 설정 파일 적용 방식이 소스 내에 기술됨) +- **출처 신뢰도:** B (Official Documentation 및 GitHub Issue 기반 기술 명세) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Comfyui/workflow_api.json.md b/10_Wiki/Comfyui/workflow_api.json.md new file mode 100644 index 00000000..10aa6530 --- /dev/null +++ b/10_Wiki/Comfyui/workflow_api.json.md @@ -0,0 +1,67 @@ +--- +id: workflow_api.json +title: "workflow_api.json" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["API Format JSON", "Backend Format JSON", "Prompt JSON"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["/workflow/convert", "comfyui-workflow-to-api-converter-endpoint", "fofr/any-comfyui-workflow", "ComfyUI-to-Python-Extension"] +github_commit: "bc85382" +--- + +# [[workflow_api.json]] + +## 🎯 한 줄 통찰 (One-line insight) +`workflow_api.json`은 UI 메타데이터를 제거하고 노드 간의 기능적 연결성만을 추출하여 ComfyUI 백엔드 엔진이 즉시 실행할 수 있도록 최적화된 직렬화된 실행 그래프이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **백엔드/API 포맷 (Backend/API Format):** 시각적 요소(위치, 크기, 그룹 등)를 배제하고 서버 사이드 처리 및 프로그램 기반 자동화에 최적화된 포맷이다 [1, 3]. +- **평탄화된 그래프 (Flattened Execution Graph):** 링크가 별도의 연결 객체가 아닌 노드 입력 내부에 직접 참조(Origin Node ID 및 Output Slot) 형태로 포함된 구조이다 [1, 3, 4]. +- **개발자 모드 종속성 (Dev Mode Dependency):** 표준 내보내기 기능과 달리, 설정 메뉴에서 'Dev mode Options'를 활성화해야만 생성이 가능한 특수 포맷이다 [5-7]. +- **/prompt 엔드포인트 호환성:** ComfyUI 서버의 API 엔드포인트에 직접 전달하여 워크플로우를 실행하기 위한 표준 데이터 구조로 사용된다 [2, 8, 9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **포맷 분화 (Schema Bifurcation):** 사용자 상호작용을 위한 'Frontend JSON(workflow.json)'과 실행을 위한 'API JSON(workflow_api.json)'을 철저히 분리하여 운영 효율성을 극대화한다 [1, 2, 10]. +- **노드 식별 기반 접근:** 각 노드는 고유한 숫자형 키(String ID)로 식별되며, 이를 통해 외부 스크립트에서 특정 노드의 입력을 동적으로 수정할 수 있다 [11, 12]. +- **역방향 의존성 탐색 (Execution Model Inversion):** 엔진이 출력 노드(Save Image 등)로부터 역방향으로 탐색하여 최종 결과에 필요한 의존성 노드만 실행하는 구조를 지원한다 [13]. + +## 📖 세부 내용 (Details) +**데이터 구조 및 속성** +`workflow_api.json`은 루트 레벨의 키가 노드 ID(문자열)인 단일 JSON 객체 구조를 가진다 [14]. 각 노드 정의에는 `class_type`(노드 클래스 이름)과 `inputs`(위젯 값 및 타 노드 출력에 대한 연결 정보)가 포함되며, 선택적으로 `_meta` 필드가 존재할 수 있다 [11, 14]. 링크 표현 방식은 `[node_id, output_slot_index]` 형태의 배열로 입력 필드에 직접 삽입된다 [3, 15]. + +**생성 및 추출 프로세스** +1. **GUI 내보내기:** 설정 메뉴의 톱니바퀴 아이콘을 통해 'Enable Dev mode Options'를 활성화한 후, 제어판에 나타나는 'Save (API Format)' 또는 'Export (API)' 버튼을 사용하여 생성한다 [6, 7, 14, 16]. +2. **이미지 메타데이터 추출:** ComfyUI에서 생성된 PNG 파일의 `tEXt` 또는 `zTXt` 청크에는 워크플로우(Frontend)와 프롬프트(API) 데이터가 함께 저장되며, `exiftool`이나 전문 추출 도구를 통해 이를 복구할 수 있다 [17-20]. +3. **서버 사이드 변환:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면 일반 워크플로우 포맷을 실시간으로 API 포맷으로 변환하는 엔드포인트를 구축할 수 있다 [9, 21]. + +**프로그래밍적 활용** +이 포맷은 Python의 `json` 라이브러리를 통해 딕셔너리 형태로 로드되어 씨드(seed), 프롬프트 텍스트, 노이즈 강도 등의 파라미터를 동적으로 변경하는 데 사용된다 [11, 22]. `Replicate`, `Mystic`, `RunComfy` 등 클라우드 API 서비스는 이 포맷을 기반으로 워크플로우를 서버리스 함수나 컨테이너화된 서비스로 배포한다 [3, 23, 24]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정보 손실의 비가역성:** API 포맷을 다시 ComfyUI 캔버스로 불러올 경우, UI 메타데이터가 삭제되어 있기 때문에 노드들이 겹쳐 보이거나 그룹 정보가 사라진 '뼈대(skeleton)' 상태로 복원되는 한계가 있다 [9, 25]. +- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드의 클래스 타입 변경에 취약하다 [26, 27]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측의 자바스크립트 변환 로직을 파이썬으로 구현하여 `/workflow/convert` 엔드포인트를 제공함 [9, 28]. (Git Commit: `bc85382`) +- **ComfyUI-to-Python-Extension:** `workflow_api.json` 입력을 받아 실행 가능한 `.py` 스크립트로 변환하는 기능을 지원함 [29, 30]. +- **Mystic Pipeline Deployment:** `new_pipeline.py` 스크립트 내에서 API 포맷 JSON을 로드하여 입력 프롬프트를 주입하고 실행하는 템플릿 구조에 적용됨 [31, 32]. +- **Replicate fofr/any-comfyui-workflow:** API JSON 블롭을 입력받아 이미지/비디오를 생성하는 범용 워크플로우 모델의 핵심 입력 데이터로 활용됨 [23, 33]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견으로 검증 가능) +- **출처 신뢰도:** B (공식 문서 및 개발자 가이드 기반 합성) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/API Format (workflow_api.json).md b/10_Wiki/Topics/Comfyui/API Format (workflow_api.json).md new file mode 100644 index 00000000..b4c26dd8 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/API Format (workflow_api.json).md @@ -0,0 +1,107 @@ +--- +id: api-format-(workflow_api.json) +title: "API Format (workflow_api.json)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Backend Format", "API JSON"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "API"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint/README.md", "comfy_api_simplified", "ComfyUI-to-Python-Extension", "Mystic pipeline code", "Replicate any-comfyui-workflow"] +github_commit: "" +--- + +# [[API Format (workflow_api.json)]] + +## 🎯 한 줄 통찰 (One-line insight) +UI 메타데이터를 제거하고 실행에 필수적인 노드 로직과 데이터 흐름만을 압축하여 서버 측 프로그래밍 및 `/prompt` 엔드포인트 실행에 최적화된 데이터 규격 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **실행 최적화 (Execution-centric):** 시각적 배치 정보가 아닌 백엔드 엔진이 프롬프트를 실행하는 데 필요한 최소한의 논리 그래프만 포함함 [1, 3]. +- **UI 메타데이터 제거 (Metadata Stripping):** 노드 위치(pos), 크기(size), 그룹, 색상 등 사용자 인터페이스와 관련된 모든 정보를 삭제하여 파일 크기를 경량화함 [1, 2, 4]. +- **내장형 링크 참조 (Embedded Linkage):** 별도의 링크 객체 배열 대신 노드 입력(inputs) 내에 소스 노드 ID와 출력 슬롯 인덱스를 직접 포함하는 구조를 가짐 [1, 5]. +- **개발자 모드 의존성 (Dev Mode Dependency):** 표준 환경에서는 숨겨져 있으며, 설정에서 'Dev mode Options'를 활성화해야만 생성 및 내보내기가 가능함 [6-8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **노드 식별 패턴:** 각 노드는 숫자 문자열(예: "5", "6") 형태의 고유 키를 가지며, 이는 그래프 내에서 기능적 매핑을 위한 식별자로 사용됨 [3, 9, 10]. +- **데이터 연결 패턴:** 특정 노드의 입력 필드에 `[노드ID, 출력슬롯번호]` 형태의 리스트(예: `[11, 12]`)를 할당하여 노드 간의 데이터 흐름을 정의함 [5]. +- **직렬화 구조:** 루트 레벨에서 노드 ID를 키로 하고, 그 값으로 `class_type`과 `inputs`를 포함하는 단일 JSON 객체 구조를 유지함 [10, 13]. + +## 📖 세부 내용 (Details) +### 1. 포맷의 정의와 목적 +API 포맷(`workflow_api.json`)은 ComfyUI 백엔드 엔진이 직접 해석할 수 있는 **평탄화된 실행 그래프(flattened execution graph)**입니다 [6]. 주로 외부 애플리케이션 통합, 자동화 스크립트 실행, 서버리스 배포 환경에서 프롬프트를 큐(queue)에 추가할 때 사용됩니다 [1, 9]. + +### 2. 기술적 구성 요소 +- **구조적 차이:** 프론트엔드 포맷(`workflow.json`)이 Litegraph 표준을 따르며 시각적 가독성을 중시하는 반면, API 포맷은 백엔드 엔진의 `/prompt` 엔드포인트 사양에 맞춰 설계되었습니다 [1, 9]. +- **노드 정의:** 각 노드 객체는 해당 노드의 클래스 이름을 나타내는 `class_type`과 실제 파라미터 및 연결 정보를 담은 `inputs` 딕셔너리로 구성됩니다 [2, 10]. +- **연결 방식:** 프론트엔드 포맷의 `links` 배열이 제거되고, 모든 연결 정보가 `inputs` 내에 직접 주입됩니다. 예를 들어 CLIP 텍스트 인코딩 노드의 `clip` 입력값은 연결된 소스 노드 정보를 리스트 형태로 보유합니다 [5]. + +### 3. 생성 및 변환 프로세스 +- **수동 생성:** 설정 메뉴에서 'Enable Dev mode Options'를 체크한 후, 제어판에 나타나는 **'Save (API Format)'** 버튼을 통해 추출합니다 [7, 8, 14]. +- **프로그래밍 방식 변환:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면 클라이언트 측 자바스크립트 로직 없이 서버 측에서 직접 프론트엔드 형식을 API 형식으로 변환할 수 있습니다 [15, 16]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가역성 문제 (Fragility):** API 포맷은 실행에는 완벽하지만 시각적 정보가 없으므로, 이를 다시 UI로 드래그하여 로드하면 노드 배치가 깨지거나 그룹 정보가 사라진 '스켈레톤(skeleton)' 상태로 나타나 편집이 매우 어렵습니다 [17, 18]. +- **버전 호환성:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드 의존성이 있는 경우 실행 실패 가능성이 높습니다 [19, 20]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 프론트엔드 워크플로우를 서버 측에서 API 포맷으로 즉시 변환하는 `/workflow/convert` 엔드포인트를 제공합니다 [15, 21]. +- **deimos-deimos/comfy_api_simplified:** API 포맷 워크플로우를 로드하여 파이썬 딕셔너리로 다루고, 노드 제목(title)을 기준으로 파라미터를 수정하여 큐에 추가하는 기능을 구현합니다 [22, 23]. +- **Mystic & Replicate:** 사용자 워크플로우를 서버리스 API로 배포할 때, 실행의 기본 단위로 `workflow_api.json`을 요구하거나 내부적으로 이를 사용하여 추론을 수행합니다 [14, 24, 25]. +- **ComfyUI-to-Python-Extension:** API 포맷의 JSON을 입력받아 독립적으로 실행 가능한 파이썬 스크립트(`.py`)로 변환하는 기능을 수행합니다 [26, 27]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 오픈소스 프로젝트 및 플랫폼에서 핵심 규격으로 활용됨) +- **출처 신뢰도:** B (Official Documentation / GitHub Repository README 및 소스 코드 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Frontend Format (workflow.json)]] + - 연결 이유: API 포맷과 대칭되는 시각적 편집용 데이터 규격임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 데이터 직렬화 시 UI 정보와 실행 정보의 분리 설계 방식. +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: API 포맷은 노드와 링크로 구성된 추상화된 그래프 구조를 표현함. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 의존성 및 실행 순서 결정 원리. + +#### [구현/활용 도구] +- [[ComfyUI API]] + - 연결 이유: API 포맷은 `/prompt` 엔드포인트 호출 시 전달되는 페이로드의 핵심 데이터임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 실제 서버 통신 및 작업 큐잉 프로세스. +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: API JSON을 파이썬 코드로 변환하여 독립 실행 환경을 구축함. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터가 실제 실행 코드로 치환되는 매핑 원리. + +### 심층 후속 질문 (Deeper Research Questions) +- 왜 ComfyUI는 시각적 정보와 실행 정보를 하나의 JSON에 통합하지 않고 두 가지 포맷으로 분리하여 관리하는가? [1] +- API 포맷에서 노드 ID가 문자열 형태의 숫자로 고정될 때, 워크플로우 편집 시 ID 충돌이나 누락을 방지하는 메커니즘은 무엇인가? [3, 28] +- `comfyui-workflow-to-api-converter-endpoint`는 클라이언트 측의 자바스크립트 변환 로직을 어떻게 파이썬 서버 측 로직으로 완벽하게 이식했는가? [15] +- 대규모 워크플로우(예: 200KB 이상)를 API 포맷으로 호출할 때 성능 저하나 데이터 누락이 발생할 가능성은 없는가? [16] +- `object_info.json`에 정의된 노드 스키마와 API 포맷의 `inputs` 데이터 구조 사이의 유효성 검사 과정은 어떻게 이루어지는가? [13] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬의 `json` 라이브러리를 사용하여 API JSON을 로드하고, 특정 노드 ID의 `inputs` 값을 변경하여 동적 프롬프트를 생성할 수 있음 [10, 29]. +- **System Design:** 프론트엔드 수정을 최소화하면서 백엔드 자동화를 구축하기 위해 서버 측에서 변환 엔드포인트를 활용하는 캐싱 전략을 수립할 수 있음 [17]. +- **Operation / Maintenance:** 커스텀 노드 업데이트 시 API 포맷 내의 `class_type` 명칭이 변경되지 않았는지 확인하여 서비스 중단을 방지해야 함 [19]. +- **Learning Path:** 노드 기반 UI에 익숙해진 후, 개발자 모드를 통해 추출된 API JSON의 구조를 분석하여 프로그래밍 방식의 자동화 단계로 진입함 [6]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: API JSON 내의 모델 파일 이름 불일치 문제를 해결하기 위한 고유 식별 기술 조사 [30]. +- [[Serverless Deployment]] + - 확장 방향: API 포맷을 클라우드 환경(Replicate, Mystic)에 배포하여 확장성 있는 AI 서비스를 구축하는 방법 [14, 31]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/API Format.md b/10_Wiki/Topics/Comfyui/API Format.md new file mode 100644 index 00000000..50e05a63 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/API Format.md @@ -0,0 +1,103 @@ +--- +id: api-format +title: "API Format" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["API JSON", "workflow_api.json", "Backend Format"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "API", "JSON", "Automation"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint", "deimos-deimos/comfy_api_simplified", "pydn/ComfyUI-to-Python-Extension"] +github_commit: "bc85382" +--- + +# [[API Format]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI API 포맷은 시각적 메타데이터를 제거하고 노드 간의 논리적 연결과 입력값만을 보존하여 서버 측 실행 및 프로그래밍 방식의 자동화에 최적화된 경량화된 실행 그래프이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **실행 그래프 (Execution Graph):** UI 좌표, 노드 크기, 그룹화 정보 등 시각적 요소를 배제하고 백엔드 엔진이 프롬프트를 실행하는 데 필요한 순수 논리 구조만 포함한다 [1, 3, 4]. +- **임베디드 링크 (Embedded Links):** 별도의 링크 객체 배열을 사용하는 대신, 노드의 입력 필드(`inputs`) 내에 소스 노드 ID와 출력 슬롯 번호를 직접 참조(예: `[5, 6]`)하여 연결을 정의한다 [1, 2, 7]. +- **기능적 키 매핑 (Functional Key Mapping):** JSON 객체의 최상위 키가 노드 ID(문자열)이며, 각 값은 `class_type`과 `inputs`를 포함하는 딕셔너리 구조를 가진다 [8-10]. +- **개발자 모드 활성화 (Dev Mode Requirement):** 일반적인 저장 방식과 달리 ComfyUI 설정에서 'Enable Dev mode Options'를 활성화해야만 내보낼 수 있는 특수 포맷이다 [11-14]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **UI/백엔드 이원화 패턴:** 사용자 인터페이스용 `workflow.json`과 실행 전용 `workflow_api.json`을 분리하여 편집 효율성과 실행 속도를 동시에 확보한다 [1, 2, 15]. +- **메타데이터 캡슐화:** PNG 이미지의 `tEXt` 또는 `zTXt` 청크에 API 포맷(prompt) 데이터를 포함시켜 이미지 자체가 실행 가능한 소스 코드 역할을 하도록 설계한다 [16, 17]. +- **직접 딕셔너리 조작 패턴:** 개발자가 JSON을 로드하여 특정 노드 ID의 `inputs` 값을 파이썬 등으로 수정 후 `/prompt` 엔드포인트에 전송하는 동적 제어 방식을 지원한다 [8, 10, 18]. + +## 📖 세부 내용 (Details) +ComfyUI의 API 포맷은 주로 `workflow_api.json` 파일로 알려져 있으며, 서버리스 API 호출이나 외부 애플리케이션 통합 시 핵심적인 역할을 한다 [2, 15]. 이 포맷은 Litegraph 표준을 따르는 프론트엔드 포맷과 달리, 백엔드 엔진이 즉시 해석할 수 있도록 평탄화(Flattened)된 구조를 가진다 [1, 11]. + +구조적으로 API 포맷은 노드 ID를 키로 사용하는 단일 JSON 객체이다 [9]. 각 노드 정의에는 해당 노드의 클래스 이름인 `class_type`과 위젯 값 및 링크 정보를 포함하는 `inputs` 딕셔너리가 들어간다 [3, 8]. 예를 들어, `CLIPTextEncode` 노드의 경우 텍스트 입력값과 함께 연결된 CLIP 모델의 노드 정보를 `[노드ID, 슬롯번호]` 형태의 배열로 보유한다 [7, 10]. + +이 포맷은 데이터 용량이 작고 효율적이지만, 다시 ComfyUI 인터페이스로 드래그했을 때 시각적 레이아웃 정보가 없어 노드들이 겹치거나 연결 구조를 파악하기 힘든 '스켈레톤(Skeleton)' 상태로 로드된다는 특징이 있다 [19, 20]. 따라서 실무에서는 시각적 편집용 원본 워크플로를 별도로 보관하는 것이 권장된다 [20]. 또한, 최근에는 시각적 포맷을 API 포맷으로 실시간 변환해주는 서버측 엔드포인트 도구들이 개발되어 이 단점을 보완하고 있다 [19, 21]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가독성 vs 실행력:** API 포맷은 인간이 읽기에 간결하지만, 시각적 정보가 결여되어 있어 복잡한 워크플로를 이 포맷만으로 수동 편집하기에는 한계가 있다 [17, 20]. +- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 구버전의 JSON API 포맷이 최신 서버 환경에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [22]. +- **데이터 유실 위험:** 표준 이미지 편집기나 소셜 미디어를 거칠 경우 PNG 메타데이터에 포함된 API 포맷 정보가 삭제될 수 있어 전송 시 주의가 필요하다 [16]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 프론트엔드 워크플로를 API 포맷으로 변환하는 서버측 `/workflow/convert` 엔드포인트를 구현하였다 [19]. + - **Git 커밋:** `bc85382` (콤보 위젯 값의 대소문자 정규화 수정 포함) [23, 24]. +- **deimos-deimos/comfy_api_simplified:** 노드 제목(Title)을 기준으로 API 포맷의 파라미터를 수정하고 큐에 등록하는 파이썬 래퍼 기능을 제공한다 [25-27]. +- **pydn/ComfyUI-to-Python-Extension:** 저장된 API 포맷 JSON을 독립 실행 가능한 `.py` 스크립트로 변환하는 CLI 기능을 포함한다 [28-30]. +- **Mystic (Pipeline AI):** 사용자의 API JSON을 파이썬 엔드포인트 내에 주입하여 서버리스 환경에서 실행하는 템플릿을 제공한다 [14, 31]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual +- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 코드 기반) [23, 32] +- **중복 검사 결과:** 신규 생성 + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Frontend Format]] + - 연결 이유: API 포맷과 대조되는 시각적 편집용 데이터 구조임. [1, 2] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메타데이터 분리 전략 및 Litegraph 표준의 한계. [1, 33] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI 워크플로가 직렬화되는 근본적인 논리 구조임. [34] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 실행 순서와 데이터 흐름 제어 원리. [34, 35] + +#### [구현/활용 도구] +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: API JSON을 파이썬 코드로 변환하는 직접적인 도구임. [28] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 객체가 실제 파이썬 함수 호출로 매핑되는 과정. [29, 36] +- [[ComfyUI Manager]] + - 연결 이유: API 포맷 로드 시 발생하는 커스텀 노드 누락 문제를 해결하는 필수 도구임. [37, 38] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 종속성 관리 및 `class_type` 기반의 노드 복구 메커니즘. [37, 39] + +### 심층 후속 질문 (Deeper Research Questions) +- API 포맷에서 노드 ID가 단순한 숫자 문자열을 넘어 기능적 키(Functional Key)로 작동할 때, 대규모 워크플로에서 ID 충돌을 방지하는 내부 메커니즘은 무엇인가? [1, 2] +- `workflow_api.json`에 포함된 `_meta` 필드는 실행 엔진에서 어떤 구체적인 역할을 수행하며, 필수 요소인가? [9] +- 서브그래프(Subgraph)가 중첩된 워크플로를 API 포맷으로 내보낼 때, 내부 링크 ID와 외부 링크 ID의 충돌을 처리하는 알고리즘은 어떻게 설계되어 있는가? [40] +- API 포맷 내의 `inputs` 필드에서 위젯 값(`widgets_values`)과 동적 링크 연결을 구분하여 처리하는 구문 분석 로직은 무엇인가? [7, 41] +- `exiftool`과 같은 외부 CLI 도구를 사용하여 PNG에서 API JSON을 추출할 때, 메타데이터 손상을 복구하거나 검증할 수 있는 표준 스키마가 존재하는가? [42, 43] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬 `json` 라이브러리를 사용하여 API JSON 파일을 로드하고, 특정 노드 ID의 입력값을 수정한 뒤 서버의 `/prompt` 엔드포인트로 POST 요청을 보내 자동화를 구현한다 [8, 10, 18]. +- **System Design:** 프론트엔드 편집 도구와 백엔드 실행기를 분리하여, 사용자는 웹 UI에서 편집하고 실제 운영 환경에서는 경량화된 API JSON만 사용하여 리소스를 최적화한다 [1, 44]. +- **Operation / Maintenance:** API JSON에는 모델 체크포인트의 이름이 하드코딩되므로, 서버 간 모델 공유 시 파일명 불일치 문제를 해결하기 위해 모델 해싱(SHA-256) 기술과 함께 운용한다 [45, 46]. +- **Learning Path:** 먼저 GUI에서 워크플로를 완성한 후, 개발자 모드를 통해 API 포맷을 내보내고 그 구조를 분석하여 프로그래밍 방식의 제어 단계로 넘어가는 것이 표준 학습 경로이다 [14, 47]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Node Definitions]] + - 확장 방향: API 포맷 내 `class_type`이 참조하는 각 노드의 입력/출력 타입 정의 연구. [43] +- [[Execution Model Inversion]] + - 확장 방향: API JSON 전체 중 필요한 노드만 선택적으로 실행하는 백엔드 최적화 원리 이해. [32, 48] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. 기반 소스 18개 종합 분석 완료. [1-186] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/API JSON.md b/10_Wiki/Topics/Comfyui/API JSON.md new file mode 100644 index 00000000..16f5ffd1 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/API JSON.md @@ -0,0 +1,67 @@ +--- +id: api-json +title: "API JSON" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["workflow_api.json", "Backend Format", "API Format"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI-WorkflowGenerator", "comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "comfy_api_simplified"] +github_commit: "" +--- + +# [[API JSON]] + +## 🎯 한 줄 통찰 (One-line insight) +API JSON은 ComfyUI의 시각적 인터페이스 요소를 배제하고 순수 실행 로직만을 추상화하여 백엔드 엔진의 프로그래밍적 제어와 자동화를 가능케 하는 핵심 데이터 규격이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **백엔드 실행 그래프 (Backend Execution Graph):** 노드 위치, 크기, 그룹 등 UI 관련 메타데이터를 제거하고 실행에 필요한 노드 타입과 입력값, 연결 관계만을 남긴 콤팩트한 형식이다 [1, 3]. +2. **임베딩된 참조 구조 (Reference-based Linking):** 별도의 링크 배열을 사용하는 프론트엔드 형식과 달리, 노드 입력 필드 내에 직접 소스 노드 ID와 출력 슬롯 인덱스를 배열 형태로 기술한다 [1, 3, 4]. +3. **개발자 모드 (Dev Mode) 활성화:** 표준 ComfyUI 환경에서 API JSON을 추출하기 위해 설정(Settings) 메뉴에서 반드시 선행 활성화해야 하는 옵션이다 [5-7]. +4. **프로그래밍적 엔드포인트 호환성:** `/prompt` 엔드포인트에 페이로드로 직접 전달되어 서버 측에서 즉시 실행될 수 있도록 최적화된 구조를 가진다 [8-10]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Bifurcation (이원화) 저장 패턴:** 사용자의 시각적 편집을 위한 `workflow.json`과 기계적 실행을 위한 `workflow_api.json`을 분리하여 각 용도에 최적화된 성능과 관리 편의성을 제공한다 [1, 8, 11]. +- **Metadata Chunk 중복 저장:** 생성된 PNG 파일의 tEXt 또는 zTXt 청크에 프론트엔드 워크플로우와 API 프롬프트를 모두 저장하여, 이미지 하나로 시각적 복원과 API 실행을 동시에 보장한다 [12, 13]. +- **Execution Model Inversion:** 엔진이 출력 노드에서부터 역방향으로 그래프를 탐색하여 결과 생성에 필요한 노드만 선별 실행함으로써 데이터 처리 효율을 극대화한다 [14]. + +## 📖 세부 내용 (Details) +### 1. 기술적 구조 및 사양 +API JSON은 루트 키가 **노드 ID(문자열)**로 구성된 단일 JSON 객체 구조를 취한다 [15, 16]. 각 노드 객체는 클래스 이름인 `class_type`과 사용자 입력 및 연결 정보를 포함하는 `inputs` 딕셔너리로 이루어진다 [3, 17]. 노드 간의 연결은 `inputs` 내에 `[노드_ID, 출력_슬롯_인덱스]` 형식의 배열로 표현되어 그래프 구조를 형성한다 [4, 18]. 이는 Litegraph 표준을 따르는 프론트엔드 포맷보다 훨씬 파일 크기가 작고 처리가 빠르다 [8]. + +### 2. 수동 생성 및 추출 방법 +가장 기본적인 생성 방법은 ComfyUI 웹 인터페이스를 이용하는 것이다. 설정 메뉴에서 **"Enable Dev mode Options"**를 체크하면 컨트롤 패널에 **"Save (API Format)"** 버튼이 노출되며, 이를 통해 즉시 다운로드 가능하다 [5, 6, 19, 20]. 또한, 이미 생성된 PNG 이미지에서 `exiftool`과 같은 CLI 도구를 사용해 메타데이터에 숨겨진 API JSON(Prompt) 데이터를 추출할 수도 있다 [21, 22]. + +### 3. 자동화 및 프로그래밍적 생성 +- **LLM 기반 생성:** `ComfyUI-WorkflowGenerator`는 자연어 지시를 해석하여 논리적 합성, 의미론적 검증, 그래프 컴파일 단계를 거쳐 실행 가능한 API JSON을 자동으로 구축한다 [23-25]. +- **동적 변환:** `comfyui-workflow-to-api-converter-endpoint` 커스텀 노드는 서버측에서 `/workflow/convert` 엔드포인트를 제공하여, 시각적 정보가 포함된 표준 JSON을 실시간으로 API 포맷으로 변환해준다 [10, 26, 27]. +- **Python 래퍼 및 확장:** `comfy_api_simplified`나 `ComfyUI-to-Python-Extension`은 API JSON을 로드하여 특정 노드의 파라미터(시드, 프롬프트 등)를 동적으로 수정한 후 큐잉하거나, 전체 워크플로우를 독립 실행형 Python 스크립트로 변환하는 기능을 제공한다 [28-30]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 제한:** ComfyUI는 업데이트가 매우 잦아 이전 버전에서 생성된 API JSON이 최신 버전의 노드 레지스트리나 스키마와 충돌하여 작동하지 않을 가능성이 상존한다 [31]. +- **데이터 파괴 위험:** 표준 이미지 편집기나 소셜 미디어 플랫폼을 통해 이미지를 공유할 경우, API JSON이 포함된 메타데이터 청크가 자동으로 삭제되어 워크플로우 정보가 영구 손실될 수 있다 [12, 31]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Mystic Python SDK 연동:** `workflow_api.json`을 사용하여 텍스트-투-비디오 워크플로우를 서버리스 엔드포인트로 배포하며, Python 스크립트에서 입력 프롬프트를 동적으로 주입한다 [32, 33]. +- **Replicate API 호출:** `fofr/any-comfyui-workflow` 모델을 통해 API JSON을 직접 입력받아 원격 GPU에서 워크플로우를 실행한다 [7, 34]. +- **ComfyUI-to-Python-Extension:** CLI를 통해 `workflow_api.json`을 입력 파일로 받아 실행 가능한 `.py` 스크립트를 생성하며, 이때 `--input_file` 플래그로 API JSON 경로를 지정한다 [35, 36]. +- **Lou@blog Python 코드:** `urllib`와 `websocket`을 사용하여 API JSON의 특정 노드 ID(예: #37 TextInput)의 `inputs.text` 값을 교체한 후 서버에 요청을 보내는 구조를 구현하였다 [16, 37]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견됨에 따라 추후 applied/validated 승격 가능) +- **출처 신뢰도:** B (공식 문서 및 실제 오픈소스 프로젝트의 README/구현 코드를 바탕으로 함) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Comfy CLI.md b/10_Wiki/Topics/Comfyui/Comfy CLI.md new file mode 100644 index 00000000..ebe6a3ae --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Comfy CLI.md @@ -0,0 +1,91 @@ +--- +id: comfy-cli +title: "Comfy CLI" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["comfy-cli"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["Comfy-Org/comfy-cli Issue #341"] +github_commit: "" +--- + +# [[Comfy CLI]] + +## 🎯 한 줄 통찰 (One-line insight) +GUI의 한계를 넘어 터미널 환경에서 워크플로우의 대량 관리, 메타데이터 복구 및 자동화된 실행을 지원하는 ComfyUI 생태계의 통합 명령줄 인터페이스 도구이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **헤드리스 자동화 (Headless Automation):** 웹 인터페이스 없이 명령줄에서 직접 워크플로우를 관리하고 실행할 수 있는 환경을 제공한다 [3, 4]. +2. **메타데이터 가공 및 복구:** 이미지 파일(PNG, WebP)이나 영상 파일(MP4)에 포함된 워크플로우 JSON을 추출, 삽입, 복사하는 기능을 통해 데이터의 영속성을 보장한다 [2]. +3. **배치 처리 (Batch Processing):** 대규모 이미지 저장소에서 워크플로우를 일괄적으로 추출하거나 관리하기 위한 효율적인 수단을 제공한다 [1, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **메타데이터 분리 전략:** `exiftool`과 같은 하위 수준 도구를 호출하거나 전용 CLI 라이브러리를 통해 이미지의 `tEXt` 또는 `zTXt` 청크에서 JSON 데이터를 격리하는 패턴을 사용한다 [1, 5, 6]. +- **통합 지원 구조:** 개별적으로 흩어진 `Workflow Extractor`, `Python API Converter` 등의 기능을 하나의 통합된 CLI(comfy-cli)로 수렴하여 관리 효율성을 극대화한다 [2]. + +## 📖 세부 내용 (Details) +Comfy CLI는 ComfyUI의 강력한 노드 기반 시스템을 터미널 및 프로그래밍 환경으로 확장하기 위해 설계되었습니다. + +- **워크플로우 추출 및 관리:** CLI 도구는 특히 대량의 이미지 파일에서 워크플로우를 복구하는 데 유용합니다. 사용자는 `exiftool -b -workflow input.png > workflow.json`과 같은 명령을 통해 시각적 메타데이터를 JSON 파일로 추출할 수 있으며, `Comfy_UI_prompt_extractor`와 같은 전문 CLI 도구는 긍정적 프롬프트, API 그래프, UI 레이아웃을 분리하여 생성하는 기능을 제공합니다 [1, 5]. +- **이미지 메타데이터 복원 기능:** GIMP와 같은 표준 이미지 편집기나 소셜 미디어 플랫폼은 파일 크기 최적화를 위해 메타데이터를 삭제하는 경우가 많습니다. CLI는 유실된 워크플로우 데이터를 다시 이미지에 삽입(Insert)하거나 다른 이미지로 복사(Copy)하는 기능을 지원하여 워크플로우의 이동성을 유지합니다 [2, 5, 6]. +- **워크플로우 전환 지원:** CLI 환경에서 [[Workflow JSON (Frontend Format)]]을 [[Workflow API JSON (Backend Format)]]으로 변환하거나, 아예 독립적으로 실행 가능한 Python 스크립트로 내보내는 기능을 결합하여 외부 애플리케이션과의 연동을 용이하게 합니다 [7, 8]. +- **설치 및 시스템 관리:** Comfy CLI는 ComfyUI 설치 가이드의 주요 항목으로 포함되어 있으며, 시스템 상태 확인(GPU VRAM, Python 버전 등) 및 노드 카탈로그 업데이트를 위한 도구로도 활용됩니다 [9-11]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **메타데이터 손상 주의:** 수동 드래그 앤 드롭 방식과 달리 CLI 도구는 대량 처리에 유리하지만, 압축 소프트웨어나 네트워크 전송 과정에서 메타데이터가 영구적으로 제거된 경우에는 CLI로도 복구가 불가능하다는 한계가 소스에서 지적됩니다 [6, 12]. +- **기능 통합 진행형:** 현재 `comfy-cli`는 이미지에서 워크플로우를 추출, 삽입, 복사하는 기능을 포함하도록 개발 및 제안 단계에 있으며, 이는 기존의 여러 개별 CLI 도구들을 대체하거나 통합하려는 시도로 분석됩니다 [2, 5]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Comfy-Org/comfy-cli Issue #341:** 이미지, WebP, MP4 등 지원되는 모든 매체에서 워크플로우를 추출, 삽입, 복사할 수 있는 기능을 `comfy-cli`에 포함시키기 위한 기능 제안 및 논의가 진행되었습니다 [2, 13]. +- **배치 워크플로우 복구:** 대규모 AI 아트 라이브러리에서 디지털 포렌식 기법을 사용하여 생성 기술을 유지하고 검색 가능한 라이브러리를 구축하는 데 활용되었습니다 [1]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 및 개발자 커뮤니티의 기능 제안을 기반으로 작성됨) +- **출처 신뢰도:** B (Official Documentation / GitHub Issue Discussion) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처 및 기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: CLI를 통해 JSON 워크플로우를 생성 및 관리하는 상위 주제임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: GUI 이외의 워크플로우 획득 경로. +- [[Workflow API JSON (Backend Format)]] + - 연결 이유: CLI 도구가 최종적으로 실행을 위해 변환하거나 추출해야 하는 타겟 형식임. + +#### [구현 및 활용 도구] +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: CLI 명령을 통해 워크플로우를 Python 코드로 변환하는 유사한 터미널 기반 도구임. +- [[ComfyUI-Manager]] + - 연결 이유: CLI에서 누락된 커스텀 노드를 감지하고 종속성을 해결할 때 상호 보완적으로 작동함. + +### 심층 후속 질문 (Deeper Research Questions) +- `comfy-cli`가 이미지 외에 영상(MP4) 메타데이터에서 워크플로우를 추출할 때 사용하는 구체적인 태그 구조는 무엇인가? +- `exiftool`을 이용한 수동 추출 방식과 `comfy-cli` 전용 명령어를 통한 추출 방식 사이의 데이터 무결성 차이는 존재하는가? +- CLI 환경에서 [[Workflow JSON (Frontend Format)]]을 거치지 않고 직접 API 전용 JSON을 이미지에 삽입하는 것이 가능한가? +- 대규모 배치 처리 시 노드 ID의 충돌이나 종속성 문제를 CLI에서 어떻게 자동으로 해결하는가? +- CLI 도구가 외부 이미지 편집기(GIMP 등)에 의해 삭제된 메타데이터를 복구하기 위한 'Shadow Backup' 전략을 가지고 있는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `comfyui-to-python` CLI를 사용하여 반복적인 생성 작업을 자동화하는 쉘 스크립트 작성 [8]. +- **System Design:** 서버 사이드에서 사용자로부터 업로드된 이미지를 받아 워크플로우를 자동 추출하여 데이터베이스화하는 파이프라인 설계 [1, 2]. +- **Operation / Maintenance:** ComfyUI 업데이트 시 `UpdateNodeCatalog` CLI 명령을 통해 노드 호환성을 일괄 점검 [10]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Metadata Extraction]] + - 확장 방향: AI 생성 이미지 내에 숨겨진 프롬프트 및 파라미터 데이터 보호 및 분석 기술. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source references 6, 33, 136, 170, 171, 182) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Comfy GPT.md b/10_Wiki/Topics/Comfyui/Comfy GPT.md new file mode 100644 index 00000000..58de13e2 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Comfy GPT.md @@ -0,0 +1,102 @@ +--- +id: comfy-gpt +title: "Comfy GPT" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyGPT", "ComfyUI-WorkflowGenerator"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "LLM", "Automation"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["DanielPFlorian/ComfyUI-WorkflowGenerator", "xiatianzs/resources", "ComfyUI/models/LLM/"] +github_commit: "82df278" +--- + +# [[Comfy GPT]] + +## 🎯 한 줄 통찰 (One-line insight) +Comfy GPT는 자연어 설명을 실행 가능한 ComfyUI 노드 그래프(JSON)로 변환하여 '비주얼 프로그래밍'을 '대화형 프로그래밍'으로 격상시키는 다단계 AI 합성 프레임워크이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **자연어 기반 워크플로우 생성 (Natural Language Generation):** 사용자의 의도(예: "SDXL을 사용한 텍스트-이미지 워크플로우 생성")를 해석하여 복잡한 노드 연결 구조를 자동 생성한다 [2]. +2. **3단계 합성 파이프라인 (Three-stage Pipeline):** 논리적 구조 생성(Generator), 노드 이름 및 호환성 검증(Validator), 최종 실행 파일 컴파일(Builder)의 단계적 공정을 거친다 [3, 4]. +3. **의미론적 노드 검증 (Semantic Node Validation):** 생성된 노드가 로컬 환경에 존재하는지 확인하고, 임베딩 모델을 통해 가장 유사한 실제 노드로 자동 교정한다 [4-6]. +4. **도메인 특화 미세 조정 모델 (Fine-tuned Models):** ComfyUI의 내부 노드 레지스트리와 스키마 사양에 최적화된 LLM(예: Qwen2.5-14B)을 중추로 활용한다 [1, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **구조적 논리 합성 패턴:** 자연어 입력을 바로 JSON으로 변환하는 것이 아니라, 중간 단계의 논리적 그래프 구조를 먼저 형성한 후 컴파일한다 [4, 6]. +- **로컬 환경 동기화 패턴:** `UpdateNodeCatalog` 노드를 통해 사용자의 로컬 ComfyUI에 설치된 네이티브 및 커스텀 노드를 스캔하여 검증 기준(Catalog)을 최신화한다 [7, 8]. +- **하이브리드 검증 전략:** 속도를 위한 '의미론적 검색' 모드와 정확도를 위한 'LLM 정밀 교정' 모드를 선택적으로 사용하여 유효성을 확보한다 [6]. + +## 📖 세부 내용 (Details) +Comfy GPT는 **"ComfyGPT: A Self-Optimizing Multi-Agent System for Comprehensive ComfyUI Workflow Generation"** 연구에 기반한 기술적 구현체이다 [4]. 이 시스템은 전문적인 노드 지식이 없는 사용자도 대화를 통해 복잡한 생성 AI 파이프라인을 구축할 수 있게 돕는다 [2]. + +- **작동 메커니즘:** + - **Generator:** Qwen2.5-14B 기반 모델이 입력된 자연어를 분석하여 노드 간의 데이터 흐름(DAG)을 정의하는 논리적 JSON 문자열을 출력한다 [5, 6]. + - **NodeValidator:** 생성된 노드 이름이 실제 설치된 노드 클래스 명칭과 일치하는지 검사한다 [6]. 일치하지 않을 경우 `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` 모델을 사용한 의미론적 검색으로 가장 적합한 노드를 제안하거나, LLM이 문맥을 통해 이름을 수정한다 [5, 6]. + - **WorkflowBuilder:** 최종 검증된 구조를 ComfyUI 실행 엔진이 이해할 수 있는 표준 [[Workflow JSON]] v1.0 규격으로 변환하고 파일로 저장한다 [3, 8, 9]. +- **기술적 특징:** GGUF 양자화 모델(q8_0)을 지원하여 효율적인 VRAM 관리가 가능하며, CUDA 및 Metal 환경에서 가속화된 추론을 제공한다 [5, 10, 11]. 또한, JSON 파일은 생성 의도와 실행 로직 사이의 '중간 바이트코드' 역할을 수행하게 된다 [3]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정적 모델의 한계:** 미세 조정된 모델은 훈련 데이터 컷오프 시점 이후에 출시된 새로운 커스텀 노드나 아키텍처에 대해서는 기본적으로 알지 못하는 '동결된(Frozen)' 상태라는 점이 한계로 지적된다 [12, 13]. +- **할루시네이션 관리:** 모델이 존재하지 않는 노드 연결을 생성할 위험이 있으므로, 향후에는 정적 미세 조성을 넘어선 실시간 적응형 아키텍처로의 진화가 필요하다고 명시되어 있다 [13, 14]. + +## 🛠️ 적용 사례 (Applied in summary) +- **GitHub 프로젝트:** `DanielPFlorian/ComfyUI-WorkflowGenerator`가 ComfyGPT 연구를 로컬 노드 수트로 구현한 독립적 사례로 확인된다 [2, 15]. +- **Git 커밋 기록:** `82df278` 커밋에서 드롭다운의 중복 모델 노출 문제가 수정되었으며, `config`, `generators`, `nodes` 등의 디렉토리 구조로 관리된다 [15]. +- **모델 경로 사양:** 사용자는 GGUF 모델과 토크나이저를 `ComfyUI/models/LLM/` 경로에 배치하여 시스템을 구동한다 [7]. +- **저장 로직:** 생성된 워크플로우 JSON은 기본적으로 `comfyUI/output` 폴더에 저장되어 즉시 로드하거나 공유할 수 있다 [16]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 GitHub 프로젝트와 연구 논문이 존재하며 구현 가이드가 소스에 포함됨) [2, 4] +- **출처 신뢰도:** B (Official Documentation / GitHub Repository README via NotebookLM) [2] +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: Comfy GPT가 해결하고자 하는 근본적인 루트 주제. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 수동 생성 방식과 자동 생성 방식의 차이점. +- [[Workflow JSON]] + - 연결 이유: Comfy GPT 파이프라인의 최종 출력물 규격. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: v1.0 스키마 제약 사항 준수의 중요성. + +#### [구현/활용 도구] +- [[Workflow API JSON]] + - 연결 이유: 생성된 JSON이 API 호출에 사용될 때의 스트림라인 포맷. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각 정보가 제거된 실행 전용 그래프 구조. +- [[ComfyUI Manager]] + - 연결 이유: 생성된 워크플로우의 커스텀 노드 의존성을 해결하는 핵심 도구. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 'Red Nodes' 오류 발생 시의 복구 메커니즘. + +### 심층 후속 질문 (Deeper Research Questions) +- 훈련 데이터 컷오프 이후 출시된 최신 커스텀 노드에 대한 할루시네이션을 `NodeValidator`가 어느 정도 수준까지 교정할 수 있는가? [12] +- `UpdateNodeCatalog` 노드가 로컬의 `INPUT_TYPES`를 스캔하여 LLM에게 전달하는 컨텍스트 주입 방식은 구체적으로 어떻게 설계되어 있는가? [8] +- GGUF 양자화 모델 사용 시, q8_0와 q4_0 간의 워크플로우 논리 합성 정확도 차이가 유의미하게 발생하는가? [10] +- 3단계 파이프라인 중 `Generator`가 생성한 '논리적 그래프'와 최종 '실행용 JSON' 사이의 데이터 유실 가능성은 없는가? [6, 8] +- LLM 기반 생성 시 복잡한 `ControlNet`의 다중 레이어 연결이나 `IPAdapter` 설정의 세밀한 파라미터 제어가 가능한가? [2, 16] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `Workflow Generator Pipeline` 노드를 추가하고 자연어 지침을 입력하여 즉시 실행 가능한 그래프를 생성함 [7, 16]. +- **System Design:** 사용자의 로컬 환경에 맞춰진 `Node Catalog`를 기반으로 맞춤형 유효성 검사 루프를 구축함 [8]. +- **Operation / Maintenance:** 새로운 커스텀 노드 설치 후 반드시 `Update Node Catalog`를 실행하여 시스템의 지식 베이스를 동기화해야 함 [17]. +- **Learning Path:** 복잡한 노드 이름을 외우는 대신, 자연어로 기능을 설명하며 워크플로우 구축 원리를 학습하는 도구로 활용 가능 [2, 18]. + +### 인접 주변 주제 (Adjacent Topics) +- [[ComfyUI Custom Scripts]] + - 확장 방향: 자동 생성된 워크플로우를 시각적 이미지(PNG/SVG)로 내보내어 관리하는 방법 연구 [19, 20]. +- [[Executing ComfyUI Workflows as Standalone Scripts]] + - 확장 방향: LLM이 생성한 JSON을 서버리스 환경에서 즉시 Python 스크립트로 실행하는 자동화 파이프라인 구축 [21, 22]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [23] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI API.md b/10_Wiki/Topics/Comfyui/ComfyUI API.md new file mode 100644 index 00000000..3beb658f --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI API.md @@ -0,0 +1,112 @@ +--- +id: comfyui-api +title: "ComfyUI API" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["API Format", "workflow_api.json"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "automation", "API"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: + - "comfyui-workflow-to-api-converter-endpoint (bc85382)" + - "ComfyUI-WorkflowGenerator (82df278)" + - "ComfyUI-to-Python-Extension (6cdcc23)" +github_commit: "" +--- + +# [[ComfyUI API]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI API는 노드 기반의 비주얼 워크플로를 **실행 가능한 데이터 구조(JSON)**로 직렬화하여, 창의적 프로세스를 자동화된 프로덕션 파이프라인으로 전환하는 핵심 인터페이스이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **API Format (workflow_api.json):** 사용자 인터페이스(UI) 메타데이터(노드 위치, 크기, 그룹 등)를 제거하고 오직 백엔드 엔진의 실행에 필요한 노드 유형과 입력 연결 정보만을 포함하는 간소화된 그래프 포맷이다 [3-5]. +- **Dev Mode Options:** API 포맷으로 워크플로를 내보내기 위해 반드시 활성화해야 하는 설정으로, 활성화 시 'Save (API format)' 버튼이 노출된다 [6-8]. +- **Serialization & Mapping:** 노드망을 JSON 형식의 딕셔너리로 변환하며, 각 노드는 고유한 numeric ID(예: "37")를 키로 사용하여 `class_type`과 `inputs` 값을 정의한다 [9-11]. +- **Prompt Endpoint (/prompt):** 생성된 API JSON 페이로드를 ComfyUI 서버의 `/prompt` 엔드포인트로 POST 요청을 보내 실제 실행을 트리거한다 [10, 12]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Execution Model Inversion:** 엔진이 모든 노드를 실행하는 대신 'Save Image'와 같은 출력 노드에서 역방향으로 탐색하여 최종 결과에 필요한 의존성 노드만 식별하고 실행한다 [13]. +- **Bifurcation of Formats:** 시각적 편집을 위한 Frontend 포맷(`workflow.json`)과 프로그래밍적 실행을 위한 Backend 포맷(`workflow_api.json`)을 분리하여 운영 효율성을 극대화한다 [3, 14]. +- **Metadata Recovery:** PNG 파일의 `tEXt` 또는 `zTXt` 청크에 숨겨진 워크플로 JSON 데이터를 `exiftool`이나 전용 추출기를 통해 복구하여 공유 및 재사용하는 패턴이 발견된다 [15-17]. + +## 📖 세부 내용 (Details) + +### 1. API JSON 생성 및 구조적 특징 +API 포맷 JSON은 백엔드 실행 최적화를 위해 설계되었다. +- **데이터 구조:** 루트 키는 노드 ID(문자열)이며, 각 값은 `class_type`과 `inputs` 딕셔너리를 포함한다 [10, 18]. +- **연결 표현:** 노드 간의 링크는 별도의 배열이 아닌 노드 입력 내에서 `[origin_node_id, output_slot_index]` 형태의 참조로 직접 임베딩된다 [3, 19]. +- **위젯 값 전환:** GUI에서 사용자가 입력한 위젯 값(시드, 텍스트 등)은 API JSON의 `inputs` 필드로 직접 매핑되어 고정된 값이 된다 [19]. + +### 2. 프로그래밍적 조작 및 자동화 +개발자는 템플릿화된 API JSON을 Python 등을 통해 동적으로 수정하여 대량 생성을 자동화할 수 있다. +- **입력값 교체:** `json` 라이브러리를 사용하여 특정 노드 ID의 `inputs` 필드(예: 프롬프트 텍스트, 시드 값)를 런타임에 변경한다 [10, 20]. +- **이미지 주입:** 외부 이미지를 API로 전달할 때는 `Load Image (Base64)` 노드를 사용하거나 이미지를 서버의 `input` 디렉토리에 업로드한 후 파일명으로 참조한다 [21, 22]. +- **결과 수신:** 생성 진행 상황과 결과 이미지는 WebSocket 통신을 통해 실시간으로 모니터링하며, `SaveImageWebsocket` 노드를 사용하여 바이너리 데이터를 직접 수신할 수 있다 [22]. + +### 3. 고도화된 생성 도구 +- **ComfyUI-to-Python-Extension:** JSON 워크플로를 독립적으로 실행 가능한 `.py` 스크립트로 변환하여 서버 없이도 헤드리스 환경에서 실행 가능하게 한다 [23, 24]. +- **Comfy API Simplified:** 노드 ID 대신 사용자가 지정한 노드 제목(title)으로 파라미터를 설정할 수 있게 하여 워크플로 수정 시 코드의 파손을 방지한다 [23, 25]. +- **LLM 기반 생성:** 자연어 설명을 입력하면 Qwen2.5와 같은 모델이 이를 해석하여 유효한 노드 그래프 구조를 자동으로 생성하고 빌드한다 [26, 27]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **하위 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [28]. +- **포맷의 비가역성:** API 포맷 JSON은 실행 효율은 높으나, 이를 다시 GUI로 드래그하여 로드할 경우 시각적 레이아웃(노드 위치 등)이 유실된 '스켈레톤' 상태로 나타나 편집이 어렵다 [12, 29]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드의 JS 로직을 Python으로 변환하여 서버 측에서 일반 JSON을 API JSON으로 즉시 변환하는 엔드포인트를 구현함 (커밋: bc85382) [12, 30]. +- **ComfyUI-WorkflowGenerator:** 자연어 프롬프트를 기반으로 3단계 파이프라인(생성-검증-빌드)을 거쳐 실행 가능한 워크플로를 생성하는 시스템 (커밋: 82df278) [27, 31]. +- **ComfyUI-to-Python-Extension:** 워크플로를 Python 코드로 번역하여 자동화 및 반복 생성에 최적화된 스크립트를 제공함 (커밋: 6cdcc23) [24, 32]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (다수의 GitHub 프로젝트를 통해 실용성 입증됨) +- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 README 기반) +- **중복 검사 결과:** 신규 생성 + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow JSON]] + - 연결 이유: API 데이터의 근간이 되는 스키마 규격 + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 속성 및 링크 스키마 v1.0의 기술적 제약 사항 [33]. + +#### [구현/활용 도구] +- [[API Format]] + - 연결 이유: ComfyUI 서버 통신을 위한 필수 데이터 포맷 + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 메타데이터 제거 및 실행 최적화 로직 [5]. +- [[ComfyUI-Manager]] + - 연결 이유: API 실행 시 누락된 커스텀 노드 의존성 해결 도구 + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 `class_type`을 기반으로 한 자동 노드 설치 프로세스 [34]. + +### 심층 후속 질문 (Deeper Research Questions) +- API JSON의 `inputs` 필드에서 노드 참조 시 사용되는 슬롯 인덱스의 정확한 매핑 규칙은 무엇인가? [35] +- `Execution Model Inversion`이 대규모 워크플로에서 실제 성능(VRAM/연산)에 미치는 정량적 영향은 어느 정도인가? [13] +- LLM 기반 워크플로 생성 시 `NodeValidator`가 사용하는 시맨틱 임베딩 방식은 커스텀 노드의 정확도를 어떻게 보장하는가? [36, 37] +- PNG 메타데이터가 손상된 경우, `exiftool` 외에 바이너리 수준에서 워크플로를 복구할 수 있는 대안적 방법이 있는가? [17, 38] +- `comfyui-workflow-to-api-converter`가 처리하는 1MB 요청 제한의 기술적 근거와 대규모 워크플로(Flux 등) 대응 방안은 무엇인가? [39, 40] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `/prompt` 엔드포인트에 전송할 JSON 페이로드를 생성하기 위해 GUI의 'Dev mode'를 활용하여 템플릿을 확보한다 [8]. +- **System Design:** 프로덕션 환경에서는 사용자의 입력을 수신하는 미들웨어를 구축하고, 템플릿 JSON의 특정 노드 ID 값을 동적으로 치환하여 ComfyUI 인스턴스에 전달한다 [22, 41]. +- **Operation / Maintenance:** 워크플로 변경 시 노드 ID가 변할 수 있으므로, 유지보수성을 위해 `comfy_api_simplified`와 같이 노드 제목 기반으로 접근하는 래퍼 사용을 권장한다 [23, 25]. +- **Learning Path:** 기본 UI 사용법 숙지 → Dev mode 활성화 및 API JSON 구조 분석 → Python `requests` 및 `websocket`을 이용한 원격 제어 순으로 학습한다 [42, 43]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Comfy GPT]] + - 확장 방향: AI 에이전트가 직접 노드를 조립하고 디버깅하는 자가 최적화 시스템 연구 [27, 44]. +- [[Model Hashing]] + - 확장 방향: 파일명 대신 해시값을 사용하여 API 호출 시 모델 불일치 문제를 해결하는 기술 [45]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI Backend Engine.md b/10_Wiki/Topics/Comfyui/ComfyUI Backend Engine.md new file mode 100644 index 00000000..58667332 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI Backend Engine.md @@ -0,0 +1,100 @@ +--- +id: comfyui-backend-engine +title: "ComfyUI Backend Engine" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI API Engine", "ComfyUI Execution Layer"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes/comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "WorkflowExecutor", "ExecutionCache"] +github_commit: "bc85382" +--- + +# [[ComfyUI Backend Engine]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI Backend Engine은 복잡한 노드 그래프(DAG)를 실행 가능한 [[API 포맷]]으로 직렬화하고, 역방향 의존성 추적을 통해 최적화된 상태로 머신러닝 워크플로우를 처리하는 핵심 실행 계층이다. [1-3] + +## 🧠 핵심 개념 (Core concepts) +1. **API JSON (Backend Format):** UI 메타데이터(좌표, 크기 등)를 제거하고 노드 클래스(class_type)와 입력(inputs) 간의 논리적 연결만 포함된 정제된 실행 데이터 구조이다. [2, 4, 5] +2. **Execution Model Inversion:** 최종 출력 노드(예: Save Image)에서 시작하여 필요한 의존성만 역방향으로 탐색해 실행함으로써 불필요한 노드 연산을 배제하는 최적화 기법이다. [3] +3. **Standalone Script Execution:** 웹 서버와 UI 계층을 분리하여 워크플로우를 독립적인 Python 스크립트나 헤드리스(Headless) 파이프라인으로 구동하는 메커니즘이다. [6-8] +4. **Dynamic Prompting:** API 엔드포인트(/prompt)에 JSON 페이로드를 전송할 때 노드 ID나 타이틀을 기반으로 파라미터를 실시간으로 수정하여 동적 워크플로우를 생성한다. [9-11] + +## 🧩 추출된 패턴 (Extracted patterns) +- **Serialization Bifurcation (직렬화 이원화):** 시각적 편집을 위한 'Frontend 포맷'과 서버 실행을 위한 'Backend API 포맷'으로 워크플로우를 구분하여 관리한다. [2, 12] +- **Backward Dependency Traversal:** 그래프 전체를 순차 실행하는 대신, 결과값 도출에 필수적인 노드들만 선별하여 실행 순서를 결정한다. [3] +- **Target Node Overriding:** JSON 내부의 특정 노드 ID를 키값으로 활용하여 시드(Seed), 프롬프트, 모델 경로 등의 값을 프로그래밍 방식으로 교체한다. [10, 13, 14] + +## 📖 세부 내용 (Details) + +ComfyUI의 백엔드 엔진은 워크플로우를 **유향 비순환 그래프(DAG)**로 처리하며, 이를 직렬화(Serialization)하여 기기 간 이식성과 프로그래밍 자동화를 지원한다. [1] 워크플로우를 API로 실행하기 위해서는 표준 JSON 포맷이 아닌 'API 전용 포맷'이 필수적이며, 이는 ComfyUI 설정 메뉴에서 **"Dev mode Options"**를 활성화해야 내보내기가 가능하다. [15-17] + +### 1. JSON 포맷의 구조적 차이 +- **Frontend JSON (workflow.json):** `nodes` 배열 안에 위치 정보(`pos`), 크기(`size`), 그룹 정보 등 UI 레이아웃 메타데이터가 포함된다. 연결은 별도의 `links` 배열에서 관리된다. [18-20] +- **API JSON (workflow_api.json):** 노드 ID가 루트 키인 딕셔너리 구조이며, UI 관련 정보가 모두 제거된다. 링크 정보는 노드 입력값 내에 직접 참조(예: `[node_id, output_slot]`) 형태로 포함되어 훨씬 컴팩트하다. [4, 18, 21, 22] + +### 2. 실행 및 최적화 메커니즘 +백엔드 엔진은 **/prompt 엔드포인트**를 통해 수신된 JSON을 분석한다. [13, 18] 엔진의 **Execution Model Inversion** 아키텍처는 그래프에 수십 개의 노드가 있더라도 최종 결과 노드에 연결되지 않은 노드는 완전히 무시하여 자원을 최적화한다. [3] 또한, `WorkflowExecutor`와 `ExecutionCache` 같은 클래스를 활용하면 서버 환경 없이도 독립적인 Python 환경에서 워크플로우를 실행할 수 있다. [9, 23] + +### 3. 프로그래밍적 확장성 +개발자는 Python의 `json` 라이브러리를 사용하여 로드된 워크플로우 객체의 특정 노드 값을 변경한 뒤 API 서버로 전송할 수 있다. [13, 24] 이 과정에서 노드 ID가 고정되지 않아 발생하는 유지보수 문제는 **Comfy API Simplified**와 같은 래퍼 라이브러리를 사용하여 노드의 제목(Title)으로 접근함으로써 해결할 수 있다. [11, 25] 최근에는 LLM을 활용해 자연어를 이 API 형식의 JSON으로 변환해주는 **ComfyUI-WorkflowGenerator** 기술도 도입되고 있다. [26, 27] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **포맷 호환성 이슈:** 표준 JSON 파일을 API 엔드포인트로 직접 보내면 에러가 발생하며, 반드시 API 포맷으로 변환해야 한다. [28] +- **API 포맷의 역변환 한계:** API 포맷 JSON을 UI로 불러오면 노드의 시각적 정보(위치, 크기 등)가 누락되어 분석 및 편집이 어려운 '스켈레톤' 상태로 로드된다. [29] +- **버전 호환성:** ComfyUI는 업데이트가 매우 빈번하여, 구버전 JSON이 최신 버전 백엔드에서 작동하지 않을 수 있으므로 주의가 필요하다. [30] + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측 JavaScript 로직을 Python으로 변환하여 서버사이드에서 non-API 포맷을 API 포맷으로 자동 변환해주는 엔드포인트(/workflow/convert)를 제공한다. [28, 31] +- **ComfyUI-to-Python-Extension:** 워크플로우를 실행 가능한 `.py` 스크립트로 변환하여 헤드리스 환경에서 실행할 수 있게 한다. [7, 8] +- **WorkflowExecutor & ExecutionCache:** 소스 코드 레벨에서 ComfyUI 워크플로우의 실행과 결과 캐싱을 관리하는 핵심 클래스 구현체이다. [9, 23] +- **P-Reinforce 관련:** LLM 기반 자동 워크플로우 생성 파이프라인(Generator -> Validator -> Builder)에서 최종 실행 객체로 활용된다. [32, 33] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견됨) +- **출처 신뢰도:** B (공식 문서 및 GitHub 기술 문서를 기반으로 합성됨) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[API JSON]] + - 연결 이유: 백엔드 엔진이 직접적으로 해석하고 실행하는 유일한 데이터 포맷이다. [4] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 데이터 흐름의 실제 직렬화 방식. [2, 21] + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 백엔드 엔진 실행 시 누락된 커스텀 노드 의존성을 해결하는 필수 도구이다. [34, 35] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내부의 class_type 정보를 기반으로 한 종속성 관리 메커니즘. [34] + +### 심층 후속 질문 (Deeper Research Questions) +- Execution Model Inversion이 복잡한 순환 구조(실제로는 DAG지만 복잡한 경우)에서 어떻게 성능을 최적화하는가? +- API 포맷 JSON에서 사용자 정의 노드(Custom Nodes)의 버전 관리 정보를 포함할 수 있는 방법은 무엇인가? [36] +- Standalone 실행 시 `ExecutionCache`가 GPU VRAM 자원을 효율적으로 해제하거나 재사용하는 구체적인 로직은 무엇인가? [23] +- `workflow_api.json` 내의 노드 ID를 수동 조작하지 않고 프로그래밍적으로 매핑할 수 있는 가장 안정적인 라이브러리는 무엇인가? [25] +- LLM 기반 생성기에서 `NodeValidator`가 지원하지 않는 새로운 커스텀 노드를 인식하게 하는 방법은 무엇인가? [37] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 웹 서비스 백엔드에서 사용자가 입력한 프롬프트를 JSON에 주입하고 ComfyUI API로 요청을 보내 이미지 생성 결과를 받아오는 데 활용된다. [24, 38] +- **System Design:** 헤드리스 렌더링 서버나 CI/CD 파이프라인에서 생성 AI 워크플로우를 자동 테스트하는 용도로 설계된다. [7, 8] +- **Operation / Maintenance:** ComfyUI Manager를 통해 백엔드에서 필요한 모델과 노드를 자동 설치하여 배포 프로세스를 간소화한다. [34] +- **Learning Path:** GUI를 통한 실험 단계에서 JSON 스키마를 이해하고, 이후 Python API를 통한 대량 생성 자동화 단계로 넘어가는 핵심 관문이다. [10, 39] + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: 백엔드에서 파일명 대신 해시값을 통해 정확한 모델 가중치를 로드하는 안정성 확보 방안 연구. [40] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Ref: [1-4, 9, 28]) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI Manager.md b/10_Wiki/Topics/Comfyui/ComfyUI Manager.md new file mode 100644 index 00000000..f8e37eea --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI Manager.md @@ -0,0 +1,94 @@ +--- +id: comfyui-manager +title: "ComfyUI Manager" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI-Manager"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes/ComfyUI-Manager"] +github_commit: "" +--- + +# [[ComfyUI Manager]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우의 **의존성 자동 해결** 및 **중앙 집중식 자원 관리**를 통해 JSON 워크플로우의 이식성과 재현성을 보장하는 핵심 확장 도구 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **의존성 해결 (Dependency Resolution):** 외부에서 로드된 JSON 파일을 분석하여 누락된 커스텀 노드 패키지를 식별하고 설치를 지원함 [1]. +- **커스텀 노드 및 모델 관리 (Nodes & Models Management):** 수천 개의 커스텀 노드와 체크포인트, LoRA, VAE 등 모델 가중치를 GUI 환경에서 검색하고 원클릭으로 설치 및 업데이트함 [2, 3]. +- **워크플로우 발견 (Workflow Discovery):** 관리자 인터페이스 내에서 ComfyWorkflows, OpenArt 등의 플랫폼과 연동하여 워크플로우를 탐색하고 직접 다운로드함 [4]. +- **보안 및 환경 설정 (Security & Config):** 서버 보안 수준에 따른 실행 제한 관리 및 터미널 로그 확인 등 시스템 유틸리티 기능을 제공함 [5, 6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **누락 노드 복구 패턴 (Red Box Recovery):** 외부 워크플로우(JSON/PNG) 로드 시 빨간색 상자가 나타나면 "Install Missing Custom Nodes" 기능을 통해 필요한 노드를 일괄 설치한 후 서버를 재시작하여 복구함 [1, 7]. +- **의존성 명시 패턴 (Dependency Marking):** 특정 노드(예: Workflow to API Converter)는 '마커 노드'를 워크플로우에 포함시켜 ComfyUI Manager가 해당 워크플로우의 의존성을 더 정확하게 감지하도록 유도함 [8, 9]. +- **모델 검색 및 해싱 패턴:** 파일명 대신 모델의 SHA-256 해시를 사용하여 서로 다른 시스템 간의 모델 경로 및 이름 불일치 문제를 해결함 [10]. + +## 📖 세부 내용 (Details) +ComfyUI Manager는 `ltdrdata`가 개발한 커스텀 노드로, ComfyUI 생태계의 복잡한 노드 간 연결과 모델 의존성을 관리하는 중추적인 역할을 수행합니다 [2]. + +- **설치 및 구조:** 사용자는 `ComfyUI/custom_nodes` 디렉토리에 해당 저장소를 `git clone` 하여 설치할 수 있으며, 설치 후 UI에 관리 메뉴가 통합됩니다 [2]. +- **JSON 워크플로우와의 관계:** ComfyUI는 노드 기반의 비순환 유향 그래프(DAG)를 JSON으로 직렬화하여 공유하는데, 이때 제작자와 사용자의 환경이 다를 경우 발생하는 노드 누락 문제를 해결하는 것이 Manager의 주된 임무입니다 [1, 11]. +- **기능 인터페이스:** + - **Install Custom Nodes:** 사용 가능한 모든 커스텀 노드 목록을 조회하고 설치합니다 [2]. + - **Install Models:** 모델 체크포인트, ControlNet, LoRA 등을 카테고리별로 검색하여 다운로드할 수 있습니다 [3]. + - **Update/Fetch:** ComfyUI 자체 및 설치된 노드들의 최신 버전을 유지합니다 [2]. +- **고급 유틸리티:** 사용자 설정 메뉴에서 "Enable Dev mode Options"를 활성화하면 API 포맷의 JSON 내보내기가 가능해지며, Manager는 이 과정에서 의존성 정보를 포함하거나 누락된 요소를 진단하는 보조 도구로 활용됩니다 [12, 13]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **보안 오류:** ComfyUI Manager 사용 시 보안 설정 수준에 따라 'This action is not allowed' 오류가 발생할 수 있으며, 이는 환경 설정 파일 수정을 통한 해결이 필요합니다 [5, 6]. +- **노드 관리 방식의 변화:** 새로운 노드 매니저(기본 Windows 빌드 포함)에서는 일부 레거시 커스텀 노드 매니저가 보이지 않을 수 있으며, 필요시 레거시 모드를 활성화해야 합니다 [14]. + +## 🛠️ 적용 사례 (Applied in summary) +- **실제 파일 경로:** `ComfyUI/custom_nodes/ComfyUI-Manager` 경로에 위치하며 시스템이 시작될 때 로드됩니다 [2]. +- **워크플로우 진단:** 외부 플랫폼(Civitai, MimicPC 등)에서 다운로드한 JSON 워크플로우를 분석하여 로컬 환경에 없는 노드를 식별하는 과정에 적용됩니다 [1, 12]. +- **의존성 보증:** `comfyui-workflow-to-api-converter-endpoint` 프로젝트에서 Manager가 해당 노드의 의존성을 탐지할 수 있도록 "Workflow to API Converter (Marker)" 노드를 제공하는 사례가 확인됩니다 [8, 9]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual +- **출처 신뢰도:** B (Official Documentation / ComfyUI-Wiki / Primary YouTube Tutorials) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 + +### 상위/유사 개념 +- [[Workflow.json (Frontend Format)]] + - 연결 이유: Manager가 분석하고 누락된 요소를 채워 넣는 주된 대상 파일 포맷입니다 [1, 15]. +- [[Custom Nodes]] + - 연결 이유: Manager가 관리하는 핵심 객체이며, 워크플로우의 기능을 확장하는 단위입니다 [2, 16]. +- [[Workflow API JSON]] + - 연결 이유: API 실행을 위해 UI 메타데이터를 제거한 최적화된 JSON 형태이며, Manager는 이 과정에서의 의존성을 확인합니다 [1, 17]. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI Manager가 JSON 파일을 파싱하여 누락된 노드의 GitHub 저장소 주소를 정확히 찾아내는 메커니즘은 무엇인가? +- 모델 해싱(SHA-256)을 통한 모델 관리 방식은 파일명 기반 관리와 비교했을 때 이식성 측면에서 구체적으로 어떤 이점을 제공하는가? [10] +- 'Terminal Log (Manager)' 노드는 실시간 디버깅 및 JSON 실행 오류 분석에서 어떤 데이터를 제공하는가? [6] +- Manager의 보안 수준(Security Level)이 'This action is not allowed' 오류를 유발하는 구체적인 임계 조건은 무엇인가? [6] +- 워크플로우 패키징 기능(`comfy-pack`)과 Manager의 의존성 해결 기능은 상호 보완적인가 아니면 독립적인 대안인가? [10, 18] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `git clone`을 통해 `custom_nodes` 폴더에 설치 후, UI의 "Manager" 버튼을 통해 모든 조작을 수행합니다 [2]. +- **System Design:** 외부 API 서버 구축 시 필요한 모든 커스텀 노드와 모델이 사전에 설치되었는지 확인하는 검증 도구로 활용합니다 [1, 19]. +- **Operation / Maintenance:** ComfyUI 및 커스텀 노드들의 업데이트를 주기적으로 체크하여 환경의 안정성을 유지합니다 [2]. +- **Learning Path:** 초보자가 복잡한 워크플로우를 분석하기 전, 누락된 노드 문제를 해결하는 첫 번째 단계로 학습합니다 [7]. + +### 인접 주변 주제 (Adjacent Topics) +- [[ComfyUI Workspace Manager]] + - 확장 방향: 워크플로우를 시각적으로 조직하고 백업하는 특화된 관리 기능을 제공합니다 [20]. +- [[Comfy CLI]] + - 확장 방향: 명령줄 인터페이스를 통해 워크플로우 추출 및 의존성 관리를 수행하는 도구입니다 [21]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine.--- \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI Workflow Extractor.md b/10_Wiki/Topics/Comfyui/ComfyUI Workflow Extractor.md new file mode 100644 index 00000000..2210ef68 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI Workflow Extractor.md @@ -0,0 +1,66 @@ +--- +id: comfyui-workflow-extractor +title: "ComfyUI Workflow Extractor" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["SethRobinson/comfyui-workflow-to-api-converter-endpoint (bc85382)", "Comfy-Org/comfy-cli issue #341", "exiftool CLI implementation"] +github_commit: "bc85382" +--- + +# [[ComfyUI Workflow Extractor]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 생성 이미지의 메타데이터(PNG Chunks)에 내장된 워크플로우 논리를 추출하여 유실된 노드 그래프를 복구하고 재사용 가능한 JSON으로 변환하는 필수 기술. [1-3] + +## 🧠 핵심 개념 (Core concepts) +- **메타데이터 임베딩 (Metadata Embedding):** ComfyUI의 'Save Image' 노드는 실행 시 전체 노드 그래프, 레이아웃, 설정 및 프롬프트를 PNG 파일의 숨겨진 메타데이터에 주입함. [4, 5] +- **PNG 청크 분석 (PNG Chunk Analysis):** 주로 `tEXt` 또는 `zTXt` 청크를 사용하여 워크플로우(Frontend 형식)와 프롬프트(API 형식)라는 두 가지 고유한 문자열을 저장함. [2] +- **데이터 복구 및 변환 (Data Recovery & Conversion):** 이미지 편집기나 소셜 미디어 플랫폼에 의해 제거될 수 있는 취약한 메타데이터를 독립적인 JSON 파일로 추출하여 공유 및 백업 가능성을 확보함. [1, 2] +- **추출 도구 생태계 (Extraction Tool Ecosystem):** 웹 기반 인터페이스부터 명령줄 도구(CLI), Python 라이브러리 및 하이 레벨 스크립트에 이르기까지 다양한 복구 경로가 존재함. [3, 6] + +## 🧩 추출된 패턴 (Extracted patterns) +- **바이너리 태그 격리 패턴:** `exiftool`과 같은 유틸리티를 사용하여 미디어 파일 내의 특정 바이너리 태그(`-workflow`)만을 분리하여 표준 JSON 파일로 출력하는 전략을 취함. [3, 6] +- **드래그 앤 드롭 로딩 메커니즘:** 추출 프로세스를 수동으로 수행하는 대신, 메타데이터가 포함된 이미지를 ComfyUI 캔버스에 직접 드롭하여 즉각적으로 노드 레이아웃을 재구성함. [4, 7, 8] +- **자동화된 배치 처리:** 대량의 이미지 저장소에서 워크플로우를 대규모로 수집하기 위해 디렉토리 전체를 스캔하고 API 그래프와 UI 레이아웃을 별도의 JSON으로 생성하는 배치 프로세싱 패턴이 발견됨. [3] + +## 📖 세부 내용 (Details) +ComfyUI Workflow Extractor는 이미지 파일 내에 직렬화된 데이터 구조를 파싱하는 전문화된 도구 모음을 의미함. ComfyUI에서 생성된 거의 모든 PNG 파일은 그 자체가 워크플로우의 운반체 역할을 하며, 이는 'Save Image' 노드가 실행될 때 최종 이미지와 함께 전체 노드 그래프를 인젝션하기 때문임. [4, 5] + +이 기술의 핵심은 PNG 규격 내의 비필수 메타데이터 영역을 활용하는 것임. 구체적으로 `tEXt` 또는 `zTXt` 청크에 두 가지 형식의 데이터를 저장하는데, 하나는 시각적 배치를 포함한 **Frontend 워크플로우**이고, 다른 하나는 실행을 위한 최적화된 **Backend API 프롬프트**임. [2] 이러한 데이터는 매우 취약하여 이미지 압축 소프트웨어나 소셜 네트워크 서비스를 거칠 경우 유실될 가능성이 높으므로, 워크플로우 추출기는 이러한 유실이 발생하기 전 혹은 저장된 라이브러리로부터 지식을 추출하는 데 중요함. [1, 2, 7] + +전문적인 추출 방법으로는 다음과 같은 것들이 존재함: +- **CLI 기반 도구:** `exiftool -b -workflow input.png > workflow.json`과 같은 명령어를 통해 바이너리 데이터를 직접 추출하거나, `ComfyUI_prompt_extractor`와 같은 전용 스크립트를 사용하여 긍정적 프롬프트와 API 그래프를 분리함. [3, 6] +- **웹 인터페이스 도구:** 'Weird Wonderful AI Art'에서 제공하는 추출기와 같이 사용자가 이미지를 업로드하면 서버 측 처리 없이(또는 보안 처리 후) 즉시 JSON 데이터를 반환하는 방식임. [1, 9] +- **통합 확장 도구:** `ComfyUI-to-Python-Extension`과 같은 도구는 추출된 워크플로우를 실행 가능한 Python 스크립트로 변환하여 헤드리스 환경에서 자동화할 수 있게 함. [10, 11] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **데이터 무결성 문제:** PNG 이미지 드래그 방식은 간편하지만, 새로 추가된 노드나 특정 커스텀 노드가 메타데이터에 올바르게 포함되지 않아 복구 시 일부 정보가 누락될 수 있다는 경고가 소스에서 확인됨. [5] +- **형식 간 충돌:** 추출 도구는 'Frontend JSON'과 'API JSON'을 구분해야 함. API 포맷은 시각적 정보(노드 위치, 크기 등)가 제거된 상태이므로 이를 다시 ComfyUI UI로 드래그하면 시각적으로 불완전한 상태로 로드될 수 있음. [12, 13] +- **메타데이터 파괴성:** 많은 표준 이미지 편집기(GIMP 등)는 이미지 저장 시 비표준 메타데이터 청크를 제거하므로, 원본 워크플로우를 유지하려면 전용 삽입/복사 도구가 필요함이 제기됨. [14] + +## 🛠️ 적용 사례 (Applied in summary) +- **SethRobinson/comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측의 자바스크립트 논리를 파이썬으로 변환하여 서버 측에서 비-API 워크플로우 형식을 API 형식으로 변환하는 `/workflow/convert` 엔드포인트를 구현함 (Commit: `bc85382`). [15, 16] +- **Comfy-Org/comfy-cli Issue #341:** 이미지뿐만 아니라 webp, mp4 등 지원되는 모든 미디어에서 워크플로우를 추출, 삽입, 복사하는 기능을 `comfy-cli`에 추가하려는 논의와 `exiftool` 활용 사례가 기록됨. [6, 14, 17] +- **WeirdWonderfulAI.Art:** 약 21,460개 이상의 워크플로우를 추출한 통계를 보유한 웹 기반 추출 도구 서비스를 운영 중임. [9] +- **exiftool CLI:** `exiftool -b -workflow` 명령을 통해 PNG에서 바이너리 워크플로우 데이터를 격리하는 표준적인 디지털 포렌식 기법으로 활용됨. [3, 6] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견으로 검증 가능성 높음) +- **출처 신뢰도:** B (Official Documentation / GitHub Issue / Technical Guides) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON Generation and Serialization.md b/10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON Generation and Serialization.md new file mode 100644 index 00000000..c3d80749 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON Generation and Serialization.md @@ -0,0 +1,102 @@ +--- +id: comfyui-workflow-json-generation-and-serialization +title: "ComfyUI Workflow JSON Generation and Serialization" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI Workflow JSON 생성 및 직렬화"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "ComfyUI API", "Serialization"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint", "comfyui_to_python.py", "WorkflowGenerator Pipeline", "/workflow/convert endpoint", "comfy_api_simplified"] +github_commit: "bc85382" +--- + +# [[ComfyUI Workflow JSON Generation and Serialization]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우 직렬화는 시각적 노드 그래프를 실행 가능한 계층적 JSON 구조(Frontend vs. API)로 변환하여 생성 AI 파이프라인의 이식성, 자동화 및 프로그래밍적 제어를 가능케 하는 핵심 메커니즘이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **JSON 포맷의 이분화 (Frontend vs. API)**: 시각적 편집과 레이아웃 정보를 포함하는 '프론트엔드 포맷(workflow.json)'과 실행 엔진에 최적화되어 UI 메타데이터가 제거된 '백엔드/API 포맷(workflow_api.json)'으로 나뉜다 [2, 3]. +- **메타데이터 임베딩 (Steganography)**: 워크플로우 데이터를 PNG, WebP 등의 이미지 파일 내부 텍스트 청크(tEXt/zTXt)에 숨겨 이미지 자체가 워크플로우 소스 코드 역할을 하게 한다 [4-6]. +- **JSON v1.0 스키마 표준**: 노드 ID, 클래스 타입, 위젯 값, 슬롯 기반 링크 연결 등을 정의하는 기술적 제약 조건 모음이다 [7, 8]. +- **실행 모델 역전 (Execution Model Inversion)**: 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색함으로써 필요한 의존성만 식별하여 실행을 최적화한다 [9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **수동 내보내기 프로토콜**: 설정 메뉴에서 'Dev mode Options'를 활성화하여 API 전용 JSON을 추출하거나, 표준 저장을 통해 UI 포함 JSON을 생성한다 [10-12]. +- **프로그래밍적 매개변수 변조**: JSON을 딕셔너리 객체로 로드한 후 특정 노드 ID의 `inputs` 값을 수정하여 시드(seed)나 프롬프트를 동적으로 변경한다 [13, 14]. +- **3단계 LLM 파이프라인**: 자연어 지시를 받아 '논리적 합성(Generator) -> 시맨틱 검증(Validator) -> 그래프 컴파일(Builder)' 과정을 거쳐 워크플로우를 자동 생성한다 [15-17]. +- **서버측 포맷 변환**: 클라이언트 자바스크립트 없이 서버 내부 노드 레지스트리를 참조하여 비 API 포맷을 API 포맷으로 변환하는 `/workflow/convert` 엔드포인트 패턴이다 [18, 19]. + +## 📖 세부 내용 (Details) +ComfyUI는 생성 프로세스를 **유향 비순환 그래프(DAG)**로 취급하며, 이를 JSON으로 직렬화하는 과정은 크게 두 가지 경로로 진행된다 [1]. + +첫째, **프론트엔드 JSON(workflow.json)**은 Litegraph 표준을 따르며 노드의 좌표, 크기, 그룹화 정보와 같은 시각적 메타데이터를 포함한다 [2, 20]. 이는 주로 사용자 인터페이스에서의 편집과 공유를 목적으로 한다 [3]. + +둘째, **API JSON(workflow_api.json)**은 실제 실행에 필요한 논리만을 남긴 스트림라인화된 그래프이다 [2]. 여기서는 링크가 별도의 객체가 아니라 노드 입력 내부에 직접 삽입된 참조 형태(`[origin_node_id, output_slot_index]`)로 표현된다 [2, 21]. + +기술적으로 **JSON v1.0 스키마**는 `nodes` 배열 내의 각 객체가 `id`, `type`, `pos`, `size`, `widgets_values`, `mode` 등의 속성을 가질 것을 요구한다 [7]. 특히 연결(Connectivity)은 입력 슬롯과 출력 슬롯의 고유 인덱스를 통해 정의되며, 이는 VAE Loader와 같이 여러 출력을 가진 노드에서 정확한 데이터 흐름을 보장하는 데 필수적이다 [22]. + +최근에는 **ComfyGPT** 연구를 기반으로 한 LLM 중심 생성 방식이 도입되어, Qwen2.5-14B와 같은 미세 조정된 모델이 자연어 설명을 실행 가능한 노드 그래프로 번역한다 [15, 23]. 또한 **ComfyUI-to-Python-Extension**과 같은 도구는 JSON 워크플로우를 순수 파이썬 스크립트로 변환하여 헤드리스(headless) 환경에서의 독립적 실행을 지원한다 [24, 25]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **JSON 버전 호환성**: ComfyUI가 빈번하게 업데이트됨에 따라 이전 버전의 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [26]. +- **메타데이터 손실 위험**: 이미지 파일에 포함된 워크플로우 메타데이터는 소셜 미디어 플랫폼이나 이미지 압축 소프트웨어에 의해 제거될 수 있으며, 이 경우 JSON 추출이 불가능해진다 [6, 26]. +- **API 포맷의 가독성**: API 포맷은 실행에는 효율적이지만 인간이 읽기 어렵고 노드 좌표가 없어 UI로 다시 불러올 때 노드들이 겹쳐 보이거나 뼈대만 남는 문제가 발생한다 [18, 27]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint**: `bc85382` 커밋에서 대소문자가 틀린 콤보 위젯 값을 정규화하는 기능이 수정되었으며, `/workflow/convert` 엔드포인트를 통해 비 API 포맷을 변환한다 [28-30]. +- **ComfyUI-to-Python-Extension**: `comfyui_to_python.py` 및 `comfyui_to_python_utils.py` 파일을 통해 JSON 워크플로우를 파이썬 코드로 변환하는 로직이 구현되어 있다 [31]. +- **DanielPFlorian/ComfyUI-WorkflowGenerator**: 자연어를 통한 워크플로우 생성을 위해 `Workflow Generator Pipeline` 노드를 제공하며, 내부적으로 `UpdateNodeCatalog`를 통해 로컬 노드 정보를 카탈로그화한다 [32-34]. +- **Mystic Pipeline**: `pipeline.yaml`과 `new_pipeline.py`를 사용하여 ComfyUI 워크플로우를 서버리스 엔드포인트로 배포할 때 API JSON 포맷이 사용된다 [35, 36]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 오픈소스 프로젝트와 공식 문서의 포맷 명세를 통해 기술적 구조 확인됨) +- **출처 신뢰도:** B (공식 문서 및 실제 구현체 GitHub 소스 코드 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI의 워크플로우 구조 자체가 DAG를 기반으로 설계됨 [1]. +- [[Litegraph Standard]] + - 연결 이유: 프론트엔드 JSON 포맷이 따르는 시각적 노드 그래프 라이브러리 표준 [2, 20]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 로드 시 발생하는 'Missing Custom Node' 오류를 해결하는 핵심 의존성 관리 도구 [37]. +- [[ComfyUI API]] + - 연결 이유: 생성된 JSON(API format)이 실제로 소모되는 최종 인터페이스 [38, 39]. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI의 'Execution Model Inversion'은 순방향 그래프 탐색 방식과 비교했을 때 대규모 워크플로우에서 어느 정도의 리소스 절감 효과를 가지는가? [9] +- 이미지 메타데이터(tEXt/zTXt) 외에 WebP나 MP4와 같은 다른 미디어 포맷에서 워크플로우 JSON을 안전하게 유지하는 표준 방식은 무엇인가? [40] +- LLM 기반 생성기에서 발생하는 '할루시네이션(노드 오연결)'을 방지하기 위한 Semantic Validator의 구체적인 임베딩 비교 알고리즘은 무엇인가? [23, 41] +- `object_info.json`을 사용하여 실시간으로 노드 스키마를 검증하는 것과 정적 카탈로그를 사용하는 방식의 성능 차이는 어떠한가? [42, 43] +- 복합적인 서브그래프(Subgraph)가 포함된 워크플로우를 API 포맷으로 직렬화할 때 노드 ID 충돌을 방지하는 내부 슬롯 매핑 전략은 무엇인가? [44] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬 `json` 라이브러리를 사용하여 로드된 워크플로우 딕셔너리의 `inputs` 키를 조작함으로써 자동화된 배치 생성을 구현할 수 있다 [13, 45]. +- **System Design:** API 전용 포맷을 사용하여 UI 오버헤드를 줄인 서버리스 추론 엔드포인트(Mystic, Replicate)를 구축한다 [39, 46]. +- **Operation / Maintenance:** ComfyUI Manager를 통해 외부에서 공유된 JSON의 커스텀 노드 누락 문제를 자동 진단하고 해결한다 [37, 47]. +- **Learning Path:** 기본 워크플로우(Default workflow)를 JSON으로 내보내 구조를 분석한 후, 점진적으로 커스텀 노드를 추가하며 스키마 변화를 관찰하는 학습이 권장된다 [48, 49]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: 워크플로우 JSON의 이식성을 위해 파일 이름 대신 모델의 해시값을 사용하여 의존성을 해결하는 기술 [50]. +- [[Steganography in Generative AI]] + - 확장 방향: 이미지 파일에 생성 파라미터를 숨기는 방식의 보안 및 데이터 보존 관련 연구 [6]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON.md b/10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON.md new file mode 100644 index 00000000..0f553ae4 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON.md @@ -0,0 +1,115 @@ +--- +id: comfyui-workflow-json +title: "ComfyUI Workflow JSON" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["워크플로우 JSON", "workflow_api.json"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "ComfyUI", "JSON"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: + - "DanielPFlorian/ComfyUI-WorkflowGenerator/README.md" + - "comfyui-workflow-to-api-converter-endpoint/README.md" + - "pydn/ComfyUI-to-Python-Extension/README.md" +github_commit: "82df278, bc85382, 6cdcc23" +--- + +# [[ComfyUI Workflow JSON]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI Workflow JSON은 복잡한 노드 기반 생성 AI 프로세스를 직렬화하여 가시적인 UI 레이아웃과 프로그램적 실행 로직 간의 상호 운용성을 보장하는 핵심 청사진이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **포맷의 이분화 (Bifurcation):** 사용자의 시각적 편집을 위한 '프런트엔드 포맷(workflow.json)'과 서버 실행에 최적화된 '백엔드/API 포맷(workflow_api.json)'으로 나뉜다 [3-6]. +2. **메타데이터 임베딩 (Metadata Embedding):** 생성된 PNG 이미지의 tEXt/zTXt 청크 내에 워크플로우 데이터를 숨겨 저장함으로써 이미지 자체가 백업 및 공유 수단이 된다 [7-9]. +3. **노드 레지스트리 기반 스키마:** 각 노드는 고유 ID, 클래스 타입, 입력/출력 슬롯 및 연결 정보를 담고 있으며, 이는 JSON Schema v1.0 규격을 따른다 [10-12]. +4. **프로그램적 제어 (Programmatic Automation):** JSON 구조를 직접 수정하거나 전용 라이브러리를 통해 워크플로우를 동적으로 생성 및 실행할 수 있다 [13-15]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **실행 모델 역전 (Execution Model Inversion):** 엔진은 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색하며 필요한 의존성만 식별하여 실행한다 [16]. +- **3단계 생성 파이프라인 (LLM):** 자연어 설명을 기반으로 논리적 구조 합성(Generator), 노드 이름 검증(Validator), 실행 가능한 JSON 컴파일(Builder) 순으로 워크플로우를 자동 생성한다 [17-19]. +- **헤드리스 변환 패턴:** 시각적 노드 그래프를 순수 Python 스크립트(.py)로 변환하여 GUI 없이 독립적으로 실행하는 구조를 가진다 [20, 21]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우는 AI 이미지 생성 프로세스를 설명하는 노드 네트워크를 직렬화한 데이터이다 [22, 23]. 주요 생성 및 관리 방법은 다음과 같다. + +**1. 포맷별 특성 및 생성** +* **프런트엔드 JSON:** 노드 위치, 크기, 그룹, 색상 등 시각적 정보를 포함하며 Litegraph 표준을 따른다 [3, 5, 24]. 일반적인 'Save' 버튼이나 `Ctrl+S`로 생성한다 [8, 25]. +* **API JSON:** UI 메타데이터를 제거하고 실행 로직(노드 타입, 입력값, 연결 관계)만 남긴 효율적인 포맷이다 [3, 6, 26]. 설정에서 'Dev mode Options'를 활성화한 후 'Save (API Format)'를 통해 추출할 수 있다 [27-30]. + +**2. 이미지 메타데이터 활용 및 추출** +ComfyUI에서 생성된 모든 이미지는 워크플로우 데이터를 내부 메타데이터에 포함한다 [31, 32]. 사용자는 PNG 파일을 캔버스에 드래그 앤 드롭하여 워크플로우를 즉시 복원할 수 있다 [7, 33, 34]. 대량의 이미지에서 JSON을 추출하기 위해 `exiftool`이나 전용 CLI 도구, 웹 기반 추출기(`Weird Wonderful AI Art` 등)가 사용된다 [35-37]. + +**3. 자동화 및 변환 도구** +* **Python API 연동:** `json` 라이브러리를 사용하여 시드, 프롬프트 등 특정 노드 파라미터를 직접 수정하고 `/prompt` 엔드포인트로 전송할 수 있다 [13, 15]. +* **변환 엔드포인트:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드는 비-API 포맷을 API 포맷으로 서버 측에서 변환하는 기능을 제공한다 [38, 39]. +* **코드 변환:** `ComfyUI-to-Python-Extension`은 JSON 워크플로우를 독립 실행 가능한 Python 코드로 번역하여 자동화 및 실험의 효율성을 높인다 [14, 21]. + +**4. LLM 기반 동적 생성** +`ComfyUI-WorkflowGenerator`는 Qwen2.5와 같은 거대언어모델을 활용하여 "SDXL을 이용한 텍스트 투 이미지 워크플로우 생성"과 같은 자연어 명령을 즉시 노드 그래프로 구축한다 [40-42]. 이 과정에서 로컬 노드 카탈로그를 스캔하여 유효성을 검증한다 [43, 44]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +* **버전 호환성:** ComfyUI의 잦은 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [33]. +* **메타데이터 소실:** 압축 소프트웨어나 소셜 미디어 플랫폼을 통해 이미지를 전송할 경우 임베딩된 워크플로우 정보가 삭제될 수 있다 [9, 33]. +* **API 포맷의 단점:** API 포맷으로만 저장된 파일은 UI 정보를 포함하지 않아 캔버스에 로드 시 노드가 겹치거나 시각적 구조가 무너진 '스켈레톤' 상태로 나타난다 [45]. + +## 🛠️ 적용 사례 (Applied in summary) +* **DanielPFlorian/ComfyUI-WorkflowGenerator:** LLM을 이용해 자연어 설명을 실행 가능한 워크플로우 JSON으로 변환하는 파이프라인 구현 (커밋: `82df278`) [19, 42, 46]. +* **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드 자바스크립트 로직을 파이썬으로 이식하여 `/workflow/convert` 엔드포인트를 통해 JSON 포맷을 변환 (커밋: `bc85382`) [38, 39, 47]. +* **pydn/ComfyUI-to-Python-Extension:** JSON 워크플로우를 `.py` 파일로 내보내어 단독 실행 가능한 스크립트 생성 환경 구축 (커밋: `6cdcc23`) [48, 49]. +* **Mystic Pipeline:** 사용자의 커스텀 워크플로우 JSON을 서버리스 엔드포인트에 배포하여 API 형태로 서빙 [50, 51]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (다양한 오픈소스 프로젝트 및 공식 문서에서 적용 사례 확인됨) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Nodes]] + - 연결 이유: 워크플로우 JSON의 기본 구성 단위 [22, 52]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간의 링크 연결 방식 및 데이터 흐름 구조 [23, 53]. +- [[Litegraph]] + - 연결 이유: 프런트엔드 JSON 포맷의 시각적 직렬화 표준 [3, 5]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 캔버스 레이아웃과 노드 좌표 관리 원리 [4]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 로드 시 누락된 커스텀 노드를 감지하고 설치하는 도구 [54-56]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 워크플로우 공유 시 발생하는 의존성 해결 방법 [55]. +- [[Comfy GPT]] + - 연결 이유: LLM 기반 워크플로우 생성의 원형이 되는 연구 [19, 40]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 자연어-그래프 변환 알고리즘의 발전 방향 [57]. + +### 심층 후속 질문 (Deeper Research Questions) +- 프런트엔드 JSON과 API JSON 간의 구조적 차이가 실제 서버 실행 성능에 미치는 정량적 차이는 무엇인가? [3, 4] +- PNG 외에 WebP나 MP4 메타데이터에 워크플로우를 효율적으로 내장하고 추출하는 기술적 표준은 어떻게 정의되는가? [58] +- 'Execution Model Inversion'이 복잡한 루프 구조를 가진 워크플로우에서도 일관된 순서를 보장하는가? [16] +- LLM 기반 생성기에서 새로운 커스텀 노드 출현 시 실시간으로 카탈로그를 업데이트하고 반영하는 효율적인 전략은 무엇인가? [57, 59] +- `.cpack.zip`과 같은 워크플로우 패키징 방식이 기존 JSON 방식의 모델 경로 문제를 어떻게 완전히 해결할 수 있는가? [60] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `/prompt` 엔드포인트를 호출할 때 API JSON의 특정 노드 ID 값을 가로채어 동적으로 파라미터를 삽입함 [13, 15]. +- **System Design:** 시각적 편집 환경(프런트엔드)과 배포 환경(백엔드)을 분리하여 효율적인 AI 프로덕션 파이프라인 구축 [3, 50, 61]. +- **Operation / Maintenance:** `ComfyUI Manager`를 통해 외부 공유 워크플로우의 커스텀 노드 누락 문제를 모니터링하고 해결 [54, 55]. +- **Learning Path:** 기본 워크플로우 템플릿 로드에서 시작하여, 메타데이터 추출을 통한 타인 워크플로우 분석, 최종적으로 API 기반 자동화 단계로 발전 [62-64]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Custom Nodes]] + - 확장 방향: JSON 내 `class_type`이 참조하는 실제 기능 구현체 및 의존성 관리 [8, 55, 65]. +- [[Model Hashing]] + - 확장 방향: JSON 파일 내 하드코딩된 모델 경로 문제를 SHA-256 해시를 이용해 해결하는 방법 [66]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source indices: [1-186]) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI Workspace Manager.md b/10_Wiki/Topics/Comfyui/ComfyUI Workspace Manager.md new file mode 100644 index 00000000..d031eef7 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI Workspace Manager.md @@ -0,0 +1,88 @@ +--- +id: comfyui-workspace-manager +title: "ComfyUI Workspace Manager" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Workspace Manager"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI 루트 디렉토리"] +github_commit: "" +--- + +# [[ComfyUI Workspace Manager]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우를 시각적으로 조직화하고 루트 디렉토리 기반의 안전한 저장 및 자산 관리 기능을 제공하는 파워 유저용 워크스페이스 최적화 도구 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **시각적 워크플로우 조직화 (Visual Organization):** 버튼 클릭 한 번으로 워크플로우를 시각적으로 확인하고 관리할 수 있는 세련된 사용자 인터페이스를 제공함 [2]. +2. **루트 디렉토리 보호 저장 (Root Directory Storage):** 워크플로우를 ComfyUI의 루트 디렉토리에 저장하여, 향후 업데이트 시 파일이 실수로 덮어씌워지는 것을 방지하고 안전한 백업 및 공유를 지원함 [2]. +3. **통합 자산 획득 (Integrated Asset Acquisition):** 관리 인터페이스 내에서 체크포인트 모델, LoRA 및 기타 필요한 파일들을 직접 다운로드할 수 있는 기능을 포함함 [3]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **업데이트 내성 저장 패턴:** 시스템 업데이트와 사용자 데이터를 분리하기 위해 워크플로우를 고정된 루트 디렉토리 구조에 보관하여 데이터 영속성을 보장함 [2]. +- **중앙 집중식 관리 패턴:** 워크플로우 파일(JSON) 관리와 모델 자산(Weights) 관리를 단일 시각 인터페이스로 통합하여 작업 흐름의 단절을 최소화함 [2, 3]. + +## 📖 세부 내용 (Details) +ComfyUI Workspace Manager는 기본 ComfyUI의 저장 및 로드 기능을 넘어선 고도의 관리 기능을 원하는 사용자들을 위한 커스텀 노드이다 [1]. 이 도구는 단순히 JSON 파일을 저장하는 것에 그치지 않고, 사용자가 보유한 수많은 워크플로우를 시각적으로 탐색하고 분류할 수 있는 전용 브라우저 역할을 수행한다 [2]. + +특히 **데이터 안전성** 측면에서 강력한 이점을 가지는데, 모든 워크플로우 데이터를 ComfyUI 설치 폴더의 루트 디렉토리에 체계적으로 보관함으로써 소프트웨어의 핵심 바이너리가 업데이트되더라도 사용자의 소중한 워크플로우 자산이 손실되지 않도록 설계되었다 [2]. 또한, 사용자는 이 인터페이스를 통해 필요한 모델이나 LoRA를 즉시 검색하고 내려받을 수 있어, 워크플로우 구성 중 발생하는 리소스 부족 문제를 도구 내에서 즉각 해결할 수 있다 [3]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +기존의 [[ComfyUI Custom Scripts]]가 저장/로드 버튼 아래에 드롭다운 메뉴를 생성하여 경로 기반 접근을 제공하는 것과 달리, Workspace Manager는 별도의 독립적이고 시각적인 인터페이스를 제공하는 상급 대안으로 분류된다 [1, 2]. 소스 데이터 내에서 기능적 모순은 발견되지 않으며, 파워 유저를 위한 편의성 확장 도구로서의 성격이 강조된다 [1]. + +## 🛠️ 적용 사례 (Applied in summary) +- **저장 위치:** 이 도구를 통해 관리되는 모든 워크플로우는 **ComfyUI의 루트 디렉토리**에 저장되어 안전하게 관리된다 [2]. +- **기능 활용:** 사용자는 인터페이스를 통해 워크플로우 관리뿐만 아니라 **모델 및 LoRA 다운로드**를 수행하여 작업 환경을 구축한다 [3]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Primary Source via NotebookLM / User Guides) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [워크플로우 관리 체계] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: Workspace Manager가 관리하는 핵심 대상인 JSON 파일의 생성 원리임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 관리 도구가 JSON의 어떤 메타데이터를 활용하여 시각화하는지 이해할 수 있음. +- [[ComfyUI Custom Scripts]] + - 연결 이유: 워크플로우의 저장 및 로드 편의성을 개선하는 유사한 목적의 도구임 [1]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 경로 기반 관리와 시각적 관리 방식의 차이점을 비교할 수 있음. + +#### [자산 및 의존성 관리] +- [[ComfyUI Manager]] + - 연결 이유: 누락된 노드 설치 및 모델 관리를 수행하는 상호보완적 도구임 [4]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: Workspace Manager의 모델 다운로드 기능과의 통합 활용법을 파악할 수 있음. + +### 심층 후속 질문 (Deeper Research Questions) +- Workspace Manager가 루트 디렉토리에 워크플로우를 저장할 때 내부적인 폴더 구조화 규칙은 무엇인가? +- 시각적 인터페이스에서 워크플로우의 썸네일이나 메타데이터를 추출하여 표시하는 메커니즘은 어떠한가? +- 루트 디렉토리에 저장된 워크플로우가 Git 등의 버전 관리 시스템과 연동될 때의 이점은 무엇인가? +- 모델 다운로드 기능이 ComfyUI Manager의 DB와 동기화되어 작동하는가, 아니면 독자적인 소스를 사용하는가? +- 대규모 워크플로우(예: 200KB 이상의 복잡한 노드 그래프) 처리 시 인터페이스의 성능 한계는 존재하는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 다수의 프로젝트별 워크플로우를 시각적으로 구분하여 관리해야 하는 제작 환경에 도입. +- **System Design:** 업데이트가 잦은 개발 환경에서 워크플로우 자산을 안전하게 보존하기 위한 저장 전략으로 채택. +- **Operation / Maintenance:** 워크플로우와 필요한 모델(Weights)을 한 곳에서 관리하여 팀 내 공유 및 인수인계 효율화. + +### 인접 주변 주제 (Adjacent Topics) +- [[Workflow JSON]] + - 확장 방향: 관리 도구가 제어하는 데이터 형식의 상세 스펙 이해 [5]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI-Manager.md b/10_Wiki/Topics/Comfyui/ComfyUI-Manager.md new file mode 100644 index 00000000..be2f0464 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI-Manager.md @@ -0,0 +1,89 @@ +--- +id: comfyui-manager +title: "ComfyUI-Manager" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ltdrdata/ComfyUI-Manager", "Comfy-Org/ComfyUI-Manager/issues/719"] +github_commit: "" +--- + +# [[ComfyUI-Manager]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI-Manager는 워크플로우 JSON의 종속성을 동적으로 해석하고 누락된 커스텀 노드와 모델을 자동 설치하여, 정적인 파일 상태의 지식을 실행 가능한 파이프라인으로 전환하는 핵심 관리 엔진이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +1. **종속성 자동 해결 (Dependency Resolution):** 외부에서 가져온 JSON 파일을 로드할 때 발생하는 "Red Box(누락된 노드)" 오류를 분석하여 필요한 커스텀 노드 패키지를 식별하고 원클릭 설치를 지원함 [1, 2]. +2. **통합 리소스 허브 (Resource Hub):** 커스텀 노드뿐만 아니라 체크포인트, LoRA, ControlNet 등 다양한 AI 모델(Weights)의 검색 및 설치를 GUI 내에서 통합 관리함 [3, 4]. +3. **워크플로우 브라우징:** Comfy Workflows 및 OpenArt와 같은 플랫폼과 직접 연결되어 워크플로우 JSON을 다운로드하기 전에 미리 보고 즉시 로드할 수 있는 통로 역할을 함 [5]. +4. **보안 및 상태 관리:** 노드 설치 시의 보안 수준(Security Level) 설정 및 서버 업데이트, 터미널 로그 확인 등 시스템 전반의 유지보수 기능을 수행함 [6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Scan-Parse-Install 패턴:** 사용자가 JSON을 로드하면 시스템이 `class_type`을 스캔하고, 로컬 레지스트리와 대조하여 누락된 항목을 파싱한 뒤, 해당 Git 리포지토리를 찾아 설치를 제안하는 일련의 흐름 [2]. +- **마커 노드 활용 패턴:** `Workflow to API Converter (Marker)`와 같은 특정 노드를 워크플로우에 포함시켜, Manager가 해당 워크플로우의 특정 종속성을 더 정확하게 감지하도록 유도하는 전략 [7, 8]. +- **중앙 집중형 업데이트 전략:** 개별적으로 `git pull`을 수행하는 대신, Manager를 통해 설치된 모든 커스텀 노드의 업데이트 상태를 일괄 확인하고 갱신함 [3, 9]. + +## 📖 세부 내용 (Details) +ComfyUI-Manager는 **ltdrdata**에 의해 개발된 커스텀 노드로, ComfyUI 생태계의 복잡한 노드 종속성 문제를 해결하기 위해 설계되었다 [3]. 사용자가 Civitai나 GitHub에서 공유된 JSON 워크플로우를 로드했을 때, 로컬 환경에 해당 커스텀 노드가 없으면 화면에 붉은색 상자가 표시된다 [2]. 이때 Manager는 JSON 내의 노드 정보를 분석하여 "Install Missing Custom Nodes" 기능을 통해 누락된 패키지를 자동으로 찾아 설치하고 서버를 재시작함으로써 워크플로우를 즉시 복구한다 [1, 2]. + +또한, 워크플로우 생성에 필수적인 **모델 관리** 기능도 강력하다. "Install Models" 메뉴를 통해 SDXL, Realistic Vision 등 주요 모델뿐만 아니라 특정 커스텀 노드에 필요한 ControlNet 모델까지 검색하여 적절한 폴더 경로에 자동으로 배치한다 [4, 10, 11]. + +설치 방법은 매우 간단하여, ComfyUI의 `custom_nodes` 디렉토리 내에서 `git clone https://github.com/ltdrdata/ComfyUI-Manager` 명령을 실행하는 것만으로 활성화된다 [3]. 최근에는 워크플로우를 API용 JSON으로 변환할 때 종속성을 명시하기 위한 'Marker' 노드 등을 제공하여, 다른 사용자와 워크플로우를 공유할 때의 호환성을 높이는 역할도 수행하고 있다 [7, 8]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **보안 수준 갈등:** Manager를 통한 자동 설치 시 'This action is not allowed'와 같은 보안 레벨 오류가 발생할 수 있으며, 이는 설정 메뉴에서의 별도 조치가 필요하다 [6]. +- **모델 명칭 불일치:** 동일한 모델임에도 파일명이 다를 경우(예: `sd_xl_base_v10.safetensors` vs `sdxl_base.safetensors`) Manager가 이를 해결하기 위해 모델 해싱(SHA-256) 기술을 활용하거나 검색 기능을 강화하고 있다 [12, 13]. +- **특정 노드 누락:** IP-Adapter와 같은 일부 복잡한 커스텀 노드의 경우 Manager를 통해서도 해결되지 않는 종속성 문제가 보고되어 지속적인 수정이 이루어지고 있다 [14]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ltdrdata/ComfyUI-Manager 리포지토리:** `ComfyUI/custom_nodes/ComfyUI-Manager` 경로에 설치되어 전체 노드 관리 시스템으로 작동 [3]. +- **Workflow to API Converter (Marker) 노드:** 워크플로우 공유 시 Manager가 종속성을 감지할 수 있도록 돕는 마커로 실제 JSON 구조 내에 포함됨 [7, 8]. +- **Issue #719 (ComfyUI-Manager):** IP-Adapter 및 누락된 모델/커스텀 노드에 대한 커뮤니티 차원의 수정 및 기여 시도가 기록됨 [14]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual +- **출처 신뢰도:** B (Official Wiki 및 튜토리얼 소스 기반 합성) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: Manager는 생성된 JSON을 타 환경에서 복구하고 실행하는 데 필수적인 도구임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 파일의 이식성(Portability) 확보 원리. +- [[Workflow API JSON (Backend Format)]] + - 연결 이유: API 형식의 JSON에서도 종속성을 추적하기 위해 Manager의 마커 기능을 사용함 [7]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 정보가 없는 API 환경에서의 노드 복구 전략. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI-Manager가 JSON의 `class_type`을 기반으로 정확한 Git 리포지토리를 매핑하는 내부 레지스트리 업데이트 알고리즘은 무엇인가? +- 모델 해싱(SHA-256) 기술이 Manager의 모델 검색 엔진에 어떻게 통합되어 파일명 불일치 문제를 해결하는가? +- 보안 레벨 설정(`Security Level Error`)이 노드 설치 권한에 미치는 구체적인 영향과 해결 방안은 무엇인가? +- `Workflow to API Converter (Marker)` 노드가 JSON 메타데이터에 기록되는 방식과 Manager가 이를 인식하는 로직은 무엇인가? +- 서브그래프(Subgraph)나 중첩된 워크플로우 구조 내에서 Manager의 종속성 감지 성능은 어떻게 보장되는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 커스텀 노드 개발 시 `INPUT_TYPES`를 정확히 정의하여 Manager의 레지스트리와 호환되도록 설계해야 함 [15]. +- **System Design:** 워크플로우 배포 시 Manager가 인식 가능한 'Marker' 노드를 포함하여 사용자 경험을 개선함 [7, 8]. +- **Operation / Maintenance:** 정기적으로 Manager를 통해 설치된 모든 패키지의 업데이트 상태를 점검하여 최신 모델 지원 환경을 유지함 [3, 9]. +- **Learning Path:** 초보 사용자가 "Red Box" 오류를 해결하고 다양한 모델을 안전하게 설치하는 첫 번째 단계로 학습함 [1, 3]. + +### 인접 주변 주제 (Adjacent Topics) +- [[ComfyUI Workspace Manager]] + - 확장 방향: Manager가 설치를 담당한다면, Workspace Manager는 설치된 노드들을 활용한 워크플로우의 시각적 조직화와 백업에 집중함 [16, 17]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI-WorkflowGenerator.md b/10_Wiki/Topics/Comfyui/ComfyUI-WorkflowGenerator.md new file mode 100644 index 00000000..ac89a087 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI-WorkflowGenerator.md @@ -0,0 +1,106 @@ +--- +id: comfyui-workflowgenerator +title: "ComfyUI-WorkflowGenerator" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["DanielPFlorian/ComfyUI-WorkflowGenerator", "catalog/", "cataloging/", "config/", "generators/", "nodes/", "tests/", "utils/", "wiki/", "workflows/"] +github_commit: "82df278" +--- + +# [[ComfyUI-WorkflowGenerator]] + +## 🎯 한 줄 통찰 (One-line insight) +자연어 설명을 기반으로 복잡한 노드 그래프 논리를 추론하고, 실행 가능한 [[Workflow API JSON]] 형식으로 자동 변환하는 LLM 기반의 지능형 워크플로우 합성 엔진 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **자연어-노드 그래프 변환 (Natural Language to Node Graph Conversion):** 사용자의 의도(예: "SDXL 기반 텍스트 투 이미지 생성")를 분석하여 적절한 노드 구성과 데이터 흐름을 정의하는 논리적 연결망을 생성함 [1-3]. +- **3단계 생성 파이프라인 (Three-stage Pipeline):** 논리적 합성(Generator), 시맨틱 검증(Validator), 그래프 컴파일(Builder) 과정을 거쳐 최종 결과물을 도출하는 구조적 아키텍처 [3-5]. +- **미세 조정된 전문 모델 (Fine-tuned Specialist LLM):** ComfyUI의 내부 노드 레지스트리 및 스키마 사양을 학습한 Qwen2.5-14B 기반 모델을 핵심 엔진으로 사용함 [1, 6]. +- **로컬 노드 동기화 (Local Node Synchronization):** 'Update Node Catalog' 기능을 통해 현재 환경에 설치된 네이티브 및 커스텀 노드를 스캔하여 모델의 지식 공백을 보완함 [7, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **시맨틱 검증 및 교정 패턴 (Semantic Validation & Correction):** LLM이 생성한 가상의 노드 이름을 로컬에 설치된 실제 노드 클래스 이름과 대조하여 자동 수정하거나 대체 노드를 제안함 [3, 4, 9]. +- **모듈형 단계별 개입 (Modular Step-wise Intervention):** 생성-검증-구축 과정을 개별 노드로 분리하여 사용자가 중간 결과물(논리 다이어그램 등)을 직접 검토하고 수정할 수 있도록 설계됨 [10, 11]. +- **환경 적응형 지식 확장 (Environment-adaptive Knowledge Expansion):** 학습 데이터의 컷오프(Cutoff) 한계를 극복하기 위해 로컬 노드 리스트를 동적으로 임베딩하여 검증에 활용하는 휴리스틱을 적용함 [7, 8, 12]. + +## 📖 세부 내용 (Details) +ComfyUI-WorkflowGenerator는 **ComfyGPT 연구**를 기반으로 구현된 독립적인 시스템으로, 사용자가 노드를 직접 배치하는 "시각적 프로그래밍" 단계에서 언어로 의도를 전달하는 "대화형 프로그래밍"으로의 전환을 목표로 한다 [2-4]. + +- **아키텍처 구조:** + 1. **Generator (논리 합성):** LLM이 자연어 지시를 해석하여 노드 종류와 연결 관계를 정의하는 추상적 JSON 구조를 생성한다 [3, 5, 9]. + 2. **Validator (시맨틱 검증):** 'Semantic search' 전용 모드 또는 'LLM refinement' 모드를 통해 생성된 노드 이름의 유효성을 검사하고 로컬 환경과의 호환성을 보장한다 [3, 9]. + 3. **Builder (그래프 컴파일):** 검증된 추상 구조를 ComfyUI 실행 엔진이 인식할 수 있는 **v1.0 스키마** 준수 워크플로우 JSON으로 최종 변환한다 [3, 8]. + +- **모델 및 실행 환경:** + - **핵심 모델:** Qwen2.5-14B를 기반으로 미세 조정되었으며, 효율성을 위해 **GGUF 양자화(q8_0)** 형식을 주로 사용한다 [6]. + - **필수 의존성:** GGUF 모델 구동을 위해 `llama-cpp-python` 라이브러리가 필요하며, 시맨틱 검색을 위해 별도의 임베딩 모델(`paraphrase-multilingual-MiniLM-L12-v2`)을 활용한다 [6, 13]. + - **카탈로그 관리:** `UpdateNodeCatalog` 노드를 실행하면 현재 설치된 모든 커스텀 노드를 스캔하여 임베딩 및 카탈로그 파일을 최신화하며, 이는 생성된 워크플로우의 정확도를 결정하는 핵심 요소이다 [7, 8]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정적 학습 데이터 vs 동적 생태계:** 미세 조정된 모델은 학습 시점 이후에 출시된 최신 커스텀 노드에 대해서는 본질적으로 지식이 없는 "동결(frozen)" 상태이다. 이를 해결하기 위해 로컬 노드 스캔(Update Catalog)을 통한 보완책이 강조된다 [12, 14]. +- **논리적 생성 vs 물리적 실행:** 모델이 논리적으로 올바른 노드 연결을 생성하더라도, 로컬 환경에 해당 체크포인트 모델이나 특정 커스텀 노드가 물리적으로 부재할 경우 최종 워크플로우는 실행 실패(Red Nodes)로 이어질 수 있다 [3, 14, 15]. + +## 🛠️ 적용 사례 (Applied in summary) +- **GitHub 프로젝트:** `DanielPFlorian/ComfyUI-WorkflowGenerator` 저장소에 전체 소스 코드와 노드 아키텍처가 공개되어 있다 [16]. +- **주요 파일 구조:** + - `nodes/`: WorkflowGenerator, NodeValidator, WorkflowBuilder 등 핵심 노드 구현체 포함 [11, 16]. + - `catalog/`: 로컬 노드 정보를 저장하고 검색하기 위한 카탈로그 관리 폴더 [8, 16]. + - `generators/`: LLM을 통한 워크플로우 논리 생성 엔진 포함 [16]. +- **특이 사항:** 6개월 전 커밋(`82df278`)을 통해 드롭다운 메뉴의 중복 모델 표시 문제가 수정된 기록이 발견된다 [16]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 논문 ComfyGPT의 아키텍처를 기반으로 하며, 실제 GitHub 구현체가 존재함) +- **출처 신뢰도:** B (GitHub Repository 및 기술 문서 기반 정보) +- **중복 검사 결과:** 신규 생성 (New discovery) + +--- + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow API JSON]] + - 연결 이유: WorkflowGenerator의 최종 출력물이자 백엔드 실행을 위한 필수 규격임 [8, 17, 18]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 메타데이터가 배제된 실행 최적화 그래프 구조. +- [[ComfyGPT]] + - 연결 이유: WorkflowGenerator의 이론적 토대가 된 다중 에이전트 워크플로우 생성 연구임 [2, 3]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: LLM이 노드 그래프를 이해하고 구성하는 원천 논리. + +#### [구현/활용 도구] +- [[ComfyUI-Manager]] + - 연결 이유: 생성된 JSON에서 누락된 커스텀 노드 의존성을 해결하는 핵심 사후 관리 도구임 [15, 19]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 외부 공유 워크플로우의 실행 가능성 확보 프로세스. + +### 심층 후속 질문 (Deeper Research Questions) +- LLM의 학습 데이터 컷오프 이후에 출시된 새로운 아키텍처(예: Wan 2.2)를 `UpdateNodeCatalog` 정보만으로 정확히 구성할 수 있는가? [12] +- Semantic Validation 단계에서 'LLM refinement'를 사용할 때 발생하는 토큰 소모량과 추론 시간 대비 정확도 향상 비율은 어느 정도인가? [9] +- 생성된 워크플로우의 `order` 및 `mode` 속성을 결정할 때 WorkflowBuilder가 사용하는 우선순위 알고리즘은 무엇인가? [8, 20] +- GGUF 양자화 강도(q4_0 vs q8_0)가 노드 간의 복잡한 연결(Link) 논리 보존력에 미치는 영향이 존재하는가? [21] +- 다중 ControlNet과 같이 중첩된 조건부 연결을 자연어만으로 완벽하게 제어하기 위한 프롬프트 엔지니어링 표준은 무엇인가? [4, 5] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `llama-cpp-python[cuda]`를 설치하여 저사양 VRAM 환경에서도 LLM 기반 워크플로우 생성이 가능하도록 최적화할 수 있음 [13, 22]. +- **System Design:** 사용자의 요구사항을 바이트코드 형태의 JSON으로 변환하는 추상화 계층으로 활용하여 전문 지식 없는 사용자의 접근성을 높임 [4, 23]. +- **Operation / Maintenance:** 커스텀 노드 대량 추가 시 반드시 `UpdateNodeCatalog`를 재실행하여 시스템의 지식 베이스를 동기화해야 함 [7, 8]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Comfy Nodekit]] + - 확장 방향: 파이썬 코드를 통해 워크플로우를 프로그래밍 방식으로 구축하는 정적 생성 방식과의 비교 연구 [24]. +- [[Litegraph]] + - 확장 방향: 워크플로우 JSON의 시각적 요소(위치, 크기)가 정의되는 프론트엔드 표준 규격 이해 [17, 25]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ComfyUI-to-Python-Extension.md b/10_Wiki/Topics/Comfyui/ComfyUI-to-Python-Extension.md new file mode 100644 index 00000000..27c01d50 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ComfyUI-to-Python-Extension.md @@ -0,0 +1,66 @@ +--- +id: comfyui-to-python-extension +title: "ComfyUI-to-Python-Extension" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Save As Script"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui_to_python.py", "comfyui_to_python_utils.py", "install.py", "init.py", "ComfyUI/custom_nodes"] +github_commit: "6cdcc23" +--- + +# [[ComfyUI-to-Python-Extension]] + +## 🎯 한 줄 통찰 (One-line insight) +시각적인 **ComfyUI 노드 그래프 워크플로우를 별도의 서버 없이 독립적으로 실행 가능한 파이썬(.py) 코드로 변환**하여 자동화 및 실험의 반복성을 극대화하는 강력한 확장 도구이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **Save As Script (UI Export):** ComfyUI 웹 인터페이스의 메뉴를 통해 현재 워크플로우를 즉시 파이썬 스크립트로 다운로드하는 기능이다 [2, 3]. +- **CLI Exporter:** 저장된 API 포맷의 JSON 파일을 명령줄 인터페이스에서 파이썬 코드로 일괄 변환하는 도구이다 [2, 4]. +- **Runtime Dependency:** 생성된 스크립트는 실행을 위해 반드시 **ComfyUI 런타임 환경(PyTorch 등)**과 코드베이스에 대한 접근 권한이 필요하다 [5, 6]. +- **Metadata Preservation:** 생성된 스크립트를 통해 저장된 이미지는 원본 워크플로우 메타데이터를 포함하므로, 다시 ComfyUI로 드래그 앤 드롭하여 복구가 가능하다 [5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Workflow-to-Script Serialization:** 시각적 DAG(Directed Acyclic Graph) 구조를 순차적인 파이썬 함수 호출 및 클래스 인스턴스화 코드로 직렬화하는 패턴을 따른다 [2, 7]. +- **Headless Execution Pattern:** 웹 서버나 프론트엔드 없이도 워크플로우를 실행할 수 있게 하여, 독립형 소프트웨어 프로젝트나 자동화 파이프라인에 통합하기 용이한 구조를 제공한다 [8, 9]. +- **Lifecycle Management:** 생성된 스크립트의 `main()` 함수 내에서 모델 및 캐시 정리를 수행하는 `finally` 블록을 포함하여 자원 관리를 최적화한다 [6]. + +## 📖 세부 내용 (Details) +- **주요 기능 및 사용법:** + - **웹 UI 확장:** `File -> Save As Script` 메뉴를 통해 `workflow_api.py` 파일로 워크플로우를 내보낸다 [3]. + - **CLI 변환:** `python comfyui_to_python.py --input_file workflow_api.json` 명령을 통해 기존 JSON 파일을 스크립트로 변환할 수 있으며, `--queue_size` 옵션으로 실행 횟수를 지정할 수 있다 [4]. + - **환경 설정:** 실행 환경에 따라 `COMFYUI_PATH`를 설정하여 ComfyUI 코드베이스 위치를 명시해야 한다 [6, 10]. +- **기술적 특징:** + - **독립 실행형 러너:** 생성된 스크립트는 프롬프트 서버가 아닌 **단발성 워크플로우 실행기(single-shot runner)**로 동작한다 [6]. + - **인자 처리:** ComfyUI의 런타임 인자 파서를 재사용하므로, `--highvram`, `--cpu`와 같은 메모리 관리 플래그를 스크립트 실행 시 직접 전달할 수 있다 [5]. + - **파이썬 버전 요구사항:** 안정적인 동작을 위해 **Python 3.12 이상**의 버전을 권장한다 [2]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **동적 워크플로우의 한계:** 한 소스에서는 이 도구가 중간 변환 단계가 필요하기 때문에 **동적인 워크플로우(Dynamic workflows)**를 실행하기에 어려움이 있다는 비판적 시각을 제시한다 [9]. +- **메뉴 위치 변동성:** 프론트엔드 버전에 따라 `Save As Script` 메뉴의 위치가 달라질 수 있다는 점이 명시되어 있다 [3, 6]. +- **최신성 유지:** 정적 데이터셋으로 훈련된 LLM 기반 생성 도구와 달리, 이 익스텐션은 로컬의 노드 레지스트리를 활용하려는 시도를 보이지만, 여전히 수동 변환 과정이 수반된다 [4, 11]. + +## 🛠️ 적용 사례 (Applied in summary) +- **pydn/ComfyUI-to-Python-Extension:** 해당 개념이 구현된 핵심 프로젝트 저장소이다 [1]. +- **comfyui_to_python.py / comfyui_to_python_utils.py:** 워크플로우를 파이썬 코드로 변환하는 로직이 담긴 실제 소스 파일들이다 [12]. +- **install.py:** 익스텐션 설치 및 의존성 관리를 위한 스크립트로 적용되어 있다 [12]. +- **Save As Script 메뉴:** ComfyUI의 `File` 메뉴 하단에 실제 인터페이스 요소로 구현되어 적용되었다 [3]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Comfyui workflow json 생성 방법.md b/10_Wiki/Topics/Comfyui/Comfyui workflow json 생성 방법.md new file mode 100644 index 00000000..9e30877b --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Comfyui workflow json 생성 방법.md @@ -0,0 +1,114 @@ +--- +id: comfyui-workflow-json-생성-방법 +title: "Comfyui workflow json 생성 방법" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI Workflow Serialization", "ComfyUI API JSON Generation"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "ComfyUI", "Workflow", "JSON", "API"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["bc85382", "82df278", "DanielPFlorian/ComfyUI-WorkflowGenerator", "SethRobinson/comfyui-workflow-to-api-converter-endpoint", "pydn/ComfyUI-to-Python-Extension"] +github_commit: "bc85382" +--- + +# [[Comfyui workflow json 생성 방법]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우 JSON은 시각적 그래프(Frontend)와 실행 가능한 로직(API) 사이를 연결하는 **직렬화된 소스 코드**이며, 수동 내보내기부터 LLM 기반 합성까지 다층적인 생성 경로를 제공한다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **형식의 이분화 (Bifurcation):** 시각적 메타데이터를 포함한 **Frontend JSON**(사용자 편집용)과 이를 제거하고 실행 로직만 남긴 **API JSON**(서버/프로그램 호출용)으로 구분된다 [4-7]. +- **메타데이터 임베딩 (Metadata Embedding):** 생성된 PNG/WebP 이미지의 tEXt 또는 zTXt 청크 내에 워크플로우 데이터를 숨겨 저장함으로써 이미지 자체가 워크플로우 백업 역할을 수행한다 [8, 9]. +- **실행 모델 역전 (Execution Model Inversion):** 최종 출력 노드에서 시작하여 필요한 의존성만 역방향으로 탐색해 실행 리스트를 구성하는 구조적 특성을 가진다 [10, 11]. +- **LLM 기반 합성 (LLM-driven Synthesis):** 자연어 설명을 세 단계(생성 → 검증 → 빌드)의 파이프라인을 거쳐 실행 가능한 노드 그래프로 자동 변환하는 최신 접근법이다 [12-14]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **개발자 모드 활성화 패턴:** API 전용 JSON을 추출하기 위해서는 설정 메뉴에서 **'Enable Dev mode Options'**를 활성화해야만 'Save (API format)' 버튼이 노출된다 [2, 15-17]. +- **노드 ID 고정화 전략:** API 환경에서 워크플로우를 제어할 때, 가변적인 노드 ID 대신 **노드 제목(Title)**이나 **사용자 정의 키**를 기반으로 파라미터를 수정하는 래퍼(Wrapper) 사용 패턴이 발견된다 [18-20]. +- **의존성 자동 해결 패턴:** 외부 JSON 로드 시 발생하는 'Missing Custom Node' 오류(빨간색 박스)를 해결하기 위해 **ComfyUI Manager**가 JSON을 파싱하여 누락된 패키지를 설치하도록 유도한다 [21-23]. + +## 📖 세부 내용 (Details) + +### 1. GUI를 통한 수동 생성 방법 +가장 기본적이고 흔한 방법으로, ComfyUI 웹 인터페이스의 컨트롤 패널을 사용한다. +- **Frontend 포맷 (workflow.json):** 캔버스 레이아웃, 노드 좌표, 그룹, 색상 등 시각적 정보를 모두 포함한다 [4, 24]. **Ctrl + S** (또는 Cmd + S) 단축키로 현재 상태를 바로 다운로드할 수 있다 [24]. +- **API 포맷 (workflow_api.json):** 서버 실행에 불필요한 UI 데이터를 제거한 정제된 그래프이다 [4, 7]. 설정에서 개발자 모드를 켠 후 생성되는 **'Save (API format)'** 버튼을 통해 추출하며, `/prompt` 엔드포인트 호출에 필수적이다 [2, 25, 26]. + +### 2. 이미지 메타데이터로부터의 추출 +이미 생성된 결과물 파일에서 워크플로우 로직을 복구하는 방법이다. +- **드래그 앤 드롭:** 워크플로우 정보가 포함된 PNG 파일을 캔버스에 떨어뜨리면 즉시 노드 구성이 복원된다 [8, 27-29]. +- **추출 도구 활용:** `ExifTool`을 사용하여 바이너리 태그를 추출하거나(`exiftool -b -workflow input.png > workflow.json`), 전문 웹 사이트(Weird Wonderful AI Art) 및 CLI 도구를 통해 벌크 추출이 가능하다 [30-33]. + +### 3. 프로그래밍 및 자동화 생성 +개발 환경에서 워크플로우를 동적으로 생성하거나 변환한다. +- **Python 딕셔너리 조작:** JSON은 기본적으로 중첩된 딕셔너리 구조이므로, `json` 라이브러리를 통해 시드, 프롬프트, 모델 경로 등의 특정 노드 입력을 직접 수정하여 다시 저장하거나 API로 보낼 수 있다 [34, 35]. +- **형식 변환 엔드포인트:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면, 일반 Frontend JSON을 서버 사이드에서 즉시 API 포맷으로 변환해주는 `/workflow/convert` API를 활용할 수 있다 [26, 36]. +- **Python 스크립트 변환:** `ComfyUI-to-Python-Extension`은 JSON 워크플로우를 순수 파이썬 코드(.py)로 변환하여 독립적인 실행 스크립트로 만들어준다 [18, 37, 38]. + +### 4. LLM 기반 자연어 생성 (AI 합성) +- **파이프라인 구조:** `ComfyUI-WorkflowGenerator`는 사용자의 자연어 명령(예: "SDXL을 사용한 텍스트-투-이미지 워크플로우 생성")을 입력받아 **Generator**(논리 구조 생성) → **Validator**(노드 이름 검증) → **Builder**(실행 가능 JSON 빌드) 과정을 거친다 [13, 14]. +- **기반 모델:** Qwen2.5-14B와 같이 미세 조정된 대규모 언어 모델을 활용하여 노드 간의 유효한 연결 관계를 추론한다 [39]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **JSON 호환성 이슈:** ComfyUI의 빈번한 업데이트로 인해 이전 버전의 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [23, 28]. +- **메타데이터 손실 위험:** 온라인 공유나 압축 과정에서 이미지의 메타데이터(JSON 정보 포함)가 제거될 수 있으며, 이 경우 드래그 앤 드롭을 통한 복구가 불가능하다 [9, 28, 40]. +- **Reroute 노드 처리:** 최근 업데이트(V2.2.0)에서는 변환기들이 새로운 'reroute' 노드를 무시하거나 적절히 처리하도록 로직이 수정되었다 [41]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Git 커밋 bc85382:** `comfyui-workflow-to-api-converter-endpoint` 프로젝트에서 대소문자 구분 오류(True vs true)를 수정하고 콤보 위젯 값을 정규화하는 로직이 적용됨 [41, 42]. +- **Git 커밋 82df278:** `ComfyUI-WorkflowGenerator`에서 드롭다운 메뉴의 중복 모델 표시 문제를 해결함 [43]. +- **/workflow/convert 엔드포인트:** Seth A. Robinson에 의해 개발된 커스텀 노드로, 비 API 포맷을 API 포맷으로 서버 측에서 변환하는 기능을 구현함 [26, 44]. +- **Save As Script 메뉴:** `pydn/ComfyUI-to-Python-Extension` 설치 시 ComfyUI의 'File' 메뉴에 추가되어 워크플로우를 파이썬 코드로 내보낼 수 있게 함 [45, 46]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 및 다수의 오픈소스 구현 사례 확인됨) +- **출처 신뢰도:** B (공식 개발 문서, 메이저 커스텀 노드 개발자의 기술 노트 및 튜토리얼 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 + +#### [아키텍처/기반 기술] +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON 형식이 기반하고 있는 시각적 그래프 표준 [4, 6]. +- [[Execution Model Inversion]] + - 연결 이유: JSON 데이터가 실제로 처리되는 백엔드 엔진의 핵심 알고리즘 [10]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 생성된 JSON의 노드 의존성을 관리하고 누락된 요소를 복구하는 필수 도구 [21, 22]. +- [[ComfyUI API]] + - 연결 이유: 생성된 API JSON이 최종적으로 소비되는 인터페이스 엔드포인트 [47, 48]. + +### 심층 후속 질문 (Deeper Research Questions) +- 왜 ComfyUI는 Frontend와 API 포맷을 분리하여 설계했으며, 이로 인해 얻는 성능적 이득은 구체적으로 무엇인가? [4, 5] +- PNG 메타데이터 청크(tEXt/zTXt)를 넘어서는 대용량 워크플로우를 이미지에 안전하게 포함시키는 대안 기술은 무엇이 있는가? [9] +- LLM 기반 생성 시, 학습 데이터에 없는 최신 커스트 노드와의 연결을 위해 RAG(검색 증강 생성)를 어떻게 결합할 수 있는가? [49] +- `Execution Model Inversion` 구조에서 사용되지 않는 노드가 JSON에 포함되었을 때 실제 실행 효율에 미치는 영향은 어떠한가? [10] +- 모델 해싱(SHA-256)을 이용해 서로 다른 환경의 JSON 내 모델 파일 경로 불일치 문제를 해결하는 표준 프로세스는 무엇인가? [50] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `/workflow/convert` 엔드포인트를 활용하여 클라이언트 앱에서 워크플로우 수정 후 즉시 실행 가능한 API 호출 생성 [26]. +- **System Design:** 워크플로우를 Git으로 관리하고, 배포 시에는 API 포맷만 추출하여 서버리스 환경(Replicate, Mystic 등)에 업로드 [16, 17, 51]. +- **Operation / Maintenance:** `object_info.json`을 사용하여 실행 전 노드 입출력 유효성을 검사함으로써 런타임 오류 방지 [52, 53]. +- **Learning Path:** 기본 워크플로우 템플릿부터 시작하여 수동 내보내기를 익힌 후, `ComfyUI-to-Python`을 통해 자동화 단계로 진입 [38, 54]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: 워크플로우 이식성 강화를 위한 모델 식별 기술 [50]. +- [[Custom Node Registry]] + - 확장 방향: JSON 내 `class_type`이 참조하는 실제 노드 구현 저장소 관리 [55]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source synthesis from 18 documents) [1-188] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Custom Node Dependency Management.md b/10_Wiki/Topics/Comfyui/Custom Node Dependency Management.md new file mode 100644 index 00000000..ee81db71 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Custom Node Dependency Management.md @@ -0,0 +1,102 @@ +--- +id: custom-node-dependency-management +title: "Custom Node Dependency Management" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["커스텀 노드 의존성 관리", "Missing Custom Nodes Resolution"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Dependency Management"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes/ComfyUI-Manager", "comfyui-workflow-to-api-converter-endpoint (V2.05)", "UpdateNodeCatalog Node"] +github_commit: "" +--- + +# [[Custom Node Dependency Management]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI의 워크플로우 이식성은 **JSON 메타데이터 내 `class_type` 분석**과 **ComfyUI Manager를 통한 자동 의존성 해결** 메커니즘에 의해 보장된다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **Red Node Detection:** 워크플로우 로드 시 로컬 레지스트리에 존재하지 않는 노드를 시각적 경고(빨간색 박스)로 식별하는 메커니즘 [1, 3, 4]. +2. **Node Registry (object_info.json):** 현재 실행 중인 ComfyUI 인스턴스에서 사용 가능한 모든 노드의 입력/출력 스키마 및 클래스 정보를 담고 있는 통합 카탈로그 [5, 6]. +3. **Class Type Mapping:** JSON 파일의 `class_type` 속성을 기반으로 커스텀 노드 패키지를 역추적하여 필요한 기능을 식별하는 프로세스 [1, 7]. +4. **Automated Resolution (ComfyUI Manager):** 미설치 노드를 파싱하여 해당 패키지를 원클릭으로 설치하고 서버를 재시작할 수 있게 하는 관리 도구 [3, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Dependency Detection Marker:** 워크플로우 공유 시 ComfyUI Manager가 의존성을 더 쉽게 감지할 수 있도록 전용 '마커 노드'를 포함시키는 전략 [9]. +- **Semantic Validation Pipeline:** LLM을 사용하여 자연어 명령에서 생성된 노드 이름이 실제 설치된 노드와 일치하는지 시맨틱 임베딩으로 검증하고 교정하는 패턴 [10, 11]. +- **Model Weight Hashing:** 파일명 불일치 문제를 해결하기 위해 SHA-256 해시를 사용하여 모델 의존성을 관리하는 고급 직렬화 방식 [4, 12]. + +## 📖 세부 내용 (Details) +ComfyUI의 의존성 관리는 워크플로우 JSON이 단순한 그래픽 레이아웃이 아니라 **실행 가능한 논리 구조(DAG)**라는 점에서 핵심적인 위치를 차지한다 [2, 13]. + +**의존성 식별 및 해결 프로세스** +사용자가 외부에서 생성된 JSON 워크플로우를 가져올 때, ComfyUI 인터페이스는 각 노드의 `class_type`을 로컬 노드 레지스트리와 대조한다 [1]. 이 과정에서 노드를 찾을 수 없는 경우 해당 노드는 캔버스에 빨간색 박스로 표시된다 [3, 14]. **ComfyUI Manager**는 이 JSON을 다시 파싱하여 누락된 커스텀 노드 패키지를 식별하며, "Install Missing Custom Nodes" 기능을 통해 자동 설치를 지원한다 [3, 8]. + +**데이터 무결성 및 레지스트리** +의존성 관리의 근간은 `object_info.json` 파일이다. 이 파일은 인스턴스 내 모든 노드의 입력/출력 유형, 기본값, 툴팁 등 상세 스키마를 포함하고 있어 도구 개발 및 입력 유효성 검사에 필수적이다 [6, 15]. 또한, 자연어 기반 워크플로우 생성 도구인 **WorkflowGenerator**는 `UpdateNodeCatalog` 노드를 통해 로컬 및 커스텀 노드를 정기적으로 스캔하여 최신 카탈로그를 유지한다 [16, 17]. + +**환경 간 불일치 해결** +로컬 경로가 하드코딩된 이미지나 모델의 경우, 타 시스템으로 워크플로우를 이동할 때 경로 오류가 발생하기 쉽다 [4]. 이를 해결하기 위해 모델 해싱을 사용하거나, `Comfy API Simplified`와 같이 노드 ID 대신 '타이틀'을 기준으로 파라미터를 설정하는 래퍼 라이브러리를 사용하여 워크플로우의 유연성을 높인다 [12, 18]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **JSON 버전 호환성:** ComfyUI는 빈번하게 업데이트되므로, 구버전의 JSON 파일이 최신 버전에서 의존성 문제 없이 완벽하게 작동한다는 보장이 없으며 수동 수정이 필요할 수 있다 [19]. +- **정적 모델의 한계:** 특정 시점에 학습된 LLM 기반 워크플로우 생성기는 학습 이후에 출시된 새로운 커스텀 노드의 존재나 의존성 관계를 알 수 없는 '동결(frozen)' 상태의 한계를 가진다 [20]. +- **보안 이슈:** 의존성 관리의 핵심인 `Impact-Pack` 플러그인 등에서 채굴 바이러스가 발견되는 등 커스텀 노드 생태계의 보안 취약점이 보고된 바 있다 [21]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI/custom_nodes/ComfyUI-Manager:** 의존성 관리 및 커스텀 노드 설치를 위한 표준 디렉토리 경로 [22]. +- **comfyui-workflow-to-api-converter-endpoint (V2.05):** 워크플로우 의존성 감지를 강화하기 위한 "Marker Node" 기능 구현 [9, 23]. +- **UpdateNodeCatalog 노드:** 가용 노드(네이티브 및 커스텀)를 스캔하여 의존성 유효성 검사에 필요한 카탈로그 파일 업데이트 [16, 17]. +- **NodeValidator:** LLM 기반 생성 워크플로우에서 노드 이름을 실제 로컬 설치 노드와 비교하여 교정하는 검증 노드 [10, 11]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (주요 도구 및 레지스트리 구조 확인됨) +- **출처 신뢰도:** B (공식 문서 및 주요 오픈소스 프로젝트 리드미 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow JSON - ComfyUI]] + - 연결 이유: 의존성 정보가 저장되는 데이터 구조의 표준. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: `class_type` 필드의 중요성. +- [[API JSON (Backend Format)]] + - 연결 이유: 시각 데이터가 제거된 순수 실행 그래프에서의 의존성 정의 방식. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 실질적인 의존성 해결 및 자동 설치 도구. +- [[object_info.json]] + - 연결 이유: 모든 노드 의존성 및 스키마의 런타임 데이터 소스. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI Manager는 서로 다른 리포지토리에서 동일한 `class_type`을 가질 경우 우선순위를 어떻게 결정하는가? [소스에 관련 정보가 부족합니다.] +- SHA-256 모델 해싱이 파일명 불일치를 해결하는 구체적인 알고리즘적 워크플로우는 무엇인가? [12] +- LLM 기반 `NodeValidator`가 오인식(Hallucination) 없이 커스텀 노드를 정확히 매핑하기 위한 프롬프트 최적화 전략은? [10, 20] +- `object_info`를 원격 서버에서 호출할 때 보안 인증이 의존성 정보 노출에 미치는 영향은? [24] +- 의존성 감지를 위한 'Marker Node'가 JSON 구조 내에서 차지하는 데이터 가중치는 어느 정도인가? [9] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 커스텀 노드 개발 시 `INPUT_TYPES`를 정확히 정의하여 `object_info.json`에 반영되도록 설계해야 함 [25]. +- **System Design:** 다중 사용자 환경에서 워크플로우를 배포할 때, 누락된 노드로 인한 빨간색 박스 오류를 방지하기 위해 ComfyUI Manager 호환성을 고려해야 함 [1]. +- **Operation / Maintenance:** 새로운 커스텀 노드 설치 후에는 `UpdateNodeCatalog`를 실행하여 의존성 레지스트리를 갱신해야 함 [17]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: 모델 파일 관리의 일관성 보장 기술. +- [[Retrieval-Augmented Generation (RAG) for Nodes]] + - 확장 방향: 미래의 동적 의존성 탐색 기술 [26]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [27] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Custom Node Registry.md b/10_Wiki/Topics/Comfyui/Custom Node Registry.md new file mode 100644 index 00000000..29b50533 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Custom Node Registry.md @@ -0,0 +1,103 @@ +--- +id: custom-node-registry +title: "Custom Node Registry" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Node Catalog", "Node Schema Registry"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/models/LLM/", "ComfyUI/custom_nodes/ComfyUI-WorkflowGenerator", "/object_info endpoint", "/workflow/convert endpoint"] +github_commit: "" +--- + +# [[Custom Node Registry]] + +## 🎯 한 줄 통찰 (One-line insight) +Custom Node Registry는 ComfyUI의 유연한 확장성을 지탱하는 핵심 데이터베이스로, JSON 워크플로의 추상화된 노드 타입을 실제 Python 실행 로직 및 스키마와 연결하는 권위 있는 원천이다. [1-3] + +## 🧠 핵심 개념 (Core concepts) +- **Node Mapping (class_type):** 워크플로 JSON 내의 `type` 또는 `class_type` 문자열을 로컬 환경에 설치된 실제 Python 클래스 기능과 매핑한다. [2, 4, 5] +- **Schema Discovery (object_info):** 실행 중인 ComfyUI 인스턴스에서 모든 노드의 입력/출력 유형, 필수 여부, 허용 범위를 동적으로 카탈로그화하여 제공한다. [3, 6] +- **Dependency Tracking:** 외부에서 유입된 JSON 워크플로를 로컬 레지스트리와 대조하여 누락된 커스텀 노드 패키지를 식별하고 관리한다. [7, 8] +- **Semantic Validation:** 자연어 기반 워크플로 생성 시, 생성된 노드 이름이 실제 로컬 레지스트리에 존재하는지 검증하고 교정하는 기준점이 된다. [9-11] + +## 🧩 추출된 패턴 (Extracted patterns) +- **Scan-and-Catalog 패턴:** 새로운 커스텀 노드를 설치하거나 업데이트한 후 `UpdateNodeCatalog` 노드 등을 실행하여 로컬 노드 환경을 최신화하고 카탈로그 파일을 생성한다. [11-13] +- **Runtime Resolution 패턴:** 백엔드 엔진은 실행 시점에 JSON의 `class_type`을 레지스트리에서 찾아 기능을 호출하며, 시각적 데이터가 제거된 API 포맷에서 이 매핑이 특히 중요하다. [2, 5, 14] +- **Schema Inversion 패턴:** `/object_info` 엔드포인트를 통해 레지스트리를 외부로 노출함으로써, 외부 앱이 ComfyUI 내부 로직을 모르더라도 노드 인터페이스를 동적으로 구성할 수 있게 한다. [3, 15] + +## 📖 세부 내용 (Details) +Custom Node Registry는 ComfyUI 워크플로 생성 및 직렬화의 근간을 이룬다. 워크플로가 JSON으로 저장될 때, 각 노드는 레지스트리에 등록된 고유한 **class_type**을 기반으로 식별된다. [2, 4] 이는 프론트엔드에서 사용하는 시각적 ID와는 별개의 기능적 키 값이다. [2, 16] + +**주요 구성 요소 및 역할:** +1. **스키마 정의 (object_info.json):** 이 레지스트리는 각 노드가 요구하는 `required` 및 `optional` 입력값, 데이터 타입, 도구 설명(tooltips) 등을 상세히 포함한다. [3] 개발자는 이를 활용해 입력값을 검증하거나 동적으로 워크플로 수정 도구를 빌드할 수 있다. [3, 15, 17] +2. **의존성 해결 및 관리:** ComfyUI Manager는 외부에서 로드된 JSON의 노드 클래스를 로컬 레지스트리와 교차 검증한다. [7] 일치하는 항목이 없을 경우 "Missing Custom Node" 에러(빨간색 박스)를 발생시키고, 레지스트리 정보를 바탕으로 자동 설치를 지원한다. [7, 18] +3. **API 변환 및 검증:** `Workflow to API Converter`와 같은 도구는 정확한 변환을 위해 ComfyUI의 실제 노드 레지스트리를 직접 참조하여 리스트, 딕셔너리 위젯, 서브그래프 등을 처리한다. [19] +4. **LLM 기반 생성의 준거 집단:** 자연어 설명을 워크플로로 변환하는 시스템(`ComfyUI-WorkflowGenerator`)은 레지스트리 데이터를 기반으로 학습되거나, 생성 단계에서 레지스트리와의 시맨틱 매칭을 통해 유효한 그래프 구조를 보장한다. [9, 10, 20] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정적 모델과 동적 레지스트리의 간극:** 고정된 데이터로 학습된 LLM 모델은 학습 시점 이후에 출시된 새로운 커스텀 노드를 레지스트리에서 인식하지 못하는 한계가 있으며, 이를 극복하기 위해 실시간 카탈로그 스캔이 필수적이다. [21-23] +- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 노드 레지스트리 내의 클래스 이름이나 구조가 변경될 수 있으며, 이로 인해 과거 버전의 JSON 파일이 최신 레지스트리에서 제대로 작동하지 않을 수 있다. [24] + +## 🛠️ 적용 사례 (Applied in summary) +- **UpdateNodeCatalog:** 사용자가 설치한 모든 네이티브 및 커스텀 노드를 스캔하여 로컬 카탈로그를 갱신하는 기능이 구현되어 있다. [11, 12] +- **ComfyUI Manager:** JSON 내의 `class_type`을 파싱하여 레지스트리에 없는 패키지를 탐지하고 설치 인터페이스를 제공한다. [7, 8] +- **Workflow to API Converter Endpoint:** 클라이언트 측 JS 로직을 Python으로 변환하여 서버 사이드에서 노드 레지스트리를 참조해 비-API 포맷을 API 포맷으로 변환한다. [19, 25] +- **object_info 엔드포인트:** `/object_info` 경로를 통해 현재 인스턴스의 전체 노드 스키마 레지스트리를 JSON 형태로 배포한다. [15] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례가 소스 코드 및 공식 문서 내 엔드포인트 형태로 다수 발견됨) [7, 15, 19] +- **출처 신뢰도:** B (Official Documentation / GitHub Repository README / API Docs 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow API JSON (Backend Format)]] + - 연결 이유: API 포맷은 시각적 메타데이터 없이 오직 레지스트리의 기능적 키에만 의존하여 실행된다. [2, 26] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터가 백엔드 실행 로직으로 변환되는 방식. [2, 5] +- [[JSON Schema v1.0]] + - 연결 이유: 레지스트리에 정의된 노드 객체들이 준수해야 할 구조적 제약 조건을 정의한다. [4] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 ID, 타입, 위젯 값 등의 기술적 사양. [4, 27] + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 레지스트리 불일치 문제를 해결하고 의존성을 관리하는 가장 보편적인 도구이다. [7, 18] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 누락된 노드 설치 및 패키지 관리 프로세스. [7, 28] +- [[ComfyUI-WorkflowGenerator]] + - 연결 이유: 자연어를 레지스트리에 존재하는 유효한 노드 그래프로 변환하는 파이프라인을 제공한다. [10, 29] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 레지스트리 데이터를 활용한 AI 기반 자동화 방법론. [9, 20, 30] + +### 심층 후속 질문 (Deeper Research Questions) +- 서로 다른 커스텀 노드 패키지 간에 클래스 이름(`class_type`)이 충돌할 경우 레지스트리는 어떤 우선순위로 이를 처리하는가? +- 수백 개의 커스텀 노드가 설치된 환경에서 동적 카탈로그 스캔(`UpdateNodeCatalog`)이 시스템 성능 및 로딩 시간에 미치는 영향은 무엇인가? +- `object_info.json`의 스키마 데이터를 활용하여 외부 웹 대시보드에서 실시간으로 ComfyUI 노드 UI를 완벽하게 재현할 수 있는가? +- 노드 레지스트리의 변경 사항(필드 추가/삭제)이 기존에 직렬화된 JSON 워크플로의 하위 호환성에 미치는 영향과 그 대응 전략은 무엇인가? +- `.cpack.zip`과 같은 워크스페이스 패키징 방식은 레지스트리 의존성 문제를 어떻게 영구적으로 해결하는가? [31] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 외부 애플리케이션 개발 시 `/object_info`를 호출하여 사용자 입력값이 노드 레지스트리 규격에 맞는지 클라이언트 사이드에서 즉시 검증할 수 있다. [3, 15] +- **System Design:** Python 스크립트에서 워크플로를 동적으로 생성할 때 노드 ID 대신 레지스트리의 타이틀이나 클래스 명을 참조하는 래퍼 라이브러리를 사용하여 유지보수성을 높일 수 있다. [32] +- **Operation / Maintenance:** 워크플로 공유 시 `Workflow to API Converter (Marker)` 노드를 추가하여 타인이나 매니저가 레지스트리 의존성을 쉽게 식별하도록 돕는다. [8] +- **Learning Path:** 노드 메뉴얼을 읽는 대신 `object_info` 데이터를 분석하여 특정 노드의 모든 가능한 입력 조합과 데이터 흐름을 기술적으로 파악할 수 있다. [3] + +### 인접 주변 주제 (Adjacent Topics) +- [[Execution Model Inversion]] + - 확장 방향: 레지스트리의 전체 노드 중 최종 출력에 필요한 노드만 선택적으로 실행하는 백엔드 최적화 원리. [33] +- [[Model Hashing]] + - 확장 방향: 노드 정의 외에도 레지스트리에서 참조하는 모델 파일의 일관성을 보장하는 기술. [34] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [Source 26, 28, 37, 41, 133, 151 기반 합성] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Custom Nodes.md b/10_Wiki/Topics/Comfyui/Custom Nodes.md new file mode 100644 index 00000000..9a374fbf --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Custom Nodes.md @@ -0,0 +1,99 @@ +--- +id: custom-nodes +title: "Custom Nodes" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["커스텀 노드", "확장 노드"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes", "GitHub: DanielPFlorian/ComfyUI-WorkflowGenerator", "GitHub: SethRobinson/comfyui-workflow-to-api-converter-endpoint", "GitHub: pydn/ComfyUI-to-Python-Extension"] +github_commit: "bc85382" +--- + +# [[Custom Nodes]] + +## 🎯 한 줄 통찰 (One-line insight) +커스텀 노드는 ComfyUI의 모듈형 아키텍처를 무한히 확장하는 핵심 동력이지만, 워크플로우 JSON의 이식성과 실행 가능성을 결정짓는 가장 큰 종속성 변수이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **생태계 확장성 (Ecosystem Extensibility):** 기본 노드 세트(Core nodes) 외에 전 세계 개발자들이 공유하는 기능을 추가하여 Stable Diffusion뿐만 아니라 비디오, 오디오, 3D 생성 등 모든 유형의 미디어 자산을 생성할 수 있게 한다 [2, 3]. +- **클래스 타입 매핑 (Class_type Mapping):** JSON 워크플로우 파일 내에서 각 노드는 `class_type` 속성을 통해 식별되며, 실행 시 로컬의 커스텀 노드 레지스트리와 대조된다 [4, 5]. +- **종속성 관리 (Dependency Management):** 외부 워크플로우를 불러올 때 해당 시스템에 특정 커스텀 노드가 없으면 'Red Boxes' 에러가 발생하며, 이를 해결하기 위해 ComfyUI Manager와 같은 도구가 필수적이다 [5, 6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **누락 노드 복구 패턴:** 외부 JSON 로드 시 발생하는 'Red Boxes'를 감지하고 ComfyUI Manager를 통해 "Install Missing Custom Nodes"를 실행하여 서버를 재시작하는 복구 흐름이 정형화되어 있다 [5, 6]. +- **마커 노드 활용 패턴:** 워크플로우 공유 시 ComfyUI Manager가 종속성을 더 쉽게 감지할 수 있도록 "Workflow to API Converter (Marker)"와 같은 특정 마커 노드를 의도적으로 포함시킨다 [7]. +- **LLM 기반 자동 검색 패턴:** `Update Node Catalog` 노드를 사용하여 현재 설치된 모든 커스텀 노드를 스캔하고, 이를 LLM이 자연어를 JSON으로 변환할 때 참조하는 데이터베이스로 활용한다 [8, 9]. + +## 📖 세부 내용 (Details) +커스텀 노드는 ComfyUI의 `custom_nodes` 디렉토리에 설치되며, 주로 Git 클론을 통해 추가된다 [10, 11]. 워크플로우 JSON 생성 시, 커스텀 노드의 정보는 다음과 같이 처리된다. + +- **JSON 내 기록:** 워크플로우가 저장될 때 각 커스텀 노드의 설정, 위젯 값, 연결 관계가 JSON의 `nodes` 배열에 포함된다 [12, 13]. API 포맷인 경우 비주얼 메타데이터가 삭제된 `class_type`과 `inputs` 정보만 남는다 [4, 14]. +- **주요 커스텀 노드 예시:** + - **ComfyUI-Manager:** 노드 및 모델 설치/관리의 중추 [10]. + - **Efficiency Nodes:** 여러 노드를 하나로 결합하여 워크플로우를 간소화함 [15, 16]. + - **AnimateDiff Evolved & VideoHelperSuite:** 비디오 생성을 위한 필수 확장 [15, 16]. + - **IPAdapter Plus & ControlNet Aux:** 정밀한 이미지 제어를 위한 노드군 [16, 17]. +- **개발자 도구와의 통합:** `Comfy Nodekit`과 같은 Python 라이브러리는 서버의 커스텀 노드 레지스트리와 자동으로 동기화되어, 프로그래밍 방식으로 워크플로우를 생성할 때 타입 안정성을 제공한다 [18]. 또한 `ComfyUI-to-Python-Extension`은 이러한 커스텀 노드가 포함된 그래프를 순수 Python 스크립트로 변환하여 독립 실행을 지원한다 [19]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 문제:** ComfyUI가 빈번하게 업데이트됨에 따라, 과거에 생성된 JSON 파일 내의 커스텀 노드 구성이 최신 버전의 노드와 충돌하여 제대로 작동하지 않을 수 있다는 경고가 존재한다 [20, 21]. +- **데이터 증발 위험:** 일반적인 이미지 편집기나 소셜 미디어 플랫폼에서 이미지를 처리할 때, 커스텀 노드 정보가 담긴 메타데이터(JSON)가 삭제될 수 있어 전용 추출 도구 사용이 권장된다 [22, 23]. + +## 🛠️ 적용 사례 (Applied in summary) +- **설치 위치:** `ComfyUI/custom_nodes` 디렉토리 하위에 각 노드 패키지가 배치됨 [10, 11]. +- **GitHub 프로젝트:** + - `DanielPFlorian/ComfyUI-WorkflowGenerator`: LLM을 통해 커스텀 노드를 포함한 워크플로우를 자동 생성하는 노드 구현 [24, 25]. + - `SethRobinson/comfyui-workflow-to-api-converter-endpoint`: (커밋 `bc85382`) 비 API 포맷의 커스텀 노드 워크플로우를 API 포맷으로 변환하는 서버 사이드 로직 구현 [26, 27]. +- **의사결정 기록:** ComfyUI Manager의 "Install Missing Custom Nodes" 기능은 커스텀 노드 부재로 인한 워크플로우 실행 실패를 해결하는 표준 운영 절차(SOP)로 확립됨 [5, 6]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (다수의 GitHub 프로젝트 및 공식 튜토리얼을 통해 실무 적용 확인됨) +- **출처 신뢰도:** B (공식 문서 및 주요 개발자 리포지토리 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처 및 기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: 커스텀 노드는 JSON 파일의 내용을 구성하는 가장 동적인 요소임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 `class_type`이 어떻게 실제 기능으로 매핑되는지 이해 가능. +- [[Workflow API JSON]] + - 연결 이유: API 실행 시 커스텀 노드의 입출력 구조가 이 포맷에 맞춰 최적화됨. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 없는 환경에서의 커스텀 노드 호출 메커니즘. + +#### [구현 및 관리 도구] +- [[ComfyUI Manager]] + - 연결 이유: 커스텀 노드의 설치, 업데이트, 누락 복구를 담당하는 전용 도구임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 복잡한 종속성 문제를 자동화하는 방법. + +### 심층 후속 질문 (Deeper Research Questions) +- 커스텀 노드의 `class_type`이 중복될 경우 ComfyUI는 어떤 우선순위로 노드를 로드하는가? +- `Update Node Catalog` 노드는 어떤 방식으로 로컬에 설치되지 않은 원격 커스텀 노드의 정보를 수집할 수 있는가? [9] +- 커스텀 노드 내에서 정의된 `INPUT_TYPES`가 JSON Schema v1.0 규격과 충돌할 때 발생하는 예외 처리 메커니즘은 무엇인가? [28] +- `comfy-pack`과 같은 도구에서 모델 해싱(SHA-256)을 사용할 때 커스텀 노드 내부의 모델 경로 의존성은 어떻게 해결되는가? [29] +- LLM 기반 워크플로우 생성기에서 학습 데이터에 없는 최신 커스텀 노드를 인식시키기 위한 RAG(Retrieval-Augmented Generation) 적용 방안은 무엇인가? [30] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 새로운 기능을 개발할 때 `ComfyUI/custom_nodes`에 Python 클래스를 정의하고 이를 JSON에서 호출 가능한 형태로 등록함 [3, 10]. +- **System Design:** API 서버 구축 시 모든 필요한 커스텀 노드가 사전 설치된 Docker 이미지를 준비해야 함 [31]. +- **Operation / Maintenance:** 워크플로우 공유 시 "Red Box" 발생을 최소화하기 위해 필수 커스텀 노드 목록을 별도로 제공하거나 마커 노드를 포함함 [6, 7]. +- **Learning Path:** 기본 워크플로우 숙지 후, `Efficiency Nodes`나 `Manager` 설치를 통해 고급 워크플로우 설계 단계로 진입함 [15, 32]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: 커스텀 노드가 사용하는 특정 모델 파일의 이름 불일치 문제를 해결하는 보완 기술 [29]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source identifiers: [1, 3, 5, 6, 10, 19, 25, 26]) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Directed Acyclic Graph (DAG).md b/10_Wiki/Topics/Comfyui/Directed Acyclic Graph (DAG).md new file mode 100644 index 00000000..798afeea --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Directed Acyclic Graph (DAG).md @@ -0,0 +1,95 @@ +--- +id: directed-acyclic-graph-(dag) +title: "Directed Acyclic Graph (DAG)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["유향 비순환 그래프", "실행 그래프"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["workflow_api.json", "Execution Model Inversion", "WorkflowExecutor", "validate_prompt"] +github_commit: "bc85382, 82df278" +--- + +# [[Directed Acyclic Graph (DAG)]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI의 워크플로우 아키텍처는 노드와 링크를 통해 데이터 흐름을 정의하며, 순환하지 않는 방향성을 가진 **Directed Acyclic Graph(DAG)** 구조를 핵심 실행 모델로 채택한다 [1]. + +## 🧠 핵심 개념 (Core concepts) +- **Node-based Connectivity:** 프로그램 객체인 노드들이 서로 연결되어 네트워크(그래프)를 형성하며, 각 노드는 모델 로더, 샘플러, 인코더 등의 특정 기능을 수행한다 [1-3]. +- **Directional Data Flow:** 데이터는 링크를 통해 한 노드의 출력 슬롯에서 다른 노드의 입력 슬롯으로 정해진 방향에 따라 흐른다 [1, 4]. +- **Acyclicity (비순환성):** 그래프 내에서 경로가 자기 자신으로 돌아오지 않는 비순환 구조를 가져 실행의 시작과 끝이 명확하다 [1]. +- **Serialization:** 복잡한 DAG 네트워크는 JSON 형식으로 직렬화되어 이식성, 버전 관리 및 프로그래밍 방식의 자동화를 가능하게 한다 [1]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Execution Model Inversion (실행 모델 역전):** 모든 노드를 순차 실행하는 대신, 'Save Image'와 같은 최종 출력 노드에서 시작하여 그래프를 역방향으로 추적, 필요한 종속성만 식별하여 실행하는 최적화 패턴이다 [5]. +- **Bifurcation of Formats (형식의 이분화):** 시각적 레이아웃을 포함하는 **Frontend Format**과 순수 실행 논리(DAG)만을 남긴 **Backend/API Format**으로 구분되어 관리된다 [6, 7]. +- **Slot-based Indexing:** 연결은 단순히 노드 간의 결합이 아니라, 특정 출력 슬롯(예: VAE Loader의 VAE 슬롯)에서 특정 입력 슬롯으로 정밀하게 매핑되는 인덱싱 구조를 따른다 [4]. + +## 📖 세부 내용 (Details) +ComfyUI는 스테이블 디퓨전과 같은 복잡한 생성형 AI 프로세스를 절차적 프레임워크로 추상화하기 위해 DAG를 활용한다 [1]. 워크플로우 자체가 DAG와 동의어로 사용되며, 이는 3D 프로그램의 '씬 그래프'나 영상 편집 프로그램의 '프로젝트 파일'과 유사한 역할을 수행한다 [8]. + +그래프의 구조적 무결성은 **JSON Schema v1.0** 규격에 의해 검증된다 [9]. 각 노드는 고유 ID, 클래스 타입(type), 그리고 위젯 값을 포함하며, `inputs` 배열은 유입되는 링크의 ID를 기록하고 `outputs` 배열은 해당 데이터를 소비하는 하위 노드들의 링크 ID 리스트를 유지한다 [4, 9]. API 형식의 JSON에서는 시각적 메타데이터가 제거되고, 링크가 별도의 배열 대신 노드 입력 내부에 직접 삽입되어 실행 효율성을 극대화한다 [6, 10]. + +실행 단계에서 엔진은 DAG의 특성을 이용해 불필요한 계산을 배제한다. 최종 출력에 기여하지 않는 노드들이 그래프에 포함되어 있더라도, 역방향 그래프 탐색(Backward Traversal)을 통해 이를 무시함으로써 성능 저하 없이 복잡한 워크플로우를 구성할 수 있다 [5]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **데이터 보존의 취약성:** DAG 구조를 PNG 메타데이터(tEXt/zTXt 청크)에 저장할 수 있으나, 일반적인 이미지 편집기나 소셜 미디어 플랫폼을 거치면 이 메타데이터가 유실되어 그래프 구조가 파괴될 수 있다는 점이 주의사항으로 언급된다 [11]. +- **형식 간의 불완전한 호환성:** API 형식으로 저장된 그래프(DAG 최적화본)를 다시 UI로 불러올 경우, 시각적 레이아웃 정보가 없어 노드들이 겹치거나 뼈대만 남는 현상이 발생할 수 있다 [12]. + +## 🛠️ 적용 사례 (Applied in summary) +- **workflow_api.json:** 시각적 요소가 제거된 순수 DAG 형태의 실행 파일 형식으로, 서버 측 처리 및 API 호출에 최적화되어 적용됨 [6, 13]. +- **Execution Model Inversion:** ComfyUI 서버 아키텍처에서 노드 실행 우선순위를 결정하고 효율성을 확보하기 위한 핵심 알고리즘으로 적용됨 [5, 14]. +- **WorkflowExecutor 클래스:** Python 스크립트에서 워크플로우 JSON을 `ExecutionList`로 변환하고 각 노드를 순회하며 실행하는 로직에 적용됨 [15]. +- **validate_prompt 함수:** 워크플로우를 실행하기 전 DAG의 유효성을 검증하는 내부 함수로 활용됨 [15]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (ComfyUI 공식 문서 및 아키텍처 분석 자료 기반) +- **출처 신뢰도:** B (Official Documentation / Technical Architectures via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: DAG 구조를 지속 가능한 파일 형태로 변환하는 상위 프로세스. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 기반 시스템의 직렬화 메커니즘. + +#### [실무 구현 도구] +- [[API Format (workflow_api.json)]] + - 연결 이유: DAG의 실행 논리만이 정제된 최종 데이터 포맷. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 메타데이터와 실행 그래프의 차이점. +- [[Execution Model Inversion]] + - 연결 이유: DAG 구조를 효율적으로 처리하기 위한 엔진의 핵심 알고리즘. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 그래프 탐색 및 최적화 원리. + +### 심층 후속 질문 (Deeper Research Questions) +- DAG 구조 내에서 의도적인 순환(Looping)이 필요한 경우(예: 반복 개선) ComfyUI는 이를 어떤 방식으로 우회하거나 처리하는가? +- Execution Model Inversion이 중첩된 [[Subgraph]] 구조를 만났을 때, 그래프 탐색의 깊이 제한이나 우선순위는 어떻게 관리되는가? [16, 17] +- 노드 ID가 중복되거나 유실된 손상된 DAG 구조를 복구하기 위한 알고리즘적 전략이 소스 데이터에 존재하는가? +- LLM 기반의 워크플로우 생성기([[ComfyUI-WorkflowGenerator]])는 DAG의 논리적 타당성을 어떤 의미론적 검증 과정을 통해 확보하는가? [18] +- `object_info.json`에 정의된 스키마가 DAG의 연결 가능성을 제한하는 제약 조건으로 어떻게 작용하는가? [19] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬의 `json` 라이브러리를 사용하여 API JSON의 노드 ID를 추적하고 `inputs` 값을 동적으로 수정하여 대량의 이미지를 생성할 수 있다 [20, 21]. +- **System Design:** 서버리스 환경(Mystic, Replicate 등)에 배포할 때, DAG 구조에서 불필요한 시각적 데이터를 제거한 API 형식을 사용해야 통신 효율성이 높아진다 [22, 23]. +- **Operation / Maintenance:** 'Red Nodes'(누락된 노드) 오류 발생 시, DAG 스키마를 파싱하여 필요한 커스텀 노드 패키지를 식별하고 설치하는 것이 필수적이다 [24]. +- **Learning Path:** 복잡한 워크플로우를 이해하려면 출력 노드에서 거꾸로 입력을 찾아가는 역방향 추적 방식을 익히는 것이 효과적이다 [5]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Litegraph]] + - 확장 방향: ComfyUI 프론트엔드에서 DAG를 시각적으로 렌더링하기 위해 사용하는 표준 포맷 연구. [6, 25] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Execution Model Inversion.md b/10_Wiki/Topics/Comfyui/Execution Model Inversion.md new file mode 100644 index 00000000..5e04bb1c --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Execution Model Inversion.md @@ -0,0 +1,94 @@ +--- +id: execution-model-inversion +title: "Execution Model Inversion" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["역방향 실행 모델", "Output-Driven Traversal"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Architecture"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI Server Documentation"] +github_commit: "" +--- + +# [[Execution Model Inversion]] + +## 🎯 한 줄 통찰 (One-line insight) +최종 출력 노드에서 시작하여 필요한 의존성만을 역추적해 실행함으로써, 워크플로 내 불필요한 노드가 성능에 미치는 영향을 완전히 배제하는 ComfyUI의 최적화 아키텍처 [1]. + +## 🧠 핵심 개념 (Core concepts) +- **출력 기반 역방향 탐색 (Output-Driven Traversal):** 실행 엔진이 모든 노드를 순차적으로 처리하는 대신, 'Save Image'와 같은 최종 출력 노드에서 시작하여 그래프를 거꾸로 거슬러 올라가며 필요한 노드만 식별함 [1]. +- **의존성 자동 식별 (Dependency Identification):** 최종 결과물에 기여하는 노드들만 실행 목록(Execution List)에 포함시키고, 연결되어 있더라도 결과에 영향을 주지 않는 노드는 무시함 [1, 2]. +- **성능 격리 (Performance Isolation):** 생성된 JSON 내에 수십 개의 미사용 노드가 포함되어 있더라도 백엔드에서 이를 실행하지 않으므로 실행 성능에 무리가 가지 않음 [1]. +- **DAG(유향 비순환 그래프) 기반 논리:** 워크플로를 방향성이 있고 순환하지 않는 그래프 구조로 취급하여 논리적인 역추적을 가능케 함 [1, 3]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **의존성 체인 검증 패턴:** `WorkflowExecutor`가 `validate_prompt` 함수를 사용하여 워크플로의 유효성을 검사하고 이를 `ExecutionList`로 변환하는 구조 [2]. +- **결과 중심 데이터 흐름:** 데이터가 모델 로더에서 시작하여 샘플러를 거쳐 출력으로 흐르지만, 실행 제어는 그 반대 방향인 출력에서 시작됨 [1, 3]. + +## 📖 세부 내용 (Details) +Execution Model Inversion은 ComfyUI의 아키텍처에서 가장 정교한 개념 중 하나로, 워크플로가 처리되는 방식을 최적화하는 핵심 기제이다 [1]. + +- **작동 원리:** 엔진은 그래프의 모든 노드를 실행하는 대신 'Save Image'와 같은 출력 노드에서 시작한다 [1]. 여기서부터 그래프를 역방향으로 탐색하여 최종 출력에 도달하기 위해 반드시 실행되어야 하는 상위 노드(의존성)들을 계층적으로 파악한다 [1]. +- **JSON 설계와의 관계:** 이 모델 덕분에 사용자는 복잡하고 큰 규모의 워크플로 JSON을 생성하면서도 성능 저하를 걱정할 필요가 없다 [1]. 백엔드 엔진은 최종 출력에 기여하지 않는 모든 노드를 지능적으로 무시하기 때문이다 [1]. +- **API 효율성:** 특히 **API Format(workflow_api.json)**으로 변환된 워크플로를 실행할 때, 이 모델은 최소한의 필수 연산만을 보장하여 서버 자원을 효율적으로 관리할 수 있게 한다 [1, 4]. +- **캐싱 메커니즘과의 연계:** `ExecutionCache`와 결합하여, 역방향 탐색 중 이미 계산된 결과가 있는 노드의 경우 실행을 건너뛰고 캐시된 데이터를 즉시 반환함으로써 효율을 극대화한다 [5]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **전체 실행 vs 부분 실행:** 전통적인 파이프라인 방식이 모든 단계를 순차적으로 실행하는 것과 달리, ComfyUI는 출력 노드에 도달하기 위한 최소 경로만을 실행하는 "Lazy Evaluation"과 유사한 특성을 보인다 [1]. +- **JSON의 유연성:** 소스에 따르면 워크플로 파일 내에 사용하지 않는 노드가 많아도 시스템에 무리가 가지 않는다는 점은 일반적인 소프트웨어 최적화 상식(리소스 최소화)과는 다른 ComfyUI만의 설계적 특징이다 [1]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI Server 공식 가이드:** 공식 문서의 'ComfyUI Server' 섹션 내에 "Execution Model Inversion Guide"라는 명칭의 기술 문서로 상세히 다루어지고 있음 [6]. +- **WorkflowExecutor 구현:** 독립 실행형 스크립트 실행 시 `WorkflowExecutor` 클래스가 `validate_prompt`를 통해 실행 목록을 생성하는 과정에 이 논리가 내재되어 있음 [2]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 가이드라인 존재 확인 [6]) +- **출처 신뢰도:** B (Official Documentation 및 전문 분석 리포트 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: Execution Model Inversion이 작동하기 위한 구조적 토대임 [3]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 링크가 어떻게 논리적 흐름을 형성하는지 파악 가능. +- [[ComfyUI Backend Engine]] + - 연결 이유: 역방향 탐색과 실행 목록 생성을 담당하는 주체임 [1, 2]. + +#### [구현/활용 도구] +- [[API Format (workflow_api.json)]] + - 연결 이유: UI 정보가 제거된 실행 중심의 JSON 포맷으로, 이 모델에 최적화되어 있음 [1, 4]. +- [[WorkflowExecutor]] + - 연결 이유: 역방향 탐색 논리를 실제 실행 코드로 구현한 클래스임 [2]. + +### 심층 후속 질문 (Deeper Research Questions) +- Execution Model Inversion 환경에서 'Bypass'된 노드는 역추적 과정에서 어떻게 처리되는가? [7] +- 여러 개의 출력 노드가 존재할 경우, 엔진은 각 출력별로 독립적인 역방향 탐색을 수행하는가? +- `ExecutionCache`가 역방향 탐색 경로에 있는 특정 노드의 실행 여부를 결정하는 구체적인 임계값은 무엇인가? [5] +- 사용자가 명시적으로 모든 노드를 강제 실행(Force Execute)하도록 설정할 수 있는 우회 방법이 존재하는가? +- 자연어 기반 워크플로 생성 도구인 `ComfyUI-WorkflowGenerator`는 이 실행 모델을 고려하여 노드 연결을 생성하는가? [8, 9] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** API 서버 구축 시 워크플로에 테스트용 노드가 섞여 있더라도 성능 영향을 최소화하며 배포 가능 [1]. +- **System Design:** 대규모 자동화 배너 광고 시스템 등에서 다양한 변종 워크플로를 하나의 JSON 템플릿으로 관리할 때 유리함 [10]. +- **Operation / Maintenance:** 워크플로 디버깅 시 실행되지 않는 노드를 식별하여 의존성 연결 오류를 파악하는 지표로 활용 가능 [11]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Lazy Evaluation in Graph Theory]] + - 확장 방향: 컴퓨터 과학 관점에서의 계산 최적화 기법 비교. +- [[Workflow JSON v1.0 Schema]] + - 확장 방향: 역방향 탐색에 필수적인 `id`, `inputs`, `links` 속성의 기술적 명세 이해 [12, 13]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on Source [1], [6]) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/ExecutionCache.md b/10_Wiki/Topics/Comfyui/ExecutionCache.md new file mode 100644 index 00000000..7e8ef662 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/ExecutionCache.md @@ -0,0 +1,60 @@ +--- +id: executioncache +title: "ExecutionCache" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["Standalone Execution Script (GitHub Gist)"] +github_commit: "" +--- + +# [[ExecutionCache]] + +## 🎯 한 줄 통찰 (One-line insight) +독립형 스크립트 환경에서 ComfyUI 워크플로우를 실행할 때 노드 출력 및 UI 데이터를 통합 관리하여 중복 계산을 방지하고 성능을 최적화하는 핵심 캐시 관리 클래스 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **통합 캐시 관리 (Unified Cache Management):** 노드 출력, UI 데이터, 객체 인스턴스의 캐싱을 중앙에서 처리하여 워크플로우 실행 효율을 높임 [2]. +- **성능 최적화 (Performance Optimization):** 불필요하고 중복되는 계산을 줄여 독립형 실행 환경의 오버헤드를 최소화함 [2]. +- **HierarchicalCache 기반 구조:** ComfyUI의 기본 계층적 캐시(HierarchicalCache) 메커니즘 위에 구축되어 노드 객체와 결과 데이터를 구조적으로 저장함 [2]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **독립형 실행 아키텍처 패턴:** 워크플로우 실행을 조율하는 `WorkflowExecutor`와 데이터 영속성을 관리하는 `ExecutionCache`가 결합되어 서버 없이도 워크플로우를 실행하는 구조를 형성함 [1, 3]. +- **데이터 캡슐화 패턴:** 노드 객체(node object), 출력 데이터(output data), UI 데이터를 하나의 캐시 단위 내에 보관하여 ComfyUI와의 호환성을 유지함 [2]. + +## 📖 세부 내용 (Details) +ExecutionCache는 ComfyUI 워크플로우를 서버 기반의 웹 인터페이스 없이 **독립형 파이썬 스크립트**로 실행하기 위해 설계된 핵심 컴포넌트임 [1, 4]. 이 클래스는 워크플로우 실행 과정에서 발생하는 다양한 데이터를 효율적으로 관리하는 역할을 수행함. + +주요 기능은 다음과 같음: +1. **데이터 저장 및 관리:** 각 노드의 실행 결과인 출력 데이터뿐만 아니라, UI 관련 데이터 및 생성된 객체 인스턴스 정보를 캐시에 저장함 [2]. +2. **중복 계산 방지:** 동일한 입력에 대해 이미 계산된 결과가 캐시에 존재할 경우 이를 재사용함으로써 실행 시간을 단축하고 컴퓨팅 자원을 절약함 [2]. +3. **호환성 유지:** ComfyUI 내부의 `HierarchicalCache`를 기반으로 동작하도록 설계되어, 서버 환경에서의 실행 로직과 최대한 유사한 동작 방식을 보장함 [2, 3]. + +이 클래스는 `WorkflowExecutor`와 함께 사용되며, `WorkflowExecutor`가 노드를 실행(`_execute_node`)할 때 필요한 입력 데이터를 조회하거나 실행 결과를 저장하는 저장소 역할을 담당함 [1, 2]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **독립형 실행의 한계:** ExecutionCache를 포함한 독립형 스크립트 방식은 ComfyUI 서버와 웹 UI가 밀접하게 연결된 기본 구조를 우회하려는 시도이나, 여전히 ComfyUI의 런타임 환경(torch 등)에 의존함 [5-7]. +- **캐시 생명주기:** 서버 환경의 Web UI 프롬프트/결과 캐싱과 달리, 이를 활용한 생성된 스크립트는 일반적으로 단발성 실행(single-shot)으로 동작하며 실행 종료 시 모델/캐시 정리를 수행함 [8]. + +## 🛠️ 적용 사례 (Applied in summary) +- **독립형 실행 스크립트 (Standalone Execution Script):** SDXL Turbo 워크플로우 등을 API JSON 형식에서 파이썬 스크립트로 직접 실행하기 위한 `WorkflowExecutor` 시스템의 일부로 구현됨 [1, 3, 4]. 해당 코드는 특정 GitHub Gist를 통해 공유되고 있음 [1, 4]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (전문 개발자 블로그 및 기술 분석 자료 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Frontend Format (workflow.json).md b/10_Wiki/Topics/Comfyui/Frontend Format (workflow.json).md new file mode 100644 index 00000000..8a90a033 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Frontend Format (workflow.json).md @@ -0,0 +1,70 @@ +--- +id: frontend-format-(workflow.json) +title: "Frontend Format (workflow.json)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "RunComfy Serverless API"] +github_commit: "" +--- + +# [[Frontend Format (workflow.json)]] + +## 🎯 한 줄 통찰 (One-line insight) +Frontend Format(`workflow.json`)은 ComfyUI의 **Litegraph 표준**을 따르며, 노드 간의 실행 로직뿐만 아니라 캔버스상의 시각적 레이아웃과 그룹 정보를 모두 보존하는 **인간 중심의 공유 및 편집용 블루프린트**이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **시각적 메타데이터(UI Metadata) 포함**: 노드의 위치(`pos`), 크기(`size`), 색상, 그룹화 구조 및 노드의 축소(collapsed) 또는 고정(pinned) 여부와 같은 시각적 상태 정보를 모두 포함한다 [1, 4, 5]. +- **Litegraph 표준 준수**: 웹 인터페이스에서의 시각적 렌더링 및 조작에 최적화된 데이터 구조를 따른다 [1, 2]. +- **명시적 링크 표현 (Explicit Links)**: 연결을 노드 내부에 매핑하는 대신, 별도의 `links` 배열 내에서 고유 ID를 가진 명시적인 연결 객체로 관리한다 [2, 4, 6]. +- **가역성(Reversibility)**: 생성된 이미지 메타데이터에 포함되어 드래그 앤 드롭만으로 원본 노드 그래프를 완벽하게 재구성할 수 있게 한다 [7-9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **포맷의 이분화(Bifurcation)**: ComfyUI는 사용자의 시각적 편집을 위한 'Frontend 포맷'과 서버의 실행 효율성을 위한 'Backend/API 포맷'을 엄격히 구분하여 운영한다 [1, 10]. +- **메타데이터 임베딩(Metadata Embedding)**: 생성된 PNG/WebP 파일의 `tEXt` 또는 `zTXt` 청크에 프론트엔드 워크플로우를 저장하여 이미지가 곧 소스 코드가 되는 패턴을 형성한다 [8, 9, 11]. +- **의존성 기반 노드 ID 할당**: 각 노드는 생성 순서 또는 사용자 정의에 따라 고유한 숫자형 문자열 ID(예: "37")를 부여받아 그래프 탐색의 키로 활용된다 [4, 5, 12]. + +## 📖 세부 내용 (Details) +프론트엔드 포맷은 ComfyUI 웹 인터페이스에서 **기본 저장(Ctrl+S)** 시 생성되는 표준 규격이다 [13]. 이는 사용자 경험을 유지하기 위해 설계되었으며, 워크플로우를 재로드했을 때 모든 노드가 정확한 좌표에 나타나도록 보장한다 [13, 14]. + +**JSON 스키마 v1.0 구성 요소 [5, 6, 15]**: +- **nodes**: 개별 노드 객체의 배열로 구성된다. + - `id`: 그래프 탐색을 위한 고유 식별자. + - `type`: 노드 레지스트리에 매핑된 클래스 이름. + - `pos`/`size`: 캔버스 좌표 및 시나리오 렌더링 크기. + - `widgets_values`: 슬라이더, 텍스트 박스, 토글 등 사용자 입력값의 배열. + - `order`: 실행 또는 렌더링 권장 순서. + - `mode`: 노드의 활성/비활성/바이패스 상태. +- **links**: 노드 간의 연결을 정의하는 상위 레벨 배열로, `[origin_id, origin_slot, target_id, target_slot, type]` 등의 정보를 포함하는 6개 항목 배열 또는 구조화된 객체 형태를 띤다 [6]. + +이 포맷은 **API 포맷과 대조**적이다. API 포맷은 시각적 메타데이터를 제거하고 실행에 필요한 로직만 남긴 '스트림라인' 버전으로, 프론트엔드 파일을 API 엔드포인트에 직접 보낼 경우 오류가 발생할 수 있다 [1, 14, 16]. 따라서 전문적인 자동화 환경에서는 프론트엔드 포맷을 원본(Source of truth)으로 관리하고, 실행 직전에 API 포맷으로 변환하는 프로세스가 권장된다 [17, 18]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 문제**: ComfyUI의 잦은 업데이트로 인해 구버전에서 생성된 프론트엔드 JSON 파일이 최신 버전에서 제대로 작동하지 않거나 시각적으로 깨지는 현상이 발생할 수 있다 [19]. +- **데이터 유실 위험**: 이미지에 포함된 프론트엔드 메타데이터는 소셜 미디어나 이미지 편집기(GIMP 등)를 거칠 경우 파일 크기 최적화 또는 개인정보 보호를 이유로 제거되는 경우가 많아 가역성이 파괴될 수 있다 [9, 20]. +- **API 실행 불가**: 프론트엔드 JSON은 `/prompt` 엔드포인트에서 직접 실행할 수 없으며, 반드시 API 포맷으로의 변환 과정이 선행되어야 한다 [16, 17]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint**: `workflow.json`(프론트엔드 포맷)을 입력받아 서버 측에서 API 포맷으로 자동 변환해 주는 커스텀 노드 프로젝트에 적용됨 [16, 18, 21]. +- **ComfyUI-to-Python-Extension**: 프론트엔드 메타데이터를 유지하여 생성된 Python 스크립트로 만든 이미지가 다시 ComfyUI로 드래그 앤 드롭될 때 워크플로우를 복구할 수 있도록 구현됨 [11]. +- **RunComfy Serverless**: 배포 시 사용자가 업로드한 `workflow.json`에서 레이아웃 정보를 추출하고 시각화 가이드로 활용함 [3, 10]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견으로 applied 단계로 승격 가능) +- **출처 신뢰도:** B (Official Documentation 및 전문 개발자 기술 문서 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. 본 문서는 소스 데이터의 기술적 명세(v1.0 스키마)와 운영 패턴(포맷 이분화)을 중심으로 합성됨. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Generative AI Pipeline.md b/10_Wiki/Topics/Comfyui/Generative AI Pipeline.md new file mode 100644 index 00000000..8f06eb68 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Generative AI Pipeline.md @@ -0,0 +1,67 @@ +--- +id: generative-ai-pipeline +title: "Generative AI Pipeline" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI Workflow JSON Serialization"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint/README.md", "DanielPFlorian/ComfyUI-WorkflowGenerator", "pydn/ComfyUI-to-Python-Extension", "ComfyUI/custom_nodes", "ComfyUI/models/LLM/"] +github_commit: "bc85382, 82df278, 6cdcc23" +--- + +# [[Generative AI Pipeline]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로 JSON은 복잡한 생성형 AI 파이프라인을 방향성 비순환 그래프(DAG) 형태로 직렬화하여 시각적 디자인과 프로그래밍적 실행 간의 가교 역할을 하는 핵심 청사진이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **형식의 이분화 (Bifurcation of Formats):** 시각적 레이아웃과 메타데이터를 포함한 '프론트엔드 형식(workflow.json)'과 실행에 필요한 필수 논리만 남긴 'API 형식(workflow_api.json)'으로 구분된다 [2, 4, 5]. +- **메타데이터 임베딩 (Metadata Embedding):** 생성된 PNG 이미지의 tEXt 또는 zTXt 청크 내에 JSON 워크플로 데이터를 숨겨 저장함으로써 이미지 자체가 워크플로 백업 역할을 수행하게 한다 [6-8]. +- **LLM 기반 합성 (LLM-Driven Synthesis):** 자연어 설명을 통해 노드 그래프를 자동 생성하는 다단계 파이프라인(생성-검증-구축)을 통해 비기술자도 복잡한 파이프라인을 구축할 수 있게 한다 [9-11]. +- **실행 모델 역전 (Execution Model Inversion):** 최종 출력 노드에서 시작하여 필요한 의존성만 역추적하여 실행함으로써 그래프 내 미사용 노드의 성능 영향을 최소화한다 [12]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **데이터 복구 및 추출 패턴:** 전용 도구(exiftool)나 온라인 추출기를 사용하여 온라인 플랫폼에서 제거되기 쉬운 이미지 메타데이터 내의 JSON 워크플로를 복구한다 [13-15]. +- **API 정규화 패턴:** 프론트엔드 형식에서 링크 객체를 제거하고 노드 입력값 내에 직접 소스 노드 ID와 슬롯 번호를 임베딩하여 실행 그래프를 간소화한다 [2, 16, 17]. +- **동적 파라미터 주입:** Python 스크립트나 래퍼 라이브러리를 통해 JSON 딕셔너리를 직접 조작하여 시드(Seed), 프롬프트 등을 동적으로 변경하며 대량 생성을 자동화한다 [18-20]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로 JSON 생성은 사용자의 목적에 따라 수동 내보내기, 이미지 메타데이터 추출, 프로그래밍적 생성 및 LLM 기반 합성의 네 가지 경로로 나뉜다. + +**1. 수동 및 시각적 생성:** 사용자는 ComfyUI 웹 인터페이스에서 노드를 연결하여 파이프라인을 설계한다. `Ctrl + S` 또는 메뉴의 'Export' 기능을 통해 프론트엔드 형식의 JSON을 생성할 수 있으며, 이는 노드 위치, 크기, 그룹화 정보 등 캔버스 레이아웃 메타데이터를 모두 포함한다 [21, 22]. API 호출을 위해서는 설정에서 'Dev mode'를 활성화한 후 'Save (API format)'를 선택해야 한다 [23, 24]. + +**2. 이미지 기반 워크플로 추출:** ComfyUI에서 생성된 모든 PNG 이미지는 기본적으로 워크플로 데이터를 포함한다 [25]. 사용자는 이미지를 캔버스에 드래그 앤 드롭하거나 `exiftool -b -workflow input.png > workflow.json` 명령어를 사용하여 JSON을 추출할 수 있다 [14, 26]. 다만, 이미지 편집기나 SNS 업로드 시 메타데이터가 삭제될 수 있으므로 주의가 필요하다 [8, 27]. + +**3. 프로그래밍적 및 API 기반 생성:** 개발자는 Python의 `json` 라이브러리를 사용하여 워크플로 템플릿의 특정 노드 ID와 입력값(inputs)을 수정할 수 있다 [18]. `Comfy API Simplified`와 같은 래퍼는 숫자 ID 대신 노드 제목으로 접근할 수 있게 하여 유지보수성을 높이며, `ComfyUI-to-Python-Extension`은 JSON을 직접 실행 가능한 `.py` 스크립트로 변환한다 [19, 28]. + +**4. LLM 기반 자연어 생성:** `ComfyUI-WorkflowGenerator`와 같은 최신 시스템은 Qwen2.5-14B와 같은 미세 조정된 모델을 사용하여 사용자의 의도를 해석한다 [9, 29]. 이 과정은 1) 논리적 그래프 구조 생성(Generator), 2) 로컬 노드 레지스트리와의 이름 일치 여부 검증(Validator), 3) 실행 가능한 JSON으로 컴파일(Builder)하는 3단계 파이프라인을 거친다 [10, 11]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 문제:** ComfyUI의 잦은 업데이트로 인해 이전 버전의 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다는 점이 지적되었다 [30]. +- **API 형식의 불완전성:** API 형식의 JSON은 실행에는 최적화되어 있으나 시각적 데이터가 제거되어 있어, 이를 다시 UI로 불러올 경우 워크플로의 구조가 파괴된 '스켈레톤' 상태로 나타나는 한계가 있다 [27, 31]. +- **의존성 오류:** 외부 소스에서 로드한 JSON은 'Missing Custom Nodes' 오류(빨간색 박스)를 일으킬 수 있으며, 이는 ComfyUI Manager를 통한 설치 및 서버 재시작으로 해결해야 한다 [32, 33]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 서버 측에서 프론트엔드 형식을 API 형식으로 변환하는 `/workflow/convert` 엔드포인트를 제공한다 (Commit `bc85382`) [31, 34, 35]. +- **ComfyUI-WorkflowGenerator:** 사용자의 자연어 명령(예: "Create a text-to-image workflow using SDXL")을 받아 `ComfyUI/models/LLM/` 내의 모델을 사용하여 워크플로를 자동 생성한다 [11, 36, 37]. +- **ComfyUI-to-Python-Extension:** 워크플로 JSON을 독립형 Python 스크립트로 변환하여 `COMFYUI_PATH` 환경 변수 설정을 통해 서버 없이도 실행 가능한 환경을 구축한다 [28, 38]. +- **P-Reinforce 적용 위치:** `ComfyUI/custom_nodes/` 디렉토리에 설치되는 다양한 커스텀 노드 패키지들에서 JSON 규격 v1.0에 맞춘 직렬화 로직이 구현되어 있다 [39-41]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/JSON Schema v1.0.md b/10_Wiki/Topics/Comfyui/JSON Schema v1.0.md new file mode 100644 index 00000000..d01ce5f0 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/JSON Schema v1.0.md @@ -0,0 +1,109 @@ +--- +id: json-schema-v1.0 +title: "JSON Schema v1.0" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI Workflow JSON v1.0"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "JSON Schema"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["/specs/workflow_json"] +github_commit: "" +--- + +# [[JSON Schema v1.0]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우 JSON v1.0은 Draft-07 사양을 준수하며, 노드 기반의 생성형 AI 파이프라인을 시각적 메타데이터와 실행 논리로 이원화하여 직렬화하는 표준 규격이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **Draft-07 Specification:** ComfyUI 워크플로우 JSON의 구조적 무결성을 보장하는 최신 공식 스키마 표준이다 [2]. +- **데이터 이원화 (Bifurcation):** 사용자 인터페이스용 'Frontend Format'과 서버 실행용 'API Format'으로 나뉘어 관리된다 [1, 3]. +- **노드 객체 속성 (Node Object Properties):** 각 노드는 ID, 유형, 위치(pos), 크기(size), 위젯 값(widgets_values) 등의 필수 및 선택적 속성을 정의해야 한다 [2, 4]. +- **슬롯 및 링크 연결성 (Slot & Link Connectivity):** 노드 간의 데이터 흐름은 고유한 링크 ID와 입력/출력 슬롯 인덱싱을 통해 정의된다 [5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **실행 모델 반전 (Execution Model Inversion):** 엔진이 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색, 필요한 의존성만 식별하여 실행하는 최적화 패턴을 따른다 [6]. +- **메타데이터 임베딩 (Metadata Embedding):** PNG 파일의 tEXt 또는 zTXt 청크에 Frontend와 API 포맷의 JSON 데이터를 동시에 저장하여 시각적 편집과 프로그래밍적 재실행을 모두 지원한다 [7-9]. +- **버전 호환성 제약:** 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 ComfyUI 버전에서 정상 작동하지 않을 수 있는 패턴이 관찰된다 [10]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우 JSON v1.0은 복잡한 노드 네트워크를 이식 가능하고 사람이 읽을 수 있는 형태의 데이터로 변환하는 핵심 메커니즘이다 [11, 12]. + +**1. 노드 객체의 기술적 구성** +- **필수 속성:** `id`(그래프 탐색용 고유 식별자), `type`(노드 레지스트리의 클래스 이름 매핑), `pos` 및 `size`(UI 렌더링용 좌표 및 크기), `order`(실행 또는 렌더링 순서), `mode`(활성/바이패스 상태)가 포함된다 [2]. +- **선택적 속성:** 사용자가 입력한 슬라이더, 텍스트 박스 등의 값을 저장하는 `widgets_values`가 존재한다 [2]. + +**2. 포맷별 구조적 차이** +- **Frontend JSON (workflow.json):** 시각적 편집을 위해 Litegraph 표준을 따르며, 노드 위치, 그룹 구조, 색상 등 모든 시각적 메타데이터를 포함한다 [1, 3, 13]. +- **API JSON (workflow_api.json):** 서버 사이드 처리에 최적화된 스트림라인 실행 그래프이다 [1]. 시각적 데이터를 제거하고 노드 입력 내에 링크를 직접 임베딩하여 효율성을 극대화한다 [1, 3, 14]. + +**3. 연결 메커니즘** +- 연결은 `links` 배열 내에서 정의되며, 각 항목은 일반적으로 `origin_id`, `origin_slot`, `target_id`, `target_slot`을 정의하는 6개 항목 배열 또는 구조화된 객체이다 [5]. +- 슬롯 인덱싱은 매우 엄격하여, 특정 노드의 여러 출력 슬롯 중 정확히 어떤 데이터가 다운스트림 노드에 소비되는지 명시해야 한다 [5]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **JSON 포맷의 취약성:** PNG 메타데이터에 포함된 JSON은 표준 이미지 편집기나 소셜 미디어 플랫폼에서 압축/편집 시 삭제되기 쉬운 취약점이 있다 [9]. +- **버전 간 비호환성:** 소스에 따르면 ComfyUI의 빈번한 업데이트로 인해 구버전 JSON이 최신 버전에서 작동하지 않을 수 있으며, 이를 해결하기 위해 ComfyUI Manager 등의 도구가 의존성을 해결해야 한다 [10, 15]. +- **필드 명칭 차이:** Frontend 포맷에서는 `type`을 사용하지만 API 포맷에서는 `class_type`이라는 명칭을 사용하여 노드를 식별한다 [3, 16]. + +## 🛠️ 적용 사례 (Applied in summary) +- **공식 문서 경로:** `/specs/workflow_json` 위치에 JSON Schema v1.0 명세가 정의되어 있다 [17]. +- **버전 관리:** 현재 가장 최신 규격은 Version 1.0이며, 이전 버전인 0.4와 구분되어 관리된다 [18]. +- **유효성 검사 도구:** `comfyui-workflow-to-api-converter-endpoint` 커스텀 노드는 서버 사이드에서 비-API 워크플로우를 v1.0 API 포맷으로 변환하는 기능을 구현하고 있다 [19, 20]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 명세 및 개발 문서 기반으로 구조화됨) [2, 21] +- **출처 신뢰도:** B (공식 문서 및 기본 소스 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Draft-07 Specification]] + - 연결 이유: JSON Schema v1.0이 기반으로 삼고 있는 기술 표준이다 [2]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터의 유효성 검사 규칙 및 구조적 제약 조건. +- [[Node-based Visual Programming]] + - 연결 이유: JSON Schema가 표현하고자 하는 추상화된 프로그래밍 모델이다 [11, 22]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드와 링크가 실제 프로그램 논리로 변환되는 원리. + +#### [구현/활용 도구] +- [[API JSON (workflow_api.json)]] + - 연결 이유: v1.0 스키마가 실제로 실행 환경에서 가장 많이 활용되는 형태이다 [1, 14]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 서버리스 배포 및 API 호출 시의 데이터 최적화 방법. +- [[Frontend JSON (workflow.json)]] + - 연결 이유: v1.0 스키마의 시각적 메타데이터를 포함하는 전체 데이터셋이다 [1, 13]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 사용자 인터페이스 상에서의 워크플로우 재구성과 공유. + +### 심층 후속 질문 (Deeper Research Questions) +- v1.0 스키마에서 Draft-07 규격이 구체적으로 어떤 유효성 검사 과정을 거쳐 노드 실행 전 오류를 방지하는가? [2] +- Frontend JSON의 시각적 메타데이터(pos, size)가 실제 백엔드 실행 엔진에 전혀 영향을 주지 않는 구조적 이유는 무엇인가? [1, 3] +- 링크 데이터 표현 방식(6개 항목 배열)에서 각 인덱스가 담고 있는 기술적 의미는 무엇인가? [5] +- [[Execution Model Inversion]] 패턴이 적용될 때, JSON 내에서 사용되지 않는 노드는 어떤 과정을 통해 무시되는가? [6] +- API 포맷에서 `class_type`이 아닌 `inputs` 내에 링크 정보가 포함되는 방식이 실행 속도에 미치는 영향은 무엇인가? [1, 3] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** Python의 `json` 라이브러리를 사용하여 노드 ID를 추적하고 `widgets_values`를 동적으로 수정하여 자동화된 이미지 생성을 구현할 수 있다 [23, 24]. +- **System Design:** 외부 애플리케이션에서 ComfyUI를 호출할 때, `workflow_api.json` 형식을 사용하여 불필요한 UI 데이터를 배제하고 전송 효율을 높인다 [1, 25]. +- **Operation / Maintenance:** `ComfyUI Manager`를 통해 JSON 내의 `class_type`을 파싱하여 누락된 커스텀 노드를 자동으로 설치하고 관리할 수 있다 [15]. +- **Learning Path:** 시각적 워크플로우를 먼저 이해한 후, 개발자 모드를 활성화하여 API 전용 JSON 포맷의 데이터 구조를 분석하는 단계로 학습이 진행된다 [26, 27]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Object_info.json]] + - 확장 방향: 실행 중인 ComfyUI 인스턴스의 노드 스키마 카탈로그를 이해하여 JSON을 동적으로 생성하는 도구 제작 [28, 29]. +- [[Metadata Stripping]] + - 확장 방향: 이미지 파일 공유 시 발생하는 워크플로우 데이터 손실 방지 및 복구 전략 [9, 19]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Lazy Evaluation in Graph Theory.md b/10_Wiki/Topics/Comfyui/Lazy Evaluation in Graph Theory.md new file mode 100644 index 00000000..60dad65b --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Lazy Evaluation in Graph Theory.md @@ -0,0 +1,100 @@ +--- +id: lazy-evaluation-in-graph-theory +title: "Lazy Evaluation in Graph Theory" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Execution Model Inversion"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["Execution Model Inversion"] +github_commit: "" +--- + +# [[Lazy Evaluation in Graph Theory]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI는 **실행 모델 역전(Execution Model Inversion)** 아키텍처를 통해 출력 노드로부터 역방향으로 그래프를 추적하여 최종 결과에 필요한 노드만 선택적으로 실행함으로써 효율성을 극대화한다 [1]. + +## 🧠 핵심 개념 (Core concepts) +- **유향 비순환 그래프 (Directed Acyclic Graph, DAG):** ComfyUI 워크플로우의 근간으로, 노드 간의 링크가 데이터의 흐름을 정의하며 순환하지 않는 구조를 형성한다 [2]. +- **실행 모델 역전 (Execution Model Inversion):** 그래프의 모든 노드를 순차적으로 실행하는 대신, '출력' 노드에서 시작하여 필요한 의존성만 역추적하는 방식이다 [1]. +- **의존성 식별 (Dependency Identification):** 백엔드 엔진이 최종 결과(예: Save Image)에 기여하지 않는 노드를 무시하고 실행 목록(Execution List)을 구성하는 프로세스이다 [1, 3]. +- **백엔드 실행 그래프 최적화:** API 포맷(workflow_api.json)은 시각적 메타데이터를 제거하고 실행에 필수적인 논리적 연결성만을 포함하여 처리 속도를 높인다 [4, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **역방향 트리거링 패턴:** 사용자나 시스템이 특정 출력 노드를 요청하면, 해당 노드에 연결된 입력 경로를 따라 상위 노드들이 활성화되는 구조를 가진다 [1]. +- **불필요한 계산 배제:** 생성된 JSON 내에 수십 개의 미사용 노드가 포함되어 있더라도 최종 출력에 기여하지 않는다면 성능에 영향을 주지 않는다 [1]. +- **동적 프롬프트 변환:** JSON 워크플로우를 유효성 검사 후 `DynamicPrompt` 및 `ExecutionList`로 변환하여 노드 실행 순서를 최적화한다 [3, 6]. + +## 📖 세부 내용 (Details) +ComfyUI의 지연 평가(Lazy Evaluation)적 접근법은 **그래프 이론의 DAG 구조**를 기반으로 한 **실행 모델 역전** 아키텍처에서 구체화된다 [1, 2]. 전통적인 선형 파이프라인과 달리, ComfyUI 엔진은 'Save Image'와 같은 출력 지점에서부터 그래프를 거꾸로 횡단(Traverse)한다 [1]. 이 과정에서 엔진은 최종 결과물을 생성하기 위해 실행되어야 할 노드와 그 순서를 식별하며, 결과에 기여하지 않는 노드는 백엔드에서 완전히 무시된다 [1]. + +이러한 방식은 대규모 워크플로우를 JSON으로 관리할 때 큰 이점을 제공한다. 사용자는 단일 JSON 파일 내에 다양한 실험적 노드 구성을 유지할 수 있으며, 실제 실행 시에는 필요한 경로만 활성화되므로 성능 저하 없이 유연한 작업이 가능하다 [1]. + +프로그래밍적 관점에서, 이러한 실행 로직은 `WorkflowExecutor` 클래스 등에 의해 캡슐화될 수 있다 [3]. 워크플로우 JSON이 로드되면 `validate_prompt` 함수를 통해 검증되고, 최종적으로 노드별 입력 데이터 검색(`get_input_data`)과 출력 데이터 생성(`get_output_data`)을 거치는 실행 목록으로 변환된다 [3, 6]. 결과적으로 JSON 파일은 단순한 데이터 저장소가 아닌, 실행 엔진이 읽고 최적화할 수 있는 **지시문(Blueprint)** 역할을 수행하게 된다 [7]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **메타데이터의 취약성:** JSON 데이터는 PNG 이미지의 메타데이터(tEXt/zTXt 청크)에 저장되지만, 이미지 편집기나 소셜 미디어 플랫폼을 거치면 이 정보가 손실될 수 있어 데이터의 영속성이 보장되지 않는다 [8]. +- **포맷 간의 괴리:** 시각적 편집용인 'Frontend Format'과 실행용인 'API Format'이 이원화되어 있어, API 포맷 파일을 UI로 다시 불러올 경우 시각적 레이아웃(노드 위치 등)이 누락되는 문제가 존재한다 [4, 9, 10]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Execution Model Inversion:** ComfyUI 공식 백엔드 로직에 적용되어 출력 노드 중심의 역방향 그래프 횡단을 구현함 [1]. +- **WorkflowExecutor:** Python 기반 독립 실행 스크립트 구현 시 워크플로우를 `ExecutionList`로 변환하고 실행하는 핵심 컴포넌트로 제안됨 [3, 6]. +- **ComfyUI-WorkflowGenerator:** LLM을 이용해 자연어 설명을 논리적 그래프 구조(JSON)로 합성하고 이를 실행 가능한 빌더로 전달하는 3단계 파이프라인에서 활용됨 [11, 12]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI 워크플로우의 구조적 근간 [2]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 데이터 흐름의 방향성과 노드 간의 위계적 연결 방식. +- [[Execution Model Inversion]] + - 연결 이유: 지연 평가를 가능하게 하는 핵심 메커니즘 [1]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 백엔드 엔진이 실행 효율성을 높이는 구체적인 알고리즘. + +#### [구현/활용 도구] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: 그래프 구조가 직렬화되어 파일로 저장되는 대상 [2, 7]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 ID, 유형, 입력값 등이 JSON 내에서 어떻게 매핑되는지. +- [[workflow_api.json]] + - 연결 이유: 지연 평가 로직이 적용되는 최종 실행용 파일 포맷 [4, 13]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각 메타데이터가 제거된 순수 실행 그래프의 구조. + +### 심층 후속 질문 (Deeper Research Questions) +- ComfyUI 백엔드에서 역방향 횡단 시 캐싱(Caching)은 중복 계산을 어떻게 방지하는가? [6] +- `DynamicPrompt`가 `ExecutionList`로 변환되는 과정에서 노드의 실행 우선순위(Order)는 어떻게 결정되는가? [3, 14] +- 노드가 'Bypass' 상태일 때 그래프 이론 측면에서 링크 연결성은 어떻게 처리되는가? [15] +- 특정 노드에만 실행을 제한하는 'Partial Execution' 기능은 지연 평가 모델과 어떻게 상호작용하는가? [16, 17] +- LLM 기반 워크플로우 생성기에서 논리적 합성(Logical Synthesis) 결과가 그래프 이론의 유효성을 만족하는지 검증하는 구체적인 알고리즘은 무엇인가? [12, 18] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 독립 실행형 스크립트를 작성할 때 `WorkflowExecutor`를 활용하여 JSON 워크플로우를 직접 제어할 수 있다 [3]. +- **System Design:** API 호출 시 필요한 노드만 포함된 `workflow_api.json`을 사용하여 네트워크 페이로드와 서버 부하를 최소화할 수 있다 [4, 5]. +- **Operation / Maintenance:** 워크플로우 수정 시 미사용 노드를 삭제하지 않고 남겨두더라도 실제 실행 성능에는 영향을 주지 않으므로 유지보수가 용이하다 [1]. +- **Learning Path:** 노드 기반 인터페이스의 시각적 로직을 이해하는 것이 곧 시스템의 실행 논리를 학습하는 과정이 된다 [19]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: 워크플로우 포터빌리티 확보를 위해 파일명 대신 해시를 이용한 모델 식별 방법 [20]. +- [[Natural Language to Workflow Generation]] + - 확장 방향: LLM을 통해 대화형으로 그래프 구조를 생성하는 미래 지향적 방식 [11, 21]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine.--- \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Litegraph Standard.md b/10_Wiki/Topics/Comfyui/Litegraph Standard.md new file mode 100644 index 00000000..2bcf7987 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Litegraph Standard.md @@ -0,0 +1,97 @@ +--- +id: litegraph-standard +title: "Litegraph Standard" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Litegraph Format", "Frontend JSON Format"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Litegraph", "Frontend"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-frontend-package/src/scripts/metadata", "ComfyUI Settings/Lite Graph"] +github_commit: "" +--- + +# [[Litegraph Standard]] + +## 🎯 한 줄 통찰 (One-line insight) +Litegraph Standard는 ComfyUI의 시각적 워크플로우를 구성하는 노드의 배치, 크기, 그룹 등 **UI 메타데이터를 포함한 그래프 구조를 정의하는 프론트엔드 직렬화 규격**이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **Frontend JSON (workflow.json):** 사용자 상호작용 및 시각화를 위해 설계된 포맷으로, Litegraph 표준을 준수하여 노드의 좌표와 레이아웃 정보를 보존한다 [1, 3]. +- **Visual Metadata:** 노드의 위치(pos), 크기(size), 색상, 그룹 구조, 노드의 축소(collapsed) 또는 고정(pinned) 상태와 같은 시각적 속성을 포함한다 [1, 4]. +- **Explicit Link Objects:** 노드 간의 연결을 별도의 배열 내에서 명시적인 연결 객체(link ID)로 표현하여 그래프 시각화를 용이하게 한다 [1, 3, 5]. +- **Node-Based Interface Compatibility:** Maya, Blender, Unreal Engine 등 타 시각적 프로그래밍 환경과 유사한 그래프 시각화 및 조작 패러다임을 제공한다 [6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **형식의 이분화 (Serialization Bifurcation):** 워크플로우를 저장할 때 시각적 편집을 위한 Litegraph 기반 '프론트엔드 포맷'과 실행 효율을 위한 'API 포맷'으로 구분하여 관리하는 패턴이 발견된다 [1]. +- **스키마 제약 조건 (Schema Constraints):** JSON v1.0 규격에 따라 노드 객체는 고유 ID, 클래스 타입, 좌표, 크기, 실행 순서(order), 모드 등을 반드시 정의해야 한다 [4]. +- **메타데이터 임베딩 (Metadata Embedding):** PNG 파일의 tEXt 또는 zTXt 청크에 Litegraph 형식의 워크플로우 데이터를 삽입하여 이미지 자체가 백업 및 공유 수단이 되도록 설계한다 [7, 8]. + +## 📖 세부 내용 (Details) +Litegraph 표준은 ComfyUI 워크플로우의 **'소스 코드' 역할을 수행하는 프론트엔드 JSON 포맷**의 기술적 근간이다 [1, 9]. 이 표준은 노드 기반의 시각적 프로그래밍 환경에서 노드 간의 데이터 흐름뿐만 아니라, 사용자가 구성한 캔버스 상의 시각적 질서를 보존하는 데 중점을 둔다 [1, 10]. + +주요 기술적 특성은 다음과 같다: +- **데이터 구조:** 루트 레벨에서 `nodes` 배열과 `links` 배열을 포함하며, 각 노드는 캔버스 상의 X, Y 좌표(`pos`)와 너비, 높이(`size`) 정보를 보유한다 [4, 5]. +- **연결 방식:** 노드 내부의 `inputs`와 `outputs`는 단순한 참조가 아닌, 전역 `links` 배열에 정의된 고유한 링크 ID를 통해 상호 연결된다 [5]. 이는 API 포맷에서 입력값에 소스 노드 정보를 직접 내장하는 방식과 대조적이다 [1]. +- **사용자 경험 지원:** 그룹화 기능 및 노드 상태(Active, Bypassed 등)를 지원하여 복잡한 워크플로우의 가독성을 높인다 [4]. +- **호환성 및 확장:** ComfyUI 설정 메뉴에는 'Lite Graph' 관련 전용 설정 카테고리가 존재하며, 이를 통해 인터페이스 동작을 제어할 수 있다 [11, 12]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **실행 호환성 문제:** Litegraph 표준 기반의 JSON(workflow.json)은 노드 좌표 등 불필요한 메타데이터가 많아 백엔드 엔진이 직접 해석하기에 비효율적이며, 종종 `/prompt` 엔드포인트에서 오류를 발생시킨다 [1, 9, 13]. 따라서 서버 실행을 위해서는 이를 API 포맷으로 변환해야 한다 [14]. +- **데이터 취약성:** PNG 이미지에 포함된 Litegraph 메타데이터는 표준 이미지 편집기나 소셜 미디어 플랫폼에서 압축/편집 시 쉽게 손실될 수 있다는 점이 지적된다 [7, 8]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-frontend-package:** 프론트엔드 자바스크립트 컨텍스트 내의 `src/scripts/metadata` 경로에서 공식적인 메타데이터 파싱 로직으로 적용됨 [15]. +- **ComfyUI 설정 메뉴:** 인터페이스 내 Settings > Lite Graph 섹션을 통해 관련 기능이 구현되어 있음 [11]. +- **workflow.json 내보내기:** ComfyUI 제어판의 'Export' 기능을 통해 생성되는 모든 표준 워크플로우 파일의 규격으로 사용됨 [16, 17]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 및 아키텍처 분석을 통해 확인됨) +- **출처 신뢰도:** B (Official Documentation 및 기술 블로그 분석 결과) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[ComfyUI Workflow JSON Generation and Serialization]] + - 연결 이유: Litegraph 표준이 직렬화 프로세스의 핵심 구성 요소임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 프론트엔드와 API 포맷 간의 기술적 차이점. +- [[Visual Programming Environment]] + - 연결 이유: Litegraph가 지향하는 사용자 인터페이스 패러다임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 기반 시스템의 범용적 설계 원리. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: Litegraph JSON을 파싱하여 누락된 커스텀 노드를 식별하고 관리함. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 워크플로우 종속성 해결 메커니즘. + +### 심층 후속 질문 (Deeper Research Questions) +- Litegraph 표준에서 정의하는 `links` 배열의 6가지 인덱스 값은 각각 구체적으로 어떤 데이터를 의미하는가? [5] +- API 포맷(workflow_api.json)으로 변환 시 Litegraph의 어떤 데이터가 가장 먼저 폐기되는가? [1, 3] +- `comfyui-frontend-package`의 자바스크립트 로직은 Litegraph 데이터를 어떻게 검증(Validation)하는가? [15] +- 노드 상태(`mode`) 중 'Bypassed' 처리가 Litegraph 직렬화 결과에 미치는 영향은 무엇인가? [18] +- 0.4 버전에서 1.0 버전으로의 Litegraph 스키마 변경 시 주요 차이점은 무엇인가? [19, 20] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 커스텀 노드 개발 시 `INPUT_TYPES`를 Litegraph 규격에 맞춰 정의하여 UI 상에서 올바르게 렌더링되도록 함 [21]. +- **System Design:** 워크플로우 관리 시스템 설계 시, 시각적 편집용 데이터와 실행 전용 데이터를 분리하여 저장하는 구조를 채택함 [1]. +- **Learning Path:** 초보자가 워크플로우 구조를 이해하기 위해 JSON 파일을 직접 열어 노드 ID와 연결 관계를 추적하는 학습 도구로 활용 가능함 [22]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Directed Acyclic Graph (DAG)]] + - 확장 방향: Litegraph가 시각적으로 표현하는 데이터 흐름의 수학적 모델. +- [[Metadata Stripping]] + - 확장 방향: 이미지 공유 과정에서 Litegraph 정보가 소실되는 보안 및 기술적 이유 분석. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Litegraph.md b/10_Wiki/Topics/Comfyui/Litegraph.md new file mode 100644 index 00000000..3bade50a --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Litegraph.md @@ -0,0 +1,58 @@ +--- +id: litegraph +title: "Litegraph" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI Settings Menu", "workflow.json"] +github_commit: "" +--- + +# [[Litegraph]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 프론트엔드 워크플로우의 시각적 레이아웃과 노드 연결 구조를 정의하는 핵심 직렬화 표준 규격 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **프론트엔드 JSON 포맷의 근간:** ComfyUI의 시각적 편집 도구인 `workflow.json` 파일이 따르는 표준으로, 노드 기반 그래프의 시각화 및 조작을 위해 설계됨 [1, 2]. +2. **시각적 메타데이터 저장:** 노드의 좌표(`pos`), 크기(`size`), 그룹 구성, 노드의 축소(collapsed) 또는 고정(pinned) 상태와 같은 UI 전용 정보를 포함함 [1, 3]. +3. **명시적 링크 시스템 (Explicit Links):** 노드 간의 연결을 별도의 `links` 배열 내에서 고유 식별자를 가진 객체로 관리하며, 이는 백엔드 실행용 API 포맷과 차별화되는 지점임 [1, 4, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **이분법적 직렬화 구조:** 사용자 인터페이스를 위한 Litegraph 기반의 '프론트엔드 포맷'과 서버 실행을 위한 'API 포맷'을 엄격히 구분하여 운영함 [1, 4, 6]. +- **캔버스 상태 복원 패턴:** Litegraph 규격을 준수함으로써 워크플로우 로드 시 사용자가 마지막으로 작업했던 좌표와 노드 배치를 정확하게 재생성함 [7, 8]. + +## 📖 세부 내용 (Details) +- **기술적 구성 요소:** Litegraph 표준에 따라 노드 객체는 `id`(고유 번호), `type`(노드 클래스명), `pos`(캔버스 내 x, y 좌표), `size`(너비 및 높이), `order`(실행/렌더링 순서) 등 필수 속성을 가짐 [3, 9]. +- **데이터 흐름 정의:** 연결성은 `inputs`와 `outputs` 배열을 통해 정의되며, 각 입력은 고유한 링크 ID를 참조하여 데이터의 기원(origin_id)과 슬롯(origin_slot)을 식별함 [5]. +- **비주얼 프로그래밍 환경:** Maya, Blender, Unreal Engine 등 전문적인 노드 기반 소프트웨어와 유사한 '절차적 프레임워크'를 제공하여 사용자가 복잡한 수학이나 코드 이해 없이도 AI 시스템을 설계할 수 있게 함 [10, 11]. +- **메타데이터 임베딩:** ComfyUI는 Litegraph 규격의 JSON 데이터를 생성된 PNG 파일의 메타데이터(tEXt/zTXt 청크)에 삽입하여, 이미지 파일을 캔버스로 드래그했을 때 워크플로우가 즉시 복구되도록 지원함 [12, 13]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 간 호환성 제약:** ComfyUI의 빈번한 업데이트로 인해 이전 버전의 Litegraph 기반 JSON 파일이 최신 환경에서 제대로 로드되지 않거나 위젯이 사라지는 현상이 발생할 수 있음 [14, 15]. +- **실행 엔진과의 괴리:** Litegraph 포맷은 시각적 정보가 비대하여 백엔드 API 요청 시 오류를 유발할 수 있으므로, 반드시 'Dev mode'를 통한 API 포맷 변환 과정이 필요함 [8, 16]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI 설정(Settings) 메뉴:** 인터페이스 내 설정 창에 'Lite Graph' 섹션이 별도로 존재하여 관련 시각 옵션을 조정할 수 있음 [17, 18]. +- **워크플로우 내보내기(Export):** 사용자가 인터페이스 메뉴에서 'Export'를 선택할 때 생성되는 `workflow.json` 파일이 이 규격을 직접적으로 사용함 [7, 9]. +- **MetaData Parsing Logic:** ComfyUI 프론트엔드 패키지 내의 자바스크립트 컨텍스트(`src/scripts/metadata`)에서 Litegraph 기반의 메타데이터 파싱이 공식적으로 수행됨 [19]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (ComfyUI 공식 문서 및 기술 사양을 통해 규격 확인됨) +- **출처 신뢰도:** B (Official Documentation / Technical Architecture Review via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Metadata Forensics.md b/10_Wiki/Topics/Comfyui/Metadata Forensics.md new file mode 100644 index 00000000..4417162c --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Metadata Forensics.md @@ -0,0 +1,61 @@ +--- +id: metadata-forensics +title: "Metadata Forensics" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Workflow Extraction", "Metadata Extraction"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Metadata", "Forensics"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-frontend-package/src/scripts/metadata", "exiftool -b -workflow input.png > workflow.json"] +github_commit: "" +--- + +# [[Metadata Forensics]] + +## 🎯 한 줄 통찰 (One-line insight) +Metadata Forensics는 이미지 파일 내부에 은닉된 생성형 AI의 실행 로직(JSON)을 역공학적으로 추출하여 생성 기원의 투명성과 워크플로우 재현성을 확보하는 핵심 기술이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +1. **Metadata Injection (메타데이터 주입):** ComfyUI의 `Save Image` 노드가 실행될 때, 최종 이미지 파일의 헤더에 전체 노드 그래프, 레이아웃, 설정 및 프롬프트 정보를 자동으로 삽입하는 프로세스이다 [4, 5]. +2. **tEXt/zTXt Chunks:** PNG 파일 형식 내에서 워크플로우(Frontend 형식)와 프롬프트(API 형식)라는 두 가지 상이한 문자열 데이터를 저장하는 특수 데이터 영역이다 [3]. +3. **Data Fragility (데이터 취약성):** 내장된 메타데이터는 표준 이미지 편집기, 소셜 미디어 플랫폼, 또는 파일 압축 유틸리티에 의해 제거되기 쉬운 "비필수적" 정보로 취급되어 소실될 위험이 높다 [3, 6]. +4. **Algorithmic Extraction (알고리즘 추출):** 전용 도구나 CLI 유틸리티를 사용하여 이미지의 바이너리 태그를 분석하고, 그 안에 포함된 직렬화된 JSON 데이터를 분리해내는 기술적 절차이다 [7, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **이중 형식 저장 패턴:** ComfyUI는 시각적 편집을 위한 'Frontend JSON'과 실행을 위한 'API JSON'을 이미지 내에 동시에 저장하여 사용자 편의성과 프로그램적 재실행 가능성을 모두 충족시킨다 [3]. +- **드래그 앤 드롭 복구 전략:** 사용자가 이미지 파일을 ComfyUI 캔버스에 직접 끌어다 놓으면 내장된 메타데이터를 즉시 파싱하여 원래의 노드 구성을 복원하는 직관적인 워크플로우 로드 방식이다 [1, 4]. + +## 📖 세부 내용 (Details) +ComfyUI에서 생성된 미디어 파일(PNG, WebP 등)은 단순한 시각적 데이터 이상의 정보를 포함하고 있다 [4, 9]. 워크플로우가 종료되는 `Save Image` 노드는 이미지 생성 시점의 **전체 노드 그래프와 설정을 파일의 숨겨진 메타데이터에 주입**한다 [4, 5]. 구체적으로 PNG 파일의 경우 `tEXt` 또는 `zTXt` 청크를 활용하여 시각적 레이아웃 정보를 담은 Frontend 형식의 JSON과 실제 백엔드 실행에 필요한 API 형식의 JSON(Prompt)을 저장한다 [3]. + +이러한 메타데이터는 워크플로우의 백업 역할을 수행하며, 다른 사용자와 생성 기법을 공유하는 효율적인 수단이 된다 [1, 9]. 그러나 **데이터의 영속성 측면에서 취약점**이 존재한다. 소셜 미디어 플랫폼이나 파일 압축 과정에서 파일 크기 절감을 위해 이러한 메타데이터를 제거하는 경우가 빈번하며, GIMP와 같은 이미지 편집기로 수정할 경우에도 원본 메타데이터가 손실될 수 있다 [3, 6, 8]. + +실무적인 포렌식 및 추출을 위해 다양한 도구가 사용된다. `exiftool`과 같은 범용 도구를 사용하여 특정 태그(`-workflow`)를 지정해 JSON을 추출할 수 있으며, `ComfyUI Workflow Extractor`와 같은 웹 기반 도구나 `comfyui_extractor.py`와 같은 전문 스크립트는 배치 프로세싱을 통해 수천 개의 이미지에서 워크플로우를 대량으로 복구할 수 있게 해준다 [2, 7, 10]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **공유 편의성 vs. 데이터 보존:** 이미지를 통한 워크플로우 공유는 가장 쉬운 방법으로 추천되지만, 네트워크 전송이나 압축 과정에서 메타데이터가 손실될 수 있으므로 **중요한 워크플로우는 별도의 JSON 파일로 저장하는 것이 권장**된다 [3, 5, 6]. +- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해, 메타데이터에서 추출한 이전 버전의 JSON 파일이 최신 버전의 인터페이스에서 정상적으로 작동하지 않을 수 있는 호환성 리스크가 존재한다 [6]. + +## 🛠️ 적용 사례 (Applied in summary) +- **파일 경로:** `comfyui-frontend-package/src/scripts/metadata` (공식 메타데이터 파싱 로직이 구현된 위치) [11]. +- **CLI 명령:** `exiftool -b -workflow input.png > workflow.json` (PNG 메타데이터 청크에서 직렬화된 JSON을 격리하는 표준 명령) [7]. +- **전문 도구:** `Comfy_UI_prompt_extractor`, `comfyui_extractor.py`, `comfyui-workflow-extractor` (AI 아트의 디지털 포렌식 및 기술 라이브러리 유지를 위한 추출 도구들) [7, 10]. +- **설계 결정:** PNG 파일 내에 `workflow`(Frontend)와 `prompt`(API) 정보를 중복 저장하여 시각적 편집과 자동화 실행을 동시에 지원함 [3]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Metadata Stripping.md b/10_Wiki/Topics/Comfyui/Metadata Stripping.md new file mode 100644 index 00000000..e7db7d6c --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Metadata Stripping.md @@ -0,0 +1,98 @@ +--- +id: metadata-stripping +title: "Metadata Stripping" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["메타데이터 제거", "Metadata Loss"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["GIMP", "Social Media Platforms", "File Compression Utilities"] +github_commit: "" +--- + +# [[Metadata Stripping]] + +## 🎯 한 줄 통찰 (One-line insight) +메타데이터 스트리핑은 이미지 파일에 내장된 워크플로우 데이터를 외부 환경(소셜 미디어, 편집기 등)이 데이터 최적화나 개인정보 보호를 목적으로 제거하여 결과물의 재현성을 파괴하는 현상이다. [1, 2] + +## 🧠 핵심 개념 (Core concepts) +- **데이터 취약성 (Data Fragility):** 이미지 내 메타데이터(tEXt/zTXt 청크)는 표준 이미지 편집기나 압축 소프트웨어에 의해 쉽게 손실될 수 있는 비필수적 데이터로 간주됨. [2] +- **청크 기반 저장 (Chunk-based Storage):** ComfyUI는 PNG 파일의 tEXt 또는 zTXt 청크를 사용하여 워크플로우(Frontend)와 프롬프트(API) JSON 문자열을 저장함. [2] +- **최적화 사이드 이펙트:** 소셜 미디어 플랫폼이나 전송 네트워크가 파일 크기를 줄이기 위해 비이미지 데이터를 자동 제거하는 과정에서 발생함. [2, 3] +- **추출 및 복구 (Extraction & Recovery):** 손실된 메타데이터를 대체하기 위해 별도의 JSON 파일을 보존하거나, 특화된 추출 도구를 사용하여 잔존 데이터를 회수하는 행위. [1, 4] + +## 🧩 추출된 패턴 (Extracted patterns) +- **플랫폼 기반 손실 패턴:** 워크플로우가 포함된 PNG를 소셜 미디어에 게시할 경우, 대부분의 플랫폼은 용량 최적화를 위해 내장된 JSON 데이터를 스트리핑함. [1, 2] +- **도구 기반 제거 패턴:** GIMP와 같은 일반적인 이미지 편집기로 파일을 수정하고 저장할 때, 사용자 정의 메타데이터가 보존되지 않고 삭제됨. [4] +- **전송 매체 종속성:** 압축 소프트웨어를 사용하거나 네트워크를 통해 파일을 전송할 때 메타데이터 정보가 누락될 가능성이 높음. [3] + +## 📖 세부 내용 (Details) +ComfyUI는 생성된 이미지 내부에 전체 노드 그래프와 설정을 주입하는 방식을 취하지만, 이 메타데이터는 매우 **불안정(fragile)**한 상태로 존재한다. [2] + +- **저장 메커니즘:** 워크플로우 정보는 주로 `Save Image` 노드가 실행될 때 최종 이미지의 숨겨진 메타데이터에 주입된다. [5, 6] 구체적으로 PNG 파일 구조 내의 `tEXt` 또는 `zTXt` 청크를 활용하여 시각적 레이아웃(Frontend format)과 실행 로직(API format)을 동시에 저장한다. [2] +- **스트리핑의 주요 원인:** + - **소셜 미디어 및 웹 플랫폼:** 이미지 게시 시 파일 크기를 줄이거나 업로더의 프라이버시를 보호하기 위해 비필수 메타데이터를 모두 제거한다. [1, 2] + - **이미지 편집 소프트웨어:** GIMP 등의 도구로 이미지를 편집하면 원본에 포함되어 있던 사용자 정의 청크 정보가 유실된다. [4] + - **파일 압축 및 전송:** 압축 유틸리티나 특정 네트워크 전송 프로토콜은 이미지 데이터 외의 부가 정보를 정리하는 경향이 있다. [2, 3] +- **영향 및 대안:** 메타데이터가 스트리핑된 이미지는 ComfyUI 캔버스로 드래그 앤 드롭해도 워크플로우를 복원할 수 없다. [3, 6] 이를 방지하기 위해 복잡한 워크플로우는 반드시 **JSON 파일** 형태로 별도 저장 및 공유하는 것이 권장된다. [6] 이미 스트리핑이 우려되는 환경에서는 `exiftool`이나 전문 추출기(Workflow Extractor)를 사용하여 데이터 유무를 확인하거나 미리 추출해 두어야 한다. [1, 7] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **이미지 vs JSON 저장의 신뢰성:** 초기에는 이미지 드래그 앤 드롭이 가장 쉬운 방법으로 소개되지만, 소스에서는 새로운 노드나 커스텀 노드가 누락될 수 있는 문제와 메타데이터 손실 위험 때문에 **JSON 파일 저장**을 최종적으로 더 강력히 권장한다. [6] +- **재삽입 요구사항:** 단순 추출을 넘어 유실된 메타데이터를 다시 이미지에 삽입(Insert)하거나 복사(Copy)하는 기능에 대한 요구가 커뮤니티에서 지속적으로 제기되고 있다. [4] + +## 🛠️ 적용 사례 (Applied in summary) +- **GIMP 편집 환경:** 사용자가 pythongosssss 워크플로우 이미지를 제작한 후 GIMP에서 수정 시 메타데이터가 삭제되어 재삽입 기능이 필요해진 사례가 보고됨. [4] +- **소셜 미디어 게시물:** 온라인에 게시된 PNG 파일들에서 일반적으로 JSON 데이터가 제거되어 있어, 이를 해결하기 위한 `Weird Wonderful AI Art` 등의 전용 추출 도구가 개발됨. [1] +- **Comfy-CLI 도구:** 이미지, webp, mp4 등 지원되는 미디어에서 워크플로우를 추출, 삽입, 복사하는 기능을 `comfy-cli`에 포함시키려는 개선 제안(Issue #341)이 진행 중임. [4, 8] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 유실 사례 및 대응 도구 존재 확인됨) +- **출처 신뢰도:** B (공식 문서 및 개발자 커뮤니티 이슈 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow JSON]] + - 연결 이유: 스트리핑되는 데이터의 실체이자 표준 규격임. [9, 10] + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON의 구조적 특성이 메타데이터 청크에 어떻게 인코딩되는지 이해 가능. +- [[PNG Metadata Chunks]] + - 연결 이유: 데이터가 물리적으로 저장되는 tEXt/zTXt 위치를 정의함. [2] + +#### [구현/활용 도구] +- [[ComfyUI Workflow Extractor]] + - 연결 이유: 스트리핑되지 않은 데이터를 이미지에서 회수하는 도구임. [1] +- [[exiftool]] + - 연결 이유: 명령줄 기반으로 이미지 메타데이터를 직접 추출하거나 조작하는 표준 도구임. [7, 11] + +### 심층 후속 질문 (Deeper Research Questions) +- PNG 외에 WebP나 MP4 포맷에서도 동일한 메타데이터 스트리핑 패턴이 발생하는가? [4] +- 메타데이터 손실을 방지하면서 이미지를 압축할 수 있는 무손실 전송 규격이 존재하는가? [2, 3] +- 스트리핑된 데이터를 복구하기 위해 AI 가 이미지의 특성을 분석하여 역으로 워크플로우를 추론하는 것이 가능한가? +- 특정 소셜 미디어 플랫폼 중 메타데이터를 보존하는 예외적인 사례가 있는가? [1] +- `exiftool`을 사용하여 정의되지 않은(unregistered) 태그에 워크플로우를 강제로 삽입할 때 발생하는 호환성 문제는 무엇인가? [11] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 워크플로우 공유 시 이미지 파일만 전달하지 말고 JSON 파일을 병행 제공하여 데이터 유실에 대비해야 함. [3, 6] +- **System Design:** API 서버 구축 시 외부에서 입력된 이미지의 메타데이터 존재 여부를 검증하는 로직이 필요함. [12] +- **Operation / Maintenance:** 커뮤니티 배포용 이미지는 메타데이터를 유지하는 전용 툴(예: pythongosssss workflow image)을 사용하여 생성하는 것이 안전함. [4] +- **Learning Path:** 워크플로우 저장 방식을 익힐 때 단순 'Save'와 'Export'의 차이, 그리고 이미지 내장 방식의 한계를 먼저 파악해야 함. [6, 13] + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: 메타데이터 유실뿐만 아니라, 워크플로우 내 모델 파일명 불일치 문제를 해결하는 보완 기술임. [14] + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [Source 3, 14, 18, 32, 170] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Model Hashing (SHA-256).md b/10_Wiki/Topics/Comfyui/Model Hashing (SHA-256).md new file mode 100644 index 00000000..489f3956 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Model Hashing (SHA-256).md @@ -0,0 +1,96 @@ +--- +id: model-hashing-(sha-256) +title: "Model Hashing (SHA-256)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["SHA-256 Model Verification", "Content-based Model Identification"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfy-pack", ".cpack.zip"] +github_commit: "" +--- + +# [[Model Hashing (SHA-256)]] + +## 🎯 한 줄 통찰 (One-line insight) +모델 해싱은 가변적인 파일 이름 대신 고유한 SHA-256 지문을 통해 모델 가중치를 식별함으로써, 서로 다른 환경 간의 워크플로 이식성과 재현성을 보장하는 핵심 기술이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **SHA-256 알고리즘:** 모델 가중치 데이터로부터 고유한 고정 길이 식별자를 생성하여 데이터의 무결성을 검증하고 식별하는 표준 해시 함수이다 [1]. +2. **이식성 및 재현성 (Portability):** 제작자와 사용자의 환경에서 모델 파일 이름(예: `sd_xl_base.safetensors` vs `sdxl_v10.safetensors`)이 다르더라도 동일한 모델임을 인식하게 한다 [1, 2]. +3. **메타데이터 통합:** 워크플로 JSON 또는 관련 아카이브 파일 내에 해시 정보를 포함시켜 시스템이 로컬 파일 시스템에서 올바른 모델을 자동으로 찾도록 지원한다 [1, 2]. +4. **의존성 해결 (Dependency Resolution):** ComfyUI Manager와 같은 도구가 누락된 모델을 검색하거나 대체 모델을 제안할 때 기준점으로 활용된다 [2]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **콘텐츠 기반 식별 (Content-Addressable Identification):** 파일 경로가 아닌 실제 데이터의 내용을 기반으로 자원을 식별하여 "Model Not Found" 오류를 방지하는 설계 패턴이다 [1]. +- **워크스페이스 패키징 (Workspace Packaging):** 단순 JSON 배포에서 벗어나 JSON, 모델 해시, 커스텀 노드 버전을 `.cpack.zip`과 같은 단일 아티팩트로 묶어 관리하는 추세가 발견된다 [2]. + +## 📖 세부 내용 (Details) +모델 해싱은 ComfyUI 워크플로의 고질적인 문제인 **모델 경로 및 이름 불일치**를 해결하기 위한 고급 직렬화 기법이다 [1]. 일반적으로 워크플로는 제작자의 로컬 경로를 참조하지만, 타인의 환경에서는 파일 이름이 다를 가능성이 높다 [1]. + +이를 해결하기 위해 **comfy-pack**과 같은 도구는 모델 가중치의 **SHA-256 해시**를 계산하여 저장한다 [1, 2]. 시스템은 실행 시 파일 이름 대신 이 해시값을 대조하여, 파일명이 다르더라도 가중치가 일치하는 로컬 파일을 찾아 연결한다 [1]. + +최근에는 워크플로 JSON 외에도 모델 해시 정보를 포함하는 **아티팩트 기반 배포**가 도입되고 있으며, 이는 향후 워크플로가 업데이트되거나 특정 노드가 더 이상 지원되지 않더라도 실행 가능성을 유지하는 기술적 토대가 된다 [2]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **최신 트렌드:** 기존의 원시(raw) JSON 의존 방식에서 모델 해시와 노드 버전 정보를 포함한 **.cpack.zip** 기반의 패키징 방식으로 진화하고 있다 [2]. +- **수동 해결의 한계:** 수동으로 모델을 다시 선택하는 방식은 대규모 자동화나 API 환경에서 비효율적이므로, 해싱을 통한 자동 검색(Comfy Manager search)이 권장되는 해결책으로 제시된다 [2]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfy-pack:** 워크플로 직렬화 시 모델 가중치의 SHA-256 해시를 생성하고 활용하는 도구로 명시됨 [1, 2]. +- **.cpack.zip (Workspace Packaging):** 워크플로 JSON과 함께 모델 해시 정보를 포함하여 배포하는 표준화된 패키지 형식에 적용됨 [2]. +- **ComfyUI Manager:** 모델 경로가 깨졌을 때 해시 정보를 바탕으로 모델을 검색하고 복구하는 기능에 활용됨 [2]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 도구인 comfy-pack과 연계된 개념으로 applied 수준에 근접함) +- **출처 신뢰도:** B (Official Documentation 및 기술 분석 자료 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[ComfyUI Workflow JSON]] + - 연결 이유: 모델 해시 정보가 저장되는 근본적인 데이터 구조임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 모델 참조 방식의 변화. +- [[Serialization Formats (Frontend vs API)]] + - 연결 이유: API 자동화 시 모델 해싱을 통한 경로 해결이 필수적임. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 누락된 모델을 해시 기반으로 찾고 설치하는 주체임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 실무적인 의존성 관리 전략. +- [[Workspace Packaging]] + - 연결 이유: 해시를 포함한 아카이브 배포의 최상위 개념임. + +### 심층 후속 질문 (Deeper Research Questions) +- SHA-256 해시 계산이 수 기가바이트(GB) 규모의 모델 파일을 로드할 때 발생하는 성능 오버헤드는 어느 정도인가? +- 모델 파일의 일부(예: 메타데이터)가 수정되었을 때 해시값이 변경되어 발생하는 위양성(False Negative) 문제를 어떻게 관리하는가? +- 서로 다른 체크포인트 병합(Merging) 모델에 대해 SHA-256 해싱이 제공하는 고유 식별의 신뢰도는 어떠한가? +- 클라우드 기반 API 환경(Replicate, Mystic 등)에서 로컬 모델 해시를 기반으로 가중치를 동적 로딩하는 메커니즘은 무엇인가? +- 모델 해싱 정보를 JSON 스키마 v1.0 내에 공식적으로 표준화하려는 RFC 논의가 존재하는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `comfy-pack`을 사용하여 워크플로를 내보낼 때 자동으로 해시값을 생성하도록 설정함 [1]. +- **System Design:** 워크플로 배포 시 파일명 대신 해시를 식별자로 사용하는 인벤토리 관리 시스템 구축 [2]. +- **Operation / Maintenance:** 모델 파일명 변경 시에도 API 호출이 끊기지 않도록 해시 기반의 모델 매핑 레이어 운영 [2]. +- **Learning Path:** 초보자가 외부 워크플로를 로드할 때 발생하는 "Model Not Found" 오류의 원인과 해시를 통한 해결 원리를 학습함 [1, 2]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Custom Node Dependency Management]] + - 확장 방향: 모델뿐만 아니라 커스텀 노드 버전의 일관성을 유지하는 방법으로 확장. + + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on Source [1, 2]) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Model Hashing.md b/10_Wiki/Topics/Comfyui/Model Hashing.md new file mode 100644 index 00000000..e5054c59 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Model Hashing.md @@ -0,0 +1,91 @@ +--- +id: model-hashing +title: "Model Hashing" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["SHA-256 Model Identification"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "portability", "serialization"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfy-pack", ".cpack.zip"] +github_commit: "" +--- + +# [[Model Hashing]] + +## 🎯 한 줄 통찰 (One-line insight) +모델 가중치의 고유한 디지털 지문(SHA-256)을 생성하여 파일명이나 경로의 불일치에 관계없이 워크플로우의 이식성과 재현성을 보장하는 핵심 기술 [1]. + +## 🧠 핵심 개념 (Core concepts) +1. **SHA-256 기반 식별:** 모델 파일의 가중치를 해싱하여 중복되지 않는 고유 식별자를 부여함 [1]. +2. **파일명 독립성 (Filename Independence):** 서로 다른 시스템에서 모델 파일명이 다르더라도(예: `sd_xl_base_v10` vs `sdxl_base`) 동일 모델임을 인식 가능하게 함 [1]. +3. **고급 직렬화 (Advanced Serialization):** 표준 JSON 포맷을 넘어 모델 해시를 포함한 아티팩트 중심의 워크플로우 패키징을 지향함 [1, 2]. +4. **의존성 무결성:** 워크플로우 실행 시 필요한 정확한 모델 버전을 확인하여 "Model Not Found" 오류를 근본적으로 해결함 [1, 2]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **콘텐츠 중심 참조 패턴:** 하드코딩된 '파일 경로' 대신 파일의 '내용(Hash)'을 기준으로 리소스를 조회하는 참조 전략 [1]. +- **워크스페이스 패키징 패턴:** JSON 워크플로우, 모델 해시, 커스텀 노드 버전을 하나의 아카이브(`.cpack.zip`)로 묶어 배포하는 표준화 패턴 [2]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우의 이식성에서 가장 큰 장애물 중 하나는 **모델 파일의 명명 규칙과 경로의 불일치**이다 [1]. 제작자의 컴퓨터에서는 `sd_xl_base_v10.safetensors`로 저장된 파일이 사용자의 환경에서는 `sdxl_base.safetensors`로 존재할 수 있으며, 이 경우 표준 JSON 워크플로우는 해당 모델을 찾지 못해 실행에 실패한다 [1, 2]. + +이를 해결하기 위해 `comfy-pack`과 같은 고급 직렬화 도구는 **SHA-256 해시**를 활용한다 [1]. 워크플로우 생성 시 모델 가중치의 해시값을 계산하여 메타데이터에 포함시키면, 시스템은 파일명 대신 해시값을 검색하여 로컬 저장소에서 일치하는 모델을 찾아낼 수 있다 [1]. + +이 기술은 단순한 오류 수정을 넘어, 향후 **워크스페이스 패키징**의 핵심 요소로 자리 잡고 있다 [2]. `.cpack.zip` 포맷은 워크플로우 JSON과 함께 모델 해시 정보를 담아, 개별 커스텀 노드가 업데이트되거나 삭제되더라도 생성 시점의 논리를 그대로 재현할 수 있는 '아티팩트 기반 배포'를 가능하게 한다 [2]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **표준 vs 확장:** 기본 ComfyUI의 "Save" 또는 "Save (API)" 기능은 현재 모델 해싱을 기본적으로 포함하지 않으며, 이는 `comfy-pack`과 같은 별도의 고급 도구나 향후 도입될 표준 포맷에서 지원되는 기능이다 [1, 2]. +- **성능 오버헤드:** 대용량 모델 파일에 대한 SHA-256 계산은 리소스를 소모할 수 있으나, 소스에서는 이를 워크플로우 안정성을 위한 필수적인 비용으로 간주한다 [1]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfy-pack:** 모델 가중치의 SHA-256 해시를 사용하여 경로 및 파일명 문제를 해결하는 직렬화 도구로 명시됨 [1]. +- **.cpack.zip (워크스페이스 패키징):** 워크플로우 JSON, 모델 해시, 커스텀 노드 버전을 통합하여 미래에도 작동 가능한 배포 단위를 생성하는 포맷에 적용됨 [2]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (comfy-pack 등 실제 도구에서 사용 중임을 확인) +- **출처 신뢰도:** B (전문 아키텍처 기술 문서 및 공식 문서 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Workflow API JSON]] + - 연결 이유: 해시 정보가 삽입되거나 참조되는 기본 실행 구조체 [3]. +- [[Serialization Formats]] + - 연결 이유: JSON 포맷을 넘어선 데이터 보존 전략의 일부 [1, 4]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 모델 검색 및 누락된 의존성 해결 시 해시 정보를 활용할 수 있는 도구 [2]. +- [[Workspace Packaging]] + - 연결 이유: 모델 해싱이 실제 구현되는 최상위 배포 단위 [2]. + +### 심층 후속 질문 (Deeper Research Questions) +- `comfy-pack`에서 SHA-256 해시를 계산할 때 대용량 모델(예: 10GB+)에 대한 계산 속도 최적화 방법은 무엇인가? +- 모델 해시가 일치하지만 파일명이 다를 때, ComfyUI 내부적으로 자동으로 연결을 매핑하는 로직은 어떻게 구현되는가? +- 향후 `.cpack.zip` 표준이 확정될 때, 모델 해시 외에 환경(Python 버전 등)에 대한 해싱도 포함될 계획이 있는가? +- 모델 가중치의 일부가 변경(Fine-tuning 등)되었을 때, 해시 변화에 따른 의존성 관리 전략은 무엇인가? +- 외부 API 서비스(Replicate, Mystic 등)에서 모델 해싱을 통한 프리로드(Pre-load) 최적화가 가능한가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `comfy-pack` 라이브러리를 사용하여 모델 의존성이 포함된 패키지를 생성할 때 해싱 로직을 호출함 [1]. +- **System Design:** 다수의 머신에서 동일한 워크플로우를 실행해야 하는 서버리스 환경에서 모델 이름 불일치 문제를 방지함 [2]. +- **Operation / Maintenance:** 모델 라이브러리의 파일명이 변경되더라도 기존 워크플로우의 작동 여부를 검증하는 무결성 체크용으로 활용함 [1]. +- **Learning Path:** 단순한 UI 저장을 넘어 아키텍처 수준의 워크플로우 자동화 및 배포를 이해하는 단계에서 학습함 [5]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Metadata Stripping]] + - 확장 방향: 이미지 배포 시 해시 정보 등 메타데이터가 손실되는 문제와 그 방지책 [6]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Natural Language to Workflow Generation.md b/10_Wiki/Topics/Comfyui/Natural Language to Workflow Generation.md new file mode 100644 index 00000000..0bb5054e --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Natural Language to Workflow Generation.md @@ -0,0 +1,69 @@ +--- +id: natural-language-to-workflow-generation +title: "Natural Language to Workflow Generation" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Natural Language to Workflow", "LLM-based Workflow Generation"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["DanielPFlorian/ComfyUI-WorkflowGenerator", "ComfyGPT research"] +github_commit: "82df278" +--- + +# [[Natural Language to Workflow Generation]] + +## 🎯 한 줄 통찰 (One-line insight) +자연어 설명을 대규모 언어 모델(LLM)을 통해 ComfyUI의 실행 가능한 노드 그래프(JSON)로 자동 변환함으로써 시각적 프로그래밍의 진입 장벽을 제거하고 생성 속도를 혁신적으로 높이는 기술이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **3단계 파이프라인 (Multi-stage Pipeline):** 논리 생성(Generator), 시맨틱 검증(Validator), 그래프 구축(Builder)의 순차적 과정을 통해 자연어를 워크플로우로 변환한다 [3, 4]. +- **노드 카탈로깅 (Node Cataloging):** 로컬에 설치된 네이티브 및 커스텀 노드를 스캔하고 색인화하여 LLM이 실제 존재하는 노드만을 사용하도록 보장한다 [5, 6]. +- **특화 LLM 미세조정 (Fine-tuned LLMs):** Qwen2.5와 같은 모델을 ComfyUI 스키마 및 노드 레지스트리 데이터로 미세 조정하여 워크플로우 구조에 최적화된 출력을 생성한다 [1, 7]. +- **시맨틱 임베딩 (Semantic Embedding):** 자연어 설명과 실제 노드 클래스 명칭 사이의 의미적 유사성을 계산하여 정확한 노드 매핑을 수행한다 [7, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **합성-검증-컴파일 루프:** LLM이 논리적 구조를 먼저 설계(Logical Synthesis)하고, 이를 로컬 노드 레지스트리와 대조(Semantic Validation)한 뒤, 최종 JSON으로 변환(Graph Compilation)하는 구조적 설계 패턴이 관찰된다 [3]. +- **로컬 환경 접지(Local Grounding):** 모델의 지식이 훈련 시점에 고정되는 한계를 극복하기 위해, 실행 전 "Update Node Catalog" 노드를 실행하여 현재 시스템의 노드 정보를 동기화하는 패턴을 사용한다 [5, 9]. + +## 📖 세부 내용 (Details) +자연어 기반 워크플로우 생성은 사용자가 "SDXL을 사용한 텍스트-투-이미지 워크플로우 생성"과 같은 지시어를 입력하면 시스템이 이를 분석하여 노드 간의 연결 관계를 정의하는 JSON 파일을 생성하는 과정이다 [2]. + +**1. 생성 단계 (Generator):** +이 단계에서는 fine-tuned된 모델(예: Qwen2.5-14B)이 지시어의 의도를 해석하여 논리적 그래프 구조를 생성한다 [3, 7]. 모델은 노드 간의 데이터 흐름(예: CLIP Text Encode에서 KSampler로의 연결)을 이해하고 이를 추상적인 JSON 형태로 출력한다 [8]. + +**2. 검증 단계 (Validator):** +생성된 논리 구조의 노드 명칭이 실제 시스템에 존재하는지 확인한다 [3, 4]. `sentence-transformers`와 같은 임베딩 모델을 사용하여 의미적으로 가장 유사한 실제 노드를 찾아 수정하며, 이 과정을 통해 LLM의 환각(Hallucination) 현상을 방지한다 [7, 8]. + +**3. 구축 단계 (Builder):** +검증된 구조를 ComfyUI 실행 엔진이 인식할 수 있는 최종 .json 포맷으로 변환한다 [3, 10]. 이 과정에서 노드의 위치(pos), 크기(size), 위젯 값(widgets_values) 등 UI 메타데이터와 실행 순서(order)가 할당된다 [10, 11]. + +**주요 기술적 사양:** +- **모델 구조:** GGUF 포맷으로 양자화된 Qwen2.5 모델군이 주로 사용되며, 효율적인 추론을 위해 llama-cpp-python 라이브러리가 요구된다 [7, 12]. +- **데이터 한계:** 정적 미세 조정을 거친 모델은 훈련 이후에 출시된 새로운 커스텀 노드에 대한 지식이 부족할 수 있으므로 지속적인 카탈로그 업데이트와 사용자의 감독이 권장된다 [9, 13]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +과거의 워크플로우 생성 방식이 수동적인 노드 연결과 JSON 편집에 의존했다면, 최신 기술인 **ComfyGPT** 아키텍처는 이를 '대화형 프로그래밍' 패러다임으로 전환하고 있다 [3]. 소스에 따르면, 정적 모델은 실시간으로 변화하는 커스텀 노드 생태계를 따라잡기 어렵다는 문제점이 제기되었으며, 이를 해결하기 위해 향후에는 정적 미세 조정을 넘어선 동적 아키텍처로의 진화가 필요함이 명시되어 있다 [9]. + +## 🛠️ 적용 사례 (Applied in summary) +- **DanielPFlorian/ComfyUI-WorkflowGenerator:** 자연어 설명을 통해 워크플로우를 생성하는 실제 커스텀 노드 구현체이다 [2, 14]. +- **핵심 노드 구성:** `Workflow Generator Pipeline`, `WorkflowGenerator`, `NodeValidator`, `WorkflowBuilder`, `UpdateNodeCatalog` 등의 노드가 실제 프로젝트 파일 구조(`nodes/`, `generators/`) 내에 구현되어 있다 [6, 8, 10, 14, 15]. +- **수정 이력:** Git 커밋 `82df278`에서 드롭다운 메뉴의 중복 모델 표시 문제가 해결된 기록이 발견된다 [14]. +- **연구 기반:** 이 기술은 "ComfyGPT: A Self-Optimizing Multi-Agent System..." 연구의 아키텍처를 로컬 ComfyUI 환경에 맞게 구현한 것이다 [2, 4]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 구현체인 ComfyUI-WorkflowGenerator 프로젝트 확인됨) +- **출처 신뢰도:** B (Official Documentation 및 GitHub 저장소 데이터 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/PNG Metadata Chunks.md b/10_Wiki/Topics/Comfyui/PNG Metadata Chunks.md new file mode 100644 index 00000000..af2e142f --- /dev/null +++ b/10_Wiki/Topics/Comfyui/PNG Metadata Chunks.md @@ -0,0 +1,72 @@ +--- +id: png-metadata-chunks +title: "PNG Metadata Chunks" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-frontend-package/src/scripts/metadata", "exiftool -b -workflow"] +github_commit: "" +--- + +# [[PNG Metadata Chunks]] + +## 🎯 한 줄 통찰 (One-line insight) +PNG 이미지의 표준 데이터 블록에 워크플로우의 시각적 구조와 실행 로직을 동시에 내장하여, 이미지 파일 자체를 **휴대 가능한 독립적 실행 스크립트**로 변모시키는 핵심 메커니즘 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **tEXt 및 zTXt 청크 (Chunks):** ComfyUI가 워크플로우 데이터를 저장하기 위해 활용하는 PNG 표준의 텍스트 데이터 보관 영역이다 [2]. +- **메타데이터 주입 (Metadata Injection):** `Save Image` 노드가 실행될 때, 최종 이미지 데이터와 함께 전체 노드 그래프, 레이아웃 설정, 프롬프트를 파일의 숨겨진 영역에 주입하는 프로세스다 [1, 4]. +- **데이터 이원화 (Bifurcation):** 하나의 이미지 내에 시각적 편집을 위한 'Frontend 포맷(workflow)'과 프로그래밍 방식의 실행을 위한 'API 포맷(prompt)' 정보를 중복 저장하여 호환성을 확보한다 [2]. +- **데이터 취약성 (Data Fragility):** 표준 이미지 편집기, 소셜 미디어 플랫폼, 또는 파일 압축 유틸리티를 거칠 경우 비필수적인 메타데이터 청크가 제거되어 워크플로우 정보가 유실될 위험이 크다 [2, 5]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **종단 노드 자동 기록 패턴:** 거의 모든 워크플로우가 `Save Image` 노드에서 종료되며, 이 노드가 실행되는 순간 현재 캔버스의 모든 상태를 이미지 메타데이터에 자동으로 동기화한다 [1]. +- **드래그 앤 드롭 복구 패턴:** 사용자가 PNG 파일을 ComfyUI 캔버스로 드래그하면, 시스템이 메타데이터 청크를 파싱하여 즉시 노드 레이아웃과 설정을 재현한다 [1, 5, 6]. +- **CLI 기반 벌크 추출 패턴:** 다수의 이미지에서 수동 조작 없이 워크플로우를 대량으로 회수하기 위해 `exiftool`과 같은 명령줄 도구를 활용하여 특정 청크 데이터를 추출한다 [7, 8]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우는 전형적인 시각적 프로그래밍의 결과물로, 이를 PNG 파일의 **메타데이터 청크**에 저장함으로써 이동성과 재현성을 극대화한다 [1, 9]. + +- **청크의 기술적 구성:** + - 주로 **tEXt** 또는 압축된 형태인 **zTXt** 청크를 사용하여 두 가지 주요 문자열을 저장한다 [2]. + - 하나는 사용자 인터페이스(UI) 상의 노드 위치, 크기, 그룹화 정보를 포함한 **Frontend JSON** 데이터다 [2, 10]. + - 다른 하나는 서버 백엔드에서 즉시 실행 가능한 형태인 **API JSON(Prompt)** 데이터로, 시각적 정보가 제거된 압축된 실행 그래프다 [2, 10, 11]. + +- **워크플로우 추출 및 분석:** + - 이미지에서 워크플로우를 추출하기 위해 전용 웹 도구나 Python 라이브러리가 사용되기도 한다 [8, 12]. + - 명령줄 도구인 `exiftool`을 사용할 경우, `-workflow` 태그를 지정하여 바이너리 데이터를 JSON 파일로 분리해낼 수 있다 [7, 8]. + - 공식적인 메타데이터 파싱 로직은 ComfyUI 프론트엔드 패키지의 자바스크립트 컨텍스트 내에서 관리된다 [13]. + +- **장점 및 한계:** + - 별도의 JSON 파일을 관리할 필요 없이 이미지 하나로 모든 생성 정보를 공유할 수 있다는 점이 가장 큰 장점이다 [14]. + - 그러나 파일이 온라인에 게시되거나 재가공될 때 메타데이터가 삭제(Stripped)되는 경우가 빈번하며, 매우 복잡하거나 최신 커스텀 노드가 포함된 경우 간혹 일부 노드 정보가 유실될 수 있다는 기술적 한계가 보고되었다 [2, 4, 12]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **저장 안정성 논란:** 첫 번째 저장 방식인 '이미지 메타데이터' 방식은 가장 간편하지만, 소스에 따르면 복잡한 노드나 특정 커스텀 노드를 누락할 가능성이 있어, 보다 확실한 백업을 위해서는 두 번째 방식인 **수동 JSON 파일 저장**이 권장된다 [4]. +- **포맷 호환성 이슈:** ComfyUI의 빈번한 업데이트로 인해, 과거 이미지 메타데이터에 내장된 구버전 JSON 형식이 최신 버전의 인터페이스에서 정상적으로 작동하지 않을 수 있다는 점이 지적되었다 [5]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Exiftool 추출 명령:** `exiftool -b -workflow input.png > workflow.json` 명령어를 통해 PNG의 메타데이터 청크에서 워크플로우 JSON을 격리하여 저장하는 사례가 확인된다 [7, 8]. +- **Frontend 파싱 위치:** 공식적인 메타데이터 파싱 로직은 `comfyui-frontend-package` 내부의 `src/scripts/metadata` 경로에서 구현 및 관리되고 있다 [13]. +- **커스텀 노드 연동:** `pythongosssss`의 워크플로우 이미지 생성 노드 등을 통해 워크플로우 정보가 포함된 이미지를 생성하고, 이를 다시 `workflow_templates`로 활용하기 위해 JSON을 추출하는 작업 흐름이 존재한다 [15]. +- **온라인 추출 도구:** `weirdwonderfulai.art` 등에서 제공하는 워크플로우 추출기는 사용자가 드롭한 PNG의 메타데이터 청크를 분석하여 JSON 파일로 다운로드할 수 있게 한다 [12, 16]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Serialization Formats (Frontend vs API).md b/10_Wiki/Topics/Comfyui/Serialization Formats (Frontend vs API).md new file mode 100644 index 00000000..08877a47 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Serialization Formats (Frontend vs API).md @@ -0,0 +1,113 @@ +--- +id: serialization-formats-(frontend-vs-api) +title: "Serialization Formats (Frontend vs API)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Frontend JSON", "API JSON", "workflow.json", "workflow_api.json"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Serialization", "API"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint (bc85382)", "ComfyUI-to-Python-Extension", "Mystic Pipeline (new_pipeline.py)"] +github_commit: "bc85382" +--- + +# [[Serialization Formats (Frontend vs API)]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI는 인간 중심의 시각적 편집을 위한 **Frontend Format**과 기계 중심의 효율적 실행을 위한 **API Format**으로 직렬화 규격을 이원화하여 관리한다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **Frontend Format (workflow.json):** 사용자와의 상호작용 및 시각화를 위해 설계된 포맷으로, Litegraph 표준을 따르며 노드 좌표, 크기, 그룹화 정보 등 모든 UI 메타데이터를 포함한다 [1, 3, 4]. +- **Backend/API Format (workflow_api.json):** 서버 사이드 처리에 최적화된 스트림라인 실행 그래프로, 시각적 메타데이터를 제거하고 실행에 필요한 노드 유형과 입력값, 연결 관계만을 유지한다 [1, 5]. +- **Metadata Stripping:** API 포맷 생성 과정에서 불필요한 UI 속성을 제거하여 파일 크기를 압축하고 실행 효율성을 극대화하는 전략이다 [1, 2]. +- **Link Embedding:** API 포맷에서는 링크가 별도의 객체가 아니라 노드 입력 내부에 `[origin_node_id, output_slot_index]` 형태의 참조값으로 직접 포함된다 [1, 6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Bifurcation Pattern:** 동일한 워크플로우를 사용 목적에 따라 시각적 레이아웃(Frontend)과 논리적 실행 순서(API)로 분리하여 저장 및 관리한다 [1]. +- **Execution Model Inversion:** 엔진 실행 시 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색함으로써, JSON 내에 미사용 노드가 있더라도 실행 성능에 영향을 주지 않도록 설계되었다 [7]. +- **Metadata Injection:** 생성된 이미지(PNG/WebP)의 텍스트 청크(tEXt/zTXt)에 두 포맷을 모두 주입하여, 이미지 자체가 실행 논리의 컨테이너 역할을 수행하도록 한다 [8, 9]. + +## 📖 세부 내용 (Details) +ComfyUI의 직렬화 구조는 크게 두 가지 운영 맥락으로 나뉜다. + +**1. Frontend JSON (workflow.json)의 구조와 역할** +이 형식은 사용자가 웹 인터페이스에서 워크플로우를 편집하고 공유할 때 사용된다 [2]. 주요 특징은 다음과 같다: +- **시각적 메타데이터:** `pos`(좌표), `size`(크기), `flags`(노드 상태), `groups`(그룹 구조)와 같은 캔버스 레이아웃 정보를 완벽하게 보존한다 [1, 10]. +- **링크 표현:** 노드 간의 연결이 별도의 `links` 배열 내에서 명시적인 연결 객체로 관리된다 [2, 11]. +- **호환성:** 웹 인터페이스에서 드래그 앤 드롭을 통해 워크플로우를 원상복구하는 데 필수적이다 [3, 12]. + +**2. API JSON (workflow_api.json)의 구조와 역할** +서버리스 배포나 외부 애플리케이션 연동 시 사용되는 실행 전용 포맷이다 [2, 13]. +- **효율성 최적화:** 모든 UI 관련 정보를 제거하여 파일 용량을 줄이고 처리 속도를 높인다 [2]. +- **노드 식별:** 노드는 고유한 기능적 키(주로 숫자 문자열)로 식별되며, `class_type`과 `inputs` 필드가 핵심을 이룬다 [2, 14]. +- **연결 방식:** 별도의 링크 객체 없이, 노드의 입력 필드 내에 소스 노드와 슬롯 번호를 직접 기입하는 방식을 취한다 [1, 2]. + +**3. 포맷 간 전환 및 생성** +기본적으로 ComfyUI 설정의 'Dev mode Options'를 활성화해야 'Save (API format)' 버튼이 노출된다 [15, 16]. 일부 도구는 Frontend 포맷을 서버 사이드에서 API 포맷으로 변환하는 기능을 제공하여 개발자가 UI 버전만 관리할 수 있도록 돕기도 한다 [17, 18]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가독성 vs 실행력:** API JSON은 실행에는 최적화되어 있으나, 다시 UI로 불러올 경우 시각적 레이아웃이 파괴된 'Skeleton' 상태로 나타나 편집이 매우 어렵다는 한계가 있다 [18]. +- **데이터 유실 위험:** PNG 이미지에 포함된 메타데이터는 SNS 업로드나 압축 과정에서 쉽게 제거될 수 있으며, 이 경우 워크플로우 복구가 불가능해진다 [9, 19]. +- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라, 이전 버전에서 생성된 JSON 파일이 최신 엔진에서 정상적으로 동작하지 않을 수 있는 모순이 존재한다 [19]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드의 변환 로직을 Python으로 구현하여 `/workflow/convert` 엔드포인트를 통해 비 API 포맷을 API 포맷으로 변환한다 (Git Commit: `bc85382`) [17, 20, 21]. +- **ComfyUI-to-Python-Extension:** API JSON 포맷을 읽어 실행 가능한 순수 Python 스크립트(`.py`)로 변환하며, `workflow_api.py`라는 기본 파일명을 사용한다 [22, 23]. +- **Mystic Pipeline:** `workflow.json`을 포함한 디렉토리 구조에서 `new_pipeline.py`를 통해 입력 프롬프트를 JSON에 주입하고 실행하는 파이프라인 아키텍처를 구성한다 [24, 25]. +- **Replicate fofr/any-comfyui-workflow:** API JSON 블록을 직접 입력받아 GPU 환경에서 실행하고 결과물을 반환하는 프로덕션 모델로 활용된다 [26, 27]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (다양한 커스텀 노드 및 확장 도구에서 적용 사례 확인됨) +- **출처 신뢰도:** B (Official Documentation / GitHub Source Code README / Expert Tutorials) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[ComfyUI Workflow JSON 생성 방법]] + - 연결 이유: 본 주제의 루트 주제로서 전체적인 생성 맥락을 제공함. +- [[Litegraph Standard]] + - 연결 이유: Frontend 포맷의 시각적 레이아웃 규격을 결정하는 핵심 기술임. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 좌표 및 링크 객체 처리 방식의 원리. + +#### [구현/활용 도구] +- [[Dev Mode Options]] + - 연결 이유: API 포맷을 추출하기 위해 반드시 선행되어야 하는 UI 설정임. +- [[ComfyUI-Manager]] + - 연결 이유: JSON 로드 시 발생하는 종속성(Custom Node) 문제를 해결하는 필수 도구임 [28]. +- [[Load Image (Base64)]] + - 연결 이유: API 요청 시 외부 이미지 파일을 JSON 내부에 직렬화하여 포함하는 주요 방식임 [29]. + +### 심층 후속 질문 (Deeper Research Questions) +- Frontend JSON의 `links` 배열 구조와 API JSON의 `inputs` 내 임베디드 참조 방식 간의 변환 알고리즘은 구체적으로 어떻게 작동하는가? +- 이미지 메타데이터(tEXt/zTXt)에 두 가지 포맷을 동시에 저장할 때 발생하는 오버헤드와 실제 처리 우선순위는 무엇인가? +- `object_info.json`은 API JSON을 동적으로 생성하거나 검증하는 과정에서 어떤 데이터 스키마를 제공하는가? [13] +- 왜 ComfyUI는 API 포맷 노출을 기본적으로 숨기고 'Dev Mode'를 통해서만 접근하도록 설계했는가? [17] +- `ComfyUI-to-Python-Extension`이 변환한 파이썬 코드와 원본 API JSON 간의 실행 효율 차이는 존재하는가? +- 복잡한 서브그래프(Subgraph)가 포함된 워크플로우를 API 포맷으로 직렬화할 때의 제약 사항은 무엇인가? [30] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 외부 Python 앱에서 ComfyUI 서버로 프롬프트를 보낼 때는 반드시 API 포맷을 사용해야 하며, 프롬프트 내 특정 노드 ID의 값을 동적으로 변경하여 전송한다 [31, 32]. +- **System Design:** 프로덕션 환경에서는 사용자가 시각적으로 편집한 `workflow.json`을 저장하고, 시스템 내부적으로 이를 API 포맷으로 변환하여 큐에 삽입하는 아키텍처가 권장된다 [18]. +- **Operation / Maintenance:** 모델 파일명 변경이나 커스텀 노드 누락에 대비하여 JSON 내의 `class_type`과 실제 서버의 `object_info`를 대조하는 검증 로직이 필요하다 [33]. +- **Learning Path:** 초보자는 Frontend JSON을 통한 시각적 학습에 집중하고, 자동화 단계로 넘어갈 때 API 포맷의 노드 ID 및 입력 구조를 파악해야 한다 [34]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: JSON 파일 내의 하드코딩된 파일명 문제를 해결하기 위한 모델 식별 기술 [35]. +- [[Retrieval-Augmented Generation (RAG) for Nodes]] + - 확장 방향: LLM을 이용해 동적으로 최적의 노드 그래프를 생성하는 미래 기술 [36]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Serverless Deployment.md b/10_Wiki/Topics/Comfyui/Serverless Deployment.md new file mode 100644 index 00000000..3ea7d637 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Serverless Deployment.md @@ -0,0 +1,67 @@ +--- +id: serverless-deployment +title: "Serverless Deployment" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["서버리스 배포", "API 배포"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["new_pipeline.py", "pipeline.yaml", "fofr/any-comfyui-workflow"] +github_commit: "bc85382" +--- + +# [[Serverless Deployment]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우의 서버리스 배포는 시각적 메타데이터를 제거하고 실행 로직만 남긴 **API 포맷 JSON(Backend Format)**을 통해 워크플로우를 독립적인 실행 가능한 프로그램으로 변환하는 과정이다 [1-4]. + +## 🧠 핵심 개념 (Core concepts) +1. **API 포맷 JSON (workflow_api.json):** 서버 사이드 실행에 최적화된 스트림라인드 그래프로, 노드 위치나 크기 같은 UI 메타데이터를 제외하고 오직 노드 타입, 입력값, 연결 정보만을 포함한다 [1, 4]. +2. **서버리스 엔드포인트 (Serverless Endpoint):** GPU 관리, 오토스케일링, 플랫폼 최적화가 포함된 확장 가능한 API 지점으로, 사용자는 인프라 관리 없이 워크플로우를 실행할 수 있다 [3]. +3. **입력 오버라이드 (Input Overrides):** 배포된 워크플로우를 호출할 때 프롬프트, 시드, 이미지 경로 등 특정 파라미터만을 동적으로 변경하여 전송하는 방식이다 [5, 6]. +4. **종속성 패키징 (Dependency Packaging):** 서버리스 환경에서 워크플로우가 작동하도록 필요한 커스텀 노드, 모델 가중치, Python 라이브러리를 도커 이미지나 YAML 설정으로 정의하는 과정이다 [7, 8]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Bifurcation(이분화) 패턴:** 사용자 편집용 'Frontend JSON'과 실행 전용 'API JSON'을 분리하여 관리하며, API 요청 시에는 반드시 후자를 사용해야 한다 [1, 9, 10]. +- **Pipeline-as-Code:** 워크플로우 실행 로직을 Python 스크립트(`new_pipeline.py`)로, 환경 설정을 YAML(`pipeline.yaml`)로 작성하여 인프라를 코드로 관리한다 [7]. +- **Remote Asset Referencing:** 로컬 파일을 직접 사용하는 대신 URL 참조나 ZIP/TAR 압축 파일 업로드를 통해 서버리스 환경에 데이터를 공급한다 [11, 12]. + +## 📖 세부 내용 (Details) +* **API 포맷 획득 프로토콜:** 서버리스 배포를 위한 JSON을 얻으려면 ComfyUI 설정(Settings) 메뉴에서 **'Enable Dev mode Options'**를 활성화해야 한다 [2, 11, 13, 14]. 이후 제어판에 나타나는 **'Save (API format)'** 또는 **'Export (API)'** 버튼을 통해 추출할 수 있다 [2, 15]. +* **플랫폼별 배포 방식:** + * **Mystic:** `pipeline.yaml`에 CUDA 및 Python 의존성을 정의하고, `new_pipeline.py`에서 ComfyUI 서버 시작 및 워크플로우 로드 로직을 구현한다 [7, 8]. 도커 이미지를 빌드하여 Mystic 계정에 푸시하면 엔드포인트가 생성된다 [8, 16]. + * **Replicate:** `fofr/any-comfyui-workflow`와 같은 범용 모델을 활용하거나 전용 API 토큰을 사용하여 Python/JavaScript 클라이언트로 워크플로우 JSON을 전송한다 [17-19]. + * **RunComfy:** 워크플로우를 'Serverless API (ComfyUI)'로 배포하며, 플랫폼이 내부적으로 `workflow_api.json`을 저장하고 API 호출 시 오버라이드 값만 적용하여 효율적으로 실행한다 [4, 6, 20]. +* **데이터 처리 및 통신:** + * **입력:** 이미지 입력 시 `Load Image (Base64)` 노드를 사용하여 JSON 내에 데이터를 직접 포함하거나, URL을 통해 클라우드 저장소의 자원을 참조한다 [11, 21]. + * **출력:** 결과물 확인을 위해 `SaveImageWebsocket` 노드를 사용하여 웹소켓 통신으로 이미지 바이너리를 수신하거나, 서버리스 플랫폼의 출력 디렉토리에 저장된 파일을 반환받는다 [21, 22]. +* **자동화 및 변환 도구:** `comfyui-workflow-to-api-converter-endpoint`를 설치하면 `/workflow/convert` 엔드포인트를 통해 일반 `workflow.json`을 API 포맷으로 서버사이드에서 즉시 변환하여 실행할 수 있다 [10, 23, 24]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +* **호환성 문제:** 표준 `workflow.json`을 API 엔드포인트(`prompt`)에 직접 전송하면 백엔드 엔진이 시각적 메타데이터를 해석하지 못해 오류가 발생한다 [10, 13]. +* **가독성 손실:** API JSON은 노드 위치 정보가 제거되었으므로, 이를 다시 ComfyUI UI로 드래그하면 노드들이 겹쳐진 '뼈대만 남은' 상태가 되어 편집이 극도로 어렵다 [25]. 따라서 원본 'Full Workflow' JSON을 반드시 별도로 보관해야 한다 [25]. +* **종속성 취약점:** 배포된 환경에 필요한 커스텀 노드가 누락되면 'Red Boxes' 에러가 발생하며, 이를 해결하기 위해 `ComfyUI-Manager`를 통한 의존성 해결이나 도커 기반의 환경 구성이 필수적이다 [8, 26, 27]. + +## 🛠️ 적용 사례 (Applied in summary) +* **`new_pipeline.py`**: Mystic 플랫폼에서 서버리스 엔드포인트를 정의하는 핵심 파이썬 파일로, 입력 프롬프트를 JSON 워크플로우에 주입하고 실행하는 템플릿 역할을 한다 [7, 22]. +* **`pipeline.yaml`**: Mystic 배포 시 CUDA 버전, Python 라이브러리 종속성, 오토스케일링 설정을 포함하는 구성 파일이다 [7, 8]. +* **`fofr/any-comfyui-workflow`**: Replicate에서 어떤 API 포맷 JSON이든 수용하여 실행할 수 있도록 설계된 범용 서버리스 모델이다 [17, 19]. +* **GitHub Commit `bc85382`**: `comfyui-workflow-to-api-converter-endpoint`에서 콤보 위젯의 대소문자 표기 오류(예: True vs true)를 수정하여 유효성 검사 실패 문제를 해결한 기록이 확인된다 [28, 29]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Steganography in Generative AI.md b/10_Wiki/Topics/Comfyui/Steganography in Generative AI.md new file mode 100644 index 00000000..b8fa0a74 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Steganography in Generative AI.md @@ -0,0 +1,62 @@ +--- +id: steganography-in-generative-ai +title: "Steganography in Generative AI" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["메타데이터 은닉", "Metadata Embedding"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI-to-Python-Extension", "Comfy_UI_prompt_extractor", "comfyui_extractor.py", "exiftool"] +github_commit: "" +--- + +# [[Steganography in Generative AI]] + +## 🎯 한 줄 통찰 (One-line insight) +생성형 AI의 결과물(이미지) 내부에 실행 가능한 워크플로우 로직(JSON)을 메타데이터 형태로 은닉함으로써, 시각적 자산과 그 제작 절차를 결합하여 완벽한 재현성을 확보하는 기술 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **메타데이터 주입 (Metadata Injection):** ComfyUI의 'Save Image' 노드가 실행될 때, 최종 이미지 파일의 숨겨진 메타데이터 영역에 전체 노드 그래프, 설정 및 프롬프트를 자동으로 포함시키는 프로세스 [2, 4]. +- **PNG 청크 구조 (tEXt/zTXt Chunks):** PNG 파일 규격 내에서 텍스트 정보를 저장하기 위해 정의된 특정 영역으로, ComfyUI는 이곳에 'workflow'(프런트엔드 포맷)와 'prompt'(API 포맷)라는 두 가지 정보를 저장함 [5]. +- **데이터 프레절리티 (Metadata Fragility):** 소셜 미디어 플랫폼이나 일반 이미지 편집기(예: GIMP)를 거칠 경우, 파일 최적화나 개인정보 보호를 위해 비필수 메타데이터인 워크플로우 JSON이 제거되어 재현성이 소실되는 특성 [4-6]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **드래그 앤 드롭 복구 패턴:** 이미지 파일을 ComfyUI 캔버스에 직접 끌어다 놓으면 내장된 JSON 데이터를 읽어 즉각적으로 노드 레이아웃을 복구하는 직관적 인터페이스 패턴 [2, 7]. +- **이중 직렬화 저장 전략:** PNG 메타데이터 내에 시각적 편집을 위한 '프런트엔드 포맷'과 실제 실행을 위한 'API/백엔드 포맷'을 동시에 저장하여 호환성을 높임 [5, 8]. +- **사후 추출 및 주입 패턴:** 메타데이터가 손실되었거나 대량의 이미지에서 로직을 추출해야 할 경우, `exiftool`이나 전용 CLI 도구를 사용하여 이진 태그에서 JSON을 분리해내는 패턴 [9, 10]. + +## 📖 세부 내용 (Details) +ComfyUI 생태계에서 스테가노그래피는 주로 생성된 이미지(PNG, WebP 등) 내부에 워크플로우의 "소스 코드"에 해당하는 JSON 데이터를 숨기는 방식으로 구현된다 [1, 2]. + +- **저장 메커니즘:** 대부분의 워크플로우는 `Save Image` 노드에서 종료되며, 이 노드가 구동될 때 생성된 이미지의 비가시적 메타데이터 영역에 전체 노드 레이아웃, 노드 간의 링크, 입력값, 모델 설정 등을 주입한다 [2, 4]. 이는 별도의 파일 없이 이미지 자체를 워크플로우의 백업 또는 공유 매체로 사용할 수 있게 한다 [4]. +- **데이터 구조의 세분화:** PNG 파일 내의 `tEXt` 또는 `zTXt` 청크를 활용하며, 여기에 두 가지 형태의 문자열이 저장된다. 하나는 UI 레이아웃 정보를 포함한 **Frontend Format(workflow.json)**이며, 다른 하나는 백엔드 엔진이 즉시 실행할 수 있도록 정제된 **API Format(prompt/workflow_api.json)**이다 [5]. +- **추출 기술:** 이미지에서 은닉된 로직을 복구하기 위해 `exiftool -b -workflow input.png > workflow.json`과 같은 명령어를 사용하여 이진 메타데이터 영역에서 JSON 스트링을 분리해낼 수 있다 [9]. 또한 `ComfyUI-to-Python-Extension`과 같은 도구는 생성된 스크립트가 저장하는 이미지에 프런트엔드 메타데이터를 포함시켜 다시 UI로 불러올 수 있도록 지원한다 [11]. +- **한계점:** 이러한 스테가노그래피 방식은 매우 편리하지만, 이미지 압축 소프트웨어나 온라인 플랫폼의 메타데이터 제거 정책에 취약하여 데이터가 유실될 위험이 상존한다 [5, 7]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정보의 불완전성:** 이미지 임베딩 방식(첫 번째 방법)은 간편하지만, 때때로 새롭게 추가된 노드나 커스텀 노드의 일부 정보를 누락하는 경우가 보고되어, 복잡한 워크플로우의 경우 별도의 JSON 파일 저장(두 번째 방법)이 권장된다 [4]. +- **버전 호환성:** ComfyUI의 빈번한 업데이트로 인해, 이미지 내부에 저장된 구버전의 JSON 메타데이터가 최신 버전의 ComfyUI에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [7]. + +## 🛠️ 적용 사례 (Applied in summary) +- **exiftool 기반 워크플로우 추출:** `exiftool -b -workflow input.png` 명령을 통해 이미지 내의 비표준 태그에 저장된 JSON을 파일로 출력함 [9, 10]. +- **ComfyUI-to-Python-Extension:** 생성된 .py 스크립트 실행 시 저장되는 이미지에 프런트엔드 워크플로우 메타데이터를 포함하도록 구현되어 있어, 결과 이미지를 다시 UI로 드래그 앤 드롭하여 재편집 가능 [11]. +- **Weird Wonderful AI Art (추출기):** 웹 브라우저 기반으로 PNG 파일에서 JSON 워크플로우 데이터를 분석하고 추출해주는 전용 서비스 도구 [12, 13]. +- **Comfy_UI_prompt_extractor:** 이미지에서 긍정 프롬프트, API 그래프, UI 레이아웃을 분리하여 별도의 JSON 파일로 일괄 생성하는 CLI 도구 [9, 10]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Subgraph.md b/10_Wiki/Topics/Comfyui/Subgraph.md new file mode 100644 index 00000000..a222cac9 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Subgraph.md @@ -0,0 +1,62 @@ +--- +id: subgraph +title: "Subgraph" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint"] +github_commit: "bc85382" +--- + +# [[Subgraph]] + +## 🎯 한 줄 통찰 (One-line insight) +Subgraph는 복잡한 ComfyUI 노드 그래프를 논리적으로 캡슐화하고 모듈화하여 관리 및 실행 효율성을 극대화하는 공식 기능이다. [1-3] + +## 🧠 핵심 개념 (Core concepts) +1. **그래프 캡슐화 (Encapsulation):** 복잡한 노드 연결 구조를 하나의 상위 노드 단위로 묶어 워크플로우 가독성을 높이고 관리 지점을 단순화한다. [2, 3] +2. **중첩 구조 지원 (Nested Support):** 서브그래프 내부에 또 다른 서브그래프를 포함하는 계층적 구조 설계가 가능하다. [3] +3. **입력 슬롯 매핑 (Slot Mapping):** 상위 노드의 입력 위치와 내부 서브그래프 정의 간의 데이터 흐름을 정확히 일치시키는 동기화 메커니즘을 포함한다. [4] +4. **실행 모델 통합:** 노드 실행 시 서브그래프 존재 여부를 감지하고, 이를 전체 실행 리스트(Execution List)의 일부로 처리한다. [5] + +## 🧩 추출된 패턴 (Extracted patterns) +- **링크 ID 충돌 방지 패턴:** 서브그래프 내부의 링크 ID가 전체 워크플로우의 링크 ID와 충돌하지 않도록 독립적인 ID 할당 체계를 유지해야 한다. [4] +- **API 변환 최적화:** 워크플로우를 API 전용 JSON으로 변환할 때, 서브그래프의 계층 구조를 보존하면서도 실행 가능한 형태의 노드 입력 참조 방식으로 스트림라이닝한다. [3, 4] + +## 📖 세부 내용 (Details) +- **공식 릴리스 및 인터페이스:** Subgraph는 ComfyUI의 공식 기능으로 릴리스되었으며, 사용자 인터페이스 가이드의 "Interface Guide" 섹션에서 주요 기능으로 다루어진다. [1, 2] +- **실행 엔진과의 상호작용:** 백엔드 실행 엔진은 `get_output_data` 함수를 통해 노드의 실행 결과 및 UI 관련 출력과 함께 서브그래프의 존재 여부에 대한 추가 정보를 반환한다. [5] +- **커스텀 노드 개발 활용:** 노드 개발자는 "Subgraph blueprints" 규격을 활용하여 특정 기능을 수행하는 서브그래프 기반의 커스텀 노드를 정의할 수 있다. [6] +- **JSON 변환 시의 기술적 처리:** + - 서브그래프 내부의 링크 ID가 외부 워크플로우와 충돌할 경우 입력 연결이 소실되는 문제가 발생할 수 있어, 이를 격리하여 처리하는 로직이 필수적이다. [4] + - 외부 노드의 슬롯 위치와 실제 서브그래프 정의 내의 입력 슬롯 위치가 다를 경우 이를 매핑하는 과정이 포함된다. [4] + - 중첩된 서브그래프를 처리하기 위해서는 재귀적인 변환 깊이 제한(예: 100회)을 두어 무한 루프를 방지하고 안정성을 확보한다. [3] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **API 호환성 이슈:** 초기에는 서브그래프가 포함된 워크플로우를 API 포맷으로 변환할 때 내부 링크 ID 충돌이나 슬롯 매핑 오류가 발생했으나, 이후 `comfyui-workflow-to-api-converter-endpoint`와 같은 툴을 통해 이러한 기술적 결함들이 해결되었다. [4, 7] +- **버전별 기능 차이:** V2.09 버전에서 서브그래프 입력 슬롯 매핑 방식이 개선되는 등 지속적인 스펙 업데이트가 이루어지고 있다. [4] + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint (V2.09):** 서브그래프 정의와 외부 노드 간의 입력 슬롯 매핑 위치가 불일치하는 문제를 해결했다. [4] +- **comfyui-workflow-to-api-converter-endpoint (V2.07):** 서브그래프 내부 링크 ID와 전체 워크플로우 링크 ID 간의 충돌로 인한 입력 연결 소실 문제를 수정했다. [4] +- **comfyui-workflow-to-api-converter-endpoint (V2.02):** 서브그래프 처리와 관련된 일반적인 버그를 수정했다. [7] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Visual Programming Environment.md b/10_Wiki/Topics/Comfyui/Visual Programming Environment.md new file mode 100644 index 00000000..a0b0ae12 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Visual Programming Environment.md @@ -0,0 +1,114 @@ +--- +id: visual-programming-environment +title: "Visual Programming Environment" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["시각적 프로그래밍 환경", "Node-based Interface"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Visual Programming"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: + - "ComfyUI/custom_nodes/ComfyUI-Manager" + - "ComfyUI-WorkflowGenerator (Commit: 82df278)" + - "comfyui-workflow-to-api-converter-endpoint (Commit: bc85382)" + - "comfyui_to_python.py" + - "/workflow/convert" + - "workflow_api.json" +github_commit: "82df278, bc85382" +--- + +# [[Visual Programming Environment]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI는 생성형 AI의 복잡한 파이프라인을 노드 기반의 유향 비순환 그래프(DAG)로 추상화하여, 코드 없이 로직을 설계하고 이를 JSON 형태로 직렬화하여 실행 및 공유할 수 있게 하는 고수준 시각적 프로그래밍 환경이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +1. **노드 기반 유향 비순환 그래프 (DAG):** 모델 로더, 샘플러, 인코더 등을 나타내는 노드들이 링크로 연결되어 데이터의 흐름을 정의하는 구조적 토대이다 [1, 4]. +2. **절차적 프레임워크 (Procedural Framework):** 정적인 메뉴 방식과 달리 알고리즘이나 절차를 통해 콘텐츠를 생성하며, 워크플로우 자체가 프로그램의 '소스 코드' 역할을 수행한다 [3, 5]. +3. **포맷의 이원화 (Bifurcation of Formats):** 시각적 편집을 위한 **Frontend JSON**과 서버 실행 및 API 호출에 최적화된 **API JSON**으로 구분되어 운영된다 [6-8]. +4. **실행 모델 역전 (Execution Model Inversion):** 그래프의 모든 노드를 실행하는 대신, 최종 출력 노드에서 거꾸로 추적하여 필요한 의존성 노드만 실행함으로써 성능을 최적화한다 [9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **메타데이터 임베딩 패턴:** 생성된 PNG 이미지의 tEXt 또는 zTXt 청크 내에 워크플로우 JSON을 삽입하여 이미지 자체가 실행 가능한 소스 코드가 되도록 설계한다 [10, 11]. +- **API 최적화 패턴:** 백엔드 실행 시 불필요한 좌표(pos), 크기(size), 그룹 등 UI 메타데이터를 제거하고 노드 간의 직접적인 참조로 그래프를 단순화한다 [6, 8, 12]. +- **의존성 해결 패턴:** 워크플로우 JSON 내 `class_type`을 로컬 레지스트리와 대조하여 누락된 커스텀 노드를 식별하고 자동으로 설치를 유도하는 구조를 가진다 [13, 14]. + +## 📖 세부 내용 (Details) +ComfyUI는 시각적 프로그래밍 환경으로서 사용자가 복잡한 수학적 이해나 프로그래밍 코드 작성 없이도 정교한 생성 AI 시스템을 설계할 수 있도록 돕는다 [2]. 이 환경의 핵심은 모든 작업 단위가 **노드(Node)**로 정의된다는 점이며, 이 노드들은 특정 슬롯(Slot)을 통해 데이터를 주고받는다 [4, 15]. + +**JSON 직렬화 아키텍처** +- **스키마 규격:** ComfyUI JSON Schema v1.0(Draft-07 사양)을 따르며, 각 노드는 `id`, `type`, `pos`, `size`, `widgets_values`, `inputs`, `outputs` 등의 속성을 필수적으로 포함한다 [16]. +- **워크플로우 생성 경로:** + - **수동 생성:** 웹 인터페이스에서 `Ctrl + S`를 통해 직렬화된 JSON 파일을 다운로드한다 [17]. + - **자동 추출:** 전용 도구(exiftool 등)를 사용하여 이미지 메타데이터에서 JSON을 복원한다 [18, 19]. + - **프로그래밍적 생성:** Python의 `json` 라이브러리를 사용해 딕셔너리 구조를 조작하거나 LLM을 통해 자연어 설명을 실행 가능한 그래프 구조로 변환한다 [20, 21]. + +**실행 환경의 분리** +프론트엔드 형식(Litegraph 표준 기반)은 캔버스 레이아웃 정보를 포함하여 인간의 협업과 시각적 편집에 적합하며, API 형식은 `/prompt` 엔드포인트에 즉시 전달 가능한 압축된 실행 그래프 형태를 띤다 [6, 12, 22, 23]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **메타데이터의 취약성:** 이미지 메타데이터에 워크플로우를 저장하는 방식은 편리하지만, 소셜 미디어나 표준 이미지 편집기에 의해 데이터가 제거(Stripped)될 위험이 크다 [11, 24]. +- **버전 호환성:** ComfyUI의 잦은 업데이트로 인해 이전 버전의 JSON 파일이 최신 환경에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [25]. +- **API 호환성 오류:** 표준 'Save'로 생성된 JSON을 API로 호출하면 오류가 발생하며, 반드시 'Dev mode'를 활성화하여 'Save (API Format)'으로 추출해야 한다 [26]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI/custom_nodes/ComfyUI-Manager:** 워크플로우 JSON을 분석하여 누락된 노드를 설치하고 관리하는 실제 구현체이다 [27, 28]. +- **ComfyUI-WorkflowGenerator (Commit: 82df278):** Qwen2.5 모델을 사용하여 자연어를 ComfyUI JSON으로 변환하는 파이프라인이 구현되어 있다 [29, 30]. +- **comfyui-workflow-to-api-converter-endpoint (Commit: bc85382):** 클라이언트 측의 JS 로직을 Python으로 변환하여 서버사이드에서 일반 JSON을 API 포맷으로 변환하는 `/workflow/convert` 엔드포인트를 제공한다 [26, 31]. +- **comfyui_to_python.py:** 시각적 워크플로우를 실행 가능한 독립적인 Python 스크립트로 변환하는 도구이다 [32]. +- **workflow_api.json:** RunComfy 등의 플랫폼에서 서버리스 API 호출의 기본 단위로 사용되는 직렬화 파일이다 [7]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견됨) +- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 분석 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI 워크플로우의 논리적 구조를 정의함 [1]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 데이터 흐름 및 의존성 관계. +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON 포맷의 시각적 메타데이터 규격을 결정함 [6, 23]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 위치, 크기 및 그룹 관리 방식. + +#### [구현/활용 도구] +- [[ComfyUI Workflow JSON]] + - 연결 이유: 시각적 환경의 설계를 저장하고 전달하는 중간 매개체임 [1, 33]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 수동/자동 생성 방법 및 스키마 구조. +- [[Execution Model Inversion]] + - 연결 이유: 그래프를 효율적으로 실행하기 위한 백엔드 최적화 기술임 [9]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 불필요한 노드 실행 방지 메커니즘. + +### 심층 후속 질문 (Deeper Research Questions) +- JSON v1.0 스키마에서 `widgets_values` 배열의 순서가 노드 실행 안정성에 미치는 영향은 무엇인가? [16] +- 이미지의 tEXt 청크 외에 SVG 포맷을 활용한 워크플로우 시각화 및 보존 전략은 어떻게 구현되는가? [34, 35] +- `object_info.json`을 활용하여 클라이언트 사이드에서 동적으로 노드 유효성을 검사하는 메커니즘은 무엇인가? [36] +- LLM 기반 생성 시 'Semantic Validation' 단계에서 발생하는 임베딩 유사도 검색의 정확도 한계는? [37, 38] +- 모델 해싱(SHA-256)을 통한 워크플로우 이식성(Portability) 해결 방식의 상세 아키텍처는? [39] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `/workflow/convert` 엔드포인트를 구축하여 프론트엔드 워크플로우를 실시간 API 포맷으로 변환 [26]. +- **System Design:** 워크플로우를 독립적인 Python 스크립트로 변환하여 헤드리스(Headless) 처리 파이프라인에 통합 [40, 41]. +- **Operation / Maintenance:** ComfyUI Manager를 통해 누락된 커스텀 노드(Red boxes)를 식별하고 복구 [13, 14]. +- **Learning Path:** 기본 예제 워크플로우를 로드하고 노드 연결 방식을 분석하여 시각적 프로그래밍 원리를 습득 [4, 42]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Generative AI Pipeline]] + - 확장 방향: 시각적 프로그래밍이 실제 AI 모델 실행 흐름으로 전환되는 전체 주기. +- [[Metadata Forensics]] + - 확장 방향: AI 생성 이미지에서 워크플로우를 추출하고 분석하는 디지털 포렌식 기술 [18]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. Drawing on sources [1-186]. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Workflow API JSON (Backend Format).md b/10_Wiki/Topics/Comfyui/Workflow API JSON (Backend Format).md new file mode 100644 index 00000000..025c2af9 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Workflow API JSON (Backend Format).md @@ -0,0 +1,98 @@ +--- +id: workflow-api-json-(backend-format) +title: "Workflow API JSON (Backend Format)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["API JSON", "Backend Format JSON"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI-WorkflowGenerator", "ComfyUI-to-Python-Extension", "comfyui-workflow-to-api-converter-endpoint", "comfy_api_simplified"] +github_commit: "" +--- + +# [[Workflow API JSON (Backend Format)]] + +## 🎯 한 줄 통찰 (One-line insight) +시각적 레이아웃 정보를 제거하고 노드 간의 실행 로직과 데이터 흐름만을 정제하여, ComfyUI 백엔드 엔진의 `/prompt` 엔드포인트에서 즉각 실행 가능한 최적화된 그래프 데이터 형식이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **UI 메타데이터의 박리 (Stripping UI Metadata):** 노드 위치, 크기, 그룹화 정보, 색상 등 캔버스 시각화를 위한 모든 데이터를 제외하여 파일 크기를 축소하고 처리 효율성을 높인다 [1-4]. +- **임베디드 링크 구조 (Embedded Link Representation):** 별도의 연결 객체 배열을 사용하는 대신, 노드 입력 필드 내에 소스 노드 ID와 출력 슬롯 번호를 직접 참조(예: `[5, 6]`)하여 관계를 정의한다 [1, 2, 7, 8]. +- **기능적 키 매핑 (Functional Key Mapping):** 각 노드는 고유한 문자열 키(ID)로 식별되며, `class_type`과 `inputs`를 핵심 속성으로 보유하여 백엔드 노드 레지스트리와 직접 매핑된다 [2, 9-11]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **개발자 모드 전환 패턴:** 수동 생성 시 설정 메뉴에서 'Enable Dev mode Options'를 활성화하여 'Save (API Format)' 버튼을 노출시키는 것이 필수 절차이다 [3, 12-15]. +- **동적 파라미터 주입 패턴:** 생성된 JSON 템플릿을 로드한 후, 특정 노드 ID의 `inputs` 딕셔너리에 접근하여 시드(Seed), 프롬프트, 이미지 경로 등을 프로그래밍 방식으로 수정하여 재전송한다 [9, 11, 16-18]. +- **데이터 인라인화 (Self-containment):** 외부 파일 참조 대신 "Load Image (Base64)" 노드 등을 통해 이미지 데이터를 Base64 문자열로 JSON 내부에 직접 포함시켜 자가 포함된 요청을 구성한다 [19, 20]. + +## 📖 세부 내용 (Details) +Workflow API JSON은 ComfyUI의 두 가지 주요 직렬화 형식 중 하나로, 주로 **프로그램 방식의 실행 및 API 호출**을 위해 설계되었다 [1, 2]. 이 형식은 Litegraph 표준을 따르는 프런트엔드 형식(`workflow.json`)과 달리 백엔드 엔진이 프롬프트를 처리하기 위해 예상하는 평면화된 실행 그래프(Flattened execution graph)를 제공한다 [1, 12]. + +기술적으로 API JSON은 루트 키가 노드 ID이고 값이 노드 정의인 단일 JSON 객체 구조를 갖는다 [10]. 각 노드 정의에는 `class_type`, `inputs`, 그리고 선택적인 `_meta` 데이터가 포함된다 [10]. 연결(Link)은 입력 리스트 내에서 `[소스_노드_ID, 소스_슬롯_인덱스]` 형태의 배열로 표현되며, 이는 특정 슬롯(예: VAE Loader의 VAE 출력 슬롯)을 명확하게 지정하는 데 중요하다 [7, 8]. + +실행 시 ComfyUI 백엔드는 이 JSON을 수신하여 '실행 모델 역전(Execution Model Inversion)' 방식을 적용한다 [21]. 즉, 'Save Image'와 같은 출력 노드에서 시작하여 그래프를 역방향으로 추적하며 필요한 의존성만 식별하여 실행한다 [21]. 이 과정 덕분에 JSON 내에 실행과 무관한 노드가 포함되어 있어도 성능에 영향을 주지 않는다 [21]. 또한, API JSON은 모델 가중치와 독립적이므로 크기가 매우 작아 버전 관리와 아카이빙에 유리하다 [22, 23]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가독성 및 편집성:** API JSON은 실행에는 최적화되어 있으나, ComfyUI UI로 다시 드래그 앤 드롭할 경우 노드 위치 정보 등이 없어 로직만 남은 '뼈대' 상태로 로드되어 시각적 편집이 어렵다는 단점이 지적된다 [24, 25]. +- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 이전 버전의 API JSON 형식이 최신 버전의 백엔드 엔진에서 정상적으로 작동하지 않을 수 있는 호환성 문제가 존재한다 [26]. +- **메타데이터 취약성:** PNG 이미지에 임베드된 API JSON 데이터는 이미지 편집기나 소셜 미디어 플랫폼을 거치면서 손실되기 쉽다 [27]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 프런트엔드 포맷을 백엔드 API 포맷으로 서버 측에서 변환하는 `/workflow/convert` 엔드포인트를 제공한다 [28, 29]. +- **ComfyUI-to-Python-Extension:** API 포맷의 JSON을 독립 실행 가능한 Python 스크립트로 변환하는 기능을 지원한다 [30, 31]. +- **comfy_api_simplified:** 노드 타이틀을 기준으로 API JSON의 파라미터를 수정하고 큐에 추가할 수 있는 Python 래퍼 라이브러리이다 [16, 18]. +- **Replicate 및 RunComfy 플랫폼:** 사용자가 업로드한 API JSON을 기반으로 서버리스 환경에서 워크플로를 실행하고 결과를 반환하는 시스템 아키텍처를 보유하고 있다 [4, 32, 33]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능) +- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처 및 데이터 표준] +- [[Workflow JSON (Frontend Format)]] + - 연결 이유: API JSON의 원형이 되는 시각적 작업 데이터 포맷이다 [1, 34]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 데이터 유무에 따른 두 포맷 간의 구조적 차이와 변환 필요성 [2]. +- [[Litegraph Standard]] + - 연결 이유: ComfyUI 프런트엔드가 채택하고 있는 그래프 시각화 표준이다 [1, 34]. + +#### [구현 및 자동화 도구] +- [[ComfyUI API Integration]] + - 연결 이유: API JSON이 실제로 활용되는 최종 목적지이다 [12, 35]. +- [[ComfyUI Manager]] + - 연결 이유: API JSON 로드 시 발생하는 커스텀 노드 의존성 문제를 해결하는 핵심 도구이다 [36, 37]. + +### 심층 후속 질문 (Deeper Research Questions) +- 시각적 레이아웃이 없는 API JSON을 다시 UI용 프런트엔드 JSON으로 복원할 때, 노드 배치 알고리즘은 어떻게 작동하는가? +- 노드 ID가 동적으로 변경될 수 있는 환경에서, 특정 노드를 타이틀(Title) 기반으로 안정적으로 식별하여 값을 수정하는 최적의 휴리스틱은 무엇인가? [16, 18] +- Execution Model Inversion 가이드에 명시된 백엔드 엔진의 노드 순회 알고리즘은 순환 참조를 어떻게 방지하는가? [21] +- 이미지 내 메타데이터에 포함된 API JSON이 손실되었을 때, 픽셀 정보를 분석하여 워크플로를 추론하는 기술적 가능성이 존재하는가? +- 대규모 배치 처리 환경에서 API JSON의 `_meta` 필드를 활용하여 실행 로그와 결과를 추적하는 방법은 무엇인가? [10] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 자동화 스크립트 작성 시 `json` 라이브러리를 사용해 API JSON의 특정 노드 `inputs` 값을 덮어씌워 서버에 POST 요청을 보낸다 [9, 20]. +- **System Design:** 서버리스 AI 서비스 구축 시, 사용자의 의도를 LLM으로 해석하여 API JSON 구조를 동적으로 생성하는 파이프라인을 설계한다 [38-40]. +- **Operation / Maintenance:** ComfyUI Manager를 통해 JSON 내에 정의된 `class_type`을 기반으로 누락된 커스텀 노드를 자동 설치하여 환경을 동기화한다 [36, 41]. +- **Learning Path:** 기본 텍스트-투-이미지 워크플로를 API 형식으로 내보내고, Python에서 시드값을 바꿔가며 실행해보는 것부터 시작한다 [20, 42]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing (SHA-256)]] + - 확장 방향: JSON 내 모델 파일 이름 불일치 문제를 해결하기 위한 모델 고유 식별 기술 [43]. +- [[Base64 Image Encoding]] + - 확장 방향: API 요청 시 파일 업로드 없이 데이터를 JSON에 직렬화하여 전달하는 방식 [19, 20]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source references 29, 30, 32, 37, 38, 42, 43, 44, 45, 46, 71, 85, 86, 116, 124, 143, 144, 151, 152, 161, 162, 174, 192, 196 등 활용) [1-4, 7-16, 18-21, 24, 28, 30, 31, 36, 43] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Workflow API JSON.md b/10_Wiki/Topics/Comfyui/Workflow API JSON.md new file mode 100644 index 00000000..e0154463 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Workflow API JSON.md @@ -0,0 +1,103 @@ +--- +id: workflow-api-json +title: "Workflow API JSON" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["workflow_api.json", "Backend Format"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.95 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["SethRobinson/comfyui-workflow-to-api-converter-endpoint", "pydn/ComfyUI-to-Python-Extension", "DanielPFlorian/ComfyUI-WorkflowGenerator", "deimos-deimos/comfy_api_simplified"] +github_commit: "" +--- + +# [[Workflow API JSON]] + +## 🎯 한 줄 통찰 (One-line insight) +Workflow API JSON은 시각적 메타데이터를 제거하고 노드 간의 순수 실행 로직과 연결성만을 최적화하여 제공하는 ComfyUI의 서버 측 실행 인터페이스용 핵심 데이터 규격이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **백엔드 실행 최적화 (Backend Optimization):** 프론트엔드용 시각적 정보(위치, 크기, 색상)를 제외하고 오직 `/prompt` 엔드포인트 실행에 필요한 데이터만 포함한다 [1-3]. +- **노드-슬롯 연결성 (Node-Slot Connectivity):** 별도의 연결 객체 대신 노드 입력(inputs) 내에 직접 [원본 노드 ID, 출력 슬롯 인덱스] 형식으로 연결 정보를 임베딩한다 [1, 4, 5]. +- **고유 식별자 체계 (Unique ID System):** 각 노드는 고유한 숫자형 문자열 키(예: "5", "6")로 식별되며, 이는 실행 그래프 내에서 데이터 흐름을 추적하는 기준이 된다 [1, 3, 6]. +- **직렬화 유연성 (Serialization Flexibility):** 사람이 읽을 수 있는 JSON 형식을 취하며, 대규모 모델 가중치와 별개로 워크플로우 로직의 배포, 버전 관리 및 자동화를 가능하게 한다 [7-9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **UI 메타데이터 스트리핑 (Metadata Stripping):** 시각적 편집용 `workflow.json`에서 API 호출용 `workflow_api.json`으로 전환 시 `pos`, `size`, `groups`와 같은 필드를 제거하여 파일 크기를 축소하고 처리 효율을 높인다 [1, 2, 5]. +- **실행 모델 인버전 (Execution Model Inversion):** 엔진이 'Save Image'와 같은 출력 노드에서 역방향으로 그래프를 탐색하여 필수 종속성만 실행하고 불필요한 노드는 무시하는 구조를 취한다 [10]. +- **입력 데이터 인젝션 (Input Injection):** 자동화 시 JSON 내의 특정 노드 ID를 찾아 시드(seed), 프롬프트(prompt), 또는 Base64 인코딩된 이미지 데이터를 동적으로 교체하여 실행한다 [6, 11-13]. + +## 📖 세부 내용 (Details) +ComfyUI의 워크플로우 직렬화 형식은 크게 **프론트엔드 포맷**과 **백엔드(API) 포맷**으로 이분화된다 [1, 2, 14]. API JSON은 서버 측 엔진이 프롬프트를 실행하는 데 필요한 최소한의 논리 그래프를 나타내며, `Litegraph` 표준을 따르는 프론트엔드 포맷과 달리 매우 간결한 구조를 갖는다 [1, 3, 15]. + +- **생성 방법:** 사용자는 설정 메뉴에서 "Dev mode Options"를 활성화해야 하며, 이후 제어판에 나타나는 "Save (API Format)" 또는 "Export (API)" 버튼을 통해 이 파일을 생성할 수 있다 [16-20]. +- **구조적 특징:** 루트 키는 노드 ID이며, 각 값은 `class_type`과 `inputs`를 포함하는 객체이다 [6, 20]. 예를 들어, 특정 노드의 입력 필드에 `[ "20", 1 ]`과 같은 배열이 있다면 이는 20번 노드의 2번 슬롯(인덱스 1) 출력이 연결되었음을 의미한다 [4]. +- **메타데이터 임베딩:** ComfyUI에서 생성된 PNG 또는 WebP 이미지에는 프론트엔드 워크플로우와 API 프롬프트(JSON 형식)가 모두 메타데이터(tEXt 또는 zTXt 청크)로 저장되어 있어, 이미지 자체를 인터페이스로 드래그하여 로직을 복구할 수 있다 [21-24]. +- **프로그래밍 방식의 조작:** 파이썬의 `json` 라이브러리를 사용하여 딕셔너리 구조를 직접 수정하거나, `comfy_api_simplified`와 같은 래퍼 라이브러리를 통해 노드 제목 기반으로 파라미터를 동적으로 변경하여 대량의 이미지를 자동 생성할 수 있다 [6, 25-27]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **가독성 vs 편집성:** API 포맷은 실행에는 효율적이나, 시각적 정보가 결여되어 있어 다시 ComfyUI 인터페이스로 불러올 경우 노드들이 겹쳐 보이거나 구조 파악이 어려운 '스켈레톤' 상태가 된다 [28-30]. +- **파일 포맷 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 구버전의 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있는 호환성 문제가 존재한다 [31, 32]. +- **커스텀 노드 의존성:** JSON 자체에는 로직만 포함되므로, 워크플로우 생성자가 사용한 동일한 커스텀 노드가 로컬 환경에 설치되어 있지 않으면 'Red Box' 오류가 발생하며 실행이 불가능하다 [33, 34]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드 JS 로직을 파이썬으로 변환하여 서버 측에서 일반 워크플로우를 API 포맷으로 즉시 변환하는 엔드포인트를 제공한다 [28, 35]. +- **ComfyUI-to-Python-Extension:** `.json` 워크플로우를 독립 실행 가능한 `.py` 스크립트로 변환하여 헤드리스(headless) 환경에서 실행할 수 있게 한다 [25, 36]. +- **ComfyUI-WorkflowGenerator:** LLM(Qwen2.5 등)을 사용하여 자연어 설명을 실행 가능한 API JSON 그래프로 합성하고 유효성을 검증한다 [37-39]. +- **fofr/any-comfyui-workflow (Replicate):** 클라우드 환경에서 JSON 블롭(blob)을 입력받아 API를 통해 워크플로우를 실행하고 결과를 반환한다 [40, 41]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 및 오픈소스 프로젝트 코드를 통해 데이터 규격 및 생성 방식 확인됨) [42, 43] +- **출처 신뢰도:** B (Official Documentation / GitHub Repository / Expert Tutorial) +- **중복 검사 결과:** 신규 생성 (New discovery) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Litegraph Standard]] + - 연결 이유: ComfyUI 프론트엔드 JSON이 시각적 표현을 위해 채택한 기반 표준임 [1, 15]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: API 포맷으로 전환 시 제거되는 UI 메타데이터의 구조적 근거 [1, 2]. +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: ComfyUI 워크플로우의 근본적인 데이터 흐름 구조임 [7, 44]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 연결성과 실행 순서가 결정되는 논리적 원리 [7, 10]. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 로드 시 발생하는 누락된 노드 및 모델 문제를 해결하는 필수 도구임 [33, 34, 45]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 워크플로우 배포 시 발생하는 의존성 관리 전략 [34, 46]. +- [[/prompt endpoint]] + - 연결 이유: API 포맷 JSON이 최종적으로 전송되어 처리되는 목적지임 [2, 16, 28]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 클라이언트-서버 간의 실제 통신 메커니즘 [12, 13]. + +### 심층 후속 질문 (Deeper Research Questions) +- API JSON 내에서 링크 정보를 별도 배열이 아닌 노드 입력(inputs) 내에 직접 임베딩하는 방식이 실행 효율성에 미치는 영향은 무엇인가? [1, 4] +- LLM 기반의 워크플로우 생성 모델은 학습 데이터 이후에 출시된 새로운 커스텀 노드의 I/O 스키마를 어떻게 동적으로 학습하고 반영할 수 있는가? [44, 47, 48] +- `object_info.json`을 활용하여 동적으로 생성된 API JSON의 유효성을 런타임에 검증하는 구체적인 알고리즘은 어떻게 설계되는가? [20, 49] +- 실행 모델 인버전(Execution Model Inversion) 과정에서 조건부 분기나 반복 루프가 포함된 복잡한 그래프의 종속성을 어떻게 추적하는가? [10] +- 모델 해싱(Model Hashing)을 통해 하드코딩된 파일 경로 문제를 해결할 때, 서로 다른 머신 간의 모델 버전 일관성을 보장하는 방법은 무엇인가? [32, 46] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 배너 광고 자동 생성 시스템 구축 시, 템플릿 JSON의 특정 노드(예: CLIPTextEncode)를 파이썬 스크립트로 수정하여 자동화할 수 있음 [12, 50]. +- **System Design:** 서버리스 환경(Mystic, Replicate 등)에서 워크플로우를 배포할 때 UI 정보를 제거한 최적화된 API JSON을 기본 실행 단위로 설정함 [5, 19, 51]. +- **Operation / Maintenance:** `comfyui-workflow-to-api-converter-endpoint`를 사용하여 프론트엔드 워크플로우만 관리하고 실행 직전에 API 포맷으로 변환함으로써 관리 포인트의 이원화를 방지함 [29, 35]. +- **Learning Path:** 초보자는 시각적 그래프를 통해 로직을 이해하고, 숙련자는 개발자 모드를 통해 추출된 JSON의 노드 ID와 파라미터 구조를 분석하여 코딩 방식의 제어로 전이함 [52-54]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Base64 Image Encoding]] + - 확장 방향: API 요청 시 로컬 파일 경로 대신 이미지 데이터를 JSON에 직접 포함하는 기술적 구현 방법 [11, 13]. +- [[RAG (Retrieval-Augmented Generation)]] + - 확장 방향: 정적 모델의 한계를 극복하기 위해 실시간 노드 라이브러리를 검색하여 워크플로우를 생성하는 차세대 AI 에이전트 설계 [44]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) [1-200] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Workflow JSON v1.0 Schema.md b/10_Wiki/Topics/Comfyui/Workflow JSON v1.0 Schema.md new file mode 100644 index 00000000..3598132b --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Workflow JSON v1.0 Schema.md @@ -0,0 +1,117 @@ +--- +id: workflow-json-v1.0-schema +title: "Workflow JSON v1.0 Schema" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["ComfyUI JSON Schema", "Workflow v1.0 Specification"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법", "Schema", "JSON"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: + - "/specs/workflow_json" + - "/src/scripts/metadata" + - "comfyui-workflow-to-api-converter-endpoint" + - "ComfyUI-to-Python-Extension" +github_commit: "bc85382" +--- + +# [[Workflow JSON v1.0 Schema]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI 워크플로우 JSON은 생성 로직을 **유도 비순환 그래프(DAG)**로 구조화하여 시각적 인터페이스와 실행 엔진 사이의 상호운용성을 보장하는 핵심 데이터 규격이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **이원적 직렬화 포맷 (Bifurcation of Formats):** 시각적 편집과 레이아웃 보존을 위한 **Frontend Format**(workflow.json)과 서버 측 실행에 최적화된 **Backend/API Format**(workflow_api.json)으로 구분된다 [3-5]. +- **Litegraph 표준 기반:** 프론트엔드 포맷은 노드 위치, 크기, 그룹화 등 시각적 메타데이터를 포함하는 Litegraph 표준을 따른다 [3, 6]. +- **슬롯 기반 연결성 (Slot-based Connectivity):** 노드 간 데이터 흐름은 고유한 입력/출력 슬롯 인덱스를 통해 정의되며, API 포맷에서는 이를 노드 내부에 인라인 참조로 내장한다 [3, 7, 8]. +- **JSON Schema v1.0 (Draft-07):** 기술적 무결성을 검증하기 위해 필수 속성과 데이터 타입을 규정하는 최신 공식 사양이다 [9-11]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Metadata Redundancy 패턴:** PNG 파일 내에 시각적 포맷(workflow)과 실행 포맷(prompt)을 동시에 내장하여, 이미지 한 장만으로 편집과 재실행이 모두 가능하도록 설계되었다 [12, 13]. +- **Execution Model Inversion:** 최종 출력 노드(Save Image 등)에서 역방향으로 그래프를 탐색하여 실행에 필요한 의존성 노드만 식별하고 불필요한 연산을 배제한다 [14]. +- **Node Functional Mapping:** API 포맷에서 링크 객체를 제거하고 `[노드ID, 슬롯번호]` 형태의 배열로 간소화하여 전송 효율과 파싱 속도를 극대화한다 [3, 15, 16]. + +## 📖 세부 내용 (Details) +### 1. 노드 객체 속성 (Node Object Properties) +v1.0 스키마에 정의된 노드 객체는 그래프 탐색 및 렌더링을 위해 다음과 같은 속성을 포함해야 한다 [8, 9]: +- **id:** 그래프 내 노드를 식별하는 고유 정수 또는 문자열 [9]. +- **type (또는 class_type):** 노드 레지스트리에 등록된 클래스 이름과 매핑되는 식별자 [9, 16]. +- **pos & size:** 캔버스상의 좌표 및 크기 정보를 담은 배열 (API 포맷에서는 제거됨) [9, 16]. +- **widgets_values:** 텍스트 박스, 슬라이더 등 사용자 입력값을 저장하는 배열 [9, 15]. +- **order & mode:** 실행/렌더링 우선순위 및 노드의 활성 상태(예: bypass)를 정의한다 [8, 9]. + +### 2. 그래프 연결 구조 (Link and Slot Connectivity) +- **연결 정의:** 노드의 `inputs` 배열은 유입되는 선의 ID를 참조하며, `outputs` 배열은 여러 하위 노드로 연결될 수 있는 링크 ID들의 배열을 포함한다 [7]. +- **슬롯 인덱싱:** 특정 노드의 출력(예: VAE Loader의 VAE 출력)이 정확히 어떤 슬롯에서 생성되어 소비되는지 명시하는 것이 필수적이다 [7]. +- **API 포맷의 특수성:** `workflow_api.json`은 시각적 링크 배열을 제거하고, 노드 입력 필드 내에 직접 `["노드ID", 슬롯_인덱스]` 값을 할당하여 실행 그래프를 평탄화(Flattening)한다 [3, 15]. + +### 3. 보조 스키마 (object_info.json) +- 실행 중인 ComfyUI 인스턴스의 모든 노드에 대한 스키마 카탈로그이다 [5, 17]. +- 각 노드가 허용하는 입력 유형, 범위, 출력 데이터 타입 및 툴팁 정보를 포함하여 외부 도구에서 JSON을 동적으로 생성하거나 검증할 때 사용된다 [17-19]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성 문제:** 소스에 따르면 현재 v1.0이 최신이지만, ComfyUI의 잦은 업데이트로 인해 0.4 버전 등 이전 버전의 JSON 파일이 최신 환경에서 정상 작동하지 않을 수 있음이 지적된다 [10, 11, 20]. +- **데이터 파편화:** 이미지 메타데이터에서 추출한 JSON은 종종 커스텀 노드 정보를 누락할 수 있으며, 이 경우 캔버스에 'Red Boxes' 에러가 발생한다 [21-23]. +- **API 포맷의 가독성:** 실행 최적화된 API JSON은 시각적 정보가 모두 제거된 'Skeleton' 형태이므로, 이를 다시 ComfyUI 인터페이스로 드래그하여 편집하기에는 부적합하다 [24, 25]. + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI 공식 사양:** `/specs/workflow_json` 경로에서 v1.0 규격을 공식 관리한다 [10]. +- **프론트엔드 메타데이터 처리:** `ComfyUI_frontend/src/scripts/metadata`에서 자바스크립트 기반의 메타데이터 파싱 로직을 구현하고 있다 [26]. +- **comfyui-workflow-to-api-converter-endpoint:** 서버 측 파이썬 로직을 통해 Frontend JSON을 API JSON 규격으로 실시간 변환하며, `bc85382` 커밋에서 콤보 위젯 값의 정규화 이슈가 해결되었다 [24, 27-29]. +- **ComfyUI-to-Python-Extension:** JSON 워크플로우를 분석하여 동일한 로직의 `.py` 실행 스크립트를 생성할 때 v1.0 스키마 구조를 참조한다 [30, 31]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (공식 문서 기반의 스펙 정의 완료) +- **출처 신뢰도:** B (Official Documentation 및 전문 기술 블로그 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 + +### 상위/유사 개념 +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: 본 스키마가 생성 방법론의 기술적 기반이 됨. +- [[Dev mode Options]] + - 연결 이유: 스키마의 두 가지 형태(Frontend/API) 중 API 포맷을 내보내기 위한 필수 전제 조건임. + +#### [아키텍처/기반 기술] +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON의 데이터 구조와 렌더링 방식을 규정함. +- [[Execution Model Inversion]] + - 연결 이유: JSON 그래프를 해석하여 효율적으로 실행하는 백엔드 최적화 원리임. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 스키마 내의 `class_type`을 분석하여 누락된 커스텀 노드를 복구함. +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: JSON 워크플로우를 파이썬 코드로 이식하는 실제 사례임. + +### 심층 후속 질문 (Deeper Research Questions) +- API 포맷에서 링크를 노드 입력 내부에 인라인화하는 방식이 순환 참조(Circular Reference) 방지에 어떤 기여를 하는가? +- `object_info.json`의 스키마 데이터와 실제 노드의 `INPUT_TYPES` 메서드 사이의 동기화 실패 시 어떤 예외 처리가 발생하는가? +- v1.0 스키마에서 `widgets_values` 배열의 순서 기반 데이터 저장이 노드 업데이트로 인한 위젯 추가 시 어떤 호환성 문제를 일으키는가? +- PNG 파일의 `tEXt` 청크 용량 제한이 매우 거대한 워크플로우 JSON(예: 수백 개의 노드) 저장에 한계로 작용하는가? +- `comfy-pack`과 같은 도구에서 사용하는 모델 해싱 기술이 JSON 스키마 내에서 어떻게 표준화될 수 있는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 외부 애플리케이션(Unity, Web App 등)에서 ComfyUI 서버에 작업을 요청할 때 API JSON을 생성하고 전송해야 한다 [28, 32]. +- **System Design:** 워크플로우 자동화를 위해 JSON 내의 특정 노드 ID와 입력 필드(예: 프롬프트, 시드)를 동적으로 수정하는 로직을 설계할 수 있다 [33, 34]. +- **Operation / Maintenance:** 커스텀 노드 업데이트 시 JSON 내 `class_type` 명칭이 변경되면 워크플로우가 파손될 수 있으므로 버전 관리가 필요하다 [20, 35]. +- **Learning Path:** 노드 기반 인터페이스의 데이터 구조를 이해하면 시각적 툴 없이도 순수 코드로 생성 AI 파이프라인을 구축할 수 있다 [30, 36]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Custom Nodes]] + - 확장 방향: JSON 스키마에 새로운 노드 타입을 등록하고 관리하는 방법 연구. +- [[Metadata Stripping]] + - 확장 방향: 소셜 미디어 배포 시 이미지 내 메타데이터 손실 대응 방안 및 외부 JSON 저장 전략. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Workflow JSON.md b/10_Wiki/Topics/Comfyui/Workflow JSON.md new file mode 100644 index 00000000..0d8c3df6 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Workflow JSON.md @@ -0,0 +1,111 @@ +--- +id: workflow-json +title: "Workflow JSON" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Workflow API JSON", "Frontend JSON"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI/custom_nodes/ComfyUI-Manager", "ComfyUI/custom_nodes/ComfyUI-WorkflowGenerator", "ComfyUI/models/LLM/", "workflow_api.py"] +github_commit: "82df278, bc85382" +--- + +# [[Workflow JSON]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI의 Workflow JSON은 노드 기반 비순환 유향 그래프(DAG)를 직렬화하여 복잡한 생성형 AI 파이프라인을 휴대 가능한 데이터로 변환하고, 이를 통해 시각적 편집과 프로그래밍적 자동화를 연결하는 핵심 매개체이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **이분화된 직렬화 포맷:** 사용자 인터페이스를 위한 **Frontend 포맷(workflow.json)**과 서버 측 실행에 최적화된 **API 포맷(workflow_api.json)**으로 나뉜다 [4-6]. +- **Litegraph 기반 스키마 (v1.0):** 노드 ID, 유형, 위치, 크기, 위젯 값 및 노드 간의 링크 배열을 포함하는 표준화된 기술 규격을 따른다 [7-9]. +- **메타데이터 임베딩 기술:** 생성된 PNG나 WebP 이미지의 tEXt/zTXt 청크 내에 JSON 데이터를 직접 삽입하여 이미지 파일 자체가 워크플로우 백업 역할을 수행하게 한다 [10, 11]. +- **실행 모델 반전 (Execution Model Inversion):** 최종 출력 노드(Save Image 등)로부터 역추적하여 필요한 의존성 노드만 실행하는 최적화 구조를 가진다 [12]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **UI-to-API 정제 패턴:** 시각적 메타데이터(좌표, 그룹, 색상)를 제거하고 노드 입력을 직접적인 노드 참조로 변환하여 파일 크기를 줄이고 실행 효율을 극대화한다 [4, 13]. +- **LLM 기반 3단계 생성 파이프라인:** 자연어 설명 해석(Logical Synthesis) → 노드 존재 여부 검증(Semantic Validation) → 실행 가능한 JSON 컴파일(Graph Compilation) 과정을 통해 워크플로우를 자동 생성한다 [14-16]. +- **의존성 복구 휴리스틱:** JSON 내 `class_type`을 로컬 레지스트리와 대조하여 누락된 커스텀 노드를 식별하고 ComfyUI Manager를 통해 일괄 설치를 제안한다 [17, 18]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우 JSON은 생성적 AI 프로세스를 절차적 프레임워크로 추상화한 결과물이다 [1, 19]. 이 데이터 구조는 인간이 읽을 수 있는 형식이며, 대용량 모델 가중치와 독립적으로 공유 및 버전 관리가 가능하다 [2]. + +**1. 주요 포맷 상세 비교** [4, 5, 13, 20-22]: +- **Frontend JSON:** Litegraph 표준을 따르며 노드의 캔버스 좌표(`pos`), 크기(`size`), 그룹 정보 등 시각적 레이아웃 데이터를 모두 보존한다. 주로 시각적 편집과 공유를 목적으로 사용된다. +- **API JSON:** `/prompt` 엔드포인트 호출을 위한 정제된 형태이다. 시각적 정보는 삭제되며, 노드 간 연결은 별도의 링크 배열이 아닌 각 노드 입력부에 `[노드_ID, 출력_슬롯_인덱스]` 형태로 직접 임베딩된다. + +**2. 생성 및 획득 방법** [23-27]: +- **수동 내보내기:** GUI의 제어판에서 `Ctrl + S`(Frontend)를 누르거나, 설정에서 'Dev mode' 활성화 후 'Save (API format)' 버튼을 클릭하여 생성한다. +- **이미지에서 추출:** 생성된 PNG 파일을 캔버스에 드래그 앤 드롭하면 내장된 JSON이 로드된다. 대량 추출 시 `exiftool`이나 `ComfyUI-Workflow-Extractor` 같은 CLI 도구를 사용하여 메타데이터 청크에서 직접 파싱할 수 있다. +- **LLM 생성:** `Qwen2.5-14B` 등 미세 조정된 모델을 사용하여 "SDXL용 텍스트-이미지 워크플로우 생성"과 같은 자연어 지시를 즉시 실행 가능한 JSON 그래프로 변환한다 [14, 28]. + +**3. 프로그래밍적 조작 및 자동화** [29-33]: +- 개발자는 Python의 `json` 라이브러리를 사용하여 노드 ID를 기반으로 프롬프트(`CLIPTextEncode`), 시드값, 체크포인트 이름 등을 동적으로 변경할 수 있다. +- `Comfy API Simplified`와 같은 래퍼 라이브러리는 숫자 ID 대신 노드 제목(Title)을 기준으로 파라미터를 설정할 수 있게 하여 코드 유지보수성을 높인다. +- 워크플로우 자체를 순수 Python 스크립트로 변환하여 서버리스 환경이나 단독 애플리케이션에서 실행할 수도 있다 [34]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **버전 호환성:** ComfyUI의 잦은 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [35]. +- **메타데이터 취약성:** 이미지 편집기, 소셜 미디어 플랫폼 등에서 파일 최적화 과정 중 워크플로우 정보가 포함된 메타데이터 청크를 삭제하는 경우가 많아 JSON 공유 시 주의가 필요하다 [10]. +- **노드 명칭 충돌:** 서로 다른 제작자가 만든 커스텀 노드가 동일한 제목을 가질 수 있어, 프로그래밍적 접근 시 숫자 ID나 고유 클래스 타입 확인이 필수적이다 [33]. + +## 🛠️ 적용 사례 (Applied in summary) +- **DanielPFlorian/ComfyUI-WorkflowGenerator:** LLM을 이용해 자연어로 JSON을 생성하는 프로젝트로, 커밋 `82df278`에서 모델 경로 해결 및 중복 드롭다운 수정이 이루어졌다 [36, 37]. +- **SethRobinson/comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측 JS 로직을 서버 측 Python으로 변환하여 Frontend JSON을 API 포맷으로 즉시 변환하는 엔드포인트를 구현했다 (커밋 `bc85382`) [38, 39]. +- **ComfyUI Manager:** JSON 내부의 노드 정의를 분석하여 `ComfyUI/custom_nodes` 디렉토리에 필요한 의존성을 자동 설치하는 매커니즘을 제공한다 [17, 40]. +- **Standalone Execution Scripts:** `sdxl_workflow_api.json`을 로드하여 독립적인 Python 환경에서 실행하는 `WorkflowExecutor` 사례가 확인되었다 [41, 42]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 오픈소스 프로젝트와 공식 문서의 구조가 일치함을 확인) +- **출처 신뢰도:** B (공식 문서 및 실제 구현 코드가 포함된 GitHub 저장소 기반) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Directed Acyclic Graph (DAG)]] + - 연결 이유: 워크플로우의 노드 연결 구조를 정의하는 수학적 기반임 [1]. + - 이해 증진: 실행 순서 결정 및 의존성 해결 원리를 이해할 수 있음. +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON 포맷의 시각적 직렬화 규격임 [4, 20]. + - 이해 증진: 노드 위치, 크기 및 시각적 플래그 저장 방식을 파악할 수 있음. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 내 정의된 커스텀 노드 의존성을 해결하는 핵심 도구임 [17]. + - 이해 증진: 공유된 워크플로우의 실행 오류를 해결하는 프로세스를 이해할 수 있음. +- [[Large Language Models (LLM)]] + - 연결 이유: 자연어를 JSON으로 변환하는 최신 자동화 기술의 핵심임 [14, 37]. + - 이해 증진: '대화형 프로그래밍'으로의 진화 방향을 이해할 수 있음. + +### 심층 후속 질문 (Deeper Research Questions) +- Frontend JSON과 API JSON 사이의 변환 과정에서 손실되는 데이터가 실행 결과에 미치는 영향은 무엇인가? [4, 39] +- 이미지 메타데이터(tEXt/zTXt) 외에 워크플로우 정보를 보존하기 위한 더 견고한 아키텍처는 무엇인가? [10, 43] +- LLM 기반 생성기에서 '훈련 시점 이후 출시된 커스텀 노드'에 대한 환각(Hallucination) 문제를 어떻게 제어하는가? [44, 45] +- Execution Model Inversion이 대규모 복합 워크플로우에서 자원 효율성을 구체적으로 얼마나 개선하는가? [12] +- 모델 해싱(SHA-256)을 JSON 내에 포함시켜 파일명 불일치 문제를 해결하는 표준화된 방식은 무엇인가? [46] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** Python의 `urllib`과 `websocket`을 사용하여 `/prompt` 엔드포인트에 JSON 페이로드를 전송하고 결과를 실시간으로 수신함 [32]. +- **System Design:** 워크플로우를 JSON으로 관리함으로써 CI/CD 파이프라인을 통한 자동 테스트 및 버전 관리가 가능해짐 [47]. +- **Operation / Maintenance:** 모델 파일 경로가 다른 환경으로 이전 시 JSON 내부의 파일명을 로컬 환경에 맞춰 수정하거나 ComfyUI Manager의 검색 기능을 활용함 [43]. +- **Learning Path:** 기본 워크플로우 템플릿 로드 → 시각적 노드 연결 변경 → JSON 내보내기 및 구조 분석 순서로 학습 권장 [48]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Model Hashing]] + - 확장 방향: JSON 파일의 기기 간 이동 시 모델 파일명 불일치 문제를 해결하는 기술적 대안 [46]. +- [[Workspace Packaging (.cpack.zip)]] + - 확장 방향: JSON 단일 파일의 한계를 넘어 모델 해시와 노드 버전까지 패키징하는 미래 표준 [43]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [1, 6, 14, 24, 25, 29, 30, 32, 37, 41, 43, 49-52] \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Workflow.json (Frontend Format).md b/10_Wiki/Topics/Comfyui/Workflow.json (Frontend Format).md new file mode 100644 index 00000000..90ff47f5 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Workflow.json (Frontend Format).md @@ -0,0 +1,109 @@ +--- +id: workflow.json-(frontend-format) +title: "Workflow.json (Frontend Format)" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["Frontend JSON", "Full Workflow Export"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfyui-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "ComfyUI-WorkflowGenerator"] +github_commit: "" +--- + +# [[Workflow.json (Frontend Format)]] + +## 🎯 한 줄 통찰 (One-line insight) +ComfyUI의 시각적 편집 상태와 노드 간의 논리적 연결을 **Litegraph 표준**에 따라 완벽하게 보존하여, 인간의 재편집과 기계적 실행 사이의 가교 역할을 수행하는 전제 상태(Full State) 스냅샷 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +1. **Litegraph 표준 준수:** ComfyUI 웹 인터페이스의 캔버스 레이아웃을 정의하는 라이브러리인 Litegraph 형식을 따르며, 시각적 렌더링에 필요한 모든 데이터를 포함한다 [1, 2]. +2. **시각적 메타데이터(Visual Metadata):** 노드의 좌표(pos), 크기(size), 그룹 구성, 색상, 노드의 축소(collapsed) 또는 고정(pinned) 상태 등의 정보를 상세히 기록한다 [1, 3, 4]. +3. **명시적 링크 구조(Explicit Links):** 노드 간의 연결을 별도의 `links` 배열 내에서 고유 ID를 가진 명시적 객체로 관리하여 그래프의 시각적 연결성을 유지한다 [2, 3, 5]. +4. **노드 식별자(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 리포지토리를 통한 교차 검증 완료) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Litegraph Standard]] + - 연결 이유: Frontend JSON 포맷의 구조적 근간이 되는 라이브러리 규격임 [1]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 배치 및 링크 렌더링 원리. +- [[Workflow.api.json (Backend Format)]] + - 연결 이유: Frontend JSON에서 UI 정보를 제거하고 실행 효율성을 극대화한 대응 포맷임 [1, 3]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 표현과 논리적 실행 구조의 분리. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: JSON 내의 `class_type`을 분석하여 누락된 커스텀 노드를 설치해주는 필수 관리 도구임 [20]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 종속성 관리 및 환경 복구 프로세스. +- [[Workflow Extractor]] + - 연결 이유: 이미지 메타데이터에 숨겨진 Frontend JSON을 추출하는 전문 도구임 [28, 29]. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메타데이터 보존 및 데이터 복구 기술. + +### 심층 후속 질문 (Deeper Research Questions) +- Frontend JSON의 `order` 필드가 실제 백엔드의 실행 순서와 항상 일치하는가? [14] +- PNG 이미지의 `tEXt` 청크와 `zTXt` 청크 중 어느 방식이 워크플로우 데이터 저장에 더 유리한가? [11] +- `comfyui-workflow-to-api-converter-endpoint`는 서브그래프(Subgraph)가 포함된 복잡한 프론트엔드 JSON을 어떻게 처리하는가? [23, 30] +- 노드 ID가 문자열로 저장될 때와 숫자로 저장될 때의 시스템 처리 차이는 무엇인가? [4, 6] +- 모델 해싱(Model Hashing) 기술이 JSON의 포터빌리티(Portability) 문제를 어떻게 해결하는가? [31] +- LLM이 생성한 논리적 다이어그램을 표준 V1.0 스키마에 맞게 검증하는 구체적인 메커니즘은 무엇인가? [26, 32] + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 커스텀 앱에서 워크플로우를 로드할 때, 우선 Frontend 포맷으로 불러와 사용자에게 시각적으로 보여준 뒤 실행 시점에만 API 포맷으로 변환하여 요청한다 [33]. +- **System Design:** 버전 관리 시스템(Git)에 워크플로우를 저장할 때, 시각적 변경 사항을 추적하기 위해 Frontend 포맷을 유지하는 것이 유리하다 [34]. +- **Operation / Maintenance:** 사용자가 공유한 이미지에서 워크플로우를 복원할 수 없는 경우, `exiftool` 등을 사용해 메타데이터 존재 여부를 선제적으로 확인한다 [29, 35]. +- **Learning Path:** 초보자는 시각적 노드 연결 방식을 통해 논리 구조를 익히고, 숙련자는 JSON의 `widgets_values`를 직접 수정하여 자동화 스크립트를 작성한다 [13, 36]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Custom Nodes]] + - 확장 방향: JSON 내의 `type` 필드가 실제 파이썬 클래스와 매핑되는 방식 연구. +- [[JSON Schema v1.0]] + - 확장 방향: 워크플로우 파일의 구조적 무결성을 검증하는 기술적 명세 확인 [14]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine based on 18 sources. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/WorkflowExecutor.md b/10_Wiki/Topics/Comfyui/WorkflowExecutor.md new file mode 100644 index 00000000..5161709f --- /dev/null +++ b/10_Wiki/Topics/Comfyui/WorkflowExecutor.md @@ -0,0 +1,94 @@ +--- +id: workflowexecutor +title: "WorkflowExecutor" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "applied" +canonical_id: "" +aliases: ["워크플로 실행기"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.90 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["GitHub Gist: Standalone execution script", "Quasilinear Musings: Executing ComfyUI Workflows as Standalone Scripts"] +github_commit: "" +--- + +# [[WorkflowExecutor]] + +## 🎯 한 줄 통찰 (One-line insight) +**[[WorkflowExecutor]]**는 ComfyUI의 웹 UI 및 서버 백엔드 종속성을 제거하여 워크플로를 독립적인 파이썬 스크립트 환경에서 실행할 수 있게 하는 핵심 오케스트레이션 엔진이다 [1, 2]. + +## 🧠 핵심 개념 (Core concepts) +- **독립적 실행 오케스트레이션**: 웹 기반 인터페이스 없이도 워크플로의 환경 초기화, 캐시 관리, 노드 실행을 총괄한다 [2]. +- **실행 그래프 구조화**: JSON 형식의 워크플로를 검증한 후 `DynamicPrompt`를 거쳐 순차적 실행이 가능한 `ExecutionList`로 변환한다 [2]. +- **노드 단위 데이터 처리**: 개별 노드의 입력 데이터를 조회(`get_input_data`)하고 연산을 수행하여 출력 데이터를 생성(`get_output_data`)하는 실행 단위를 제어한다 [3]. +- **캐시 통합 관리**: `ExecutionCache`와 연동하여 노드 출력 및 객체 인스턴스를 저장함으로써 중복 계산을 방지하고 성능을 최적화한다 [3, 4]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **Backend-Only Execution Pattern**: 시각적 메타데이터가 포함된 Frontend JSON 대신, 노드 간의 직접적인 입력 참조를 포함하는 [[Workflow API JSON (Backend Format)]]만을 사용하여 실행 효율성을 극대화한다 [5, 6]. +- **Validation-to-Execution Pipeline**: 실행 전 `validate_prompt`를 통해 그래프의 무결성을 선제적으로 확인하고, 이를 동적 리스트로 컴파일하여 실행하는 단계적 파이프라인 구조를 따른다 [2]. + +## 📖 세부 내용 (Details) +**[[WorkflowExecutor]]**는 ComfyUI 워크플로를 서버리스 환경이나 독립형 애플리케이션으로 배포하고자 하는 개발자들을 위한 해결책으로 고안되었다 [1, 7]. 기본적으로 ComfyUI는 프론트엔드와 백엔드가 밀접하게 결합되어 있으나, 이 엔진은 해당 로직을 분리하여 헤드리스(Headless) 처리를 가능하게 한다 [1]. + +실행 과정은 크게 세 단계로 나뉜다. 첫째, 입력받은 API 형식의 JSON 워크플로를 ComfyUI 내부의 `validate_prompt` 함수를 사용하여 검증한다 [2]. 둘째, 검증된 데이터를 `DynamicPrompt` 객체로 구성하고, 이를 다시 실행 순서가 정의된 `ExecutionList`로 변환한다 [2]. 셋째, 이 리스트를 순회하며 개별 노드를 `_execute_node` 메서드를 통해 실행한다 [3]. + +노드 실행 시에는 `get_input_data`를 호출하여 이전 노드의 출력값이나 위젯 값을 수집하고, 이를 `get_output_data` 함수에 전달하여 실제 연산을 수행한다 [3]. 이 과정에서 생성된 결과물과 실행 상태는 **[[ExecutionCache]]**에 저장되어, 동일한 연산의 반복을 피하고 실행 속도를 높이는 데 기여한다 [3, 4]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **종속성 모순**: ComfyUI의 기본 아키텍처는 서버와 UI가 강하게 결합되어 있어 독립 실행이 불가능하다고 여겨졌으나, **[[WorkflowExecutor]]**는 내부 함수들을 직접 호출하는 방식으로 이 제약을 극복했다 [1, 4]. +- **형식 요구사항**: 일반적인 `workflow.json`은 시각적 메타데이터를 포함하므로 **[[WorkflowExecutor]]**에서 직접 사용할 수 없으며, 반드시 'Dev mode'에서 내보낸 [[Workflow API JSON (Backend Format)]]을 사용해야 한다 [5, 6]. + +## 🛠️ 적용 사례 (Applied in summary) +- **Quasilinear Musings 프로젝트**: Timothy Lin이 제안한 "Executing ComfyUI Workflows as Standalone Scripts"의 핵심 구성 요소로 구현되었다 [7, 8]. +- **독립 실행 스크립트**: GitHub Gist에 공개된 소스 코드에서 `WorkflowExecutor` 클래스가 실제로 정의되어 있으며, SDXL Turbo 워크플로를 독립적인 `.py` 파일로 실행하는 데 성공적으로 적용되었다 [2, 4, 6]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** applied (GitHub Gist 및 기술 블로그를 통해 실제 구현 코드가 확인됨 [2, 8]) +- **출처 신뢰도:** B (전문 기술 블로그 및 오픈 소스 구현 사례 기반 [2, 7]) +- **중복 검사 결과:** 신규 생성 (기존 소스 내 독립 실행 엔진 개념 정의) + + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[Comfyui workflow json 생성 방법]] + - 연결 이유: 본 주제의 루트 주제이며 워크플로 데이터의 생성 기원을 정의함. +- [[Workflow API JSON (Backend Format)]] + - 연결 이유: **[[WorkflowExecutor]]**가 실행을 위해 반드시 필요로 하는 데이터 규격임 [5]. + +#### [구현/활용 도구] +- [[ExecutionCache]] + - 연결 이유: 실행 효율성을 위해 **[[WorkflowExecutor]]**와 함께 필수적으로 사용되는 캐시 시스템임 [3]. +- [[ComfyUI-to-Python-Extension]] + - 연결 이유: 워크플로를 파이썬 코드로 변환하여 독립 실행한다는 목적을 공유하는 대안적 도구임 [1]. + +### 심층 후속 질문 (Deeper Research Questions) +- WorkflowExecutor가 `validate_prompt`를 수행할 때 커스텀 노드의 존재 여부를 어떻게 확인하는가? [2] +- `ExecutionList` 생성 시 순환 참조(Circular Reference)가 있는 그래프에 대한 방어 로직은 어떻게 작동하는가? [2] +- **[[ExecutionCache]]**가 메모리 한계에 도달했을 때의 데이터 축출 정책은 어떻게 정의되어 있는가? [3] +- 독립 실행 환경에서 `SaveImage` 노드와 같은 파일 출력 노드의 경로 지정 방식은 어떻게 처리되는가? [6] +- WorkflowExecutor를 통해 실행할 때와 표준 ComfyUI 서버를 통해 실행할 때의 VRAM 점유 효율 차이는 어느 정도인가? +- 대규모 배치 처리를 수행할 때 WorkflowExecutor의 병렬 실행 가능성은 어떻게 설계되어 있는가? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** 파이썬 환경에서 ComfyUI 서버를 띄우지 않고 AI 생성 파이프라인을 자동화할 때 사용된다 [6]. +- **System Design:** 도커(Docker) 컨테이너 내에서 최소한의 오버헤드로 특정 워크플로를 실행하는 마이크로서비스 아키텍처에 적합하다 [1]. +- **Operation / Maintenance:** 서버 백엔드 업데이트 없이 특정 실행 로직만을 독립적으로 유지보수해야 할 때 유용하다 [1]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Execution Model Inversion]] + - 확장 방향: 출력 노드에서 시작하여 필요한 종속성만 실행하는 최적화 모델에 대한 심층 이해 [9]. +- [[ComfyUI Manager]] + - 확장 방향: 독립 실행 환경에서 누락된 커스텀 노드를 관리하고 설치하는 방법론 조사 [10]. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/Workspace Packaging.md b/10_Wiki/Topics/Comfyui/Workspace Packaging.md new file mode 100644 index 00000000..17258612 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/Workspace Packaging.md @@ -0,0 +1,97 @@ +--- +id: workspace-packaging +title: "Workspace Packaging" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [".cpack.zip", "Artifact-based Deployment"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["comfy-pack", ".cpack.zip"] +github_commit: "" +--- + +# [[Workspace Packaging]] + +## 🎯 한 줄 통찰 (One-line insight) +단순한 노드 그래프 직렬화를 넘어, 모델 해시와 커스텀 노드 버전 등 실행 의존성 전체를 하나의 아티팩트로 묶어 워크플로우의 영구적 재현성을 보장하는 차세대 배포 표준 [1]. + +## 🧠 핵심 개념 (Core concepts) +1. **아티팩트 기반 배포 (Artifact-based Deployment):** 원시 JSON 파일 대신 워크플로우 실행에 필요한 모든 컨텍스트를 포함하는 패키지 단위의 배포 방식 [1]. +2. **모델 가중치 해싱 (Model Weight Hashing):** 파일명에 의존하는 대신 SHA-256 해시를 사용하여 서로 다른 환경에서도 동일한 모델을 고유하게 식별하고 매핑 [1, 2]. +3. **버전 고정 (Version Locking):** 워크플로우 설계 당시 사용된 커스텀 노드의 특정 버전을 기록하여, 향후 노드 업데이트나 기능 중단(deprecation)으로 인한 오류를 방지 [1]. +4. **.cpack.zip 규격:** 워크플로우 JSON, 모델 해시 리스트, 커스텀 노드 버전 정보를 포함하도록 제안된 통합 패키지 형식 [1]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **불변성 확보 패턴 (Immutability Pattern):** JSON + SHA-256 Hash + Node Versioning을 결합하여 시간이 지나도 동일한 출력을 보장하는 '정적 실행 환경'을 구축함 [1]. +- **환경 독립적 식별 패턴 (Environment-Agnostic Identification):** 물리적 파일 경로(sd_xl_base.safetensors)가 아닌 데이터의 지문(Hash)을 통해 자원을 검색함으로써 이식성 문제를 해결함 [1, 2]. + +## 📖 세부 내용 (Details) +ComfyUI 워크플로우는 기존에 PNG 메타데이터나 단순 JSON 파일로 공유되었으나, 이는 모델 파일명 불일치나 커스텀 노드 버전 차이로 인한 'Red Nodes' 오류에 취약한(fragile) 구조를 가짐 [1, 3, 4]. **Workspace Packaging**은 이러한 한계를 극복하기 위해 워크플로우를 고립된 실행 단위로 취급함 [1]. + +주요 구성 요소는 다음과 같음: +- **워크플로우 직렬화:** 표준 JSON v1.0 규격에 따른 노드 및 링크 데이터 포함 [1, 5]. +- **의존성 체크섬:** `comfy-pack`과 같은 도구를 사용하여 모델 가중치의 SHA-256 해시를 생성하며, 이를 통해 사용자의 로컬 환경에서 파일명이 다르더라도 올바른 모델을 찾아낼 수 있음 [1, 2]. +- **노드 컨텍스트:** 특정 시점의 커스텀 노드 코드 상태를 고정하여 시스템의 일관성을 유지함 [1]. + +이 방식은 특히 고도화된 생성형 AI 프로덕션 환경에서 워크플로우가 미래에도 정상 작동하도록 보장하는 '버전 관리 및 아카이빙'의 핵심 기술로 자리 잡고 있음 [1, 6]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **모순:** 현재 가장 널리 쓰이는 방식은 Metadata가 포함된 PNG이나, 이는 보안 소프트웨어나 소셜 미디어 플랫폼에 의해 데이터가 손실되기 쉬워(stripped) 신뢰도가 낮음 [3]. +- **업데이트:** 단순 JSON 저장 방식에서 시스템 전체 상태를 패키징하는 `.cpack.zip` 기반의 아티팩트 배포로 패러다임이 전환되고 있음 [1]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfy-pack:** 모델 가중치의 SHA-256 해시를 사용하여 물리적 경로가 아닌 논리적 식별자로 모델을 관리하는 기능이 구현됨 [1, 2]. +- **.cpack.zip:** 워크플로우 JSON, 모델 해시, 노드 버전 정보를 통합 저장하기 위한 미래형 아티팩트 파일 규격으로 제안됨 [1]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (미래 지향적 기술로 제안되었으며 comfy-pack 등 일부 도구에서 구현 시작) +- **출처 신뢰도:** B (Official Documentation 및 전문 아키텍처 분석 기반) +- **중복 검사 결과:** 신규 생성 + +## 🔗 관련 문서 링크 (Related document links) + +### 상위/유사 개념 +#### [아키텍처/기반 기술] +- [[ComfyUI Workflow JSON]] + - 연결 이유: 패키징의 핵심이 되는 직렬화 데이터 형식. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 기반 데이터 구조의 표준화된 저장 방식. +- [[Model Hashing]] + - 연결 이유: 패키지 내에서 자원을 식별하는 유일한 기술적 수단. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 파일명 불일치 문제를 해결하는 SHA-256 기반 매핑 원리. + +#### [구현/활용 도구] +- [[ComfyUI Manager]] + - 연결 이유: 패키지 내 명시된 누락 노드를 탐지하고 복구하는 역할을 수행. + - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 의존성 자동 해결 및 설치 프로세스. + +### 심층 후속 질문 (Deeper Research Questions) +- `.cpack.zip` 패키지 내에서 모델 파일 자체를 포함하지 않고 해시만으로 대용량 가중치를 효율적으로 확보하는 원격 저장소 연동 프로토콜은 무엇인가? +- 커스텀 노드 버전 고정이 Git 커밋 해시를 사용하는 방식과 시맨틱 버저닝(Semantic Versioning)을 사용하는 방식 중 어느 것이 더 높은 호환성을 제공하는가? +- Workspace Packaging 기술이 Replicate나 Mystic과 같은 서버리스 API 환경에서 콜드 스타트(Cold Start) 시간에 미치는 영향은 어떠한가? +- 수백 개의 커스텀 노드가 얽힌 복잡한 워크플로우에서 모든 의존성을 누락 없이 패키징하기 위한 검증 알고리즘은 어떻게 설계되는가? +- 패키징된 아티팩트의 무결성을 검증하기 위해 SHA-256 외에 디지털 서명(Digital Signature)을 결합하는 보안 모델의 가능성은? + +### 실무 적용 맥락 (Practical Application Contexts) +- **Implementation:** `comfy-pack` 도구를 사용하여 프로젝트별 모델 해시 리스트를 생성하고 관리함 [2]. +- **System Design:** CI/CD 파이프라인에서 워크플로우 변경 시마다 `.cpack.zip` 아티팩트를 자동 생성하여 배포함 [1]. +- **Operation / Maintenance:** 특정 시점에 생성된 이미지를 재현해야 할 경우, 해당 패키지를 로드하여 노드 및 모델의 환경을 즉각 복원함 [1]. +- **Learning Path:** 단순 JSON 저장을 넘어 모델 해시의 중요성과 의존성 관리의 원리를 학습하는 고도화 단계임 [6]. + +### 인접 주변 주제 (Adjacent Topics) +- [[Retrieval-Augmented Generation (RAG) for Nodes]] + - 확장 방향: 정적으로 고정된 패키지를 넘어 실시간으로 최신 노드 정보를 탐색하고 반영하는 기술. +- [[Execution Model Inversion]] + - 확장 방향: 패키징된 거대 그래프 내에서 실제 출력에 필요한 노드만 선별하여 실행하는 최적화 기법. + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. 기초 아키텍처 및 .cpack.zip 규격 정의 포함. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/exiftool.md b/10_Wiki/Topics/Comfyui/exiftool.md new file mode 100644 index 00000000..ad920491 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/exiftool.md @@ -0,0 +1,58 @@ +--- +id: exiftool +title: "exiftool" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: [] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["ComfyUI.config"] +github_commit: "" +--- + +# [[exiftool]] + +## 🎯 한 줄 통찰 (One-line insight) +`exiftool`은 미디어 파일의 메타데이터 청크 내에 임베딩된 ComfyUI 워크플로 JSON 데이터를 추출, 삽입 및 복구하기 위한 표준 명령줄 유틸리티이다. [1], [2] + +## 🧠 핵심 개념 (Core concepts) +1. **메타데이터 추출 (Metadata Extraction):** PNG 파일의 `tEXt` 또는 `zTXt` 청크와 같은 바이너리 태그에서 직렬화된 워크플로 JSON을 독립된 파일로 분리한다. [3], [1] +2. **워크플로 복구 (Workflow Recovery):** 이미지 편집기(예: GIMP) 사용으로 인해 삭제된 메타데이터를 원본 파일에서 추출하여 재삽입함으로써 워크플로의 무결성을 유지한다. [4], [2] +3. **비표준 태그 정의 (Non-standard Tag Definition):** ComfyUI 워크플로 데이터는 비표준 태그에 저장되므로, 쓰기 작업을 수행할 때는 해당 태그를 허용하는 구성 설정이 필요하다. [2] + +## 🧩 추출된 패턴 (Extracted patterns) +- **바이너리 출력 패턴:** `-b` 플래그를 사용하여 특정 태그(`-workflow`)의 원시 데이터를 캡처하고 리다이렉션(`>`)을 통해 JSON 파일로 저장하는 전략을 사용한다. [1], [2] +- **설정 기반 삽입 패턴:** `exiftool`이 등록되지 않은 태그 쓰기를 거부하는 문제를 해결하기 위해 `%unreg` 지시어를 포함한 설정 파일을 참조하여 비표준 태그에 데이터를 주입한다. [2] + +## 📖 세부 내용 (Details) +`exiftool`은 ComfyUI 워크플로 관리 및 디지털 포렌식에서 핵심적인 역할을 수행하는 도구이다. [1] ComfyUI는 이미지 생성 시 `Save Image` 노드를 통해 워크플로(Frontend 포맷)와 프롬프트(API 포맷) 정보를 PNG 메타데이터에 주입하는데, `exiftool`은 이러한 바이너리 태그를 읽고 쓰는 데 최적화되어 있다. [5], [3], [1] + +구체적인 기술적 상세는 다음과 같다: +- **추출 메커니즘:** 대규모 이미지 저장소에서 드래그 앤 드롭 방식의 수동 추출이 비효율적일 때, `exiftool -b -workflow input.png > workflow.json` 명령을 통해 워크플로를 일괄적으로 격리할 수 있다. [1] 이는 이미지 내부의 직렬화된 JSON 데이터를 보존하면서 파일 시스템으로 인출하는 표준적인 방법이다. [1] +- **삽입 및 복사:** 단순한 추출을 넘어, 한 이미지의 워크플로를 다른 미디어(PNG, WebP, MP4 등)로 복사하거나 재삽입하는 것이 가능하다. [4] 단, 워크플로 태그는 표준 규격이 아니므로, `exiftool`은 기본적으로 이 태그에 대한 수정을 거부할 수 있다. 이를 해결하기 위해 사용자는 태그를 미등록(`%unreg`) 상태로 정의하는 별도의 설정 파일을 활용해야 한다. [2] +- **대안 도구와의 관계:** `Comfy_UI_prompt_extractor`나 `comfymeta` 등 특정 목적을 가진 CLI 및 UI 도구들이 존재하지만, `exiftool`은 가장 원형적인 유틸리티로서 워크플로 삽입 및 복사 기능을 구현하는 기반 기술로 언급된다. [2] + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **데이터 휘발성:** `exiftool`의 성능과 관계없이, 메타데이터 자체가 취약하다는 점이 지적된다. 소셜 미디어 플랫폼이나 표준 이미지 압축 유틸리티는 파일 크기 절감 및 프라이버시 보호를 위해 워크플로 JSON이 포함된 비필수 메타데이터를 제거하는 경우가 많으므로, 원본 파일이 아닐 경우 `exiftool`을 통한 추출이 불가능할 수 있다. [6], [7], [3] + +## 🛠️ 적용 사례 (Applied in summary) +- **ComfyUI.config 활용:** 워크플로 데이터를 비표준 태그에 추가하기 위해 `exiftool` 설정 파일에서 해당 태그를 `%unreg`로 정의하여 사용한 사례가 보고되었다. [2] +- **CLI 워크플로 추출:** `exiftool -b -workflow input.png > workflow.json` 명령어를 통해 PNG 파일에서 워크플로 데이터를 직접 추출하여 JSON 파일로 변환하는 방식이 표준으로 사용된다. [1], [2] + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 명령어와 설정 파일 적용 방식이 소스 내에 기술됨) +- **출처 신뢰도:** B (Official Documentation 및 GitHub Issue 기반 기술 명세) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/Comfyui/workflow_api.json.md b/10_Wiki/Topics/Comfyui/workflow_api.json.md new file mode 100644 index 00000000..10aa6530 --- /dev/null +++ b/10_Wiki/Topics/Comfyui/workflow_api.json.md @@ -0,0 +1,67 @@ +--- +id: workflow_api.json +title: "workflow_api.json" +category: "10_Wiki/Topics" +status: "draft" +verification_status: "conceptual" +canonical_id: "" +aliases: ["API Format JSON", "Backend Format JSON", "Prompt JSON"] +duplicate_of: "" +source_trust_level: "B" +confidence_score: 0.85 +created_at: 2026-05-19 +updated_at: 2026-05-19 +review_reason: "" +merge_history: [] +tags: ["research", "Comfyui workflow json 생성 방법"] +raw_sources: ["NotebookLM Synthesis"] +applied_in: ["/workflow/convert", "comfyui-workflow-to-api-converter-endpoint", "fofr/any-comfyui-workflow", "ComfyUI-to-Python-Extension"] +github_commit: "bc85382" +--- + +# [[workflow_api.json]] + +## 🎯 한 줄 통찰 (One-line insight) +`workflow_api.json`은 UI 메타데이터를 제거하고 노드 간의 기능적 연결성만을 추출하여 ComfyUI 백엔드 엔진이 즉시 실행할 수 있도록 최적화된 직렬화된 실행 그래프이다 [1-3]. + +## 🧠 핵심 개념 (Core concepts) +- **백엔드/API 포맷 (Backend/API Format):** 시각적 요소(위치, 크기, 그룹 등)를 배제하고 서버 사이드 처리 및 프로그램 기반 자동화에 최적화된 포맷이다 [1, 3]. +- **평탄화된 그래프 (Flattened Execution Graph):** 링크가 별도의 연결 객체가 아닌 노드 입력 내부에 직접 참조(Origin Node ID 및 Output Slot) 형태로 포함된 구조이다 [1, 3, 4]. +- **개발자 모드 종속성 (Dev Mode Dependency):** 표준 내보내기 기능과 달리, 설정 메뉴에서 'Dev mode Options'를 활성화해야만 생성이 가능한 특수 포맷이다 [5-7]. +- **/prompt 엔드포인트 호환성:** ComfyUI 서버의 API 엔드포인트에 직접 전달하여 워크플로우를 실행하기 위한 표준 데이터 구조로 사용된다 [2, 8, 9]. + +## 🧩 추출된 패턴 (Extracted patterns) +- **포맷 분화 (Schema Bifurcation):** 사용자 상호작용을 위한 'Frontend JSON(workflow.json)'과 실행을 위한 'API JSON(workflow_api.json)'을 철저히 분리하여 운영 효율성을 극대화한다 [1, 2, 10]. +- **노드 식별 기반 접근:** 각 노드는 고유한 숫자형 키(String ID)로 식별되며, 이를 통해 외부 스크립트에서 특정 노드의 입력을 동적으로 수정할 수 있다 [11, 12]. +- **역방향 의존성 탐색 (Execution Model Inversion):** 엔진이 출력 노드(Save Image 등)로부터 역방향으로 탐색하여 최종 결과에 필요한 의존성 노드만 실행하는 구조를 지원한다 [13]. + +## 📖 세부 내용 (Details) +**데이터 구조 및 속성** +`workflow_api.json`은 루트 레벨의 키가 노드 ID(문자열)인 단일 JSON 객체 구조를 가진다 [14]. 각 노드 정의에는 `class_type`(노드 클래스 이름)과 `inputs`(위젯 값 및 타 노드 출력에 대한 연결 정보)가 포함되며, 선택적으로 `_meta` 필드가 존재할 수 있다 [11, 14]. 링크 표현 방식은 `[node_id, output_slot_index]` 형태의 배열로 입력 필드에 직접 삽입된다 [3, 15]. + +**생성 및 추출 프로세스** +1. **GUI 내보내기:** 설정 메뉴의 톱니바퀴 아이콘을 통해 'Enable Dev mode Options'를 활성화한 후, 제어판에 나타나는 'Save (API Format)' 또는 'Export (API)' 버튼을 사용하여 생성한다 [6, 7, 14, 16]. +2. **이미지 메타데이터 추출:** ComfyUI에서 생성된 PNG 파일의 `tEXt` 또는 `zTXt` 청크에는 워크플로우(Frontend)와 프롬프트(API) 데이터가 함께 저장되며, `exiftool`이나 전문 추출 도구를 통해 이를 복구할 수 있다 [17-20]. +3. **서버 사이드 변환:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면 일반 워크플로우 포맷을 실시간으로 API 포맷으로 변환하는 엔드포인트를 구축할 수 있다 [9, 21]. + +**프로그래밍적 활용** +이 포맷은 Python의 `json` 라이브러리를 통해 딕셔너리 형태로 로드되어 씨드(seed), 프롬프트 텍스트, 노이즈 강도 등의 파라미터를 동적으로 변경하는 데 사용된다 [11, 22]. `Replicate`, `Mystic`, `RunComfy` 등 클라우드 API 서비스는 이 포맷을 기반으로 워크플로우를 서버리스 함수나 컨테이너화된 서비스로 배포한다 [3, 23, 24]. + +## ⚖️ 모순 및 업데이트 (Contradictions & updates) +- **정보 손실의 비가역성:** API 포맷을 다시 ComfyUI 캔버스로 불러올 경우, UI 메타데이터가 삭제되어 있기 때문에 노드들이 겹쳐 보이거나 그룹 정보가 사라진 '뼈대(skeleton)' 상태로 복원되는 한계가 있다 [9, 25]. +- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드의 클래스 타입 변경에 취약하다 [26, 27]. + +## 🛠️ 적용 사례 (Applied in summary) +- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측의 자바스크립트 변환 로직을 파이썬으로 구현하여 `/workflow/convert` 엔드포인트를 제공함 [9, 28]. (Git Commit: `bc85382`) +- **ComfyUI-to-Python-Extension:** `workflow_api.json` 입력을 받아 실행 가능한 `.py` 스크립트로 변환하는 기능을 지원함 [29, 30]. +- **Mystic Pipeline Deployment:** `new_pipeline.py` 스크립트 내에서 API 포맷 JSON을 로드하여 입력 프롬프트를 주입하고 실행하는 템플릿 구조에 적용됨 [31, 32]. +- **Replicate fofr/any-comfyui-workflow:** API JSON 블롭을 입력받아 이미지/비디오를 생성하는 범용 워크플로우 모델의 핵심 입력 데이터로 활용됨 [23, 33]. + +## ✅ 검증 상태 및 신뢰도 +- **상태:** draft +- **검증 단계:** conceptual (실제 적용 사례 다수 발견으로 검증 가능) +- **출처 신뢰도:** B (공식 문서 및 개발자 가이드 기반 합성) +- **중복 검사 결과:** 신규 생성 (New discovery) + +## 📝 변경 이력 (Change history) +- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. \ No newline at end of file diff --git a/10_Wiki/Topics/memory/episodes/ep_2026-05-15_tetris라는_폴더를_만들고_거기에_react_기반으로_테트리스_게임_.json b/10_Wiki/Topics/memory/episodes/ep_2026-05-15_tetris라는_폴더를_만들고_거기에_react_기반으로_테트리스_게임_.json new file mode 100644 index 00000000..5fc52c8c --- /dev/null +++ b/10_Wiki/Topics/memory/episodes/ep_2026-05-15_tetris라는_폴더를_만들고_거기에_react_기반으로_테트리스_게임_.json @@ -0,0 +1,27 @@ +{ + "id": "262cd2f1-d533-4f6c-91c2-de044b44570a", + "sessionId": "task_1778819919539", + "title": "tetris라는 폴더를 만들고 거기에 react 기반으로 테트리스 게임 하나 만들어. 우선 만들기 전에...", + "summary": "시작: tetris라는 폴더를 만들고 거기에 react 기반으로 테트리스 게임 하나 만들어. 우선 만들기 전에 기획하고 설계하고 그 다음에 고딩으로 들어가면 좋겠어 → 최종: 지금까지 우리가 작업하면서 self reflector 기능이 있는데. 잘 반영되고 있는건지 확인해주면 좋겠어.", + "keyDecisions": [ + "텍서트(Conclusion Text): Final Result]**", + "현재의 `connectai`는 **'개인용 지능형 에이전트'**로서는 매우 수준 높은 설계를 가지고 있습니다. 하지만 프로젝트의 규모가 '개인의 메모'를 넘어 '방대한 데이터셋'을 다루게 될 경우, 지금의 **Ful", + "받으신다고 하셔서 일단은 홀드를 한 이틀 정도 해놨었잖아요.", + "참석자 7 46:53", + "* 5월 19일까지 최종 수정 빌드 완료 및 외부 시연용 영상 제작 계획 수동" + ], + "topics": [ + "참석자", + "그러니까", + "이렇게", + "모바일", + "그래서", + "같아요", + "그러면", + "거예요" + ], + "projectContext": "e:\\Wiki", + "timestamp": 1778840072869, + "duration": 0, + "messageCount": 77 +} \ No newline at end of file diff --git a/10_Wiki/Topics/memory/episodes/ep_2026-05-18_e_wiki_00_raw_script_test_ai로_새로운_비즈니스_저.json b/10_Wiki/Topics/memory/episodes/ep_2026-05-18_e_wiki_00_raw_script_test_ai로_새로운_비즈니스_저.json new file mode 100644 index 00000000..ad803fdf --- /dev/null +++ b/10_Wiki/Topics/memory/episodes/ep_2026-05-18_e_wiki_00_raw_script_test_ai로_새로운_비즈니스_저.json @@ -0,0 +1,21 @@ +{ + "id": "4549141d-0e03-4af8-b9fd-581b41891078", + "sessionId": "task_1779074798650", + "title": "E:\\Wiki\\00_Raw\\Script_test\\AI로 새로운 비즈니스 저와 함께 비행기 타고 샌프란시...", + "summary": "시작: E:\\Wiki\\00_Raw\\Script_test\\AI로 새로운 비즈니스 저와 함께 비행기 타고 샌프란시스코 구글로 떠나시죠 l EP.1 구글 IO 실리콘밸리__FmcX0VKJres → 최종: 만약 내가 유사한 내용으로 영상을 제작 하고 싶다면, 어떻게 해야하는지 스크립트 써줄 수 있어? \n\n스크립트 써줄때 콘티도 말해주고 그 다음에 상세 스크립트를 써주는게 좋을 것 같", + "keyDecisions": [], + "topics": [ + "스크립트를", + "wiki", + "00_raw", + "script_test", + "ai로", + "새로운", + "비즈니스", + "비행기" + ], + "projectContext": "e:\\Wiki", + "timestamp": 1779078041153, + "duration": 0, + "messageCount": 7 +} \ No newline at end of file diff --git a/10_Wiki/Topics/memory/episodes/ep_2026-05-18_e_wiki_connectai_이_프로젝트야.json b/10_Wiki/Topics/memory/episodes/ep_2026-05-18_e_wiki_connectai_이_프로젝트야.json new file mode 100644 index 00000000..10bb6fef --- /dev/null +++ b/10_Wiki/Topics/memory/episodes/ep_2026-05-18_e_wiki_connectai_이_프로젝트야.json @@ -0,0 +1,15 @@ +{ + "id": "81c78f42-315b-4af0-a694-3f6dc6fe624b", + "sessionId": "task_1779065343970", + "title": "E:\\Wiki\\connectai 이 프로젝트야", + "summary": "E:\\Wiki\\connectai 이 프로젝트야 ASTRA OFFICE 부분 관련해서 개선할 부분이 너무 많아. 개선점이 무었이 있는지 의견 주면 좋겠어. E:\\Wiki\\connectai GIT에서 PUll 해", + "keyDecisions": [], + "topics": [ + "wiki", + "connectai" + ], + "projectContext": "e:\\Wiki", + "timestamp": 1779065687652, + "duration": 0, + "messageCount": 7 +} \ No newline at end of file diff --git a/10_Wiki/Topics/memory/episodes/ep_2026-05-18_지금_작업하고_있는거_취소해.json b/10_Wiki/Topics/memory/episodes/ep_2026-05-18_지금_작업하고_있는거_취소해.json new file mode 100644 index 00000000..8c820f28 --- /dev/null +++ b/10_Wiki/Topics/memory/episodes/ep_2026-05-18_지금_작업하고_있는거_취소해.json @@ -0,0 +1,12 @@ +{ + "id": "cf21f52b-4219-4951-b10e-7b92d9dfbbf6", + "sessionId": "task_1779106388454", + "title": "지금 작업하고 있는거 취소해", + "summary": "지금 작업하고 있는거 취소해 지금 페이지들을 봤는데 작동안되는 페이지도 많고, 동시에 이미지가 없는 이미지들도 있어. 더미 값이지만 일단 모든 이미지를 다 추가해주고 클릭했을때의 보여줘야할 페이지들도 다 보일 수 있게 수정해줘.", + "keyDecisions": [], + "topics": [], + "projectContext": "e:\\Wiki", + "timestamp": 1779108915969, + "duration": 0, + "messageCount": 4 +} \ No newline at end of file diff --git a/10_Wiki/Topics/memory/long_term.json b/10_Wiki/Topics/memory/long_term.json index 6cd6ead5..851b8db7 100644 --- a/10_Wiki/Topics/memory/long_term.json +++ b/10_Wiki/Topics/memory/long_term.json @@ -8,8 +8,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655981978, - "lastReferencedAt": 1778655981978, - "referenceCount": 0 + "lastReferencedAt": 1779106389633, + "referenceCount": 5 }, { "id": "5d44cb85-e018-468c-a7be-dbfa44546fce", @@ -18,8 +18,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655981979, - "lastReferencedAt": 1778655981979, - "referenceCount": 0 + "lastReferencedAt": 1779106389633, + "referenceCount": 5 }, { "id": "4cb93674-fd06-4cf4-96f9-9ac2008a6b49", @@ -28,8 +28,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655981979, - "lastReferencedAt": 1778655981979, - "referenceCount": 0 + "lastReferencedAt": 1779106389633, + "referenceCount": 4 }, { "id": "acb8373d-3a17-4266-9f7e-608349add88c", @@ -38,8 +38,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655981986, - "lastReferencedAt": 1778655981986, - "referenceCount": 0 + "lastReferencedAt": 1779106389633, + "referenceCount": 4 }, { "id": "64b1c34d-64a0-493a-82ee-298c0fd1900f", @@ -48,8 +48,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655981992, - "lastReferencedAt": 1778655981992, - "referenceCount": 0 + "lastReferencedAt": 1779106389633, + "referenceCount": 5 }, { "id": "2e323e3f-bd37-4b25-8cd7-d21ddee58728", @@ -58,8 +58,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655981997, - "lastReferencedAt": 1778655981997, - "referenceCount": 0 + "lastReferencedAt": 1779106389633, + "referenceCount": 4 }, { "id": "e54c9135-67ac-4a46-b337-95af5bce61bb", @@ -68,8 +68,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655981998, - "lastReferencedAt": 1778655981998, - "referenceCount": 0 + "lastReferencedAt": 1779074730275, + "referenceCount": 2 }, { "id": "cee8c995-169d-481f-90e4-10cdb920dea5", @@ -78,8 +78,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655981998, - "lastReferencedAt": 1778655981998, - "referenceCount": 0 + "lastReferencedAt": 1779074803033, + "referenceCount": 1 }, { "id": "1438ba42-23b4-4751-bb64-aa583bbf43e0", @@ -88,8 +88,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655982004, - "lastReferencedAt": 1778655982004, - "referenceCount": 0 + "lastReferencedAt": 1779074803033, + "referenceCount": 1 }, { "id": "8f248ce7-e9f8-42a9-bc4a-eadfd3534419", @@ -98,8 +98,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655982011, - "lastReferencedAt": 1778655982011, - "referenceCount": 0 + "lastReferencedAt": 1779106389633, + "referenceCount": 2 }, { "id": "e0e13452-6fb1-40d4-8f7e-b3c24e07263b", @@ -158,8 +158,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655982028, - "lastReferencedAt": 1778655982028, - "referenceCount": 0 + "lastReferencedAt": 1779074803033, + "referenceCount": 1 }, { "id": "1a3671d5-1300-4a26-a9d1-3469c705a927", @@ -168,8 +168,8 @@ "source": "session:task_1778642741077", "confidence": 0.7, "createdAt": 1778655982028, - "lastReferencedAt": 1778655982028, - "referenceCount": 0 + "lastReferencedAt": 1779106389633, + "referenceCount": 2 }, { "id": "2b5867b3-6842-4bd5-ab71-79e54d94beb8", @@ -240,7 +240,197 @@ "createdAt": 1778655982068, "lastReferencedAt": 1778655982068, "referenceCount": 0 + }, + { + "id": "ec70d45f-665c-43e6-8e04-72afa35c468a", + "category": "rule", + "content": "항상 이거예요. 네 항상 이거", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072790, + "lastReferencedAt": 1778840072790, + "referenceCount": 0 + }, + { + "id": "da7281ea-67d0-4d11-a22e-de8fe2530bbe", + "category": "rule", + "content": "무조건 정가 기준 그러니까 할인가는 매 구매 페이지에 반영 뭐 이렇게 헷갈리지 않게 뭘 써줘야 될 것 같아요.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072791, + "lastReferencedAt": 1779074803033, + "referenceCount": 1 + }, + { + "id": "a85600e4-0991-4803-83d4-e414ec5f2eef", + "category": "rule", + "content": "무조건 한 섹터에 21개가 맥스야 이거를 딱 이렇게 각인시키고 싶은 것도 있어요.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072791, + "lastReferencedAt": 1779106389633, + "referenceCount": 2 + }, + { + "id": "da138a29-ae01-468a-a2dd-b1e349d3af9e", + "category": "rule", + "content": "항상 거기에 맞춰서 너희들이 내리고 올렸다고 막 하면 몇 개만 더 넣어줘요.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072792, + "lastReferencedAt": 1778840072792, + "referenceCount": 0 + }, + { + "id": "fe879dd3-ebf2-4aa6-8667-24a03baa7ca8", + "category": "rule", + "content": "항상\n\n참석자 4 1:06:26", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072798, + "lastReferencedAt": 1778840072798, + "referenceCount": 0 + }, + { + "id": "81e1c769-3dd0-4708-ba62-434d01541a3e", + "category": "rule", + "content": "앞으로 선택을 할 때도요.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072805, + "lastReferencedAt": 1778840072805, + "referenceCount": 0 + }, + { + "id": "6a31f93a-ae13-47a9-a0eb-f0f990d47a17", + "category": "rule", + "content": "앞으로 동일한 어떤 뭔가가 온다 그러면 좀 더 빠를 수는 있잖아요.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072810, + "lastReferencedAt": 1778840072810, + "referenceCount": 0 + }, + { + "id": "64dca6a5-0ec1-4015-bc8f-148701c08a1e", + "category": "rule", + "content": "앞으로 원칙으로 하시자고 하니까 바깥에 안 들어가니까 홀 마시로 돌려 이 중요하지 않다고 하니까", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072815, + "lastReferencedAt": 1778840072815, + "referenceCount": 0 + }, + { + "id": "b45e0a4b-6f25-46d5-a3a6-9d80b8565c8e", + "category": "rule", + "content": "다음부터는 돈 받을 거예요.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072820, + "lastReferencedAt": 1778840072820, + "referenceCount": 0 + }, + { + "id": "32067848-bc29-4046-995c-a1930c930a61", + "category": "preference", + "content": "저는 좋아요. 저는 좋아", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072824, + "lastReferencedAt": 1778840072824, + "referenceCount": 0 + }, + { + "id": "451d2a29-2420-4f13-ad17-62d4bcc2a4bf", + "category": "goal", + "content": "Goal: 원하는 목표", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072829, + "lastReferencedAt": 1778840072829, + "referenceCount": 0 + }, + { + "id": "18604089-47fb-4b98-879b-8e8595d73cfe", + "category": "goal", + "content": "Goal\n사용자가 얻고 싶은 목표", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072834, + "lastReferencedAt": 1778840072834, + "referenceCount": 0 + }, + { + "id": "51d6ae78-4c61-4830-8ad4-c550f8fc3931", + "category": "goal", + "content": "Goal: 논문의 outline을 더 명확하게 만들고 싶다.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072838, + "lastReferencedAt": 1779074612073, + "referenceCount": 1 + }, + { + "id": "0a257ba3-b320-48e4-bec0-e0bef68b6069", + "category": "decision", + "content": "결론\n\nAI 답변의 실패는 단순한 모델 성능 문제가 아니라, 사용자의 불완전한 의도 전달에서도 발생한다.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072838, + "lastReferencedAt": 1778840072838, + "referenceCount": 0 + }, + { + "id": "947dd1e0-a369-4023-8829-381d72a6fefd", + "category": "decision", + "content": "Conclusion 구조로 정리해줘.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072839, + "lastReferencedAt": 1779074730275, + "referenceCount": 3 + }, + { + "id": "e0cdc235-8907-4934-b9f8-24c9f36f8e0d", + "category": "decision", + "content": "결론\n\nC-G-C-F-Q 모델은 사용자가 모든 정보를 길게 설명하도록 강요하지 않으면서도, AI가 답변에 필요한 최소 맥락을 확보하도록 돕는다.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072845, + "lastReferencedAt": 1779106389633, + "referenceCount": 1 + }, + { + "id": "d4804a31-585e-49bc-b6a3-4c1751dcf312", + "category": "decision", + "content": "결론\n\n좋은 AI 상호작용은 한 번에 완벽한 질문을 요구하는 것이 아니라, 사용자와 AI가 함께 의도를 정교화하는 대화 절차를 필요로 한다.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072850, + "lastReferencedAt": 1779074730275, + "referenceCount": 3 + }, + { + "id": "19d285cc-70c5-49e5-8abf-6f25a8f2b924", + "category": "decision", + "content": "Conclusion\nSummary", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072855, + "lastReferencedAt": 1779074730275, + "referenceCount": 3 + }, + { + "id": "e7056c41-7a01-4e1c-b3c8-64480cd95077", + "category": "rule", + "content": "반드시 해결 가능한 방식으로 생성한다.", + "source": "session:task_1778819919539", + "confidence": 0.7, + "createdAt": 1778840072860, + "lastReferencedAt": 1778840072860, + "referenceCount": 0 } ], - "lastUpdated": 1778655982068 + "lastUpdated": 1779108916044 } \ No newline at end of file