LivePortrait双模式全流程部署与推理实践指南

准备阶段：环境评估与适配方案

诊断系统兼容性

在开始部署LivePortrait前，需要先对系统环境进行全面评估。这就像给电脑做"体检"，确保各个部件都能满足软件运行需求。

环境适配决策树

是否满足基础要求?
├── 操作系统
│   ├── Windows 10/11 → 支持人类模式
│   ├── Ubuntu 18.04+ → 支持双模式
│   └── macOS 12+ → 仅支持人类模式
├── Python版本
│   ├── 3.10.x → 推荐
│   └── 其他版本 → 需创建3.10环境
└── 硬件配置
    ├── GPU (推荐)
    │   ├── NVIDIA CUDA 11.1+ → 最佳选择
    │   └── Apple M系列 → macOS兼容方案
    └── CPU → 兼容性模式(性能有限)

系统要求详情

组件	最低要求	推荐配置	重要性
操作系统	Windows 10/11, Ubuntu 18.04+, macOS 12+	Ubuntu 20.04+	⭐⭐⭐
Python	3.10.x	3.10.9	⭐⭐⭐
CUDA (GPU)	11.1+	11.8	⭐⭐
内存	8GB RAM	16GB+ RAM	⭐⭐
显存	4GB VRAM	8GB+ VRAM	⭐⭐⭐
存储空间	10GB可用空间	20GB+可用空间	⭐

安装基础依赖

基础版安装路径（适合新手）

# Ubuntu/Debian系统工具安装
sudo apt update
sudo apt install -y git wget curl build-essential ffmpeg libsox-dev

# 安装Miniconda环境管理工具
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3
export PATH="$HOME/miniconda3/bin:$PATH"
conda init bash

# 创建并激活虚拟环境
conda create -n LivePortrait python=3.10 -y
conda activate LivePortrait

# 克隆项目代码
git clone https://gitcode.com/GitHub_Trending/li/LivePortrait
cd LivePortrait

# 安装基础依赖
pip install -r requirements_base.txt
pip install -r requirements.txt

进阶版安装路径（适合开发者）

# 创建隔离环境（推荐使用mamba加速）
conda install mamba -n base -c conda-forge
mamba create -n LivePortrait python=3.10 -y
conda activate LivePortrait

# 根据CUDA版本安装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 -r requirements.txt

# 安装开发工具
pip install black flake8 isort pre-commit
pre-commit install

⚠️ 风险提示：PyTorch版本必须与CUDA版本匹配，否则会导致GPU无法使用。可以使用nvcc -V命令检查CUDA版本。

macOS特殊配置

# 使用专门的macOS依赖文件
pip install -r requirements_macOS.txt

# 设置环境变量以启用MPS后端
export PYTORCH_ENABLE_MPS_FALLBACK=1

预训练模型部署

模型文件就像应用程序的"大脑"，包含了训练好的人工智能参数。

模型下载方法

# 安装huggingface_hub工具
pip install -U "huggingface_hub[cli]"

# 国内用户建议使用镜像
export HF_ENDPOINT=https://hf-mirror.com

# 下载预训练权重
huggingface-cli download KwaiVGI/LivePortrait \
    --local-dir pretrained_weights \
    --exclude "*.git*" "README.md" "docs"

模型目录结构

成功下载后，pretrained_weights目录应包含以下结构：

pretrained_weights/
├── insightface/           # 人脸检测模型
├── liveportrait/          # 人类模式核心模型
│   ├── base_models/       # 基础模型组件
│   └── retargeting_models/ # 重定向模型
└── liveportrait_animals/  # 动物模式模型
    ├── base_models/
    └── retargeting_models/

🛠️ 替代方案：如果无法通过命令行下载，可以手动从项目文档提供的百度网盘链接下载模型文件，并按照上述结构放置。

核心阶段：双模式部署与推理实践

人类模式部署

人类模式是LivePortrait的核心功能，专注于人像动画生成。

启动Gradio界面

# 启动人类模式Gradio界面
python app.py

启动成功后，会在浏览器中打开如下界面：

该界面主要包含三个区域：

• 源图像/视频上传区：左侧上传需要动画化的肖像
• 驱动视频上传区：右侧上传控制动画的驱动视频
• 参数调整区：中间下方可调整动画参数

命令行推理示例

# 使用默认示例进行快速测试
python inference.py

# 指定源图像和驱动视频
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d0.mp4

# 使用动作模板文件（.pkl格式）- 推荐用于快速推理
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d5.pkl

🔧 技巧：.pkl格式的动作模板是预先处理好的动作特征，比直接使用视频作为驱动源速度更快，内存占用更低。

关键参数配置

参数	类型	默认值	说明
flag_stitching	bool	True	是否启用缝合功能，小幅度头部运动时推荐启用
driving_option	str	"expression-friendly"	驱动选项："expression-friendly"（表情优先）或"pose-friendly"（姿态优先）
driving_multiplier	float	1.0	运动强度乘数，值越大动作越夸张
animation_region	str	"all"	动画区域："exp"（表情）、"pose"（姿态）、"lip"（嘴唇）、"eyes"（眼睛）、"all"（全部）

动物模式部署

