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

개요

이 가이드는 Apple Silicon(M1/M2/M3) Mac에서 HunyuanDiT를 HuggingFace diffusers 라이브러리를 통해 설치하고 실행하는 방법을 설명합니다. Mac에서는 CUDA 대신 Apple의 MPS(Metal Performance Shaders) 백엔드를 사용하여 GPU 가속 추론이 가능합니다.

참고: HunyuanDiT는 모델 크기가 상당히 크므로(기본 모델 약 10GB 이상), 충분한 디스크 공간과 RAM이 필요합니다. 최소 16GB RAM을 권장하며, 32GB 이상이면 안정적으로 사용할 수 있습니다.

사전 요구사항

시스템 요구사항

항목	최소 사양	권장 사양
칩	Apple M1	Apple M2 / M3
RAM	16GB	32GB 이상
디스크 여유 공간	20GB	30GB 이상
macOS	12.6	13.0 이상
Python	3.9 (arm64)	3.10 / 3.11 (arm64)

Python 환경 확인

반드시 arm64 버전의 Python을 사용해야 합니다. Rosetta2로 실행 중인 x86 Python은 MPS 백엔드를 지원하지 않습니다.

1python3 -c "import platform; print(platform.machine())"2# 출력: arm64  (이 값이어야 함)

설치 방법

1단계: 가상 환경 생성

1python3 -m venv hunyuan-env2source hunyuan-env/bin/activate

또는 conda를 사용하는 경우:

1conda create -n hunyuan python=3.102conda activate hunyuan

2단계: PyTorch 설치 (MPS 지원 버전)

MPS 백엔드는 PyTorch 2.0 이상을 권장합니다. 공식 PyTorch 사이트에서 macOS용 pip 설치 명령어를 사용합니다.

1pip install torch torchvision torchaudio

설치 후 MPS 가용 여부를 확인합니다:

1import torch2print(torch.backends.mps.is_available())   # True 이어야 함3print(torch.backends.mps.is_built())       # True 이어야 함

3단계: diffusers 및 관련 패키지 설치

1pip install diffusers transformers accelerate sentencepiece protobuf

패키지별 역할:

패키지	역할
`diffusers`	HunyuanDiT 파이프라인 제공
`transformers`	텍스트 인코더(CLIP, T5)
`accelerate`	모델 로딩 최적화
`sentencepiece`	mT5 토크나이저
`protobuf`	T5 모델 직렬화 형식 지원

Apple Silicon MPS 설정

기본 MPS 파이프라인 로드

