如何跑通 SadTalker：音频驱动面部动画的完整部署与配置指南

如何跑通 SadTalker：音频驱动面部动画的完整部署与配置指南

【免费下载链接】SadTalker[CVPR 2023] SadTalker：Learning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalker

SadTalker 是一个音频驱动面部动画模型：给它一张人脸照片加一段音频，它就能生成口型、表情和头部动作都自然的说话视频。这份指南按你实际操作顺序展开：先自检硬件，再搭干净环境，把模型文件落到正确位置，最后二选一（GPU/CPU）跑出第一段视频，常用报错做成速查问答。

动手前先检查你的硬件

低于这条线会怎样：没有 NVIDIA 显卡能跑但一段音频要等几分钟；4GB 显存开 512 分辨率加增强会紧张（可降回 256）；内存不足 8GB 时进程可能被系统直接杀掉。

从零搭一个干净环境

先拿到代码：

git clone https://gitcode.com/GitHub_Trending/sa/SadTalker # 拉取项目代码 cd SadTalker

Linux / macOS（依赖 conda，没有就先装 Anaconda）：

conda create -n sadtalker python=3.8 # 创建 3.8 隔离环境，避免污染其他项目 conda activate sadtalker # 激活环境 pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 torchaudio==0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113 # 先装 PyTorch：wheel 需按 CUDA 版本挑选，requirements.txt 里故意不含 torch conda install ffmpeg # 安装系统级视频处理工具，SadTalker 输出视频靠它 pip install -r requirements.txt # 一次装齐其余依赖：face_alignment、librosa、gfpgan、gradio 等

Windows（PowerShell，用虚拟环境即可）：

python -m venv .venv :: 创建隔离环境（需先装 Python 3.8，勾选 Add to PATH） .venv\Scripts\activate :: 激活环境 pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 torchaudio==0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113 pip install -r requirements.txt scoop install ffmpeg :: 一条命令装 ffmpeg（也可下官方二进制包后手动加入 PATH）

装完顺手验证一句：python -c "import torch; print(torch.__version__, torch.cuda.is_available())"，有显卡且驱动正常时第二个值应为True。

把模型文件一次放到该在的位置

代码和模型是分离的，环境装好后模型还没落地。Linux / macOS 用户直接跑仓库自带的脚本：

bash scripts/download_models.sh # 自动创建 checkpoints/ 和 gfpgan/weights/，下全部模型

Windows 用户不用跑这个 bash 脚本：从项目 Releases 页面找到模型下载源（README 里列了 Google Drive / GitHub Releases / 百度云盘），或找一台能跑脚本的机器下完后，把checkpoints/和gfpgan/两个目录整体拷到 Windows 项目的同一层目录。

放完之后长这样（用ls -lh checkpoints gfpgan/weights核对）：

checkpoints/ ├── SadTalker_V0.0.2_256.safetensors # 256 分辨率面部渲染模型（打包版） ├── SadTalker_V0.0.2_512.safetensors # 512 分辨率面部渲染模型 ├── mapping_00229-model.pth.tar # 映射网络，默认 crop 模式用 └── mapping_00109-model.pth.tar # 映射网络，全身 full 模式用 gfpgan/weights/ ├── GFPGANv1.4.pth # 人脸增强权重 ├── alignment_WFLW_4HG.pth ├── detection_Resnet50_Final.pth └── parsing_parsenet.pth

两条选择规则（逻辑写在 src/utils/init_path.py）：

• checkpoints/里只要存在.safetensors文件，程序就走新版打包模型，实际加载哪个由--size 256/512决定；
• --preprocess full用mapping_00109，其余模式用mapping_00229——四个文件都下全，别挑着要。

完整性一眼过：两个.safetensors应为 1GB 量级，两个mapping约几百 MB 量级，且没有 0 字节文件。有缺就重跑一次脚本，wget -nc支持断点续传，不会重复下已完整的文件。

按硬件二选一，生成第一段视频 🎬

仓库自带示例音频和示例人像，不传任何参数也能直接出片：

python inference.py # 默认吃内置示例素材，结果输出到 results/<时间戳>.mp4

换成自己的素材，比如这张仓库示例人像：

python inference.py --driven_audio examples/driven_audio/chinese_news.wav \ --source_image examples/source_image/art_5.png \ --enhancer gfpgan # 叠加 gfpgan 人脸增强，脸部更清晰

按回车之后发生的事：

路线 A · GPU（推荐）：inference.py默认自动检测 CUDA，有卡就直接走 GPU，1 分钟音频一般是几十秒量级。默认--size 256、--batch_size 2即可；8GB 以上显存可提到--size 512 --batch_size 4。

路线 B · CPU：先换装 CPU 版 PyTorch，再跑命令时加--cpu：

pip install torch==1.12.1+cpu torchvision==0.13.1+cpu torchaudio==0.12.1 --extra-index-url https://download.pytorch.org/whl/cpu python inference.py --cpu --batch_size 1 --size 256 --driven_audio <音频> --source_image <图片>

CPU 是分钟级速度，--enhancer增强同样很慢，首跑建议先关掉，音频也别超过 1 分钟。

报错自救：原文 → 原因 → 一条命令

• ffmpeg is not recognized as an internal or external command原因：ffmpeg 没装或不在 PATH。 解决：Linuxconda install ffmpeg，macOSbrew install ffmpeg，Windowsscoop install ffmpeg并确认bin目录在%PATH%里。

• FileNotFoundError: ... checkpoints\BFM_Fitting\similarity_Lm3D_all.mat原因：模型没下全，或目录放错位置。 解决：在项目根目录跑bash scripts/download_models.sh，确认checkpoints/与inference.py同级。

• RuntimeError: unexpected EOF, expected ... more bytes. The file might be corrupted.原因：某个模型文件下载中断、内容不完整。 解决：重跑下载脚本断点续传；仍报就删掉该文件重新下载。

• ModuleNotFoundError: No module named 'ai'原因：旧版epoch_20.pth检查点文件损坏。 解决：重新下载 checkpoints 目录，并核对文件大小。

• RuntimeError: CUDA out of memory原因：显存不够，常见于 512 分辨率 + 增强 + 大 batch 组合。 解决：设置环境变量PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128（Linux/macOS 用export，Windows 用set），同时把参数降为--batch_size 1 --size 256。

• Error while decoding stream #0:0: Invalid data found when processing input原因：音频格式不支持，只收 wav / mp3。 解决：ffmpeg -i 原始文件 -ar 16000 -ac 1 out.wav先转码。

• Illegal Hardware（Apple Silicon）原因：dlib 架构不匹配。 解决：pip uninstall dlib后pip install dlib重装。

更多情况可翻仓库自带的 FAQ。

跑通之后往哪走

下一步试全身动画：加--preprocess full --still --enhancer gfpgan；参数含义、ref 模式、自由视角等玩法都在 最佳实践文档 里，想要鼠标操作就跑bash webui.sh打开 WebUI。

【免费下载链接】SadTalker[CVPR 2023] SadTalker：Learning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalker