Wan2.2 + Wan2GP로 로컬 AI 영상 생성 환경 구축하기: GGUF Q4_K_M으로 VRAM 부족 해결

H100 없어도 됩니다. VRAM 12GB GPU 두 장짜리 서버에서 Wan2.2 TI2V 영상 생성을 돌리는 데 성공했습니다. 핵심은 모델 전체를 FP16으로 올리려 하지 않고, GGUF Q4_K_M 양자화 파일을 쓰는 겁니다. Docker 컨테이너부터 Gradio UI 접속까지, 직접 삽질하면서 정리한 세팅 가이드입니다.

---

핵심 요약

Wan2.2는 알리바바 Wan AI 팀이 2025년 7월 공개한 오픈소스 영상 생성 모델입니다. T2V(텍스트→영상), I2V(이미지→영상), TI2V(텍스트+이미지→영상) 세 가지 태스크를 지원하고, 파라미터 규모에 따라 5B와 14B 두 계열이 있습니다. Apache 2.0 라이선스라서 상업적 사용도 가능합니다.

이 가이드에서 쓰는 모델은 Wan2.2-TI2V-5B입니다. 이미지를 기준 프레임으로 주고 텍스트 프롬프트로 움직임을 지시하면 영상을 만들어주는 모델인데, 5B 파라미터라서 14B 계열보다 VRAM 요구량이 훨씬 낮습니다. 그럼에도 FP16 풀 모델은 12GB VRAM 카드 두 장으로 빡빡하기 때문에 GGUF Q4_K_M 양자화 파일을 씁니다. Q4_K_M은 4비트 K-means 양자화의 중간 품질 버전으로, 파일 크기와 품질 사이의 균형이 실용적으로 가장 좋다는 게 커뮤니티 검증 결과입니다.

UI는 Wan2GP를 씁니다. deepbeepmeep이 만든 커뮤니티 래퍼로, 공식 Wan2.2 코드베이스에 Gradio UI와 GGUF 로딩 지원을 붙인 프로젝트입니다. Flash Attention이나 Sage Attention 없이도 돌아가고, 구형 GPU 아키텍처처럼 최신 커널이 지원 안 되는 환경에서도 우회할 수 있습니다.

Docker 이미지는 pytorch/pytorch:2.5.1-cuda11.8-cudnn9-devel을 씁니다. 호스트 드라이버가 CUDA 12.x라도 CUDA 11.8 기반 이미지가 Pascal 계열 GPU에서 패키지 빌드 호환성이 더 안정적입니다. ffmpeg은 apt 기본 패키지 대신 johnvansickle.com 정적 빌드를 씁니다. apt 버전은 오래됐고 일부 코덱이 빠져 있어서 영상 인코딩에서 에러가 날 수 있기 때문입니다.

---

실전 1: Docker 컨테이너 세팅

Docker 컨테이너를 띄울 때 GPU 할당과 포트 바인딩 두 가지가 핵심입니다. --gpus '"device=0,1"'처럼 큰따옴표 안에 작은따옴표가 들어가는 이중 인용 방식이 반드시 필요한데, 이 형식이 틀리면 컨테이너가 GPU를 인식하지 못하고 CPU로만 돌아갑니다.

아래 스크립트로 컨테이너를 생성하고 진입합니다. /aiwork/wan을 컨테이너 내부 /workspace로 마운트하기 때문에 컨테이너를 날려도 모델 파일과 생성된 영상이 호스트에 그대로 남습니다.

#!/bin/bash
# 호스트 작업 디렉토리 생성
mkdir -p /aiwork/wan

# 컨테이너 생성 (최초 1회)
docker run -itd \
    --gpus '"device=0,1"' \
    --name wan2gp_workspace \
    -v /aiwork/wan:/workspace \
    -p 7860:7860 \
    pytorch/pytorch:2.5.1-cuda11.8-cudnn9-devel \
    bash

# 컨테이너 진입
docker exec -it wan2gp_workspace bash

# GPU 인식 확인
nvidia-smi

# Python에서도 확인
python -c "import torch; print(torch.cuda.device_count(), torch.cuda.get_device_name(0))"

컨테이너 재시작 후 다시 진입할 때는 docker start wan2gp_workspace && docker exec -it wan2gp_workspace bash를 씁니다. docker run을 다시 실행하면 컨테이너가 새로 생성되어 설치한 패키지가 사라지니 주의합니다.

---

실전 2: ffmpeg 최신 정적 빌드 설치

