custom_nodes/dolphin_nodes/dataset_builder/README.md

Wan 2.2 LoRA Dataset Builder

임의의 이미지/영상 폴더를 넣으면 피사체 중심으로 크롭하고 로컬 VLM으로 캡션을 달아, LoRA 학습 스크립트(musubi-tuner 등)에 바로 넣을 수 있는 images/, videos/, .txt 캡션, dataset.toml 초안을 생성하는 독립 CLI 도구.

ComfyUI 노드가 아님 — __init__.py에서 import하지 않으므로 ComfyUI 노드 로딩에 관여하지 않고, python_embeded\python.exe로 직접 실행한다.

사용 전제: 학습 대상 인물/캐릭터가 명백히 성인이어야 함. 나이가 불명확하거나 앳돼 보이는 인물의 성적 콘텐츠 데이터셋 구축에는 이 도구를 쓰지 말 것.

사용법

D:\SD\ComfyUI_windows_portable\python_embeded\python.exe ^
  dataset_builder\build.py ^
  --input "D:\raw_media" ^
  --output "D:\wan_lora_dataset" ^
  --trigger "ohwx man" ^
  --captioner joycaption

--input 폴더를 재귀적으로 스캔해 이미지(jpg/png/webp/bmp)와 영상(mp4/mov/mkv/avi/webm)을 자동 분류하여 처리한다.

파이프라인

1. 피사체 감지: mediapipe 얼굴 검출 → (실패 시) OpenCV Haar cascade 얼굴 검출 → (그래도 실패 시) ultralytics YOLOv8n 사람 검출 → (그래도 없으면) 전체 프레임 그대로 사용. 사람이 아닌 사물/장면 LoRA는 자연스럽게 "전체 프레임" 경로로 빠진다.
2. 버킷 매칭 + 크롭: 감지된 bbox를 얼굴 2.2배 / 사람 1.3배로 패딩한 뒤, Wan 480p/720p/1080p × (가로/세로/정사각) 버킷 중 종횡비가 가장 가까운 것을 골라 그 해상도로 크롭+리사이즈(16 배수 정렬). 원본 해상도보다 커지는(업스케일) 버킷은 자동으로 건너뛴다 — --max-tier로 상한만 지정.
3. 영상 씬 분할: OpenCV 히스토그램 차분으로 컷 지점을 찾고, --clip-min-sec ~ --clip-max-sec 범위로 클립을 나눈다. 클립마다 대표 프레임 몇 장의 bbox 중앙값으로 크롭을 고정하고(프레임 흔들림 방지), --video-fps로 리샘플, 4n+1 프레임 수로 트리밍, optical flow 평균 크기로 "static/subtle/moderate/fast motion" 태그를 캡션에 덧붙인다.
4. 캡셔닝 (--captioner):
   • joycaption (기본) — fancyfeast/llama-joycaption-beta-one-hf-llava. 주의: HuggingFace 모델 카드에 "학습용 캡션" 전용 프롬프트 문자열이 공식 문서화되어 있지 않아, 여기 쓰인 지시문(caption.py의 DEFAULT_PROMPT)은 자체 작성한 기본값이다. 원하는 스타일이 있으면 --caption-prompt로 바꿔라.
   • florence2 — microsoft/Florence-2-large, 가볍고 빠름(~0.77B).
   • wd14 — SmilingWolf/wd-vit-tagger-v3 (onnx), booru 태그 스타일.
   • 공통: --trigger로 넘긴 트리거 워드를 캡션 맨 앞에 자동 삽입.

출력

output_dir/
  images/0001.jpg, 0001.txt, ...
  videos/0001.mp4, 0001.txt, ...
  dataset.toml   # musubi-tuner 스타일 초안 — 실제 트레이너 버전 문서와 대조 후 사용

모델 다운로드 / VRAM 참고

• 최초 실행 시 HuggingFace에서 캡셔너 가중치(JoyCaption 16GB, Florence-2-large ~1.5GB, WD14 ~수백MB)와 ultralytics yolov8n.pt(6MB)를 자동 다운로드한다. 네트워크/디스크 용량 확인 후 실행할 것.
• RTX 5090 32GB 기준, ComfyUI가 이미 VRAM을 점유 중이면 JoyCaption(8B, bf16 기준 ~16GB)이 부족할 수 있다. 이 경우 --load-in-4bit(bitsandbytes)로 줄이거나, ComfyUI 서버를 잠시 내려두고 실행할 것.

알려진 환경 특이사항

• 이 embedded Python 환경은 import torch만 해도 인터프리터 종료 시 비정상 종료 코드(예: -1073740791)를 낸다. dataset_builder와 무관한 기존 환경 이슈이며, 실제 작업(파일 저장)은 그 전에 이미 끝난 뒤 발생하는 종료 시점 크래시라 결과물에는 영향 없음. 배치 스크립트에서 종료 코드로 성공/실패를 판단하지 말고 콘솔 로그의 Done. 줄로 확인할 것.

검증된 것 / 안 된 것

• crop_resize.py(버킷 매칭 수학), detect.py(다단계 폴백), scene_split.py (씬 컷 + 클립 추출 + 4n+1 트리밍 + 모션 태그)는 실제 샘플 이미지/영상으로 스모크 테스트 완료.
• caption.py(JoyCaption/Florence-2/WD14 실제 추론 호출)는 모델 가중치 다운로드가 커서 이번 세션에서 end-to-end로 돌려보지 않았다. 클래스/전처리는 각 모델의 공식 문서(HF 모델 카드, wd-tagger Space 소스)를 대조해 작성했지만, 처음 실행할 때 캡셔너 쪽 에러가 나면 그 부분부터 확인할 것.