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（CVPR 2023）把一张单人像加一段音频，驱动成口型同步的说话人视频。这篇文章带你完整走通本地安装、配置与运行的过程：先判断 GPU 还是 CPU 环境，再装依赖和 FFmpeg，把模型文件放进正确目录，跑通第一次推理，最后排查显存不足、模型文件缺失等常见报错。

先判断：你该用哪种部署方式

装任何东西之前，先确认三件事：有没有 NVIDIA GPU、操作系统是什么、是否打算生成高分辨率视频。这决定了 PyTorch 装哪个版本、参数怎么选。

你的情况	推荐做法	备注
有 NVIDIA GPU（≥4GB 显存）	安装 CUDA 11.3 版 PyTorch	可开 GFPGAN 增强，速度最快
无 GPU，想用 CPU 跑	装 CPU 版 PyTorch，运行时加--cpu	生成慢，建议--size 256、--batch_size 1，不开增强
macOS（M1/M2）	pip install torch torchvision torchaudio+ 单独pip install dlib	项目文档在 M1 上验证过
Windows	Python 3.8 + 把 FFmpeg 加入 PATH	可以双击webui.bat直接启动 WebUI

无论哪种环境，FFmpeg 都是必需的——视频写入和音频解码都依赖它。

最短路径：第一次跑通

下面按 Linux/Unix 流程给出最短步骤（Windows、macOS 的差异在 docs/install.md 里有说明）。

1. 克隆仓库，创建独立环境：

git clone https://gitcode.com/GitHub_Trending/sa/SadTalker cd SadTalker conda create -n sadtalker python=3.8 conda activate sadtalker

用 conda 隔离环境是为了避免依赖冲突，Python 版本固定 3.8。

2. 安装与 CUDA 匹配的 PyTorch（CUDA 11.3；没有 GPU 就装 CPU 版）：

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

3. 安装 FFmpeg 和其余依赖：

conda install ffmpeg pip install -r requirements.txt

requirements.txt里已包含face_alignment、librosa、gfpgan、safetensors等固定版本的核心包。TTS只在使用 Gradio 演示的文字转语音时需要，可之后用pip install TTS补装。

4. 下载模型文件（见下一节），然后在仓库根目录直接运行：

bash scripts/download_models.sh python inference.py

inference.py不带参数时会使用仓库内置的示例素材（examples/driven_audio/bus_chinese.wav和examples/source_image/full_body_1.png）。终端打印The generated video is named: ...后，到results/下按时间戳命名的.mp4文件就是输出。跑通这一步，环境就算就绪了。

模型文件应该放在哪里

模型必须下载，代码不会自动生成它们。Linux/macOS 直接执行上一节的bash scripts/download_models.sh即可，脚本会自动建好目录并支持断点续传。下载完成后结构应该是：

目录	文件	作用
checkpoints/	SadTalker_V0.0.2_256.safetensors	256 分辨率面部渲染模型
checkpoints/	SadTalker_V0.0.2_512.safetensors	512 分辨率面部渲染模型
checkpoints/	mapping_00229-model.pth.tar	映射网络，默认crop模式使用
checkpoints/	mapping_00109-model.pth.tar	映射网络，full模式使用
gfpgan/weights/	alignment_WFLW_4HG.pth、detection_Resnet50_Final.pth、GFPGANv1.4.pth、parsing_parsenet.pth	人脸检测与修复模型，--enhancer gfpgan时需要

src/utils/init_path.py里的选择逻辑值得了解：

• checkpoints/下能找到任意*.safetensors时，程序按--size参数自动加载SadTalker_V0.0.2_256.safetensors或SadTalker_V0.0.2_512.safetensors；找不到时会回退到旧版 pth 模型并打印警告，此时需要用旧版检查点并加--old_version。
• --preprocess带full时改用mapping_00109-model.pth.tar，否则用mapping_00229-model.pth.tar。

如果不想联网下载，也可以从项目发布页获取打包好的检查点和 GFPGAN 离线补丁，解压到同样的目录即可。

