Files

T

2026-05-19 18:08:09 +09:00

8.9 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

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)

상위/유사 개념

[아키텍처 및 데이터 표준]

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]

8.9 KiB Raw Blame History