그림 한 장에 담기는 것, 담기지 않는 것
ComfyUI 공식 문서는 이 기능을 «생성한 그림을 그 레시피와 함께 저장하는 것»에 빗댄다. 그림은 결과이고, 파일 안에 함께 적힌 워크플로는 그 결과를 만든 단계를 설명한다는 것이다. README도 생성한 PNG를 웹 화면에 끌어다 놓거나 불러오면 시드를 포함한 전체 워크플로를 얻는다고 적었다. ComfyUI 예제 페이지의 그림들이 모두 이 방식으로 배포되는 것도 같은 이유다. 예제 페이지는 저장소의 모든 그림에 메타데이터가 들어 있어 Load 버튼이나 끌어다 놓기로 전체 워크플로를 얻을 수 있다고 안내한다.
반대로 담기지 않는 것도 공식 문서에 분명히 적혀 있다. 워크플로에는 그것이 기대는 모델 파일, 입력 재료, 커스텀 노드 꾸러미가 들어 있지 않다. 소스 코드를 보면 이유가 보인다. 예를 들어 Load Image 노드의 입력은 input 폴더에 있는 파일 이름을 고르는 칸이다. 워크플로에 남는 것도 그 파일 이름이지 그림 자체가 아니다. 체크포인트와 LoRA도 마찬가지로 파일 이름만 남는다. 정리하면 이렇다.
| 되살아나는 것 | 되살아나지 않는 것 |
|---|---|
| 노드 종류와 연결선 | 체크포인트 · LoRA 같은 모델 파일 |
| 노드 칸의 값(프롬프트 글, 시드, steps 등) | Load Image에 넣었던 입력 그림 |
| 노드 위치 · 크기 · 그룹(workflow 항목이 있을 때) | 커스텀 노드 꾸러미와 그 의존성 |
그래서 그림 한 장으로 받은 워크플로는 «재료 목록이 적힌 레시피»에 가깝다. 재료가 내 컴퓨터에 없으면 레시피는 열려도 요리는 되지 않는다. 이 부분은 뒤의 «되살아나도 바로 돌지 않는 이유» 절에서 다시 다룬다.
저장하는 순간 — Save Image가 적는 두 줄
워크플로가 그림 안으로 들어가는 길은 세 단계다. 화면(프런트엔드)이 실행 요청을 보내고, 서버가 그 값을 저장 노드에 넘기고, 저장 노드가 PNG에 적는다.
첫째, 실행 버튼을 누르면 프런트엔드는 서버로 보내는 요청에 두 가지를 싣는다. 하나는 prompt라는 이름의 실행용 그래프이고, 다른 하나는 extra_data 안의 extra_pnginfo에 담긴 workflow, 곧 화면에 보이는 그래프 전체다.
둘째, 서버 쪽 execution.py는 노드가 숨은 입력으로 PROMPT를 달라고 하면 원래 받은 prompt를, EXTRA_PNGINFO를 달라고 하면 요청의 extra_pnginfo 값을 채워 넘긴다. 공식 문서도 PROMPT를 «클라이언트가 서버로 보낸 전체 프롬프트», EXTRA_PNGINFO를 «저장되는 모든 PNG 파일의 메타데이터로 복사될 사전»이라고 정의한다.
셋째, nodes.py의 SaveImage 클래스는 바로 이 두 숨은 입력을 받는다. 저장할 때 메타데이터 끄기 옵션이 꺼져 있으면 Pillow의 PngInfo를 만들고, prompt를 json.dumps로 글자로 바꿔 «prompt»라는 이름으로 적은 뒤, extra_pnginfo 안의 항목마다 같은 방식으로 이름과 값을 적는다. 프런트엔드가 보낸 extra_pnginfo에는 workflow가 들어 있으므로, 결과적으로 PNG에는 «prompt»와 «workflow» 두 글 항목이 생긴다. 공식 문서도 PNG 출력의 표준 필드 이름이 prompt와 workflow라고 적었다. 저장 쪽 nodes.py와 읽는 쪽 app.ts를 직접 열어 대조하면, 적는 이름과 불러올 때 찾는 이름이 그대로 맞물린다.
같은 코드에서 몇 가지가 더 확인된다. Save Image는 PNG를 압축 수준 4로 쓴다. Preview Image 노드는 Save Image를 그대로 물려받아 같은 저장 함수를 쓰되, output 폴더가 아니라 temp 폴더에 압축 수준 1로 쓴다. 미리보기 그림에도 같은 메타데이터가 들어가는 구조이지만, 보관할 그림이라면 output 폴더에 남는 Save Image 쪽을 쓰는 것이 맞다.
PNG 안을 들여다보면 — tEXt 청크와 한글 프롬프트
PNG 파일은 맨 앞의 서명 뒤로 «청크»라는 토막이 줄지어 있는 구조다. ComfyUI 프런트엔드의 PNG 읽기 코드는 이 구조를 그대로 따라간다. 먼저 파일 앞부분이 PNG 서명인지 확인하고, 서명 8바이트 뒤부터 청크마다 길이(4바이트)와 이름(4바이트)을 읽은 뒤, 길이에 머리와 꼬리 12바이트를 더한 만큼 건너뛰며 다음 청크로 간다. 그러다 이름이 tEXt나 iTXt인 청크를 만나면, 첫 번째 0 바이트 앞까지를 항목 이름으로, 그 뒤를 내용으로 읽어 모아 둔다.
글 청크가 어디에 놓이는지는 PNG를 쓰는 쪽 코드에서 보인다. Pillow는 PngInfo로 넘겨받은 tEXt · iTXt 청크를 그림 데이터인 IDAT보다 먼저 쓴다. 공식 문서 표현대로 메타데이터는 파일 형식 안에 들어갈 뿐 보이는 그림이나 영상 내용을 바꾸지 않는다.
한글 프롬프트는 왜 깨지지 않나
PNG의 tEXt 청크는 latin-1 글자만 담는 칸이다. Pillow의 add_text도 값을 latin-1로 바꿔 보고, 안 되면 유니코드를 담는 iTXt 청크로 돌려 적는다. 그렇다면 한글 프롬프트가 든 워크플로는 iTXt로 갈까. 소스를 따라가면 그렇지 않다. ComfyUI는 값을 적기 전에 json.dumps로 바꾸는데, Python 공식 문서에 따르면 ensure_ascii가 참(기본값)이면 ASCII 밖의 글자를 모두 이스케이프한다. SaveImage는 이 옵션을 따로 바꾸지 않으므로, 한글은 \uXXXX 꼴의 영문 글자로 바뀌어 적히고 글 항목 전체가 tEXt 청크에 들어간다. 불러올 때는 JSON을 다시 풀면서 원래 한글로 돌아온다.
이 사실은 PNG를 메모장 같은 편집기로 열어 볼 때 쓸모가 있다. 파일 앞쪽에서 prompt와 workflow라는 글자 뒤로 JSON이 이어지는 것을 볼 수 있지만, 한글 프롬프트는 알아보기 어려운 이스케이프 글자로 보인다. 깨진 것이 아니라 원래 그렇게 적힌 것이다.
workflow와 prompt — 같은 그래프의 두 모양
PNG 안의 두 항목은 같은 그래프를 서로 다른 목적으로 적은 것이다. 공식 문서는 workflow를 «노드 · 연결 · 배치 정보를 포함한 전체 워크플로 그래프», prompt를 «워크플로를 실행하는 데 쓰인 API 프롬프트»로 구분하고, 앞의 것은 프런트엔드에서 워크플로를 되살리는 용도, 뒤의 것은 서버에 제출하는 실행용 표현이라고 설명한다. 이름이 prompt라서 프롬프트 글만 들어 있을 것 같지만, 실제로는 실행에 필요한 노드와 입력값 전체다.
| workflow 항목 | prompt 항목 | |
|---|---|---|
| 담는 것 | 노드 · 연결선 · 위치 · 크기 · 그룹 | 노드 번호별 종류(class_type)와 입력값 |
| 쓰는 곳 | 캔버스를 원래 모습으로 되살리기 | 서버에 실행 요청 보내기 |
| 같은 모양의 JSON 파일 | 저장 형식(Save) | API 형식(Export Workflow (API)) |
이 구분은 JSON 파일에도 그대로 이어진다. 공식 API 형식 문서는 프런트엔드가 워크플로를 두 형식으로 저장할 수 있다고 적었다. 저장 형식은 위치 · 크기 같은 배치 정보와 색 · 그룹을 담아 화면에서 다시 열기 위한 것이고, API 형식은 노드 번호를 키로 쓰고 배치 정보와 색 · 그룹을 뺀 프로그램 제출용이다. API 형식 파일도 화면에서 열 수는 있지만 배치 정보 없이 열린다고 문서는 표에 적었다. 저장 형식 파일을 API 형식으로 바꾸려면 화면에서 연 뒤 Export Workflow (API)로 다시 내보내면 된다.
끌어다 놓는 순간 — ComfyUI가 확인하는 순서
파일을 캔버스에 놓으면 프런트엔드는 먼저 파일 종류에 맞는 읽기 함수를 고른다. PNG는 앞에서 본 청크 읽기, WebP는 EXIF, FLAC · MP3 · Ogg 같은 소리 파일과 WebM · MP4 같은 영상 파일은 각자의 방식으로 읽고, 확장자가 json이면 파일 내용을 그대로 읽는다. 공식 문서의 형식표도 PNG는 tEXt 청크, 움직이는 WebP는 EXIF 태그, MP4 · WebM은 컨테이너 메타데이터 태그, latent 파일은 safetensors 메타데이터에 적힌다고 정리한다.
읽어 낸 값을 어떻게 쓸지는 app.ts의 handleFile이 정한다. 순서는 다음과 같다.
- workflow 항목이 있으면 먼저 쓴다. 노드 · 선 · 값 · 배치를 그대로 되살린다. 코드는 workflow부터 확인하고, 읽기에 성공하면 거기서 끝낸다.
- 없으면 prompt 항목을 본다. 모든 항목에 class_type 글자와 inputs 묶음이 있어야 API 형식으로 인정하고, 노드와 값을 되살린다. 배치 정보는 없다.
- 그것도 없으면 parameters 글을 본다. AUTOMATIC1111 계열 도구가 PNG에 남기는 생성 설정 글을 풀어 기본 노드로 그래프를 짜 보는 마지막 수단이다.
- 셋 다 없으면 그림 · 소리 · 영상 파일은 입력 재료로 취급한다. 그림이라면 Load Image 노드가 하나 생기고 그 그림이 들어간다. 이도 저도 아니면 오류 알림을 띄운다.
공식 문서의 설명도 같다. 파일에 workflow와 prompt가 모두 있으면 workflow로 캔버스를 다시 짓고, 워크플로가 없으면 지원하는 미디어 파일을 보통의 입력 재료로 다룬다. 끌어다 놓기 말고 메뉴로 열어도 된다. 다만 메뉴 이름은 문서마다 File → Open, Workflows → Open으로 다르게 적혀 있으니, 쓰는 판의 화면에서 «열기»에 해당하는 항목을 찾는다. README의 단축키 표에는 Ctrl + O가 워크플로 불러오기로 적혀 있다.
그림 · 소리 · 영상 파일을 두 개 이상 한꺼번에 놓으면 위 순서를 타지 않는다. 그림은 각각 Load Image 노드로 들어가고, 여러 장이면 묶음 노드에 이어진다. 워크플로를 되살리려면 그림을 한 장씩 놓는다.
되살아나도 바로 돌지 않는 이유
워크플로가 열렸다고 곧바로 실행되지는 않는다. 앞에서 본 대로 파일에는 레시피만 있고 재료는 없기 때문이다. 공식 문서도 모델 · 입력 재료 · 커스텀 노드를 옮기거나 이름을 바꾸면 되살린 워크플로가 실행되지 않을 수 있다고 적었다. 막히는 자리는 대개 셋이다.
- 모델이 없다 — 공식 첫 생성 안내에 따르면 대부분의 설치본에는 기본 모델이 없어서, 워크플로를 불러오면 빠진 모델 경고가 뜨고, 경고를 누르면 빠진 모델 이름과 받는 링크가 보인다. 데스크톱 · 포터블에서 모델 폴더가 어디인지는 설치 방식과 모델 폴더 정리에 있다.
- 노드가 빨갛게 뜬다 — 공식 문서는 노드가 없거나 오류가 있으면 워크플로를 끝낼 수 없고, 그 노드가 표시된다고 설명한다. 남이 만든 워크플로라면 대개 내 컴퓨터에 없는 커스텀 노드다. Manager로 빠진 노드를 찾는 순서는 입문 가이드의 빨간 노드 절에 정리했다.
- 입력 그림이 없다 — Load Image에는 파일 이름만 남으므로, 원작자의 input 폴더에 있던 그림은 따라오지 않는다. 내 그림을 다시 넣어 준다.
커스텀 노드 설치는 코드를 내려받아 custom_nodes 폴더에 넣고 그 의존성까지 설치하는 일이다. 공식 문서도 파일 안의 메타데이터를 «없을 수도 있고 믿을 수 없는 입력»으로 다루라고 하고, 워크플로가 실행에 필요한 모든 모델과 커스텀 노드를 담고 있다고 가정하지 말라고 적었다. 출처를 모르는 그림이 요구하는 노드 꾸러미라면 설치 전에 그 저장소가 어떤 곳인지 먼저 확인한다.
메타데이터가 사라지는 경우
같은 ComfyUI 그림인데 놓아도 노드가 안 나오고 Load Image 노드만 생긴다면, 파일에서 메타데이터가 빠진 것이다. 공식 문서가 꼽는 원인은 세 가지다.
- 메타데이터 저장을 끄고 만든 파일 — 실행 옵션
--disable-metadata를 붙여 띄우면 저장하지 않는다. 소스 코드의 옵션 설명도 «파일에 프롬프트 메타데이터 저장을 끈다»이다. 데스크톱 판은 Settings → Server-Config의 «Disable saving prompt metadata in files» 항목이 같은 일을 한다. - 저장 노드가 워크플로 정보를 받지 못한 파일 — 화면을 거치지 않고 API로 prompt만 보내 실행하면 extra_pnginfo가 비어 있을 수 있다. 이 경우 PNG에는 prompt만 남고, 불러오면 위 순서의 2번으로 노드와 값만 되살아난다.
- 다른 프로그램이 다시 인코딩한 파일 — 그림 · 영상 편집기는 파일을 다시 인코딩하면서 메타데이터를 지울 수 있다. 화면을 캡처한 그림은 애초에 새로 만든 그림이라 글 청크가 없다. 그림을 올릴 때 다시 압축하는 서비스를 거친 파일도 같은 경우가 될 수 있다.
반대로 파일을 그대로 복사하면 워크플로도 함께 복사된다. 공식 문서는 메타데이터가 따로 떨어진 파일이 아니라 저장할 때 출력 파일 안에 쓰이므로, 복사하면 함께 가고 파일을 다시 쓰는 작업은 그것을 지우거나 바꿀 수 있다고 정리한다.
JSON 파일로 저장하고 나누기
그림이 중간에 변환될 걱정이 있다면 워크플로를 JSON 파일로 따로 저장해 나누는 편이 확실하다. 공식 문서는 워크플로를 JSON 파일로 저장해 생성 결과와 별개로 나눌 수 있다고 안내하고, README 단축키 표에는 Ctrl + S가 워크플로 저장으로 적혀 있다. 프로그램에서 실행할 용도라면 Export Workflow (API)로 API 형식 파일을 따로 내보낸다.
JSON 파일을 캔버스에 놓을 때도 프런트엔드가 형식을 가려 읽는다. json.ts는 파일에 templates 항목이 있으면 템플릿 묶음으로, 모든 값에 class_type이 있으면 API 형식(prompt)으로, 둘 다 아니면 저장 형식(workflow)으로 본다. 그 뒤는 그림과 똑같이 앞의 순서를 탄다. 프런트엔드 저장소의 기본 워크플로 예제 파일을 열어 보면 맨 위에 nodes · links · groups 같은 항목이 있고, 노드마다 pos(위치)와 size(크기)가 들어 있다. 저장 형식이 배치 정보를 담는다는 문서 설명과 맞는다.
자주 묻는 것
그림을 끌어다 놓았는데 노드 대신 Load Image 노드만 생겨요.
그 파일에 워크플로 메타데이터가 없다는 뜻입니다. ComfyUI는 workflow · prompt · parameters 가운데 아무것도 찾지 못하면 그림을 입력 재료로 보고 Load Image 노드에 넣습니다. 메타데이터를 끄고 저장했거나, 편집기 · 캡처 · 다시 압축하는 과정을 거치면서 빠진 경우가 대표적입니다.
PNG 안의 prompt 항목에는 프롬프트 글만 들어 있나요?
아닙니다. 이름은 prompt지만 실행에 필요한 노드 번호, 노드 종류, 입력값 전체가 담긴 API 형식 그래프입니다. 화면 배치까지 담긴 것은 workflow 항목이고, 둘 다 있으면 ComfyUI는 workflow를 먼저 써서 캔버스를 되살립니다.
JSON으로 저장하는 것과 그림 한 장으로 나누는 것은 무엇이 다른가요?
담기는 그래프는 같지만, 그림은 다른 프로그램이 다시 인코딩하면 메타데이터가 빠질 수 있습니다. JSON 파일은 그런 걱정이 없고 그림과 따로 나눌 수 있습니다. 프로그램에서 돌릴 용도라면 Export Workflow (API)로 API 형식 JSON을 따로 내보냅니다.
워크플로는 열렸는데 실행하면 오류가 나요.
파일에는 모델 · 입력 그림 · 커스텀 노드가 들어 있지 않습니다. 빠진 모델 경고가 뜨면 안내된 링크로 모델을 받아 모델 폴더에 넣고, 빨간 노드는 Manager로 빠진 커스텀 노드를 찾아 설치합니다. Load Image에는 파일 이름만 남으므로 입력 그림도 다시 넣어 줍니다.
내 그림에 프롬프트가 남지 않게 하려면 어떻게 하나요?
ComfyUI를 --disable-metadata 옵션으로 띄우거나, 데스크톱 판 Settings → Server-Config에서 «Disable saving prompt metadata in files»를 켭니다. 이렇게 만든 파일로는 나중에 워크플로를 되살릴 수 없으니, 보관용 그림은 따로 남겨 둡니다.
참고 자료
- ComfyUI 공식 문서. Workflow Metadata — workflow · prompt 두 필드의 뜻, 형식별 저장 위치(PNG tEXt · WebP EXIF · MP4/WebM 컨테이너 태그 · latent), 끄는 옵션, 읽는 방법, 한계 목록. docs.comfy.org
- ComfyUI 공식 문서. Workflow API Format — 저장 형식과 API 형식 비교표, Export Workflow (API) 메뉴, 형식 바꾸는 법, API 형식 예시. docs.comfy.org
- ComfyUI 공식 문서. Workflows — 워크플로를 JSON으로 저장해 나누는 법, 출력 파일에 워크플로가 들어간다는 설명, 빠진 노드 표시. docs.comfy.org
- ComfyUI 공식 문서. Getting Started with AI Image Generation — 그림 · JSON으로 워크플로 불러오는 메뉴, 빠진 모델 경고와 받는 링크. docs.comfy.org
- ComfyUI 소스 코드 nodes.py — SaveImage의 숨은 입력, PngInfo.add_text로 prompt와 extra_pnginfo 항목을 적는 줄, 압축 수준, PreviewImage의 temp 폴더, LoadImage의 파일 이름 입력. github.com
- ComfyUI 소스 코드 execution.py — PROMPT · EXTRA_PNGINFO 숨은 입력을 실행 요청의 값으로 채우는 부분. github.com
- ComfyUI 소스 코드 comfy/cli_args.py — --disable-metadata 옵션과 설명 문구. github.com
- ComfyUI README — 생성한 PNG를 끌어다 놓으면 시드까지 포함한 워크플로를 얻는다는 설명, Ctrl+S · Ctrl+O 단축키. github.com
- ComfyUI 프런트엔드 소스 코드 src/scripts/api.ts — 실행 요청에 prompt와 extra_data.extra_pnginfo.workflow를 함께 싣는 부분. github.com
- ComfyUI 프런트엔드 소스 코드 src/scripts/metadata/png.ts — PNG 서명 확인, 청크를 하나씩 건너뛰며 tEXt · iTXt 글을 읽는 반복문. github.com
- ComfyUI 프런트엔드 소스 코드 src/scripts/metadata/parser.ts — 파일 종류별로 메타데이터 읽는 함수를 고르는 분기. github.com
- ComfyUI 프런트엔드 소스 코드 src/scripts/app.ts — handleFile의 workflow → prompt → parameters 순서, 메타데이터 없는 그림을 Load Image 노드로 넣는 부분, 여러 파일을 놓았을 때의 분기. github.com
- ComfyUI 프런트엔드 소스 코드 src/scripts/metadata/json.ts — JSON 파일을 templates · API 형식 · 저장 형식으로 가르는 기준. github.com
- Pillow 소스 코드 PngImagePlugin.py — add_text가 latin-1로 적히면 tEXt, 아니면 iTXt로 적는 분기, 글 청크를 IDAT 앞에 쓰는 순서. github.com
- Python 공식 문서. json 모듈 — ensure_ascii 기본값이 참이면 ASCII 밖 글자를 이스케이프한다는 설명. docs.python.org
- ComfyUI Examples — 예제 그림마다 메타데이터가 있어 Load 버튼이나 끌어다 놓기로 전체 워크플로를 얻는다는 설명. comfyanonymous.github.io
- ComfyUI 공식 문서. Custom Nodes — 커스텀 노드 설치(코드 받기 · 의존성 설치), Manager로 빠진 노드 찾기. docs.comfy.org
- ComfyUI 공식 문서. Hidden and Flexible inputs — PROMPT는 클라이언트가 보낸 전체 프롬프트, EXTRA_PNGINFO는 저장되는 PNG 메타데이터로 복사되는 사전이라는 정의. docs.comfy.org
