数字人JoyVASA 实战记录

一、项目背景最近在看数字人相关内容找到这个项目JoyVASA 是京东健康(JD Health International Inc.)与浙江大学联合开源的扩散模型驱动的音频→肖像动画框架论文JoyVASA Portrait and Animal Image Animation with Diffusion-Based Audio-Driven Facial Dynamics and Head Motion Generation它解决的是单张静态图 一段音频 → 一段会说话、有表情、会点头的视频论文侧重点是长视频的稳定性与多类主体(人/动物)的统一建模。音频驱动—— 仅需一张参考图 一段音频自动生成唇形同步真人肖像动画—— 写实人像说话视频动物肖像动画—— 猫、狗等动物面部说话动画多语种适配—— 训练数据为私有中文 公开英文混合中英文都可用长视频稳定—— 滑动窗口推理避免长序列崩坏二、技术原理JoyVASA 不是端到端直接出视频而是两阶段解耦的┌─────────────────────────────────────────────────────────────┐ │ Stage 1 离线/一次性 - 训练解耦的人脸表征 │ │ (LivePortrait 提供 appearance encoder motion encoder) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Stage 2 推理时 - 扩散 Transformer 采样运动序列 │ │ audio features (HuBERT/wav2vec2) → motion sequences │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Warping Generator - 用采样到的关键点 warp 表征渲染出视频 │ └─────────────────────────────────────────────────────────────┘2.1 解耦面部表征(Decoupled Facial Representation)参考图 → appearance encoder(LivePortrait)提取静态 3D 面部外观特征参考图 → motion encoder 提取 3D 关键点这一拆分的好处外观与运动解耦任意静态 3D 表征都能和任意运动序列组合所以长视频可以分段生成运动、复用同一张外观天然解决帧间连续性问题。2.2 扩散 Transformer 生成运动音频 → 音频编码器(chinese-hubert-base 适配中文) → 音频特征音频特征 → DiT(Diffusion Transformer) 滑动窗口采样 → 目标运动序列identity-independent运动生成不依赖人物身份所以同一段运动可以驱动不同的人/动物。2.3 渲染源关键点 采样到的目标关键点 → 计算变形场 → warp appearance feature → generator → 视频帧。三、环境准备3.1 硬件与系统(官方已测试)平台系统CUDA显卡LinuxUbuntu 20.0412.1A100WindowsWindows 1112.1RTX 4060 Laptop 8GB实际社区反馈RTX 3090 / 4090 / 4090D 都能跑显存建议 ≥ 8GB。3.2 软件依赖# 1. 基础环境conda create-njoyvasapython3.10-yconda activate joyvasa# 2. Python 依赖pipinstall-rrequirements.txt# 3. 系统依赖 ffmpegsudoapt-getupdatesudoapt-getinstallffmpeg-y# 4. 可选仅当你需要跑 animal 模式时cdsrc/utils/dependencies/XPose/models/UniPose/ops python setup.py buildinstallcd-MultiScaleDeformableAttention不是pip install而是要进子目录setup.py源码编译。这是新手最常踩的坑之一。3.3 源码克隆gitclone https//github.com/jdh-algo/JoyVASA.gitcdJoyVASA四、权重下载这是全网最容易出错的地方。原仓库默认目录名是pretrained_weights/不是checkpoints/。整套项目需要 5 套权重4.1 JoyVASA 主模型mkdir-ppretrained_weightscdpretrained_weightsgitlfsinstallgitclone https//huggingface.co/jdh-algo/JoyVASAcd..4.2 音频编码器cdpretrained_weights# 中文 HuBERTgitclone https//huggingface.co/TencentGameMate/chinese-hubert-base# 可选wav2vec2-base# git clone https//huggingface.co/facebook/wav2vec2-base-960hcd..4.3 LivePortrait 权重cdpretrained_weights# 方法 Ahuggingface_hub CLIpipinstall-Uhuggingface_hub[cli]huggingface-cli download KwaiVGI/LivePortrait\--local-dir.\--exclude*.git*README.mddocscd..4.4 InsightFace buffalo_l 模型# 一般随 huggingface-cli 下载 LivePortrait 时会自动包含# 若缺失自行mkdir-ppretrained_weights/insightface/models/buffalo_l# 从 insightface 官方源或 LivePortrait 仓库的对应位置取# 2d106det.onnx、det_10g.onnx 是关键文件4.5 最终目录结构(官方要求)JoyVASA/ ./pretrained_weights/ ├── insightface │ └── models │ └── buffalo │ ├── 2d106det.onnx │ └── det_10g.onnx ├── JoyVASA │ ├── motion_generator │ │ └── iter_0020000.pt │ └── motion_template │ └── motion_template.pkl ├── liveportrait │ ├── base_models │ │ ├── appearance_feature_extractor.pth │ │ ├── motion_extractor.pth │ │ ├── spade_generator.pth │ │ └── warping_module.pth │ ├── landmark.onnx │ └── retargeting_models │ └── stitching_retargeting_module.pth ├── liveportrait_animals │ ├── base_models │ │ ├── appearance_feature_extractor.pth │ │ ├── motion_extractor.pth │ │ ├── spade_generator.pth │ │ └── warping_module.pth │ ├── retargeting_models │ │ └── stitching_retargeting_module.pth │ └── xpose.pth ├── TencentGameMate:chinese-hubert-base │ ├── chinese-hubert-base-fairseq-ckpt.pt │ ├── config.json │ ├── gitattributes │ ├── preprocessor_config.json │ ├── pytorch_model.bin │ └── README.md └── wav2vec2-base-960h │ ├── config.json │ ├── feature_extractor_config.json │ ├── model.safetensors │ ├── preprocessor_config.json │ ├── pytorch_model.bin │ ├── README.md │ ├── special_tokens_map.json │ ├── tf_model.h5 │ ├── tokenizer_config.json │ └── vocab.json ├── src/ ├── inference.py ├── app.py ├── requirements.txt └── train.py五、三种运行方式5.1 命令行推理(inference.py)5.1.1 真人模式python inference.py\-rassets/examples/imgs/joyvasa_003.png\-aassets/examples/audios/joyvasa_003.wav\--animation_modehuman\--cfg_scale2.0joyvasa_003_joyvasa_0035.1.2 动物模式python inference.py\-rassets/examples/imgs/joyvasa_001.png\-aassets/examples/audios/joyvasa_001.wav\--animation_modeanimal\--cfg_scale2.05.1.3 短命令 vs 全命令短全说明-r--reference参考图-a--audio驱动音频--animation_modehuman/animal--cfg_scale表情强度--driving_optionexpression-friendly/pose-friendly--driving_multiplier运动幅度倍率--flag_normalize_lip是否归一化唇形--flag_relative_motion是否相对运动--do_crop/--scale/--vx_ratio/--vy_ratio裁剪控制5.2 WebUI(app.py)python app.py启动后浏览器打开http//127.0.0.17862← 注意是 7862不是 7860WebUI 包含三大区Input Section上传参考图 音频Configuration Section动画模式、CFG、裁剪、归一化Generate Button 输出视频Gradio 默认端口是 7860但官方app.py写的是 7862这是为了避免和 LivePortrait 等同生态项目冲突。六、参数详解6.1 关键参数参数官方说明默认范围animation_mode动画模式humanhuman/animalcfg_scale表情强度4.00.0 ~ 10.0driving_option驱动风格expression-friendlyexpression-friendly/pose-friendlydriving_multiplier运动强度倍率1.00.0 ~ 2.0flag_normalize_lip唇形归一化TrueTrue/Falseflag_relative_motion相对运动TrueTrue/Falseflag_remap_input贴回原图TrueTrue/Falseflag_stitching_input拼接模块TrueTrue/Falsedo_crop是否裁剪TrueTrue/Falsescale裁剪缩放2.31.8 ~ 4.0vx_ratio横向裁剪偏移0.0-0.5 ~ 0.5vy_ratio纵向裁剪偏移-0.125-0.5 ~ 0.5cfg_scale推荐 1.5~2.5官方源码默认值是 4.0实测 2.0~4.0 出自然结果5 表情夸张、1.5 表情平淡。6.2 参数作用图谱┌──────────────────┐ │ cfg_scale │ │ ↑ 更夸张 │ │ ↓ 更含蓄 │ └──────────────────┘ ↕ animation_mode ──► human / animal pipeline 选择 ↕ ┌────────────────────┐ ┌────────────────────┐ │ driving_option │ │ driving_multiplier │ │ expression-friendly│ │ ↑ 运动更明显 │ │ pose-friendly │ │ ↓ 运动更轻微 │ └────────────────────┘ └────────────────────┘ 裁剪三件套(scale / vx_ratio / vy_ratio) ──► 控制人脸在画面中的取景位置6.3 调参经验值目标推荐参数组合自然口播cfg_scale2.0driving_optionexpression-friendlydriving_multiplier1.0头部动作多driving_optionpose-friendlydriving_multiplier1.3夸张表情(主播风格)cfg_scale4.0~5.0driving_multiplier1.5几乎不动(配静态BGM)cfg_scale1.0driving_multiplier0.5七、输入素材规范7.1 图片项建议主体单一人物或单一动物面部角度正面 / 轻微侧脸最佳大侧脸容易崩清晰度面部无遮挡、无重度美颜、无糊脸分辨率≥ 512×512过低影响关键点提取动物眼睛、嘴部必须清晰可见7.2 音频项建议格式WAV PCM 16-bit采样率16 kHz 单声道(官方最优)时长任意内部用滑动窗口质量人声清晰、低背景噪音、无明显混响格式转换示例ffmpeg-iinput.mp3-vn-ar16000-ac1-ca pcm_s16le output.wav八、能力边界官方明确擅长真人 / 猫狗等动物面部说话动画中英文双语文本驱动唇形同步质量高、表情自然长视频通过滑动窗口稳定推理轻量级、依赖干净、MIT 可商用官方不擅长 / 文档未声明大幅转头、大幅肢体动作复杂背景动态、镜头运镜多人 / 多动物同时动画二次元 / 插画肖像(虽然human模式勉强能跑但官方未声明)实时推理(论文自述real-time 是 future work)水印、溯源、防深伪(没有任何机制)⚠️ 商用合规提醒MIT 协议本身允许商用但 依赖项(LivePortrait、wav2vec2、HuBERT)各自的协议需要单独核查训练数据含京东私有中文数据 公开英文数据商业化前建议法务审一遍数据来源九、常见问题与排查现象原因解决ModuleNotFoundError MultiScaleDeformableAttentionanimal 模式必装源码编译跑src/utils/dependencies/XPose/models/UniPose/ops下setup.py build installffmpeg command not found缺系统依赖apt-get install ffmpegWebUI 打开 7860 端口空白端口错了实际是 7862cfg_scale2表情仍夸张误用全音轨 wav采样率不是 16k用 ffmpeg 转 16k mono wav动物图跑human模式脸崩mode 不匹配--animation_mode animal推理非常慢缺 CUDA / 用 CPU 跑必须有 NVIDIA GPU CUDA 12.x生成的视频没声音这是正常的inference.py只输出画面声音需自己用 ffmpeg 合回把声音合回的官方习惯做法ffmpeg-igenerated_video.mp4-iinput.wav -cv copy -ca aac final.mp4十、总结JoyVASA 把音频驱动肖像动画这件事做到了一个比较舒服的折中点架构上用LivePortrait 解耦表征 DiT 扩散生成运动的两阶段设计绕开了端到端扩散模型长视频崩坏的硬伤。生态上原生支持动物、中文友好、MIT 协议、依赖干净部署门槛低。能力上对自然表情 唇形同步 轻点头这一档需求目前是开源里做得比较像样的。取舍上明确不追求大幅动作、镜头运镜、实时性这些是显式不擅长。