HunyuanVideo 설치 및 사용 가이드 (Mac)

개요

이 가이드는 Apple Silicon(M1/M2/M3/M4) Mac에서 HunyuanVideo를 설치하고 텍스트-투-비디오(T2V) 생성을 실행하는 방법을 설명한다. HunyuanVideo 원본은 CUDA(NVIDIA GPU) 환경을 기본 대상으로 하지만, HunyuanVideo_MLX 커뮤니티 포트를 통해 Apple Silicon의 Metal 가속을 활용해 Mac에서도 실행할 수 있다.

주의: HunyuanVideo 13B 모델은 상당한 메모리를 요구한다. 원활한 실행을 위해 **32GB 이상의 통합 메모리(Unified Memory)**를 권장하며, 16GB 환경에서는 저해상도·단시간 영상으로만 제한적 사용이 가능하다.

사전 요구사항

필수 소프트웨어:

• Homebrew: macOS 패키지 관리자
• Miniconda 또는 Miniforge: conda 환경 관리 (Apple Silicon 네이티브 버전)
• HuggingFace 계정 및 액세스 토큰: 모델 가중치 다운로드 시 필요

설치 방법

1단계: Miniforge 설치 (Apple Silicon 네이티브 conda)

1brew install miniforge2conda init zsh   # zsh 사용 시3# 터미널을 재시작하거나 아래 명령 실행4source ~/.zshrc

2단계: Python 환경 생성

1conda create -n hunyuan python=3.10 -y2conda activate hunyuan

3단계: HunyuanVideo_MLX 저장소 클론

1git clone https://github.com/gaurav-nelson/HunyuanVideo_MLX.git2cd HunyuanVideo_MLX

4단계: 의존성 설치

1pip install -r requirements.txt

MLX, mlx-community 패키지 등 Apple Silicon 최적화 라이브러리가 자동으로 설치된다.

5단계: HuggingFace 토큰 설정

HuggingFace에서 액세스 토큰을 발급받은 뒤 .env 파일을 생성한다.

1# https://huggingface.co/settings/tokens 에서 토큰 발급2echo "HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx" > .env

6단계: 모델 가중치 다운로드

1python download_weights.py

모델 전체 크기는 약 30~40GB이므로 네트워크 속도에 따라 수십 분이 소요될 수 있다.

Apple Silicon MPS 설정

HunyuanVideo_MLX는 기본적으로 Apple의 **Metal Performance Shaders(MPS)**를 통해 GPU를 활용한다. 별도의 설정 없이 Apple Silicon Mac이면 자동으로 Metal 가속이 적용된다.

환경 변수를 통해 메모리 사용 비율을 조절할 수 있다.

1# 64GB RAM 환경 (더 많은 메모리 허용)2export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.83 4# 32GB RAM 환경5export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.76 7# 16GB RAM 환경 (보수적으로 제한)8export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.5

이 설정을 영구 적용하려면 ~/.zshrc에 추가한다.

1echo 'export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.7' >> ~/.zshrc2source ~/.zshrc

기본 T2V 사용법

커맨드라인으로 비디오 생성

1python sample_video_mps.py \2  --video-size 544 960 \3  --video-length 65 \4  --prompt "a cat is running in a field, realistic, cinematic lighting" \5  --save-path ./results

주요 인수:

Python 스크립트로 사용

1import subprocess2 3prompt = "a golden retriever playing fetch on a sunny beach, slow motion, photorealistic"4output_path = "./results/beach_dog.mp4"5 6subprocess.run([7    "python", "sample_video_mps.py",8    "--video-size", "544", "960",9    "--video-length", "65",10    "--prompt", prompt,11    "--save-path", "./results"12])

파라미터 조절

해상도와 종횡비

메모리 여유에 따라 해상도를 조절한다.

