LivePortrait实战指南：从入门到精通的完整路径

2026-04-04 09:16:30作者：范靓好Udolf

LivePortrait是一款强大的肖像动画生成工具，能够将静态肖像图片转换为生动的动态视频。本指南将带你完成从环境搭建到高级应用的全过程，掌握人像与动物肖像动画的制作技巧，解决常见技术问题，让你的静态肖像焕发活力。

一、开发环境搭建

环境准备是使用LivePortrait的第一步，本章节将详细介绍如何配置满足要求的系统环境，安装必要依赖，并验证安装结果，为后续使用打下坚实基础。

1.1 系统环境要求

LivePortrait对系统环境有一定要求，确保你的设备满足以下条件：

操作系统：Windows 10/11, Ubuntu 18.04+, macOS 12+
Python：3.10.x（推荐3.10.9）
CUDA：11.1+（CUDA：NVIDIA提供的GPU加速计算平台）
内存：8GB RAM（推荐16GB+）
显存：4GB VRAM（推荐8GB+）
存储空间：10GB可用空间（推荐20GB+）

1.2 基础依赖安装

准备工作

确保系统已安装必要的基础工具和依赖库。

执行命令

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

# macOS系统
brew install git wget curl ffmpeg

# Windows系统
# 下载并安装Git for Windows：https://git-scm.com/download/win
# 下载ffmpeg.exe和ffprobe.exe并添加到系统PATH

验证结果

# 验证Git安装
git --version

# 验证FFmpeg安装
ffmpeg -version

1.3 Python环境配置

准备工作

使用Miniconda创建独立的Python环境，避免依赖冲突。

执行命令

# 下载并安装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

验证结果

# 验证Python版本
python --version  # 应显示Python 3.10.x

# 验证conda环境
conda info --envs  # 应显示LivePortrait环境且带*号

1.4 项目代码与依赖安装

准备工作

克隆项目代码并安装Python依赖包。

执行命令

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

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

# 安装GPU相关依赖
pip install -r requirements.txt

验证结果

# 验证主要依赖
python -c "
import numpy as np
import cv2
import torch
import gradio
print('所有主要依赖安装成功！')
"

1.5 预训练模型下载

准备工作

下载必要的预训练模型权重文件。

执行命令

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

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

提示：如果无法访问HuggingFace，可设置镜像：export HF_ENDPOINT=https://hf-mirror.com

验证结果

# 检查模型文件是否下载成功
ls -l pretrained_weights/liveportrait/base_models/
# 应看到appearance_feature_extractor.pth等文件

📝 要点总结

确保系统满足最低配置要求，推荐使用Ubuntu系统获得最佳性能
必须安装FFmpeg，否则无法处理视频文件
使用独立的conda环境可以避免依赖冲突
预训练模型较大，请确保网络稳定且有足够存储空间
国内用户建议使用HF镜像加速模型下载

二、核心功能解析

LivePortrait提供了强大的肖像动画生成能力，主要包括人类模式和动物模式两种核心功能。本章节将详细介绍这两种模式的特点、使用方法和技术原理，帮助你理解并掌握其核心功能。

2.1 人类模式动画生成

人类模式是LivePortrait的核心功能，专注于人像动画生成，支持图像到视频和视频到视频的转换，通过先进的面部关键点检测和运动迁移技术，使静态肖像图片动起来。

技术原理

人类模式基于InsightFace进行人脸检测和关键点识别，通过外观特征提取器提取源图像特征，运动提取器分析驱动视频的运动信息，再通过变形网络和SPADE生成器生成最终的动画效果。

基本使用方法

准备工作

确保已完成环境搭建和模型下载，准备好源图像和驱动视频。

执行命令

# 使用默认示例进行快速测试
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

关键参数说明

-s/--source：源图像或视频路径
-d/--driving：驱动视频或动作模板路径
--flag_stitching：是否启用缝合功能（默认True）
--driving_multiplier：运动强度乘数（默认1.0）
--animation_region：动画区域，可选"exp", "pose", "lip", "eyes", "all"（默认"all"）

