LivePortrait 快速上手指南：3 条命令免费本地，让静态照片开口说话-平芜编程栈

LivePortrait 快速上手指南：3 条命令免费本地，让静态照片开口说话

【免费下载链接】LivePortraitBring portraits to life!项目地址: https://gitcode.com/GitHub_Trending/li/LivePortrait

相册里的照片只能看，动不起来？LivePortrait 能解决：给一段视频当驱动，照片里的人就会眨眼、微笑、转头，全程本地完成。这篇指南面向零基础新手，带你装环境、跑出第一个动画、避开常见坑。

一分钟看懂：它是干什么的

LivePortrait 是一款开源人像动画工具，出自论文LivePortrait: Efficient Portrait Animation with Stitching and Retargeting Control的官方 PyTorch 实现。它的流程很直白：你提供一份"源"（静态人像，或一段人像视频）和一个"驱动"（真人视频、单张表情图，或预先提取的.pkl动作文件），它就输出一段动画——源人像的表情、眼神、头部动作跟着驱动走，最后自动贴回原始画面。

它适合三类人：想把旧照片做成动态图发内容的创作者；需要"表情包"素材的剪辑党；以及不想把人脸上传到在线服务、希望隐私留在本地的用户。

三个核心能力：

驱动方式灵活：视频、单张图片、.pkl动作模板都能驱动，.pkl跳过逐帧人脸检测、推理更快；
人像视频编辑：源素材本身可以是视频，用驱动"重演"原片表情，即 v2v 编辑；
精细重定向（Retargeting）：滑块直控眼睛开合、嘴唇、微笑、眉毛、眼神和头部俯仰/偏航/翻滚，即时预览。

准备工作：需要什么才能跑

显卡：NVIDIA 显卡效果最好（4090 级别可接近实时，中端卡也能用）；Apple Silicon 的 Mac 支持人类模式；完全没有 GPU 可加--flag_force_cpu跑纯 CPU，但非常慢（实验性功能）。
系统：Linux / Windows / macOS（Apple Silicon）；动物模式（猫狗照片）仅支持 Linux 或 Windows 配 NVIDIA 卡。
软件：git、conda、FFmpeg。脚本依赖 ffmpeg/ffprobe 做视频编码与拼接，属于必装项。
磁盘：预训练权重大小约几个 GB，预留足够空间。
Python：建议用 conda 建独立 3.10 环境，避免污染其他项目。

第一次跑通：从克隆到出片

1. 克隆代码

git clone https://gitcode.com/GitHub_Trending/li/LivePortrait cd LivePortrait

拿到完整项目代码；成功信号：当前目录下出现 LivePortrait 文件夹，内含inference.py、app.py、assets/等。

2. 创建并激活环境

conda create -n LivePortrait python=3.10 conda activate LivePortrait

建一个隔离的 3.10 环境；成功信号：命令行提示符前出现(LivePortrait)。

3. 安装依赖

pip install -r requirements.txt

装全部第三方库；NVIDIA 用户若本机 torch 版本与 CUDA 不匹配，请先到 PyTorch 官网按nvcc -V查到的版本安装对应 torch。成功信号：命令结束且无报错。macOS Apple Silicon 用户改用：

pip install -r requirements_macOS.txt

4. 下载预训练权重

pip install -U "huggingface_hub[cli]" huggingface-cli download KlingTeam/LivePortrait --local-dir pretrained_weights --exclude "*.git*" "README.md" "docs"

把全部模型权重拉到pretrained_weights/目录；成功信号：目录结构与 assets/docs/directory-structure.md 描述一致。下载慢时，先执行export HF_ENDPOINT=https://hf-mirror.com再跑上面命令走镜像。

5. 首跑

python inference.py

用仓库自带示例素材直接推理；成功信号：animations/目录下生成一个*_concat.mp4，内容按"驱动视频、源素材、生成结果"三段拼接，打开即可对比效果。