1# 540p 16:9 (권장 시작점, ~32GB RAM 필요)2--video-size 544 9603 4# 360p 16:9 (저메모리 환경)5--video-size 336 6246 7# 정방형 1:18--video-size 544 5449 10# 세로형 9:16 (숏폼 스타일)11--video-size 960 544

프레임 수와 영상 길이

1# 약 1초 (24프레임, 최소 권장)2--video-length 253 4# 약 2.7초 (65프레임, 균형점)5--video-length 656 7# 약 5초 (129프레임, 최대 권장)8--video-length 129

프레임 수는 4n + 1 형식(25, 29, 33, ... 65, 97, 129)을 사용하는 것이 안정적이다.

추론 스텝 수와 시드

1python sample_video_mps.py \2  --video-size 544 960 \3  --video-length 65 \4  --prompt "..." \5  --infer-steps 50 \6  --seed 42 \7  --save-path ./results

• --infer-steps: 기본값 50, 낮추면 빠르지만 품질 저하 (최소 20 권장)
• --seed: 재현 가능한 결과를 위한 랜덤 시드

메모리 최적화

환경 변수 조합

1# 메모리가 부족할 때 시도할 설정2export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.63export PYTORCH_MPS_LOW_WATERMARK_RATIO=0.5

해상도 단계적 축소

OOM(Out of Memory) 오류가 발생하면 해상도와 프레임 수를 순차적으로 줄여 시도한다.

모델 정밀도 낮추기

메모리를 절약하기 위해 FP16 또는 INT8 양자화(quantization)를 사용하는 경우, 저장소의 README에서 양자화 옵션 플래그를 확인한다. MLX 빌드에서는 4-bit 양자화를 통해 메모리 사용량을 최대 절반 수준으로 줄일 수 있다.

자주 발생하는 오류 해결

OOM (Out of Memory) 오류

해결 방법:

1. PYTORCH_MPS_HIGH_WATERMARK_RATIO 값을 낮춘다 (예: 0.7 → 0.5)
2. --video-size를 줄인다 (예: 544×960 → 336×624)
3. --video-length를 줄인다 (예: 65 → 25)
4. 다른 메모리를 많이 사용하는 앱(브라우저, 크롬 탭 등)을 종료한다

모델 다운로드 실패

해결 방법:

1. HuggingFace 토큰 설정 페이지에서 토큰을 발급받는다
2. .env 파일에 HF_TOKEN=hf_xxx...을 정확히 입력했는지 확인한다
3. huggingface-cli login 명령으로 직접 로그인한다

1pip install huggingface_hub2huggingface-cli login3# 프롬프트에 토큰 입력

MPS 관련 연산 오류

해결 방법: 이 오류는 특정 PyTorch 연산이 MPS 백엔드에서 지원되지 않을 때 발생한다. CPU 폴백을 활성화한다.

1export PYTORCH_ENABLE_MPS_FALLBACK=1

이 설정을 ~/.zshrc에 추가하면 영구적으로 적용된다.

conda 환경 활성화 오류

해결 방법:

1# Miniforge 초기화 재실행2~/miniforge3/bin/conda init zsh3source ~/.zshrc

설치 중 패키지 충돌

1# 환경을 완전히 재생성2conda deactivate3conda env remove -n hunyuan4conda create -n hunyuan python=3.10 -y5conda activate hunyuan6pip install -r requirements.txt

참고 링크

• HunyuanVideo_MLX (Mac 포트): github.com/gaurav-nelson/HunyuanVideo_MLX
• HunyuanVideo 공식 GitHub: github.com/Tencent-Hunyuan/HunyuanVideo
• HuggingFace 모델 페이지: huggingface.co/tencent/HunyuanVideo
• Diffusers 공식 문서: huggingface.co/docs/diffusers/en/api/pipelines/hunyuan_video
• HuggingFace Mac 토론: huggingface.co/tencent/HunyuanVideo/discussions/13
• M4 MacBook 상세 실행 가이드 (Gist): gist.github.com/mdbecker/be0c1730e4a9a8830e46c72812f18a6e