Luisacaotica/ComfyUI-MiniMaxH3Mod

ComfyUI‑MiniMaxH3Mod – ComfyUI에서 MiniMax H3용 참조 모드 지원

이것이 무엇인가

• 비주얼 프로그래밍 UI ComfyUI용 사용자 정의 노드 팩으로, "RefMod" 생성, 로드, 검사 및 적용을 위한 노드 세트를 추가합니다. 이는 MiniMax H3 모델(이미지, 비디오 및 오디오 참조)용 재사용 가능한 참조 번들입니다.
• 이 노드는 MiniMax H3를 학습시키거나 확산 코어를 대체하지 않습니다. 모델의 VAE로 시각/오디오 데이터를 인코딩하고, 잠재 텐서를 .safetensors 파일에 저장하고, 생성 중에 해당 잠재 변수를 모델에 다시 공급할 뿐입니다.

주요 개념

개념	의미
RefMod	시각, 비디오 또는 오디오 잠재 변수와 메타데이터(토큰 수, 모양 등)를 포함하는 .safetensors 파일.
H3 RefMod 생성	단일 이미지/비디오/오디오를 RefMod로 인코딩합니다.
H3 RefMod Master 생성	시각 및 오디오를 함께 인코딩하여 단일 번들 파일(또는 두 개의 별도 파일)을 생성합니다.
H3 RefMod 적용	하나 이상의 로드된 RefMod를 생성 프롬프트와 결합하여 저장된 잠재 변수를 조건으로 제공합니다.
H3 RefMods 로드 / H3 RefMod Axis 로드	등록된 refmods 폴더를 탐색하고 선택한 번들을 출력하는 UI 위젯.
번들	버전 5 형식으로 여러 양식(시각 + 오디오)을 보유하는 단일 .safetensors 파일.

주요 기능(v0.2.6 기준)

• 독립 실행형 생성기 – H3 RefMod 생성 및 H3 RefMod Master 생성은 다운스트림 노드 없이 실행할 수 있습니다. details 문자열을 반환하고 선택적으로 파일을 씁니다.
• 마스크 목록 처리 – H3 RefMod 마스크 수집을 사용하면 각 마스크를 원래 해상도로 유지한 마스크 목록을 생성 노드에 공급할 수 있습니다.
• 전체 참조 비디오 샘플링 – 샘플링 전에 인과 프레임 수를 지정하여 이전의 16프레임 하드 제한을 피할 수 있습니다.
• 컴팩트한 추가형 로더 – 로더 노드는 하나의 보이는 슬롯으로 시작합니다. + RefMod 추가를 클릭하면 최대 8개의 슬롯이 표시되며, 각 슬롯에는 자체 모두 / 시각 / 오디오 선택기와 강도 컨트롤이 있습니다.
• 단일 파일 시각 + 오디오 번들 – save_layout=bundle을 사용하면 Master 노드가 시각 및 오디오 참조를 모두 포함하는 하나의 .safetensors 파일을 씁니다.
• 라이브러리 및 검사기 UI – 저장된 RefMod를 검색/필터링하고, 첫 프레임 또는 전체 비디오를 미리 보고, 짧은 오디오 미리듣기를 듣고, 토큰 예산 정보를 볼 수 있습니다.
• 예산 정책 – truncate(기본값)는 초과 토큰을 자동으로 줄입니다. error는 토큰 예산을 초과하면 중단합니다. 시각용 max_tokens, 오디오용 audio_max_tokens, 전체 max_total_tokens 제한이 별도로 있습니다.
• RefMod 새로 고침 – 전체 ComfyUI 모델 목록을 재설정하지 않고 파일 시스템에서 드롭다운 목록을 업데이트합니다.
• 크로스 플랫폼 지원 – Windows 및 Apple Silicon(M5 Ultra, macOS 27, PyTorch 2.14)에서 테스트됨. 선택적 비디오 백엔드(opencv-python, imageio).

설치

