Wan2.1 설치 및 사용 가이드 (Mac)

개요

이 가이드는 Apple Silicon Mac(M1/M2/M3/M4)에서 Wan2.1 비디오 생성 모델을 설치하고 사용하는 방법을 설명한다. Wan2.1은 공식적으로 CUDA(NVIDIA GPU)를 기본 지원하지만, PyTorch의 MPS(Metal Performance Shaders) 백엔드와 PYTORCH_ENABLE_MPS_FALLBACK 환경 변수를 활용하면 Apple Silicon에서도 실행할 수 있다.

권장 모델: Mac에서는 메모리 제약으로 인해 T2V-1.3B 모델 사용을 권장한다. 14B 모델은 M4 Max(128GB) 수준의 고사양 Mac에서도 100GB 이상의 통합 메모리를 사용한다.

사전 요구사항

하드웨어

항목	T2V-1.3B (권장)	T2V-14B / I2V-14B
통합 메모리(RAM)	최소 16 GB, 권장 32 GB 이상	최소 64 GB, 권장 128 GB 이상
저장공간	모델 약 5 GB + 작업 공간 10 GB	모델 약 30 GB + 작업 공간 20 GB
칩	M1 이상	M2 Ultra / M3 Max / M4 Max

소프트웨어

macOS 12.3 이상 (MPS 지원)
Python 3.10 이상
Git
Homebrew (선택, 가상환경 관리 편의)

설치 방법

1. 가상환경 생성 및 활성화

1python3 -m venv wan_env2source wan_env/bin/activate

2. PyTorch 설치 (MPS 지원)

Apple Silicon에서는 PyTorch 공식 빌드가 MPS를 기본 포함한다.

1pip install torch torchvision torchaudio

설치 확인:

1python -c "import torch; print(torch.backends.mps.is_available())"2# True 출력 시 정상

3. diffusers 및 의존 패키지 설치

1pip install diffusers transformers accelerate ftfy imageio[ffmpeg]

4. Wan2.1 저장소 클론 (선택)

CLI 방식으로 사용할 경우 저장소를 클론한다.

1git clone https://github.com/Wan-Video/Wan2.1.git2cd Wan2.13pip install -r requirements.txt

Apple Silicon MPS 설정

MPS 백엔드를 활성화하려면 실행 전에 반드시 아래 환경 변수를 설정해야 한다. 일부 연산이 MPS에서 지원되지 않을 때 CPU로 자동 폴백된다.

1export PYTORCH_ENABLE_MPS_FALLBACK=1

영구적으로 설정하려면 ~/.zshrc에 추가한다:

1echo 'export PYTORCH_ENABLE_MPS_FALLBACK=1' >> ~/.zshrc2source ~/.zshrc

T2V 기본 사용법 (텍스트→비디오)

diffusers 파이프라인 방식 (권장)

1import torch2from diffusers import AutoModel, WanPipeline3from diffusers.utils import export_to_video4from transformers import UMT5EncoderModel5 6# MPS 디바이스 설정7device = torch.device("mps")8 9# 모델 로드 (1.3B 경량 모델)10model_id = "Wan-AI/Wan2.1-T2V-1.3B-Diffusers"11 12text_encoder = UMT5EncoderModel.from_pretrained(13    model_id, subfolder="text_encoder", torch_dtype=torch.float1614)15vae = AutoModel.from_pretrained(16    model_id, subfolder="vae", torch_dtype=torch.float3217)18transformer = AutoModel.from_pretrained(19    model_id, subfolder="transformer", torch_dtype=torch.float1620)21 22pipeline = WanPipeline.from_pretrained(23    model_id,24    vae=vae,25    transformer=transformer,26    text_encoder=text_encoder,27    torch_dtype=torch.float16,28)29pipeline.to(device)30 31# 비디오 생성32prompt = "A cat walking on a sunny beach, waves in the background, cinematic style"33negative_prompt = (34    "worst quality, low quality, blurred, static, overexposed, deformed"35)36 37output = pipeline(38    prompt=prompt,39    negative_prompt=negative_prompt,40    num_frames=33,         # 프레임 수 (33 = 약 2초 @ 16fps)41    height=480,42    width=832,43    guidance_scale=6.0,44    num_inference_steps=50,45).frames[0]46 47export_to_video(output, "output.mp4", fps=16)48print("영상 저장 완료: output.mp4")

CLI 방식 (저장소 클론 후)

1export PYTORCH_ENABLE_MPS_FALLBACK=12 3python generate.py \4  --task t2v-1.3B \5  --device mps \6  --offload_model True \7  --t5_cpu \8  --prompt "A drone shot over a misty mountain forest at sunrise" \9  --size 832*480 \10  --frame_num 33

