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. 가상환경 생성 및 활성화

python3 -m venv wan_env
source wan_env/bin/activate

2. PyTorch 설치 (MPS 지원)

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

pip install torch torchvision torchaudio

설치 확인:

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

3. diffusers 및 의존 패키지 설치

pip install diffusers transformers accelerate ftfy imageio[ffmpeg]

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

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

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

Apple Silicon MPS 설정

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

export PYTORCH_ENABLE_MPS_FALLBACK=1

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

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

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

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

import torch
from diffusers import AutoModel, WanPipeline
from diffusers.utils import export_to_video
from transformers import UMT5EncoderModel

# MPS 디바이스 설정
device = torch.device("mps")

# 모델 로드 (1.3B 경량 모델)
model_id = "Wan-AI/Wan2.1-T2V-1.3B-Diffusers"

text_encoder = UMT5EncoderModel.from_pretrained(
    model_id, subfolder="text_encoder", torch_dtype=torch.float16
)
vae = AutoModel.from_pretrained(
    model_id, subfolder="vae", torch_dtype=torch.float32
)
transformer = AutoModel.from_pretrained(
    model_id, subfolder="transformer", torch_dtype=torch.float16
)

pipeline = WanPipeline.from_pretrained(
    model_id,
    vae=vae,
    transformer=transformer,
    text_encoder=text_encoder,
    torch_dtype=torch.float16,
)
pipeline.to(device)

# 비디오 생성
prompt = "A cat walking on a sunny beach, waves in the background, cinematic style"
negative_prompt = (
    "worst quality, low quality, blurred, static, overexposed, deformed"
)

output = pipeline(
    prompt=prompt,
    negative_prompt=negative_prompt,
    num_frames=33,         # 프레임 수 (33 = 약 2초 @ 16fps)
    height=480,
    width=832,
    guidance_scale=6.0,
    num_inference_steps=50,
).frames[0]

export_to_video(output, "output.mp4", fps=16)
print("영상 저장 완료: output.mp4")

CLI 방식 (저장소 클론 후)

export PYTORCH_ENABLE_MPS_FALLBACK=1

python generate.py \
  --task t2v-1.3B \
  --device mps \
  --offload_model True \
  --t5_cpu \
  --prompt "A drone shot over a misty mountain forest at sunrise" \
  --size 832*480 \
  --frame_num 33

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

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

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

import torch
from diffusers import AutoencoderKLWan, WanImageToVideoPipeline
from diffusers.utils import export_to_video, load_image
from transformers import CLIPVisionModel

device = torch.device("mps")
model_id = "Wan-AI/Wan2.1-I2V-14B-480P-Diffusers"

image_encoder = CLIPVisionModel.from_pretrained(
    model_id, subfolder="image_encoder", torch_dtype=torch.float32
)
vae = AutoencoderKLWan.from_pretrained(
    model_id, subfolder="vae", torch_dtype=torch.float32
)

pipe = WanImageToVideoPipeline.from_pretrained(
    model_id,
    vae=vae,
    image_encoder=image_encoder,
    torch_dtype=torch.float16,
)
pipe.to(device)
pipe.enable_model_cpu_offload()  # 메모리 절약

# 입력 이미지 로드
image = load_image("input.jpg")

prompt = "The cat slowly turns its head and blinks, soft natural lighting"
negative_prompt = "worst quality, low quality, blurred, static"

output = pipe(
    image=image,
    prompt=prompt,
    negative_prompt=negative_prompt,
    num_frames=33,
    height=480,
    width=832,
    guidance_scale=5.0,
    num_inference_steps=50,
).frames[0]

export_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

해상도 조합 예시:

# 세로형 (모바일)
height=832, width=480

# 가로형 (와이드)
height=480, width=832

# 정사각형
height=480, width=480

메모리 최적화

1. CPU 오프로딩 활성화

# 순차 CPU 오프로딩 (가장 적극적, 속도 느림)
pipeline.enable_sequential_cpu_offload()

# 모델 단위 CPU 오프로딩 (균형)
pipeline.enable_model_cpu_offload()

2. VAE 슬라이싱 / 타일링

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

3. 어텐션 슬라이싱

pipeline.enable_attention_slicing()

4. 프레임 수 줄이기

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

5. bfloat16 대신 float16 사용

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

torch_dtype=torch.float16  # bfloat16 대신 사용

자주 발생하는 오류 해결

NotImplementedError: MPS does not support ...

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

export PYTORCH_ENABLE_MPS_FALLBACK=1

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

RuntimeError: MPS backend out of memory

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

# 1. 프레임 수 줄이기
num_frames=17

# 2. 해상도 낮추기
height=480, width=480

# 3. CPU 오프로딩
pipeline.enable_sequential_cpu_offload()

# 4. 기존 캐시 정리
import gc
import torch
gc.collect()
torch.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 모델 다운로드 오류

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

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

개요