Gradio界面使用

LivePortrait提供了直观的Gradio界面，方便用户进行交互操作：

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

启动后，在浏览器中访问显示的URL，即可看到如下界面：

界面主要分为三个步骤：上传源图像/视频、上传驱动视频、点击"Animate"按钮生成动画。

2.2 动物模式动画生成

动物模式是LivePortrait的特色功能，专门针对猫、狗等宠物设计，能够为动物肖像图片添加生动的动态效果，让宠物照片"活"起来。

技术原理

动物模式使用X-Pose框架进行动物关键点检测，在约23万帧动物数据上进行了微调，能够捕捉动物面部特征和表情变化，生成自然的动画效果。

环境准备

准备工作

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

执行命令

# 安装X-Pose依赖
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 --no_flag_stitching --driving_multiplier 1.75

关键参数说明

--no_flag_stitching：动物模式推荐禁用缝合功能（默认True）
--driving_multiplier：运动强度乘数，动物模式建议使用1.75-2.0

Gradio界面使用

动物模式同样提供Gradio界面：

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

启动后，界面如下所示：

2.3 图像驱动动画

LivePortrait支持使用图像作为驱动信号，将一张图像的表情迁移到另一张图像上，实现静态图像间的表情转换。

使用方法

准备工作

准备源图像和驱动图像。

执行命令

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

功能特点

支持单张图像驱动，无需视频
可精确控制表情迁移效果
适用于艺术创作和表情编辑

2.4 视频重定向

视频重定向功能允许用户调整视频中人物的表情和动作，例如修改嘴唇张开程度、调整运动平滑度等，实现对视频内容的精细控制。

使用方法

准备工作

准备源视频和目标参数。

执行命令

# 启动视频重定向界面
python app.py --retargeting

在界面中上传源视频，调整参数，点击"Retargeting Video"按钮生成结果：

关键参数说明

target lip-open ratio：目标嘴唇张开比例
motion smooth strength：运动平滑强度
crop scale：裁剪比例

📝 要点总结

人类模式适用于人像动画，动物模式专门针对宠物设计
动作模板文件(.pkl)可以显著提高推理速度
图像驱动功能支持静态图像间的表情迁移
视频重定向功能可精细调整视频中的表情和动作
动物模式需要额外安装X-Pose依赖，且不支持macOS系统

三、实践案例教程

理论学习之后，实践是掌握LivePortrait的关键。本章节提供多个实用案例，从简单到复杂，帮助你逐步掌握各种功能的使用方法，实现不同场景下的肖像动画效果。

3.1 如何创建人类表情动画

本案例将展示如何使用预设的动作模板为静态人像图片添加各种表情动画，如微笑、眨眼等。

准备工作

准备一张正面人像照片（建议分辨率512x512以上）
确保已完成环境搭建和模型下载

执行步骤

微笑表情动画

python inference.py -s input_portrait.jpg -d assets/examples/driving/laugh.pkl --driving_multiplier 1.2

眨眼动画

python inference.py -s input_portrait.jpg -d assets/examples/driving/wink.pkl --animation_region eyes

惊讶表情动画

python inference.py -s input_portrait.jpg -d assets/examples/driving/d12.pkl --driving_multiplier 1.5

关键参数调整

--driving_multiplier：调整运动强度，值越大表情越夸张
--animation_region：指定动画区域，如"eyes"仅动画眼睛区域

预期结果

生成的视频文件将保存在results目录下，显示人像做出相应的表情动作。

3.2 如何制作动物头部运动动画

本案例将展示如何为宠物照片添加头部转动、表情变化等动画效果，让宠物照片栩栩如生。

准备工作

准备一张清晰的宠物照片（猫或狗效果最佳）
确保已安装动物模式所需的额外依赖

执行步骤

猫咪头部转动动画

python inference_animals.py -s cat_photo.jpg -d assets/examples/driving/d0.mp4 --no_flag_stitching --driving_multiplier 2.0