1import torch2from diffusers import HunyuanDiTPipeline3 4pipe = HunyuanDiTPipeline.from_pretrained(5    "Tencent-Hunyuan/HunyuanDiT-Diffusers",6    torch_dtype=torch.float32   # MPS는 float16보다 float32가 안정적7)8pipe = pipe.to("mps")9 10# RAM이 64GB 미만이면 반드시 설정 (메모리 절약)11pipe.enable_attention_slicing()

주의: MPS 백엔드에서는 torch.float16 사용 시 일부 연산에서 불안정할 수 있습니다. 안정성을 위해 torch.float32를 사용하고, 속도가 필요하다면 torch.bfloat16을 시도해보세요.

기본 이미지 생성

영어 프롬프트로 이미지 생성

1import torch2from diffusers import HunyuanDiTPipeline3 4pipe = HunyuanDiTPipeline.from_pretrained(5    "Tencent-Hunyuan/HunyuanDiT-Diffusers",6    torch_dtype=torch.float327).to("mps")8 9pipe.enable_attention_slicing()10 11prompt = "A majestic snow-capped mountain at sunset, photorealistic, 8k resolution"12negative_prompt = "blurry, low quality, watermark"13 14image = pipe(15    prompt=prompt,16    negative_prompt=negative_prompt,17    num_inference_steps=50,18    guidance_scale=6.0,19    height=1024,20    width=1024,21).images[0]22 23image.save("output_en.png")24print("이미지 저장 완료: output_en.png")

중국어 프롬프트로 이미지 생성

HunyuanDiT는 중국어 프롬프트를 번역 없이 직접 처리할 수 있습니다:

1import torch2from diffusers import HunyuanDiTPipeline3 4pipe = HunyuanDiTPipeline.from_pretrained(5    "Tencent-Hunyuan/HunyuanDiT-Diffusers",6    torch_dtype=torch.float327).to("mps")8 9pipe.enable_attention_slicing()10 11# 중국어 프롬프트: "달빛 아래 고요한 대나무 숲"12prompt = "月光下宁静的竹林，水墨画风格，高清"13negative_prompt = "模糊，低质量，水印"14 15image = pipe(16    prompt=prompt,17    negative_prompt=negative_prompt,18    num_inference_steps=50,19    guidance_scale=6.0,20    height=1024,21    width=1024,22).images[0]23 24image.save("output_zh.png")25print("이미지 저장 완료: output_zh.png")

파라미터 조절

주요 생성 파라미터와 그 효과를 정리합니다:

파라미터	기본값	설명
`num_inference_steps`	50	디노이징 스텝 수. 높을수록 품질 향상, 속도 감소 (20~100 권장)
`guidance_scale`	6.0	프롬프트 충실도. 높을수록 프롬프트에 충실, 다양성 감소 (4~10 권장)
`height` / `width`	1024	생성 이미지 크기. 아래 지원 해상도 참고
`negative_prompt`	None	이미지에서 제외할 요소 설명
`num_images_per_prompt`	1	한 번에 생성할 이미지 수 (MPS에서는 1 권장)
`use_resolution_binning`	True	해상도 자동 최적화

지원하는 해상도

정사각형:  1024×1024, 1280×1280
가로형:    1024×768, 1152×864, 1280×960, 1280×768
세로형:    768×1024, 864×1152, 960×1280, 768×1280

메모리 최적화

Apple Silicon의 통합 메모리(Unified Memory) 특성상 RAM이 곧 VRAM이므로, 메모리 관리가 중요합니다.

Attention Slicing (필수 권장)

1# 어텐션 연산을 여러 단계로 분할하여 메모리 절약2pipe.enable_attention_slicing()3 4# 더 작은 청크 사이즈로 더 강한 메모리 절약5pipe.enable_attention_slicing(slice_size=1)

CPU Offloading

RAM이 부족할 경우 모델 일부를 CPU로 오프로드합니다:

1# 파이프라인 구성 요소를 필요할 때만 GPU로 이동2pipe.enable_model_cpu_offload()

주의: enable_model_cpu_offload()는 현재 MPS에서 완전히 지원되지 않을 수 있습니다. 오류 발생 시 이 줄을 제거하고 enable_attention_slicing()만 사용하세요.

사용 후 메모리 해제

연속 사용 시 메모리를 명시적으로 해제합니다:

1import gc2import torch3 4# 이미지 생성 후5del image6gc.collect()7torch.mps.empty_cache()

여러 이미지를 배치 대신 반복문으로 생성

MPS 백엔드에서 배치 추론은 불안정할 수 있습니다. 여러 이미지는 반복문으로 생성하세요:

1prompts = [2    "A serene lake at dawn",3    "A bustling city street at night",4    "A field of wildflowers in spring",5]6 7images = []8for prompt in prompts:9    image = pipe(prompt=prompt, num_inference_steps=30).images[0]10    images.append(image)11    torch.mps.empty_cache()   # 매 생성 후 캐시 비우기

자주 발생하는 오류 해결

오류 1: `NotImplementedError: The operator 'aten::...' is not currently implemented for MPS`

일부 연산이 MPS에서 미구현된 경우입니다.

1# 해결: 해당 연산을 CPU로 폴백 설정2import os3os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"4 5# 스크립트 실행 전 환경변수로 설정하는 것이 더 안정적6# 터미널에서: export PYTORCH_ENABLE_MPS_FALLBACK=1

오류 2: `RuntimeError: MPS backend out of memory`

메모리 부족 오류입니다.

1# 해결 방법 순서대로 시도:2 3# 1. Attention slicing 활성화4pipe.enable_attention_slicing(slice_size=1)5 6# 2. 이미지 크기 줄이기7image = pipe(prompt=prompt, height=768, width=768).images[0]8 9# 3. 추론 스텝 수 줄이기10image = pipe(prompt=prompt, num_inference_steps=25).images[0]11 12# 4. MPS 캐시 비우기13torch.mps.empty_cache()

오류 3: 첫 번째 추론 결과가 이상한 경우 (PyTorch 구버전)

PyTorch 1.13을 사용할 경우 발생하는 워밍업 문제입니다.

1# 해결: 첫 번째 추론은 워밍업으로 사용하고 결과 버리기2_ = pipe(prompt, num_inference_steps=1)3 4# 이후 정상 추론5image = pipe(prompt).images[0]

오류 4: `sentencepiece` 관련 임포트 오류

1# 해결: sentencepiece 재설치2pip install sentencepiece protobuf --upgrade

오류 5: 모델 다운로드가 느리거나 중단되는 경우

1# 환경변수로 HuggingFace 캐시 경로 지정2import os3os.environ["HF_HOME"] = "/path/to/large/disk/hf_cache"4 5# 또는 다운로드 재시도 설정6from huggingface_hub import snapshot_download7snapshot_download("Tencent-Hunyuan/HunyuanDiT-Diffusers", resume_download=True)

참고 링크

항목	링크
HunyuanDiT 소개 페이지	HunyuanDiT 소개
GitHub 공식 저장소	Tencent-Hunyuan/HunyuanDiT
HuggingFace 모델	Tencent-Hunyuan/HunyuanDiT-Diffusers
diffusers 파이프라인 문서	Hunyuan-DiT — diffusers docs
MPS 최적화 가이드	Metal Performance Shaders — diffusers docs
PyTorch MPS 공식 문서	PyTorch MPS backend
논문 (arXiv)	arXiv:2405.08748

개요