SadTalker 作为 Stable Diffusion WebUI 扩展安装、权重配置与常见问题完整指南【免费下载链接】SadTalker[CVPR 2023] SadTalkerLearning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalker本文以仓库文档 docs/webui_extension.md 为骨架结合 scripts/extension.py、scripts/download_models.sh、src/utils/init_path.py 等源码系统讲解如何将 SadTalkerCVPR 2023 语音驱动单图说话人脸动画以扩展Extension形式接入 AUTOMATIC1111 stable-diffusion-webui从扩展安装、模型权重下载与路径配置到启动 WebUI 完成一张图 一段音频 → 说话视频的完整链路并覆盖 CPU 运行、full 模式等常见排障同时剖析扩展插件与 WebUI 底层的协作机制。一、写在前面为什么要把 SadTalker 装进 WebUISadTalker 的核心能力是用一段语音驱动一张静态人像生成口型与表情自然、附带头部运动的说话视频。仓库同时提供两种使用方式独立运行的 Gradio 演示python app_sadtalker.py或 webui.sh / webui.bat以及作为 stable-diffusion-webui 的扩展插件运行。选择扩展方式的核心收益在于复用现有环境直接安装在已配置好的 stable-diffusion-webui 里不另起服务工作流串联可与 txt2img / img2img 生成的图像无缝衔接把文生图 → 让图中人物说话串成一条完整 AIGC 流水线scripts/extension.py 中专门提供了get_img_from_txt2img/get_img_from_img2img两个函数用于自动拾取 WebUI 最近一次生成的图片设置面板统一管理输出目录等选项会注册进 WebUI 的 Settings 页面。本文面向的是将 SadTalker 以扩展形式接入 stable-diffusion-webui的场景下文所有路径约定均以此为前提。二、前置准备与扩展安装2.1 安装 stable-diffusion-webui 并添加 SadTalker 扩展第一步是安装最新版本的 stable-diffusion-webuiAUTOMATIC1111 版然后在 WebUI 中通过Extensions → Install from URL填入 SadTalker 仓库地址完成扩展安装或手动将仓库克隆到stable-diffusion-webui/extensions/SadTalker/目录下。WebUI 启动时会自动扫描extensions/目录并加载每个扩展。SadTalker 扩展的入口即仓库根下的 scripts/extension.py它通过script_callbacks.on_ui_tabs(on_ui_tabs)与script_callbacks.on_ui_settings(on_ui_settings)两个回调向 WebUI 注册自己的界面 Tab 与设置项。2.2 首次加载时的依赖自动补齐扩展被加载后on_ui_tabs会先调用install()scripts/extension.py检查依赖。该函数内置了一份带固定版本的依赖清单凡 WebUI 环境中缺失的包会通过launch.run_pip自动安装Python 包锁定版本用途face-alignment1.3.5人脸关键点检测imageio2.19.3图像/视频读写官方注释强调需要较新版本imageio-ffmpeg0.4.7FFmpeg 视频编解码绑定librosa0.8.0音频特征提取驱动语音分析pydub0.25.1音频处理scipy1.8.1数值计算yacs0.1.8配置系统读取 src/config 下的 YAML 配置av最新音视频容器处理gfpgan最新人脸增强器对应界面的 GFPGAN enhancer 选项注源码中 dlib 的安装分支被注释掉dlib is not necessary currently因此当前版本不再强制要求 dlib。依赖就绪后扩展会将stable-diffusion-webui/extensions/SadTalker加入sys.path并调用 app_sadtalker.py 中的sadtalker_demo(checkpoint_path..., config_path..., warpfnwrap_queued_call)构建 Gradio 界面——这正是扩展 Tab 中SadTalker页面的来源。三、下载模型权重Checkpoints扩展本体只是前端与推理框架真正驱动生成的是若干预训练权重文件。安装完成后必须下载全部 checkpoints否则扩展无法工作。3.1 一键脚本下载Linux / macOS仓库提供了一键下载脚本 scripts/download_models.sh在任意你喜欢的工作目录文档示例为SOMEWHERE_YOU_LIKE执行cd SOMEWHERE_YOU_LIKE bash (wget -qO- https://raw.githubusercontent.com/Winfredy/OpenTalker/main/scripts/download_models.sh)如果你的仓库已克隆到本地也可以直接运行仓库内的脚本cd SadTalker bash scripts/download_models.sh该脚本会在当前目录创建./checkpoints/并下载全部权重同时在./gfpgan/weights/下准备人脸增强GFPGAN所需的模型。3.2 Windows 手动下载Windows 用户可到 SadTalker 官方 Releasesv0.0.2-rc页面逐个下载以下权重文件放入统一的 checkpoints 目录。3.3 权重清单以仓库脚本为准根据 scripts/download_models.sh 与扩展的完整性检测逻辑完整的权重清单如下文件名用途SadTalker_V0.0.2_256.safetensors256 分辨率统一模型新格式SadTalker_V0.0.2_512.safetensors512 分辨率统一模型新格式betamapping_00109-model.pth.tar映射网络full 模式使用mapping_00229-model.pth.tar映射网络crop/resize 等模式使用auido2exp_00300-model.pth音频→表情系数旧版 pth兼容用auido2pose_00140-model.pth音频→姿态系数旧版 pth兼容用epoch_20.pth人脸重建3DMM 拟合旧版兼容用facevid2vid_00189-model.pth.tar人脸渲染face render旧版兼容用wav2lip.pth唇形同步旧版兼容用shape_predictor_68_face_landmarks.datdlib 68 点人脸关键点旧版兼容用脚本还会额外下载 GFPGAN 人脸增强所需的 4 个权重到./gfpgan/weights/alignment_WFLW_4HG.pth人脸对齐detection_Resnet50_Final.pth人脸检测GFPGANv1.4.pthGFPGAN 主模型parsing_parsenet.pth人脸解析3.4 新旧两种模型格式的加载逻辑从 src/utils/init_path.py 可以看到模型加载的完整逻辑若 checkpoints 目录下存在*.safetensors文件则优先使用新格式统一模型SadTalker_V0.0.2_size.safetensorssize 取 256 或 512此时只需一个文件即可完成全部推理若不存在 safetensors则回退到旧版多文件 pth 格式audio2exp、audio2pose、face_recon、face-render、wav2lip 等根据预处理模式选择映射网络与渲染配置preprocess含full时使用mapping_00109-model.pth.tar与facerender_still.yaml否则使用mapping_00229-model.pth.tar与 src/config/facerender.yaml。这解释了为什么新版本强烈建议直接下载 safetensors文件更少、加载更快且官方在更新日志中说明 3.12 版本曾因第三方包安全性问题加固了 WebUI 扩展Fixed the WebUI safe issues because of 3rd-party packages。四、配置权重路径两种方式4.1 方式一放入自动检测目录推荐将 checkpoints 放入以下两个目录之一扩展会自动识别stable-diffusion-webui/models/SadTalker/ stable-diffusion-webui/extensions/SadTalker/checkpoints/自动检测逻辑见 scripts/extension.py 的get_default_checkpoint_path()它依次检查models/SadTalker与extensions/SadTalker/checkpoints两个目录并分别用check_all_files_safetensor()只要求 4 个 safetensors/mapping 文件齐备和check_all_files()要求全部 8 个旧版文件齐备做完整性校验。优先满足 safetensor 校验的目录会被选中随后该路径被写入环境变量SADTALKER_CHECKPOINTS供后续加载使用。4.2 方式二通过环境变量显式指定覆盖默认路径如果不想使用上述默认目录例如权重存放在独立磁盘可以在启动脚本中设置SADTALKER_CHECKPOINTS环境变量# Windowswebui_user.bat set SADTALKER_CHECKPOINTSD:\SadTalker\checkpoints # Linux/macOSwebui_user.sh export SADTALKER_CHECKPOINTS/path/to/SadTalker/checkpoints⚠️ 前提条件此方式仅在你直接通过webui_user.shLinux或webui_user.batWindows启动 WebUI 时生效。这两个脚本是用户在 stable-diffusion-webui 目录下手动创建/维护的用户级启动脚本环境变量会随进程传递给 WebUI 及 SadTalker 扩展。从源码可以看到该变量的完整流转链路scripts/extension.py 的install()中若检测到SADTALKER_CHECKPOINTS已设置直接打印其路径否则尝试自动检测默认目录并写入该环境变量两者都失败时会打印提示要求手动在webui_user.bat/webui_user.sh中配置scripts/extension.py 的on_ui_tabs()中优先读取os.getenv(SADTALKER_CHECKPOINTS)未设置时才回退到extensions/SadTalker/checkpoints/该路径最终传入sadtalker_demo(checkpoint_path...)由 src/gradio_demo.py 的SadTalker(checkpoint_path, config_path, lazy_loadTrue)完成模型装配。五、启动 WebUI 并生成说话视频5.1 启动方式Linux/macOS 执行webui.sh或webui_user.shWindows 双击webui_user.bat也可以使用其他你习惯的方式启动 stable-diffusion-webui。启动完成后在 WebUI 顶部 Tab 中找到SadTalker页签即可使用。补充若你不使用 stable-diffusion-webui 扩展而是希望直接运行 SadTalker 自带的独立 WebUI仓库同样提供了 webui.shLinux/macOS内部调用 launcher.py 自动装依赖并启动与 webui.batWindows。launcher.py 会校验 Python 版本Windows 要求 3.10Linux 支持 3.73.11官方以 3.10.6 作为测试基准。5.2 扩展页面的核心参数在 SadTalker 页签中左侧上传Source image源人像支持 txt2img/img2img 输出图直接接入与Input audio驱动音频Linux 下还可直接用内置 TTS 从文本合成音频见 app_sadtalker.py右侧 Settings 面板可调节以下参数参数类型/范围默认值说明Pose styleSlider 0~460头部姿态风格0 为最接近源图face model resolutionRadio 256/512256选择 256 或 512 分辨率模型对应SadTalker_V0.0.2_size.safetensorspreprocessRadio: crop / resize / full / extcrop / extfullcrop输入图像预处理方式full系列为全身模式Still ModeCheckbox关减少头部运动与full预处理配合batch sizeSlider 1~102生成批大小GFPGAN as Face enhancerCheckbox关使用 GFPGAN 对人脸做增强需要已下载 gfpgan 权重点击Generate后右侧输出生成视频。参数含义可进一步参考仓库的 docs/best_practice.md 最佳实践文档。细节当运行在 WebUI 内时生成回调会被包装为wrap_queued_call见 app_sadtalker.py使任务进入 WebUI 的任务队列避免阻塞界面。生成的视频默认输出到stable-diffusion-webui/outputs/SadTalker/可在Settings → SadTalker小节中通过 Path to save results of sadtalker 选项对应 scripts/extension.py 注册的sadtalker_result_dir自定义。六、常见问题FAQ6.1 CPU 运行需要禁用 safe unpickle如果你在纯 CPU环境下运行需要为 WebUI 追加--disable-safe-unpickle启动参数否则模型加载会被安全机制拦截。在用户启动脚本中配置# Windowswebui_user.bat set COMMANDLINE_ARGS--disable-safe-unpickle # Linux/macOSwebui_user.sh export COMMANDLINE_ARGS--disable-safe-unpickle这也与 3.x 版本扩展的安全加固背景相关safetensors 格式本身即是一种更安全的模型序列化格式可避免pickle反序列化带来的任意代码执行风险。6.2 无法使用 full 模式如果你遇到full全身模式不可用的问题请确认已下载mapping_00109-model.pth.tarfull 模式专用的映射网络权重见 src/utils/init_path.py确认 checkpoints 目录完整性满足扩展检测要求查阅项目 issues/discussions 中关于 full 模式的讨论官方 issue #78获取历史排障信息。从源码可以确认 full 模式与普通模式走的是不同的配置与权重分支full前缀会启用facerender_still.yaml并加载mapping_00109而 crop/resize 等模式使用facerender.yaml与mapping_00229。6.3 其他提示扩展的依赖安装是幂等的install()会先通过launch.is_installed()检查已安装的包不会重复安装因此重复启动不会卡在依赖阶段若扩展找不到任何权重启动日志会明确提示 please manually set the SADTALKER_CHECKPOINTS in webui_user.bat (windows) or webui_user.sh (linux)此时按第四节方式二配置即可权重目录应同时满足扩展完整性检测与 src/utils/init_path.py 的加载规则safetensors 优先缺失时回退旧版 pth。七、总结扩展模式的完整工作流回顾整个接入过程SadTalker WebUI 扩展的完整工作流可以概括为注册script_callbacks.on_ui_tabs/on_ui_settings将 SadTalker 页面与设置项挂载进 WebUIscripts/extension.py装配install()补齐 Python 依赖并解析SADTALKER_CHECKPOINTS环境变量 → 自动检测目录 → 手动提示推理sadtalker_demo()构建 Gradio 界面点击 Generate 后经由wrap_queued_call进入 WebUI 队列调用SadTalker.test()完成音频特征 → 3D 运动系数 → 人脸渲染 → 可选 GFPGAN 增强→ 视频输出产出结果保存到outputs/SadTalker/并可在 WebUI 中与文生图/图生图流程无缝衔接。至此你已经掌握将 SadTalker 作为 stable-diffusion-webui 扩展从安装到实战的全部要点。若在 GPU 环境下首次使用记得优先下载 safetensors 统一模型若在 CPU 环境使用别忘了--disable-safe-unpickle这一关键开关。【免费下载链接】SadTalker[CVPR 2023] SadTalkerLearning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考