狗狗表情变化动画

python inference_animals.py -s dog_photo.jpg -d assets/examples/driving/aggrieved.pkl --no_flag_stitching --driving_multiplier 1.8

关键参数调整

--driving_multiplier：动物模式建议使用1.75-2.0，使动作更明显
--no_flag_stitching：动物模式必须禁用缝合功能

注意事项

提示：动物模式目前主要针对猫和狗优化，其他动物效果可能有限。

3.3 如何进行视频到视频转换

本案例将展示如何将一个视频中的表情和动作迁移到另一个视频上，实现面部动作的迁移和编辑。

准备工作

准备源视频和驱动视频（建议时长5-10秒）
确保系统性能足够（推荐GPU显存8GB以上）

执行步骤

视频重定向基础转换

python inference.py -s source_video.mp4 -d driving_video.mp4 --flag_crop_driving_video

生成动作模板用于快速推理

python inference.py -s source_image.jpg -d driving_video.mp4
# 生成的.pkl文件可用于后续快速推理
python inference.py -s new_source.jpg -d driving_video.pkl

高级参数调整

# 调整裁剪比例和运动平滑度
python inference.py -s source.mp4 -d driving.mp4 --source_crop_scale 2.2 --motion_smooth_strength 0.00003

预期结果

生成的视频将保留源视频的人物特征，同时模仿驱动视频的表情和动作。

3.4 如何使用Gradio界面进行交互式编辑

Gradio界面提供了直观的可视化操作方式，适合快速尝试不同参数和效果，无需编写命令行。

准备工作

确保已安装gradio依赖（包含在requirements.txt中）
准备源图像/视频和驱动视频/图像

执行步骤

启动Gradio界面

# 人类模式
python app.py

# 动物模式
python app_animals.py

使用界面生成动画
- 上传源图像/视频
- 上传驱动视频或选择示例
- 调整参数（裁剪比例、运动强度等）
- 点击"Animate"按钮生成动画
保存结果
- 点击生成结果下方的"Download"按钮保存视频
- 可调整参数后重新生成，比较不同效果

界面功能介绍

源文件区域：上传或选择源图像/视频
驱动文件区域：上传或选择驱动视频/图像
裁剪选项：调整源文件和驱动文件的裁剪比例和位置
动画选项：设置运动强度、动画区域等参数
结果区域：显示生成的动画结果

📝 要点总结

动作模板文件(.pkl)可以显著提高后续推理速度
适当调整driving_multiplier参数可以获得更自然或更夸张的效果
视频到视频转换对硬件要求较高，建议先使用短视频测试
Gradio界面适合快速尝试不同参数和效果
生成的结果文件默认保存在results目录下

四、常见问题解决

在使用LivePortrait的过程中，可能会遇到各种技术问题。本章节汇总了常见问题的现象、原因和解决方案，帮助你快速排查并解决问题，确保项目顺利运行。

4.1 环境配置问题

CUDA版本不匹配

问题现象：运行时出现CUDA error: no kernel image is available for execution错误，或模型无法加载到GPU。

解决方法：

检查当前CUDA版本：
```
nvcc -V
```

根据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

# CUDA 12.1
pip install torch==2.3.0 torchvision==0.18.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu121

FFmpeg缺失

问题现象：出现ImportError: FFmpeg is not installed错误，或无法生成输出视频。

解决方法：

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
# 下载ffmpeg.exe和ffprobe.exe，放置在项目根目录或添加到系统PATH

4.2 模型加载问题

模型文件缺失

问题现象：出现FileNotFoundError，提示找不到模型文件。

解决方法：

检查pretrained_weights目录是否存在：
```
ls -l pretrained_weights/
```

重新下载模型：

huggingface-cli download KwaiVGI/LivePortrait --local-dir pretrained_weights --exclude "*.git*" "README.md" "docs"

检查文件权限：
```
chmod -R 755 pretrained_weights/
```

模型版本不匹配

