madebyollin/taehv

🥮 훈위안 동영상용 소형 오토인코더 (TAEHV)

무엇인가요 – TAEHV는 Hunyuan Video, MiniMax-H3, Wan-Video, CogVideoX, Open-Sora, LTX-2 등 여러 모델에 동봉된 원본 전체 크기 VAE보다 동영상 프레임을 잠재 표현으로 인코딩하고, 그 잠재 표현을 더 빠르고 훨씬 적은 GPU 메모리로 디코딩할 수 있는 컴팩트한 오토인코더입니다.

왜 중요한가요 – 전체 크기의 동영상 VAE는 일반적으로 짧은 클립(예: 512×320의 61프레임)을 디코딩할 때 6~9GB의 GPU 메모리와 수 초가 필요합니다. TAEHV는 NVIDIA GH200에서 이를 <0.5GB와 ≈0.5초로 줄여, 실시간 미리보기, 인터랙티브 생성, 라이브 스트리밍 처리를 가능하게 합니다.

지원되는 동영상 모델

모델	로드할 가중치 태그	예제 노트북
MiniMax H3	`taeh3`	–
Hunyuan Video 1.5	`taehv1_5` (더 높은 품질은 `taehv1_5_super`)	`TAEHV1.5_Encoding_Decoding_Demo.ipynb`
Wan 2.1	`taew2_1`	–
Wan 2.2 5B	`taew2_2` (또는 `taew2_2_super`)	`TAEW2.2_T2I_Demo.ipynb`
Wan 2.2 14B	`taew2_1` (Wan 2.1 VAE 사용)	–
Qwen Image	`taew2_1`	–
CogVideoX	`taecvx`	`TAECVX_T2I_Demo.ipynb`
Hunyuan Video 1	`taehv`	`TAEHV_T2I_Demo.ipynb`
Open-Sora 1.3	`taeos1_3`	–
LTX-2	`taeltx_2`	`TAELTX2_Encoding_Decoding_Demo.ipynb`
LTX-2.3 / 2.5	`taeltx2_3` (더 적은 흐림을 원하면 `taeltx2_3_wide`)	–
Mochi 1 & SVD	보조 리포지토리 TAEM1 및 TAESDV 참조

리포지토리 루트에 .pth 가중치 파일이 있으며, ./safetensors 폴더에는 동등한 .safetensors 파일이 있습니다. TAEHV는 체크포인트 이름에서 자동으로 올바른 아키텍처를 선택합니다. 파일 이름을 바꾸면 arch_name=를 수동으로 전달할 수 있습니다.

사용 방법

from taehv import TAEHV

# 체크포인트 로드 (예: Hunyuan-Video-1.5)
vae = TAEHV("taehv1_5.pth")

# 동영상 텐서 인코딩 (N, C, T, H, W) → 잠재 표현
latents = vae.encode_video(video_tensor)

# 잠재 표현을 동영상으로 디코딩
decoded = vae.decode_video(latents)

속도 트릭 – 업스케일링 비활성화:

vae = TAEHV(decoder_time_upscale=(False, False),
            decoder_space_upscale=(False, False, False))

병렬 디코딩 – decode_video에 parallel=True를 설정하면 모든 프레임을 한 번에 처리 (더 많은 메모리 필요).
스트리밍 – 라이브 또는 단계별 처리를 위해 StreamingTAEHV 래퍼를 사용하면 디코딩된 프레임을 즉시 생성합니다. 스트리밍 데모 노트북을 참조하세요.
Diffusers 통합 – 값 범위([0,1] 대 [-1,1])와 텐서 레이아웃(NTCHW 대 NCTHW)의 차이를 처리하는 작은 래퍼가 제공됩니다 (TAEW2.1_Diffusers_Encoding_and_Decoding_Demo.ipynb 참조).

위치

ComfyUI – 메인 브랜치(PR #10884)에서 내장 지원 및 커뮤니티 노드: ComfyUI-WanVideoWrapper, ComfyUI-VideoHelperSuite, ComfyUI-Bleh.
stable-diffusion.cpp – PR #937를 통해 추가됨.
SDNext – vladmandic에 의해 통합됨.
Wan-Video Self-Forcing 데모 – 공식 Wan 2.1 데모에서 사용됨.

다른 곳에 지원을 추가한 경우, 저자는 PR을 환영합니다.

제한 사항

품질 희생 – TAEHV는 빠르고 가볍지만 원본 VAE의 시각적 정밀도에 미치지 못합니다. 저자는 벤치마크(MoViRec)와 측면 비교 이미지를 제공합니다.
슈퍼 가중치 – 일부 모델에 대해 더 높은 품질 버전(*_super)이 있으며, 약간 더 많은 계산과 메모리 사용량이 필요합니다.

시작 자료

프로파일링 노트북 – examples/TAEHV_Profiling.ipynb (실행 시간 및 메모리 사용량).
데모 노트북 – 다양한 *_Demo.ipynb 파일로 텍스트-투-비디오, 인코딩/디코딩, 스트리밍, Diffusers 사용을 보여줍니다.
모델 가중치 – 리포지토리 루트 또는 safetensors/ 폴더에서 다운로드.
인용 – 학술용으로 바로 붙여넣기 가능한 BibTeX 항목 제공.

TL;DR

TAEHV는 중국 및 오픈소스 동영상 확산 모델의 증가하는 목록에 대해 즉시 사용 가능한 가벼운 VAE 대체품입니다. 디코딩 시간을 초 단위에서 밑초 단위로, 메모리 사용량을 약 8GB에서 <0.5GB로 줄여 실시간 미리보기와 인터랙티브 비디오 생성을 가능하게 하며, 약간의 품질 저하가 있지만 선택적 '슈퍼' 체크포인트로 완화할 수 있습니다.