LivePortrait는 단일 초상화 이미지에 구동 영상의 움직임을 이식하여 생생한 얼굴 애니메이션을 생성하는 AI 기반 오픈소스 도구입니다. 콰이쇼우(Kuaishou) 기술팀이 개발했으며, 사람뿐 아니라 고양이·개 등 동물의 표정 애니메이션도 지원합니다. 스티칭(stitching) 및 리타게팅(retargeting) 제어 기능을 통해 콘텐츠 제작, 영상 편집, 디지털 엔터테인먼트 등 다양한 분야에 활용할 수 있습니다.
핵심 기능
- 정지 이미지를 동적 비디오로 변환
- 구동 비디오의 동작을 소스 얼굴에 전이
- 눈, 입, 머리 자세(피치·롤·요) 세밀 조정
- 반려동물 모드 지원
- Gradio 기반 실시간 웹 인터페이스
시스템 요구 사항
| 구성 요소 | 최소 사양 | 권장 사양 | 비고 |
|---|---|---|---|
| 운영체제 | Windows 10 / macOS 12+ / Ubuntu 20.04+ | Windows 11 / macOS 13+ / Ubuntu 22.04+ | 주요 OS 지원 |
| CPU | 쿼드코어 | 옥타코어 이상 | 전처리 속도에 영향 |
| 메모리 | 8 GB RAM | 16 GB RAM | 안정성 향상 |
| GPU | 내장 그래픽 | NVIDIA GPU (VRAM 4 GB 이상) | CUDA 가속 권장 |
| 저장 공간 | 10 GB | 20 GB SSD | 모델 파일 용량 큼 |
| Python | 3.8 이상 | 3.10 | 3.10 권장 |
사전 도구 설치
Git
# macOS
brew install git
# Ubuntu
sudo apt update && sudo apt install git -y
# 설치 확인
git --version
Conda
# Miniconda 설치 (Linux)
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
# 초기화
conda init
FFmpeg
# macOS
brew install ffmpeg
# Ubuntu
sudo apt install ffmpeg libsox-dev -y
# 설치 확인
ffmpeg -version
프로젝트 클론 및 가상 환경
git clone https://gitcode.com/GitHub_Trending/li/LivePortrait
cd LivePortrait
# 전용 Conda 환경 생성 (환경명: lportrait)
conda create -n lportrait python=3.10 -y
conda activate lportrait
의존성 패키지 설치
아래는 CUDA 11.8을 기준으로 한 PyTorch 설치 예시입니다. 본인 환경의 CUDA 버전을 먼저 확인하세요.
# CUDA 버전 확인
nvcc -V
# PyTorch 설치 (CUDA 11.8)
pip install torch==2.3.0 torchvision==0.18.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu118
# 공통 의존성
pip install -r requirements_base.txt
# 추가 패키지
pip install onnxruntime-gpu==1.18.0 transformers==4.38.0
macOS (Apple Silicon) 사용자는 아래 명령을 사용합니다.
pip install -r requirements_macOS.txt
사전 학습 모델 다운로드
# Hugging Face Hub CLI 설치
pip install -U "huggingface_hub[cli]"
# 국내 미러 설정 (선택)
export HF_ENDPOINT=https://hf-mirror.com
# 모델 가중치 다운로드 (로컬 디렉터리: pretrained_weights)
huggingface-cli download KwaiVGI/LivePortrait --local-dir pretrained_weights --exclude "*.git*" "README.md" "docs"
기본 동작 확인
# 사람 모드 실행
python inference.py
# macOS Apple Silicon인 경우
PYTORCH_ENABLE_MPS_FALLBACK=1 python inference.py
실행이 완료되면 animations 폴더에 결과 영상이 생성됩니다.
동물 모드 설정 (Linux / Windows 전용)
동물 모드는 XPose 의존성 빌드가 필요합니다.
# MultiScaleDeformableAttention 빌드
cd src/utils/dependencies/XPose/models/UniPose/ops
python setup.py build install
cd -
# 동물 모드 테스트
python inference_animals.py -s assets/examples/source/s39.jpg -d assets/examples/driving/wink.pkl --driving_multiplier 1.75 --no_flag_stitching
Gradio 웹 인터페이스 실행
# 사람 모드 UI
python app.py
# 동물 모드 UI
python app_animals.py
# 외부 접근 허용 및 포트 지정
python app.py --server_port 7861 --share --server_name 0.0.0.0
성능 가속 옵션
하드웨어에 따른 추천 설정입니다.
| GPU 등급 | 추천 옵션 | 예상 속도 향상 |
|---|---|---|
| 엔트리 레벨 | --batch_size 1 --low_res | 약 30% |
| 미드레인지 (RTX 3060 급) | --fp16 --num_workers 4 | 약 50% |
| 하이엔드 (RTX 4090 급) | --batch_size 4 --fp16 | 약 2배 |
| Apple Silicon | --mps --low_mem | 약 40% |
Torch 컴파일을 활성화하려면 아래 플래그를 추가하세요(첫 실행 시 시간이 소요됨).
python app.py --flag_do_torch_compile
실전 예제
이미지 + 비디오 구동
# 소스 이미지(s0.jpg)에 구동 비디오(d0.mp4)의 움직임 적용
python inference.py -s assets/examples/source/s0.jpg -d assets/examples/driving/d0.mp4
비디오 → 비디오 변환
python inference.py -s assets/examples/source/s13.mp4 -d assets/examples/driving/d0.mp4
사전 계산된 모션 템플릿(.pkl) 사용
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d5.pkl
이미지-투-이미지 구동
python inference.py -s assets/examples/source/s0.jpg -d assets/examples/source/s1.jpg --image_driving
구동 비디오 자동 크롭
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d13.mp4 --flag_crop_driving_video
# 크롭 파라미터 사용자 지정
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d13.mp4 --flag_crop_driving_video --scale_crop_driving_video 2.2 --vy_ratio_crop_driving_video -0.1
문제 해결
모델 다운로드 실패
# 미러 사용
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download KwaiVGI/LivePortrait --local-dir pretrained_weights
# 수동 다운로드: 공식 페이지에서 직접 받아 pretrained_weights 폴더에 압축 해제
CUDA 오류
# 설치된 CUDA 버전 확인
nvcc -V
python -c "import torch; print(torch.version.cuda)"
# PyTorch 재설치 (버전 일치)
pip install torch==2.3.0 torchvision==0.18.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu118
메모리 부족
python inference.py --low_res
python inference.py --low_mem
python inference.py --batch_size 1
macOS 성능 저하
PYTORCH_ENABLE_MPS_FALLBACK=1 python app.py --low_mem
확장 및 커뮤니티 통합
LivePortrait는 FaceFusion 3.0, ComfyUI, Stable Diffusion WebUI 등 여러 프로젝트에서 플러그인 형태로 통합되었습니다. 자세한 설정은 src/config/ 디렉터리의 YAML 파일들을 참고하세요.
속도 벤치마크를 원한다면 아래 스크립트를 실행하십시오.
python speed.py
cat assets/docs/speed.md