输入素材方面，仓库examples/下自带了一批可直接试用的素材：

• 音频：examples/driven_audio/下多个.wav文件。程序只支持 wav 或 mp3，其他格式先用 FFmpeg 转一下。
• 图片：examples/source_image/下的人像图。官方最佳实践说明该模型面向写实真人面部，插画风格效果不理想。

GPU 与 CPU：参数怎么选

设备是自动检测的：inference.py里如果torch.cuda.is_available()为真且没加--cpu，就用 CUDA。所以 CPU 用户显式加--cpu就行。参数建议：

参数	GPU 常用值	CPU / 小显存
--size	256，追求质量用 512	固定 256
--batch_size	2（默认）	1
--enhancer	gfpgan	建议不传，增强会额外占显存
设备	无需参数	加--cpu

512 模型是 beta 版，画质更高但显存和时间成本也更高；显存紧张时优先退回 256 而不是硬扛。

验证环境是否真的就绪

跑之前可以用三条命令快速自检：

python -c "import torch; print(torch.__version__, torch.cuda.is_available())" ffmpeg -version ls checkpoints gfpgan/weights

第一条确认 PyTorch 版本以及 CUDA 是否可用（True表示 GPU 会被自动识别）；第二条确认 FFmpeg 在 PATH 中；第三条确认模型文件都下载到位。三条都正常后，跑一次默认的python inference.py，看results/是否产出视频。

常见报错：按错误信息定位

现象	可能原因	处理方式
ffmpeg is not recognized as an internal or external command	FFmpeg 未安装或不在 PATH	Linux：conda install ffmpeg；macOS：brew install ffmpeg；Windows：把 FFmpeg 加入%PATH%
FileNotFoundError ... similarity_Lm3D_all.mat等路径类报错	模型未下载或放错目录	重新执行bash scripts/download_models.sh，对照上一节的目录结构检查
RuntimeError: unexpected EOF ... The file might be corrupted	文件下载中断或损坏	重新下载对应文件，下载脚本支持断点续传
ModuleNotFoundError: No module named 'ai'	旧版模型文件异常（与epoch_20.pth相关）	核对模型文件大小后重新下载
Illegal Hardware Instruction（Mac M1 常见）	dlib 架构不匹配	单独执行pip install dlib重装
RuntimeError: CUDA out of memory	显存不足	见下方小节
Error while decoding stream ... Invalid data found	音频格式不受支持	输入只支持 wav / mp3，用 FFmpeg 先转出.wav
Can't get the coeffs of the input	输入图无法提取人脸系数	换一张清晰、正脸的写实人像

显存不足时怎么调整

先降低--size 256、--batch_size 1，并去掉--enhancer；仍不够时再设置环境变量优化显存分配：

# Linux / macOS export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128 # Windows set PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128

设置后在同一会话里再运行python inference.py ...即可生效。

跑通之后：下一步可以做什么

• 调整动效：--expression_scale调表情幅度（越大越夸张），--pose_style在 0–46 之间切换头部姿态风格，细节见 docs/best_practice.md。
• 选对--preprocess：默认crop只生成裁剪出的说话人脸；resize整图缩放输出（⚠️ 不适合全身图）；full生成后贴回原图，配合--still可保持原姿态、抑制眨眼与头部晃动。
• 参考视频模式：--ref_eyeblink、--ref_pose可以从参考视频借取眨眼和头部姿态，examples/ref_video/下有现成示例。
• 3D 人脸可视化：--face3dvis额外安装后可用，流程见 docs/face3d.md。
• WebUI：python app_sadtalker.py启动 Gradio 界面（需pip install TTS），或 Windows 下双击webui.bat、Linux/macOS 下bash webui.sh。已有 Stable Diffusion WebUI 的话，可看 docs/webui_extension.md 装扩展。
• 遇到本文没覆盖的报错，先查 docs/FAQ.md，再去项目 Issue 区搜索。

【免费下载链接】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