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）做的就是这件事。若你卡在模型下载、依赖报错或显存不足上，这份指南把拉代码、建环境、下模型到跑出第一条说话视频的路径拆清楚，按自己的节奏取用即可。
先想清楚：走哪条路
动手装环境前，先判断自己要哪种结果，能省掉不必要的折腾。三条典型路线各有取舍：
- 快速体验：只想看效果、不折腾本地环境。直接用仓库自带 Gradio 界面或云端 Colab，短时间内就能看到说话视频，适合先验证思路。
- 稳定部署：要长期跑、批量出片。本地 conda 建隔离环境 + 命令行推理，可控、可复现，是大多数人的最终落点。
- 质量调优：追求人脸细节。在稳定部署之上，把渲染分辨率提到 512 并叠加 GFPGAN 人脸增强，画面更锐利，代价是更吃显存。
先定路线，后面的底座与命令才能对号入座。
通用底座
这一节解决"装在哪、装什么"，把前置软件与代码仓库一次性就位。
要做什么：装 Python 3.8、Conda、Git、FFmpeg 四件套，拉下 SadTalker 代码，并建一个隔离虚拟环境，避免依赖互相污染。
git clone https://gitcode.com/GitHub_Trending/sa/SadTalker cd SadTalker conda create -n sadtalker python=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 conda install ffmpeg pip install -r requirements.txt为什么是这个顺序：先建隔离环境再装 PyTorch 与依赖，能防止系统 Python 被污染；FFmpeg 单独用 conda 装，省掉手动配 PATH 的麻烦。
跨平台提示：macOS（含 M 系列芯片）额外执行pip install dlib；Windows 建议把 FFmpeg 加进 PATH，或改用 WSL。细节见 docs/install.md。
三条部署路径，按需取用
底座就位后，按选定路线取对应命令即可，不必全跑。
快速体验（WebUI）
场景：只想点按钮出片。
bash webui.sh # Linux/macOS，Windows 直接双击 webui.bat预期结果：自动建虚拟环境并拉起浏览器界面，上传图片与音频点生成即可。若要走 Gradio 脚本，先pip install TTS再python app_sadtalker.py。
稳定部署（命令行推理）
场景：要批量、可复现地出片。
bash scripts/download_models.sh这条脚本会自动建checkpoints/与gfpgan/weights/两个目录，并拉下全部模型：mapping_00109-model.pth.tar、mapping_00229-model.pth.tar、SadTalker_V0.0.2_256.safetensors、SadTalker_V0.0.2_512.safetensors，以及 GFPGAN 增强用的GFPGANv1.4.pth等。下载完成后，用 inference.py 做命令行推理即可。
质量调优（高分辨率 + 增强）
场景：对人脸细节有要求。
python inference.py --driven_audio <音频.wav> --source_image <图片.png> --size 512 --enhancer gfpgan预期结果：512 分辨率叠加 GFPGAN 修复的人脸，比默认 256 更清晰。
首次运行与验收
这一节解决"怎么算跑通"。先下模型，再跑一条最短的推理命令：
bash scripts/download_models.sh python inference.py \ --driven_audio examples/driven_audio/chinese_news.wav \ --source_image examples/source_image/full_body_1.png \ --result_dir results判断成功看两点：终端最后打印出The generated video is named: ...，且results/下按时间戳生成了.mp4。打开这段视频，人像口型跟随音频变化，就代表环境、模型、依赖全部就位。素材可随意替换，源图与驱动音频都在 examples/ 里。
高频翻车点速查
遇到报错先对下表，多数问题出在模型没下全或依赖缺一项。
| 报错症状 | 可能原因 | 处理办法 |
|---|---|---|
ffmpeg找不到 | FFmpeg 未装或没进 PATH | Linuxconda install ffmpeg；macOSbrew install ffmpeg；Windows 加入 PATH |
No module named 'ai' | 模型文件缺失或损坏 | 重跑bash scripts/download_models.sh，核对checkpoints/内文件大小 |
FileNotFoundError: ...similarity_Lm3D_all.mat | 3DMM 资源目录不全 | 确认 src/config/ 中该文件存在 |
unexpected EOF ... might be corrupted | 增强模型没下全 | 补齐gfpgan/weights/下的四个权重文件 |
CUDA out of memory | 显存碎片化 / 分辨率过高 | 见下方环境变量；必要时降回 256 |
| 音频解码报错 | 输入格式不对 | 只支持wav/mp3，转成其一再传入 |
显存不足时，先设分配策略再启动推理：
# 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 ...更多场景可在 docs/FAQ.md 里继续查。
进阶调优
跑通之后，下面这些开关能让你控制动画的"神韵"，按需叠加。
- 参考视频控姿态：用
--ref_pose传入一段视频借用人物头部动作；--ref_eyeblink单独借眨眼，让眉毛更自然。参考视频见 examples/ref_video/。 - 全身/整图动画：加
--preprocess full --still，把裁切区域贴回原图，减少头部乱晃，适合全身像。 - 表情强度：
--expression_scale调大让表情更夸张，调小更收敛。 - 自由视角：
--input_yaw -20 30 10之类可指定头部偏航角度序列，做 4D 自由视角。
完整参数含义见 docs/best_practice.md。
收尾
到这里，从拉代码、下模型到跑出说话视频的路径已经走通，剩下的是换素材、调参数出你想要的成片。模型与功能仍在迭代，建议定期用git pull同步代码、重跑bash scripts/download_models.sh更新权重；遇到更深的依赖或部署问题，回到 docs/FAQ.md 与 docs/install.md 对照排查。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