--offload_model True: 미사용 모델 레이어를 CPU로 오프로드해 메모리 절약
--t5_cpu: T5 텍스트 인코더를 CPU에서 실행해 GPU 메모리 확보

I2V 사용법 (이미지→비디오)

이미지를 입력으로 받아 움직이는 영상을 생성한다. I2V 모델은 14B 파라미터만 지원하므로 충분한 메모리(64 GB 이상)가 필요하다.

1import torch2from diffusers import AutoencoderKLWan, WanImageToVideoPipeline3from diffusers.utils import export_to_video, load_image4from transformers import CLIPVisionModel5 6device = torch.device("mps")7model_id = "Wan-AI/Wan2.1-I2V-14B-480P-Diffusers"8 9image_encoder = CLIPVisionModel.from_pretrained(10    model_id, subfolder="image_encoder", torch_dtype=torch.float3211)12vae = AutoencoderKLWan.from_pretrained(13    model_id, subfolder="vae", torch_dtype=torch.float3214)15 16pipe = WanImageToVideoPipeline.from_pretrained(17    model_id,18    vae=vae,19    image_encoder=image_encoder,20    torch_dtype=torch.float16,21)22pipe.to(device)23pipe.enable_model_cpu_offload()  # 메모리 절약24 25# 입력 이미지 로드26image = load_image("input.jpg")27 28prompt = "The cat slowly turns its head and blinks, soft natural lighting"29negative_prompt = "worst quality, low quality, blurred, static"30 31output = pipe(32    image=image,33    prompt=prompt,34    negative_prompt=negative_prompt,35    num_frames=33,36    height=480,37    width=832,38    guidance_scale=5.0,39    num_inference_steps=50,40).frames[0]41 42export_to_video(output, "i2v_output.mp4", fps=16)

주요 파라미터 조절

파라미터	설명	권장값 (Mac)
`num_frames`	생성할 총 프레임 수	17~33 (메모리 부족 시 줄일 것)
`height` / `width`	출력 해상도	480 × 832 (1.3B), 720 × 1280 (14B)
`guidance_scale`	프롬프트 충실도 vs 다양성	5.0~7.0
`num_inference_steps`	디노이징 스텝 수 (많을수록 고품질, 느림)	30~50
`fps` (export)	출력 영상 프레임레이트	16

해상도 조합 예시:

1# 세로형 (모바일)2height=832, width=4803 4# 가로형 (와이드)5height=480, width=8326 7# 정사각형8height=480, width=480

메모리 최적화

1. CPU 오프로딩 활성화

1# 순차 CPU 오프로딩 (가장 적극적, 속도 느림)2pipeline.enable_sequential_cpu_offload()3 4# 모델 단위 CPU 오프로딩 (균형)5pipeline.enable_model_cpu_offload()

2. VAE 슬라이싱 / 타일링

1# 대용량 영상 디코딩 시 메모리 분산2pipeline.enable_vae_slicing()3pipeline.enable_vae_tiling()

3. 어텐션 슬라이싱

1pipeline.enable_attention_slicing()

4. 프레임 수 줄이기

생성 시간과 메모리는 프레임 수에 비례한다. 테스트 시 num_frames=17(약 1초)로 시작해 점진적으로 늘린다.

5. bfloat16 대신 float16 사용

Mac MPS는 bfloat16을 일부 미지원하는 경우가 있으므로 torch.float16을 사용한다.

1torch_dtype=torch.float16  # bfloat16 대신 사용

자주 발생하는 오류 해결

NotImplementedError: MPS does not support ...

원인: 특정 PyTorch 연산이 MPS 백엔드에서 미지원
해결:

1export PYTORCH_ENABLE_MPS_FALLBACK=1

이 환경 변수를 설정하면 미지원 연산이 자동으로 CPU에서 실행된다.

RuntimeError: MPS backend out of memory

원인: 통합 메모리 부족
해결:

1# 1. 프레임 수 줄이기2num_frames=173 4# 2. 해상도 낮추기5height=480, width=4806 7# 3. CPU 오프로딩8pipeline.enable_sequential_cpu_offload()9 10# 4. 기존 캐시 정리11import gc12import torch13gc.collect()14torch.mps.empty_cache()

TypeError: unsupported dtype bfloat16 on MPS

원인: Apple Silicon MPS가 bfloat16 미지원
해결: 모든 torch_dtype=torch.bfloat16을 torch.float16으로 교체한다.

slow_conv2d_cpu is not supported on MPS

원인: 특정 합성곱 연산의 MPS 미지원
해결: PYTORCH_ENABLE_MPS_FALLBACK=1 환경 변수 설정으로 해결된다.

HuggingFace 모델 다운로드 오류

원인: 네트워크 또는 인증 문제
해결:

1pip install huggingface_hub2huggingface-cli login  # 토큰 입력 (무료 계정 가능)

개요