apt 기본 패키지 ffmpeg은 버전이 낮고 일부 코덱이 빠져 있습니다. 영상 인코딩 단계에서 에러가 날 수 있어서 johnvansickle.com의 정적 빌드로 교체합니다. 정적 빌드는 의존성 없이 바이너리 하나로 돌아가기 때문에 Docker 환경에서 특히 관리하기 편합니다.

apt로 먼저 기존 ffmpeg을 제거하고, wget으로 최신 정적 빌드를 받아서 시스템 PATH에 설치합니다.

# 기존 apt ffmpeg 제거
apt-get remove -y ffmpeg

# 다운로드 도구 설치
apt-get install -y wget xz-utils

# 최신 정적 빌드 다운로드
wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz

# 압축 해제
tar xf ffmpeg-release-amd64-static.tar.xz

# 바이너리를 시스템 PATH로 이동
mv ffmpeg-*-amd64-static/ffmpeg /usr/local/bin/
mv ffmpeg-*-amd64-static/ffprobe /usr/local/bin/

# 설치 확인
ffmpeg -version
# ffmpeg version 7.x.x 이상이 나오면 정상

설치가 완료되면 ffmpeg -version에서 빌드 날짜와 코덱 목록이 출력됩니다. libx264, libvpx 등이 포함된 걸 확인하면 됩니다. 다운로드 파일과 압축 해제 폴더는 용량 정리를 위해 삭제해도 됩니다.

# 임시 파일 정리
rm -rf ffmpeg-release-amd64-static.tar.xz ffmpeg-*-amd64-static

---

실전 3: Wan2GP 설치

ffmpeg 세팅이 끝나면 Wan2GP를 클론하고 패키지를 설치합니다. Wan2GP는 pip 패키지가 아니라 GitHub 레포를 직접 클론해서 씁니다. requirements.txt를 먼저 설치하고 나서 gguf와 huggingface_hub를 따로 설치하는 순서를 지켜야 버전 충돌을 피할 수 있습니다.

# Wan2GP 클론
cd /workspace
git clone https://github.com/deepbeepmeep/Wan2GP.git
cd Wan2GP

# Python 패키지 설치
pip install -r requirements.txt
pip install gguf huggingface_hub

# 설치 확인
python -c "import gguf; print('gguf OK')"
python -c "from huggingface_hub import hf_hub_download; print('hf_hub OK')"

설치 중 CUDA 관련 빌드 에러가 나오면 CUDA_HOME 환경변수가 없어서일 수 있습니다. export CUDA_HOME=/usr/local/cuda를 먼저 실행하고 다시 시도하면 해결되는 경우가 많습니다.

---

실전 4: 모델 파일 다운로드

모델 파일은 세 가지를 따로 받습니다. 텍스트 인코더(UMT5), VAE, 그리고 GGUF 양자화 디퓨전 모델입니다. 전부 한 번에 받으면 수십 GB를 다운로드하는데, --include 패턴으로 필요한 것만 골라 받는 게 훨씬 빠릅니다.

다운로드 중 끊길 수 있어서 --resume-download 플래그를 반드시 붙입니다. HuggingFace 토큰이 있으면 속도 제한 없이 받을 수 있습니다.

# HuggingFace 토큰 설정 (선택, 있으면 더 빠름)
export HF_TOKEN="your_token_here"

# 모델 저장 디렉토리 생성
mkdir -p /workspace/models
mkdir -p /workspace/Wan2GP/models

# 1. UMT5 텍스트 인코더 (약 10GB)
huggingface-cli download \
  Wan-AI/Wan2.2-TI2V-5B \
  --include "umt5*" \
  --local-dir /workspace/models/ \
  --resume-download

# 2. VAE (약 400MB)
huggingface-cli download \
  Wan-AI/Wan2.2-TI2V-5B \
  --include "wan2.2_vae*" \
  --local-dir /workspace/models/ \
  --resume-download

# 3. GGUF Q4_K_M 디퓨전 모델
huggingface-cli download \
  Wan-AI/Wan2.2-TI2V-5B \
  "Wan2.2-TI2V-5B-Q4_K_M.gguf" \
  --local-dir /workspace/Wan2GP/models/ \
  --resume-download

# 다운로드 확인
ls -lh /workspace/models/
ls -lh /workspace/Wan2GP/models/

다운로드 완료 후 파일 구조가 아래처럼 돼 있으면 정상입니다.