# 1️⃣ ComfyUI의 custom_nodes 폴더에 클론합니다
 git clone https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod \
    custom_nodes/ComfyUI-MiniMaxH3Mod
# 2️⃣ ComfyUI를 다시 시작합니다(또는 사용자 정의 노드 다시 로드)
# 3️⃣ 종속성은 ComfyUI‑Manager가 자동으로 설치하거나 다음을 실행합니다:
pip install -r custom_nodes/ComfyUI-MiniMaxH3Mod/requirements.txt

이 팩에는 MiniMax H3를 이미 지원하는 작동하는 ComfyUI 설치(즉, 기본 H3 VAE 및 조건 노드)가 필요합니다. 추가 MiniMax‑H3 코드는 번들로 제공되지 않습니다. 이 모드는 기존 VAE와만 통신합니다.

일반적인 워크플로우

1. 참조 생성 – 이미지, 짧은 비디오 또는 오디오 클립을 H3 RefMod 생성(또는 Master) 노드에 놓습니다. max_tokens, budget_policy, mask/mask_list 등을 조정합니다. 실행을 누르면 등록된 refmods 폴더에 .safetensors 파일이 나타납니다.
2. 참조 로드 – H3 RefMods 로드(또는 Axis 변형)를 사용하여 저장된 파일을 선택합니다. 여러 슬롯을 한 번에 로드하고 슬롯별 강도를 설정할 수 있습니다.
3. 생성 중 적용 – 로더 출력을 H3 RefMod 적용에 연결한 다음 결과 조건을 일반 MiniMax H3 생성 파이프라인(예: 샘플러 노드)에 공급합니다. 모델은 텍스트 프롬프트와 함께 저장된 잠재 변수에 주의를 기울입니다.
4. 검사 / 조정 – H3 RefMod 검사를 열어 토큰 수를 확인하고, 저장된 시각/오디오를 미리 보고, 다시 실행하기 전에 강도를 조정합니다.

제한 사항 및 알려진 문제

• 음성 복제는 작동하지 않습니다 – 오디오 추출은 작동하지만 현재 구현은 화자의 정체성을 안정적으로 전송할 수 없습니다.
• 학습 없음 – "학습" 시각 모드(training / Compressed Reference)는 잠재 풀링 + 선택적 정제 단계일 뿐입니다. LoRA나 다른 모델을 학습하지 않습니다.
• 토큰 예산은 엄격합니다 – max_tokens(시각) 또는 audio_max_tokens를 초과하면 truncate를 선택하지 않는 한 중단됩니다. 예산은 품질을 보장하지 않습니다. 주의 비용만 제한합니다.
• 오디오-비주얼 동기화 보장되지 않음 – 번들은 시각 및 오디오 잠재 변수를 별도로 저장합니다. 소스 파일이 제공하는 것 이상으로 시간적으로 정렬되지 않습니다.
• 파일 시스템 전용 영속성 – RefMod는 디스크에 .safetensors로 저장됩니다. 노드 팩에 의해 버전 관리되지 않습니다.
• 플랫폼 특이점 – 주로 Windows에서 테스트됨. Apple Silicon 지원은 존재하지만 모든 워크플로우를 다루지 않을 수 있습니다.

시작 위치

• 저장소에는 데모 번들이 포함되어 있습니다: mods/vanellope_example.safetensors. 설치 후 로더 드롭다운에 vanellope_example로 나타납니다. 강도 1.0으로 H3 RefMod 적용에 연결하고 *"a candy racer in a karting scene"*과 같은 프롬프트를 시도하세요.

추가 자료

• 전체 변경 로그: CHANGELOG.md
• 검증 및 알려진 제한 사항: REVIEW_FOLLOWUP.md
• 번들 파일 형식 세부 정보: BUNDLE_FORMAT.md

---

ComfyUI‑MiniMaxH3Mod는 MiniMax H3용 저장 및 조건 중심 확장입니다. 아티스트가 시각/오디오 참조를 한 번 캡처하고 모델을 재학습하지 않고도 이후 생성에서 효율적으로 재사용할 수 있게 합니다.