企业官网建设流程全解析

如何 4 步装好 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 的音频驱动说话头视频工具：给它一张人像和一段语音，它能输出口型、表情与声音对齐的说话视频。这篇带你走完 SadTalker 安装全流程——环境、依赖、模型文件、验证，命令均可直接复制，文末附硬件参数对照和 SadTalker 常见报错速查。

📋 核对动手前的硬件与系统清单

两点提醒：Python 锁定 3.8，更高版本容易和旧依赖起冲突；没有 GPU 的机器也能跑，运行时加--cpu即可，只是生成会从 GPU 上的几十秒拉长到几分钟。下文命令按 GPU + CUDA 11.3 路线给出。

🚀 搭建环境、安装依赖与下载模型文件

1. 建一个隔离的 Python 3.8 环境

git clone https://gitcode.com/GitHub_Trending/sa/SadTalker cd SadTalker

拉取代码仓库并进入项目目录，后续所有命令都在这个目录里执行。

conda create -n sadtalker python=3.8 conda activate sadtalker

新建名为 sadtalker 的独立 conda 环境并激活，避免和你系统里已有的包互相打架。

2. 装好 PyTorch 与 FFmpeg

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

安装与 CUDA 11.3 配套的 PyTorch（实际跑模型的深度学习框架）。纯 CPU 机器换成 +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

conda install ffmpeg

FFmpeg 是负责视频帧处理的底层工具，缺了它无法合成视频；Windows 用户需手动安装并确认ffmpeg -version能出结果。

pip install -r requirements.txt

按 requirements.txt 一次装齐全部 Python 依赖，其中关键的几个：numpy 1.23.4 / scipy 1.10.1 负责数值计算，face_alignment 1.3.5 做面部关键点检测，librosa 0.9.2 解析音频，basicsr 1.4.2 与 facexlib 0.3.0 处理面部超分，gradio 提供本地网页界面，safetensors 是更安全的模型存储格式。

可选组件：

pip install TTS

gradio 网页版的文本转语音要用到，不用网页界面可跳过。macOS 用户（尤其 M1/M2）建议单独pip install dlib装面部检测组件，避免架构报错。Windows 与 macOS 的更多细节见 docs/install.md。

3. 下载并摆好全部模型文件

bash scripts/download_models.sh

这个脚本会自动建目录并下载全部模型，已存在的文件直接跳过。完成后项目里应有这些文件：

checkpoints/

• SadTalker_V0.0.2_256.safetensors— 256 分辨率面部渲染主包，约 1.2GB
• SadTalker_V0.0.2_512.safetensors— 512 分辨率渲染包，细节更好，约 1.2GB
• mapping_00109-model.pth.tar— MappingNet，全身（full）模式需要，约 200MB
• mapping_00229-model.pth.tar— MappingNet，裁剪（crop）头部模式用，约 200MB

gfpgan/weights/

• alignment_WFLW_4HG.pth— 人脸对齐模型
• detection_Resnet50_Final.pth— 人脸检测模型
• GFPGANv1.4.pth— 人脸修复增强模型
• parsing_parsenet.pth— 人脸解析模型

文件不用手工改名挪位置：src/utils/init_path.py 会自动选模型——checkpoints 下只要存在 .safetensors 就走新版，并按--size加载 256 或 512 的包；preprocess 含 full 时用 mapping_00109，否则用 mapping_00229。若你刻意使用旧版 pth 模型（如 wav2lip.pth、auido2exp_00300-model.pth、epoch_20.pth），运行时加--old_version。

4. 验证环境并跑通第一条视频

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

打印 PyTorch 版本与 CUDA 是否可用，第二个值显示 True 说明 GPU 路线就绪。

ffmpeg -version ls checkpoints gfpgan/weights

前一条确认 FFmpeg 在 PATH 里，后一条核对模型文件是否齐全，缺了就回到第 3 步。

然后用仓库自带素材做一次完整生成：

python inference.py --driven_audio examples/driven_audio/bus_chinese.wav \ --source_image examples/source_image/full_body_1.png

用示例语音驱动示例人像，走一遍裁剪、音频转系数、渲染全流程，成品视频保存在 results/ 目录下，文件名是时间戳。

上图就是命令里用的那张默认输入图。

习惯网页操作的话，Linux/macOS 执行bash webui.sh即可启动 gradio 网页界面，Windows 双击webui.bat。

🎛️ 调整参数：GPU 与 CPU 两套配置

inference.py 会自动检测设备：torch.cuda.is_available()为真且没加--cpu时走 cuda，否则走 cpu。常用参数对照：

GPU 路线（CUDA 11.3、8GB+ 显存）：

python inference.py --driven_audio audio.wav --source_image img.png \ --size 512 --batch_size 4 --enhancer gfpgan

--size 512启用 512 模型提升画质（默认是 256）；--batch_size 4多帧并行渲染，更吃显存；--enhancer gfpgan追加一次人脸修复。显存峰值约 3–6GB。

CPU 路线：

python inference.py --driven_audio audio.wav --source_image img.png \ --cpu --size 256 --batch_size 1

强制 CPU 跑，保持 256 与单帧批处理，不挂 enhancer，用速度换内存。

🩺 排查常见报错：现象、原因与解法

1. ffmpeg is not recognized as an internal or external command原因：FFmpeg 没装或不在 PATH。解法：Linux 执行conda install ffmpeg，macOS 执行brew install ffmpeg，Windows 安装后把 bin 目录加入 PATH，再用ffmpeg -version复验。

2. FileNotFoundError: [Errno 2] No such file or directory: checkpoints\BFM_Fitting\similarity_Lm3D_all.mat原因：模型文件缺失或放错目录。解法：重跑bash scripts/download_models.sh，再对照第 3 步清单逐项核对目录结构。

3. RuntimeError: unexpected EOF, expected 237192 more bytes. The file might be corrupted.或ModuleNotFoundError: No module named 'ai'原因：文件下载不完整或损坏，后者一般对应 epoch_20.pth 被截断。解法：用wget -c 链接断点续传同一文件，或整包重下 gfpgan 文件夹，下载后核对文件大小。

4. RuntimeError: CUDA out of memory原因：显存不够，512 分辨率加大 batch 时更容易触发。解法：--batch_size降到 1、--size降到 256，并在运行前限制显存分配：

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

5. Illegal Hardware Error（Mac M1/M2 多见） 原因：dlib 与 Apple Silicon 架构不匹配。解法：确认 Python 是 arm64 版本后执行pip install dlib重装。

6. Error while decoding stream #0:0: Invalid data found when processing input ... Header missing原因：音频格式不支持，SadTalker 只收 wav 和 mp3。解法：先转换，例如ffmpeg -i input.aac -ar 16000 -ac 1 output.wav，再把 wav 喂给 inference.py。

环境与模型都就位后，换一张自己的人像和一段语音，就能让 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