/workspace/
├── models/
│   ├── umt5_xxl_fp8_e4m3fn_scaled.safetensors  (~10GB)
│   └── wan2.2_vae.safetensors                   (~400MB)
└── Wan2GP/
    └── models/
        └── Wan2.2-TI2V-5B-Q4_K_M.gguf          (~3~4GB)

---

실전 5: 서버 실행

설치와 모델 다운로드가 끝났으면 Gradio 서버를 띄웁니다. --i2v 플래그는 Image-to-Video 모드(TI2V 포함), --server-name 0.0.0.0은 컨테이너 외부에서 접속할 수 있도록 모든 인터페이스에 바인딩합니다. Wan2GP가 models 폴더의 GGUF 파일을 자동으로 감지해서 로드하기 때문에 별도 설정 없이 실행하면 됩니다.

cd /workspace/Wan2GP
python wgp.py --i2v --server-name 0.0.0.0

# 서버가 뜨면 아래 메시지가 나옴
# Running on local URL:  http://0.0.0.0:7860

호스트 브라우저에서 http://서버IP:7860으로 접속하면 Gradio UI가 뜹니다. 처음 접속 시 GGUF 모델을 메모리에 올리는 데 수십 초가 걸리는 건 정상입니다. GPU 메모리에 올라가고 나면 이후 생성 요청은 훨씬 빠르게 시작됩니다.

백그라운드로 돌리고 싶다면 nohup으로 실행하고 로그를 파일로 뺍니다.

# 백그라운드 실행
nohup python wgp.py --i2v --server-name 0.0.0.0 \
  > /workspace/wgp.log 2>&1 &

# 로그 실시간 확인
tail -f /workspace/wgp.log

# 프로세스 확인
ps aux | grep wgp.py

---

실전 6: GGUF Q4_K_M을 선택한 이유와 영상 생성 팁

Wan2.2-TI2V-5B의 원본 FP16 가중치는 약 10GB입니다. VRAM 12GB 카드 두 장을 합치면 24GB처럼 보이지만, 모델 가중치 외에 중간 활성화 텐서, VAE, 텍스트 인코더(UMT5 약 10GB)까지 올라가면 단순 합산 이상의 메모리가 필요합니다. GGUF Q4_K_M으로 디퓨전 모델 가중치를 양자화하면 크기가 절반 이하로 줄어들면서 VRAM 여유가 생깁니다.

양자화 레벨 선택 기준도 명확합니다. Q4_K_S보다 품질이 좋고, Q8보다 가볍습니다. VRAM이 더 여유롭다면 Q5_K_M이나 Q8_0으로 올리면 품질이 더 나옵니다. 반대로 12GB 단일 카드라면 Q4_K_S나 Q3_K_M으로 내려가야 OOM을 피할 수 있습니다.

# 생성 중 VRAM 사용량 모니터링
watch -n 2 nvidia-smi

# Python에서 확인
python -c "
import torch
for i in range(torch.cuda.device_count()):
    free, total = torch.cuda.mem_get_info(i)
    used = (total - free) / 1024**3
    print(f'GPU {i}: {used:.1f}GB / {total / 1024**3:.1f}GB')
"

영상 생성 시 프롬프트와 파라미터 설정이 결과 품질에 직접 영향을 줍니다. 영어 프롬프트가 한국어보다 훨씬 잘 먹히고, 움직임과 분위기를 구체적으로 서술할수록 원하는 결과가 나옵니다. 해상도와 프레임 수는 VRAM 여유에 맞게 조정해야 합니다. VRAM 12GB 두 장 기준으로 480P 17프레임은 안정적으로 돌아가고, 33프레임은 조금 빡빡합니다. 720P는 OOM 확률이 높으니 일단 480P로 테스트하고 여유가 확인되면 올리는 순서를 권장합니다.

---

마무리

Wan2.2 + Wan2GP + GGUF Q4_K_M 조합은 고가 GPU 없이 로컬에서 이미지→영상 생성을 돌릴 수 있는 현실적인 방법입니다. 12GB VRAM 카드 두 장으로 480P 영상 생성이 가능하고, Docker로 환경을 격리해두면 호스트 Python 환경을 건드리지 않아서 유지보수도 편합니다. ffmpeg은 apt 기본 패키지 대신 정적 빌드를 설치해야 인코딩 에러를 피할 수 있다는 점이 처음에 놓치기 쉬운 부분입니다. 속도가 느리고 720P는 빡빡하다는 한계는 있지만, 상용 API에 비용을 낼 필요 없이 완전히 로컬에서 영상을 뽑아낼 수 있다는 자체가 의미 있습니다.