两个高频参数：-s指定源照片/视频，-d指定驱动（视频或.pkl）；-o可换输出目录。Apple Silicon Mac 用户跑任何脚本都需前置环境变量：PYTORCH_ENABLE_MPS_FALLBACK=1 python inference.py。

核心玩法：三个真实使用场景

场景 1：用网页界面 + 驱动视频出片

怎么做：运行python app.py，启动后浏览器打开http://127.0.0.1:8890。左侧上传源素材（图片或视频），右侧选一段驱动视频，点 Animate 即可。

预期效果：底部出现两段结果——贴回原始图像空间的版本、人脸裁剪空间版本，直接预览哪个更自然。界面内置示例素材，点一下就能试跑，最适合作为第一次体验。

关键参数：-p修改服务端口（默认 8890）；想提速可开--flag_do_torch_compile，见下方速查表。

场景 2：没有视频，用一张表情图驱动

怎么做：在app.py界面把右侧 Driving Video 切换为图片模式，挑一张表情清晰、尽量正面的照片，点 Animate。

预期效果：源人像会模仿这张图的单个表情与眼神生成动画，适合"借"一个特定神态。下图从左到右依次是驱动图、源图、生成结果。

关键参数（Animation Options 面板）：

driving multiplier：驱动强度，越大表情变化越明显；
driving option：expression-friendly偏表情还原，pose-friendly偏头部姿态，按素材二选一。

场景 3：没有驱动素材，滑块直接调表情

怎么做：在app.py的重定向区域上传一张源人像，拖动眼睛开合、嘴唇开合、微笑、眨眼、眉毛、眼神以及头部 pitch/yaw/roll 滑块，结果即时刷新，可反复多跑几轮。

预期效果：界面同时给出"重定向结果"与"贴回结果"，直接看到合成进原图后的效果。做"点头、摇头、微笑"这类静态图微动效，这是最顺手的入口。

关键参数：target eyes-open ratio与target lip-open ratio（0 为闭合、1 为全开）；relative pitch / yaw / roll控制头部三个方向的转动。

排查速查表

现象	可能原因	解决办法
输出视频出现黑框	半精度（FP16）推理与显卡不兼容	将`--flag_use_half_precision`设为`False`
用自己的驱动视频，人脸发虚、裁切偏移	驱动不符合建议格式（非 1:1、肩部运动大、首帧非中性表情）	手动裁成 1:1、聚焦头部、首帧中性正面；或加`--flag_crop_driving_video`自动裁剪，再用`--scale_crop_driving_video`、`--vy_ratio_crop_driving_video`微调
表情幅度不够 / 动作太夸张	默认驱动强度不适合当前素材	调`--driving_multiplier`；在`--driving_option`的 expression-friendly 与 pose-friendly 间切换
推理速度慢	未启用编译加速，或硬件偏弱	Linux 下`python app.py --flag_do_torch_compile`（预热约 1 分钟，后续提速 20%～30%；Windows/macOS 不支持）
启动时报 FFmpeg 缺失	未安装 ffmpeg / ffprobe	先装好 FFmpeg，参考 assets/docs/how-to-install-ffmpeg.md

新手必问

没有 NVIDIA 显卡能跑吗？能。命令行支持--flag_force_cpu（实验性），纯 CPU 推理偏慢；Apple Silicon Mac 可正常跑人类模式（前置PYTORCH_ENABLE_MPS_FALLBACK=1），速度约为 RTX 4090 的 1/20，且不支持动物模式。

.pkl动作模板是什么？从驱动视频预先提取好的"动作文件"，如wink.pkl、laugh.pkl。用它驱动可跳过逐帧人脸检测，速度更快；同时你无需把驱动者的原始视频交给别人，对隐私更友好。

生成的内容能商用吗？项目开源并附带 LICENSE。但作者明确提醒：人像动画存在被滥用制作 deepfake 的风险，请负责任地使用；生成结果本身也带有可识别的视觉伪影。

输出视频有声音吗？有。默认保留驱动侧音轨（audio_priority默认driving），改成source则保留源素材的音频。