动物模式是LivePortrait的特色功能，专门针对猫、狗等宠物设计。

环境准备

动物模式需要额外安装X-Pose依赖：

# 进入X-Pose操作目录
cd src/utils/dependencies/XPose/models/UniPose/ops

# 编译并安装MultiScaleDeformableAttention操作
python setup.py build install

# 返回项目根目录
cd ../../../../../../..

⚠️ 注意：动物模式目前不支持macOS系统，且X-Pose仅允许非商业科学研究使用。

启动动物模式界面

# 启动动物模式Gradio界面
python app_animals.py

动物模式界面专为宠物图像设计，提供了适合动物特征的参数调整选项：

动物模式推理命令

# 动物模式推理示例
python inference_animals.py -s assets/examples/source/s39.jpg -d assets/examples/driving/wink.pkl --no_flag_stitching --driving_multiplier 1.75

🔧 最佳实践：动物模式建议禁用缝合功能（--no_flag_stitching）并使用较高的运动强度（1.5-2.0）以获得更明显的动画效果。

双模式技术对比

特性	人类模式	动物模式
关键点检测	InsightFace	X-Pose
训练数据	人类面部数据	23万帧动物数据
缝合支持	完全支持	不支持
重定向支持	完全支持	不支持
平台兼容性	Linux, Windows, macOS	Linux, Windows
推荐运动强度	1.0-1.2	1.5-2.0

拓展阶段：问题诊断与效能调优

常见问题诊断

硬件相关问题

问题	根本原因	解决方案
CUDA error: out of memory	GPU显存不足	1. 降低输入图像分辨率 2. 启用半精度推理 3. 关闭其他占用GPU的程序
MPS backend out of memory	Mac显存不足	1. 使用--flag_force_cpu强制CPU模式 2. 减小source_max_dim参数
推理速度过慢	计算资源不足	1. 检查是否使用了GPU 2. 生成.pkl动作模板后再推理 3. 启用torch.compile（Linux）

软件配置问题

问题	根本原因	解决方案
No face detected	面部检测失败	1. 使用更清晰的正面照片 2. 降低检测阈值--det_thresh 0.3 3. 手动裁剪面部区域
FFmpeg not found	视频处理工具缺失	1. 安装ffmpeg：sudo apt install ffmpeg 2. Windows用户需将ffmpeg添加到PATH
ModuleNotFoundError	依赖未正确安装	1. 重新安装依赖：pip install -r requirements.txt 2. 检查是否激活了正确的conda环境

性能优化策略

推理速度优化

# 启用半精度推理（减少显存使用并加速）
python inference.py --flag_use_half_precision True

# 使用torch.compile加速（仅Linux支持）
python app.py --flag_do_torch_compile

# 生成动作模板用于后续快速推理
python inference.py -s source.jpg -d driving_video.mp4
# 生成的.pkl文件可用于快速推理
python inference.py -s source.jpg -d driving_video.pkl

各模块性能基准（RTX 4090）

模块	参数量(M)	推理时间(ms)	优化建议
外观特征提取器	0.84	0.82	默认配置即可
运动提取器	28.12	0.84	默认配置即可
SPADE生成器	55.37	7.59	可启用半精度
变形网络	45.53	5.21	可启用半精度
缝合重定向模块	0.23	0.31	默认配置即可

内存优化配置

在src/config/inference_config.py中调整以下参数：

# 降低源图像最大尺寸（默认1280）
source_max_dim: int = 1024

# 启用半精度计算
flag_use_half_precision: bool = True

# 调整批量处理大小（默认1）
batch_size: int = 2  # 根据GPU内存调整

高级应用技巧

肖像编辑与重定向

LivePortrait提供了强大的肖像编辑功能，可以通过调整参数改变面部表情和姿态：

使用方法：

# 启动编辑模式
python app.py --enable_editor

在编辑界面中，可以调整以下参数：

• 面部运动滑块：控制头部姿态和位置
• 面部表情滑块：调整微笑、皱眉、眨眼等表情
• 眼睛开合度和嘴唇开合度：精确控制面部特征

图像驱动动画

除了视频驱动，LivePortrait还支持使用单张图像作为驱动源，将一个人的表情迁移到另一个人脸上：

使用命令：

# 图像驱动图像动画
python inference.py -s assets/examples/source/s0.jpg -d assets/examples/driving/d12.jpg --driving_image

📊 效果对比：视频驱动适合复杂动作，图像驱动适合特定表情迁移，动作模板适合快速重复生成相同动作。

实用工具推荐

1. 环境检测脚本：检查系统是否满足LivePortrait运行要求，自动识别潜在问题
2. 性能监控工具：实时监控GPU/CPU使用率、内存占用和推理速度
3. 问题诊断手册：详细的错误代码解释和解决方案

这些工具可以帮助用户快速定位和解决问题，优化LivePortrait的运行效果。

通过本指南，您应该能够顺利部署LivePortrait的双模式系统，并掌握基本的推理和优化技巧。无论是创建生动的人像动画还是为宠物照片添加趣味动作，LivePortrait都能提供强大的技术支持。随着使用的深入，您可以进一步探索高级参数调整和自定义模型训练，以获得更符合需求的动画效果。