SadTalker 语音驱动人脸动画：一条命令跑通，8 个高频报错一次搞定-平芜编程栈

SadTalker 语音驱动人脸动画：一条命令跑通，8 个高频报错一次搞定

【免费下载链接】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 仓库，跑python inference.py就炸：模型文件缺失报FileNotFoundError，推理到一半又抛CUDA out of memory？别慌，这两个坑都是环境没配齐。按下面步骤走，你能独立跑通 SadTalker 首次推理，输出口型对嘴的视频；拿到 8 条高频报错的速查方案；再用 2 条进阶命令，按自己需求调整表情和画面范围。

能独立跑通 SadTalker 首次推理，在results/目录得到第一个口播视频
能解释checkpoints/与gfpgan/weights/里每个模型的用途，判断下载是否完整
能写出带--still、--expression_scale等参数的进阶命令

环境自检：动手前 60 秒确认

一张表过完依赖，缺哪补哪。

依赖	版本要求	一句话用途	缺失时的快速补救
Conda	任意较新版本	建隔离虚拟环境	官网装 Anaconda / Miniconda
Python	3.8（推荐）	项目指定解释器	`conda create -n sadtalker python=3.8`
PyTorch	1.12.1 + cu113	推理核心，需与显卡 CUDA 版本匹配	`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`
FFmpeg	任意新版	视频编码输出，必装	Linux`conda install ffmpeg`；macOS`brew install ffmpeg`；Windows 用 scoop 或手动加 PATH
Git	任意新版	克隆仓库	`scoop install git`（Windows）

平台差异只有两处：Windows 记得确认ffmpeg在%PATH%里；macOS（含 M1）装完依赖后还要单独执行pip install dlib，否则人脸关键点检测直接挂。没有 GPU 也能跑，加--cpu参数即可，只是速度会明显慢。

核心操作：三步跑通 SadTalker 安装

从克隆到出片只需三个动作：拉代码、装依赖、下模型、推一遍。

一键拉代码

仓库自带全部示例素材，省得自己找图找音频。

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

装依赖配环境

依赖版本在 requirements.txt 里锁死了，照单安装最稳。

conda create -n sadtalker python=3.8 conda activate sadtalker # CUDA 11.3 显卡用官方指定版本；CPU 环境直接 pip install torch torchvision torchaudio 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 # 仅 macOS（M1）需要单独装原版 dlib pip install dlib

模型自动下载

不装模型一切白搭。脚本会自动创建checkpoints/和gfpgan/weights/两个目录并逐个拉取权重，总大小约 2GB，请留够磁盘和耐心。

文件名	大小	用途
`mapping_00109-model.pth.tar`	约 50MB	音频到表情系数网络
`mapping_00229-model.pth.tar`	约 50MB	音频到姿态系数网络
`SadTalker_V0.0.2_256.safetensors`	约 400MB	256 分辨率完整模型包（内置 BFM_Fitting 人脸重建库）
`SadTalker_V0.0.2_512.safetensors`	约 800MB	512 分辨率完整模型包
`gfpgan/weights/`（4 个权重）	约 600MB	人脸检测与 GFPGAN 修复，供`--enhancer gfpgan`使用

bash scripts/download_models.sh

⚠️ 脚本用了wget -nc，中断后重跑会断点续传，不用删掉重下。

首次推理出视频

素材现成：examples/下 15 条驱动音频、20+ 张源图、2 条参考视频。先用默认参数推一条最短路径，确认链路通了再谈调参。

# 首次推理：256 分辨率、默认 crop 预处理 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，视频就在该时间戳目录下打开看口型。

踩坑速查：高频报错对照表

报错别急着重装环境，先对号入座。

报错关键词	根因	修复命令/操作
`No module named 'ai'`	`epoch_20.pth`缺失或损坏	重跑`bash scripts/download_models.sh`
`CUDA out of memory`	显存碎片化分配失败	`export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128`（Windows 用`set`）
`FileNotFoundError ... similarity_Lm3D_all.mat`	512 模型包没下全，BFM 库缺失	确认`checkpoints/`下两个`.safetensors`完整
`unexpected EOF ... file might be corrupted`	权重下到一半中断	重跑下载脚本（`wget -nc`可续传）
`ffmpeg is not recognized`	系统 PATH 缺 ffmpeg	`conda install ffmpeg`，或 Windows 加 PATH
`Illegal Instruction`（Mac M1）	dlib 架构不兼容	`pip install dlib`单独重装
`Invalid data found when processing input`	输入音频不是 wav/mp3	先把音频转成 wav 再喂给`--driven_audio`
终端打印`Can't get the coeffs of the input`	图中人脸检测失败	换正脸清晰图，或改用`--preprocess crop`

以上没覆盖到的，先翻官方 FAQ 再到项目 issue 区搜，九成问题都有前人踩过了。

跑通之后：进阶与延伸

会跑之后，把参数变成你的。

换素材调参数，效果立竿见影

两个参数最值得玩：--expression_scale控制表情幅度（默认 1.0），--still让头部保持源图姿态、少晃动，适合全身图。

# 全身图动画：full 预处理 + still 保持原姿态 + GFPGAN 人脸修复 python inference.py \ --driven_audio examples/driven_audio/chinese_poem1.wav \ --source_image examples/source_image/full_body_1.png \ --preprocess full --still --enhancer gfpgan \ --expression_scale 1.2 --size 512 \ --result_dir results_full

预期效果：脸部贴回原图全身画面，头部基本不转，表情比默认更生动，512 分辨率加 gfpgan 修复后人脸清晰度明显提升。完整参数含义见最佳实践文档。