问题现象：出现Unexpected key(s) in state_dict错误，模型加载失败。

解决方法：

确保代码和模型版本匹配：

git pull  # 更新代码到最新版本

删除旧模型并重新下载：

rm -rf pretrained_weights/
huggingface-cli download KwaiVGI/LivePortrait --local-dir pretrained_weights

4.3 推理运行问题

内存不足

问题现象：出现CUDA out of memory错误，或程序意外终止。

解决方法：

降低输入图像分辨率：

python inference.py -s source.jpg -d driving.mp4 --source_max_dim 1024

启用半精度推理：

python inference.py --flag_use_half_precision True

使用CPU模式（速度较慢）：
```
python inference.py --flag_force_cpu
```

面部检测失败

问题现象：出现No face detected警告，或输出结果异常。

解决方法：

使用清晰的正面照片作为输入
降低检测阈值：
```
python inference.py --det_thresh 0.3
```

手动裁剪面部区域：

python inference.py --source_crop_scale 2.0 --source_crop_x 0 --source_crop_y 0

输出视频有黑块

问题现象：生成的视频中出现黑色块状区域。

解决方法：

禁用半精度推理：

python inference.py --flag_use_half_precision False

更新PyTorch版本：

pip install --upgrade torch torchvision

4.4 动物模式特有问题

X-Pose安装失败

问题现象：动物模式运行时出现ModuleNotFoundError: No module named 'MultiScaleDeformableAttention'。

解决方法：

重新安装X-Pose依赖：

cd src/utils/dependencies/XPose/models/UniPose/ops
python setup.py clean
python setup.py build install
cd -

检查是否安装了正确的CUDA版本和编译器

动物关键点检测失败

问题现象：动物模式运行时没有检测到动物面部关键点。

解决方法：

使用清晰的动物面部照片，确保面部特征可见
调整裁剪参数，确保动物面部位于图像中央

尝试使用示例图像验证：

python inference_animals.py -s assets/examples/source/s39.jpg -d assets/examples/driving/wink.pkl

📝 要点总结

CUDA版本不匹配是最常见问题，需确保PyTorch版本与CUDA兼容
模型文件缺失或损坏时需重新下载
内存不足时可通过降低分辨率或启用半精度推理解决
面部检测失败通常与输入图像质量有关，建议使用清晰正面照片
动物模式需要额外安装X-Pose依赖，且不支持macOS系统

附录：性能优化技巧

为了获得更好的使用体验，这里提供一些实用的性能优化技巧，帮助你在不同硬件条件下提高LivePortrait的运行速度和效率。

A.1 推理速度优化

使用动作模板文件

# 首先生成模板
python inference.py -s source.jpg -d driving_video.mp4
# 后续使用模板快速推理
python inference.py -s new_source.jpg -d driving_video.pkl

启用torch.compile加速（仅限Linux系统）
```
python app.py --flag_do_torch_compile
```

调整批量处理大小

python inference.py --batch_size 4  # 根据GPU内存调整

A.2 内存使用优化

降低输入分辨率

python inference.py --source_max_dim 1024

启用半精度推理

python inference.py --flag_use_half_precision True

及时释放内存 在代码中添加：

import torch
torch.cuda.empty_cache()  # 在关键步骤后添加

A.3 平台特定优化

Windows系统

set CUDA_VISIBLE_DEVICES=0
set PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

macOS系统

export PYTORCH_ENABLE_MPS_FALLBACK=1
export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.8

Linux系统

export PYTORCH_CUDA_ALLOC_CONF=backend:cudaMallocAsync

A.4 质量与速度平衡

优化级别	配置方法	速度提升	质量影响
高质量模式	默认配置	基准速度	最佳质量
平衡模式	--flag_use_half_precision True	+30%	轻微下降
快速模式	--source_max_dim 768 --flag_use_half_precision True	+60%	明显下降
极速模式	--source_max_dim 512 --flag_use_half_precision True --batch_size 8	+100%	显著下降