JoyHallo：中文数字人模型

📖 引言

在音频驱动的视频生成任务中，制作中文视频面临着诸多挑战。一方面，高质量的中文数据集收集难度较大；另一方面，中文复杂的唇部动作使得模型训练相较于英文更为复杂。为此，我们从京东健康国际公司的员工处收集了29小时的中文语音视频数据，构建了jdh-Hallo数据集。该数据集涵盖了不同年龄段和多种说话风格，内容既包括日常对话也涉及专业医学领域。为了使JoyHallo模型适应中文场景，我们引入了Chinese wav2vec2模型进行音频特征提取，并提出了一种半解耦结构来捕捉唇部、表情和姿态特征之间的相互关系。这一改进不仅提升了信息利用效率，还使推理速度提升了14.3%。值得注意的是，JoyHallo依然保持了其强大的英文视频生成能力，展现出出色的跨语言生成性能。

📰 新闻

• 2024年11月19日：🎉🎉🎉 我们自豪地推出全新模型JoyVASA。它比其他生成模型更轻量、更快。点击此处查看主页。

🎬 视频—中文—女性

https://github.com/user-attachments/assets/389e053f-e0c4-433c-8c60-80f9181d3f9c

🎬 视频—中文—男性

https://github.com/user-attachments/assets/1694efd9-2577-4bb5-ada4-7aa711d016a6

🎬 视频—英文

https://github.com/user-attachments/assets/d6b2efea-be76-442e-a8aa-ea0eef8b5f12

🧳 框架

⚙️ 安装

系统要求：

• 经测试支持Ubuntu 20.04及CUDA 11.3
• 测试GPU：A100

创建环境：

# 1. 创建基础环境
conda create -n joyhallo python=3.10 -y
conda activate joyhallo

# 2. 安装依赖
pip install -r requirements.txt

# 3. 安装ffmpeg
sudo apt-get update  
sudo apt-get install ffmpeg -y

🎒 准备模型检查点

1. 下载基础检查点

使用以下命令下载基础权重：

git lfs install
git clone https://huggingface.co/fudan-generative-ai/hallo pretrained_models

2. 下载chinese-wav2vec2-base模型

使用以下命令下载chinese-wav2vec2-base模型：

cd pretrained_models
git lfs install
git clone https://huggingface.co/TencentGameMate/chinese-wav2vec2-base 

3. 下载JoyHallo模型

git lfs install
git clone https://huggingface.co/jdh-algo/JoyHallo-v1 pretrained_models/joyhallo

为方便起见，我们已将模型权重上传至Hugging Face平台。

模型	数据集	Hugging Face 链接
JoyHallo	jdh-Hallo	JoyHallo

4. pretrained_models 目录结构

最终的pretrained_models目录应如下所示：

./pretrained_models/
|-- audio_separator/
|   |-- download_checks.json
|   |-- mdx_model_data.json
|   |-- vr_model_data.json
|   `-- Kim_Vocal_2.onnx
|-- face_analysis/
|   `-- models/
|       |-- face_landmarker_v2_with_blendshapes.task
|       |-- 1k3d68.onnx
|       |-- 2d106det.onnx
|       |-- genderage.onnx
|       |-- glintr100.onnx
|       `-- scrfd_10g_bnkps.onnx
|-- hallo/
|   `-- net.pth
|-- joyhallo/
|   `-- net.pth
|-- motion_module/
|   `-- mm_sd_v15_v2.ckpt
|-- sd-vae-ft-mse/
|   |-- config.json
|   `-- diffusion_pytorch_model.safetensors
|-- stable-diffusion-v1-5/
|   `-- unet/
|       |-- config.json
|       `-- diffusion_pytorch_model.safetensors
|-- wav2vec/
|   `-- wav2vec2-base-960h/
|       |-- config.json
|       |-- feature_extractor_config.json
|       |-- model.safetensors
|       |-- preprocessor_config.json
|       |-- special_tokens_map.json
|       |-- tokenizer_config.json
|       `-- vocab.json
`-- chinese-wav2vec2-base/
    |-- chinese-wav2vec2-base-fairseq-ckpt.pt
    |-- config.json
    |-- preprocessor_config.json
    `-- pytorch_model.bin

🚧 数据要求

图像：

• 裁剪为正方形。
• 人脸需正面朝向，占据图像的50%–70%。

音频：

• 格式为wav。
• 支持中文、英文或混合语种，要求音频清晰且背景音乐适宜。

[!重要提示] 以上要求适用于训练与推理过程。

🚀 推理

1. 命令行推理

使用以下命令执行推理：

sh joyhallo-infer.sh

[!提示] 若希望提升推理速度，可将configs/inference/inference.yaml中的inference_steps由40调整为15，这将立即提高效率。您还可以进一步降低该值，但可能会导致生成效果变差。同时可以尝试调整cfg_scale参数。

通过修改configs/inference/inference.yaml中的参数，您可以指定使用的音频和图像文件，并切换不同的模型。推理结果将保存在opts/joyhallo目录下。该配置文件中的参数说明如下：

• audio_ckpt_dir：模型权重路径。
• ref_img_path：参考图像路径。
• audio_path：参考音频路径。
• output_dir：输出目录。
• exp_name：输出文件夹名称。

2. Web演示推理

使用以下命令启动Web演示：

sh joyhallo-app.sh

演示将在http://127.0.0.1:7860上运行。

⚓️ 训练或微调JoyHallo

在训练或微调模型时，您有两个选择：可以从阶段1开始，或者仅训练阶段2。

1. 使用以下命令从阶段1开始训练

sh joyhallo-alltrain.sh

这将自动启动两个阶段的训练（包括阶段1和阶段2），你可以参考 configs/train/stage1_alltrain.yaml 和 configs/train/stage2_alltrain.yaml 来调整训练参数。

2. 使用以下命令仅训练阶段2

sh joyhallo-train.sh

这将从 阶段2 开始训练，你可以参考 configs/train/stage2.yaml 来调整训练参数。

🎓 准备训练数据

1. 按照以下目录结构准备数据，确保数据符合前面提到的要求

jdh-Hallo/
|-- videos/
|   |-- 0001.mp4
|   |-- 0002.mp4
|   |-- 0003.mp4
|   `-- 0004.mp4

2. 使用以下命令处理数据集

# 1. 从视频中提取特征。
python -m scripts.data_preprocess --input_dir jdh-Hallo/videos --step 1 -p 1 -r 0
python -m scripts.data_preprocess --input_dir jdh-Hallo/videos --step 2 -p 1 -r 0

# 2. 获取jdh-Hallo数据集。
python scripts/extract_meta_info_stage1.py -r jdh-Hallo -n jdh-Hallo
python scripts/extract_meta_info_stage2.py -r jdh-Hallo -n jdh-Hallo

[!NOTE] 请按顺序执行步骤1和步骤2，因为它们执行不同的任务。步骤1会将视频转换为帧、从每个视频中提取音频，并生成所需的掩码。步骤2则使用InsightFace生成人脸嵌入，使用Chinese wav2vec2生成音频嵌入，且需要GPU支持。若需并行处理，可使用 -p 和 -r 参数。其中 -p 参数指定要启动的实例总数，将数据分成 p 份；-r 参数指定当前进程应处理的那部分数据。你需要手动启动多个实例，并为每个实例设置不同的 -r 值。

💻 对比

1. 普通话下的准确率对比

模型	IQA $\uparrow$	VQA $\uparrow$	Sync-C $\uparrow$	Sync-D $\downarrow$	Smooth $\uparrow$	Subject $\uparrow$	Background $\uparrow$
Hallo	0.7865	0.8563	5.7420	13.8140	0.9924	0.9855	0.9651
JoyHallo	0.7781	0.8566	6.1596	14.2053	0.9925	0.9864	0.9627

注：此处使用的评估指标来自以下仓库，结果仅供参考：

• IQA和VQA：Q-Align
• Sync-C和Sync-D：Syncnet
• Smooth、Subject和Background：VBench

2. 英语下的准确率对比

模型	IQA $\uparrow$	VQA $\uparrow$	Sync-C $\uparrow$	Sync-D $\downarrow$	Smooth $\uparrow$	Subject $\uparrow$	Background $\uparrow$
Hallo	0.7779	0.8471	4.4093	13.2340	0.9921	0.9814	0.9649
JoyHallo	0.7779	0.8537	4.7658	13.3617	0.9922	0.9838	0.9622

3. 推理效率对比

	JoyHallo	Hallo	提升
GPU内存（512*512，步长40）	19049m	19547m	2.5%
推理速度（16帧）	24s	28s	14.3%

📝 引用

如果你觉得我们的工作对你有帮助，请考虑引用我们：

@misc{shi2024joyhallo,
  title={JoyHallo: Mandarin语言的数字人模型}, 
  author={Sheng Shi and Xuyang Cao and Jun Zhao and Guoxin Wang},
  year={2024},
  eprint={2409.13268},
  archivePrefix={arXiv},
  primaryClass={cs.CV},
  url={https://arxiv.org/abs/2409.13268}, 
}

🤝 致谢

我们衷心感谢 Hallo、wav2vec 2.0、Chinese-wav2vec2、Q-Align、Syncnet、VBench 以及 Moore-AnimateAnyone 等项目的贡献者们，感谢他们开放的研究精神和卓越的工作成果。

JoyHallo 快速上手指南

JoyHallo 是一个专为普通话设计的数字人视频生成模型，由京东健康团队开源。它支持中、英及混合语言驱动，能够生成口型自然、表情丰富的数字人视频。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Ubuntu 20.04 (推荐)
• GPU: 推荐使用 NVIDIA A100 或其他高性能显卡
• CUDA 版本: 11.3
• Python 版本: 3.10
• 其他依赖: ffmpeg, git, git-lfs

提示：国内用户建议配置 pip 国内镜像源（如清华源或阿里源）以加速依赖下载。

2. 安装步骤

2.1 创建虚拟环境并安装依赖

# 1. 创建基础环境
conda create -n joyhallo python=3.10 -y
conda activate joyhallo

# 2. 安装 Python 依赖
pip install -r requirements.txt

# 3. 安装 ffmpeg (Ubuntu/Debian)
sudo apt-get update  
sudo apt-get install ffmpeg -y

2.2 下载模型权重

项目依赖多个预训练模型，请按顺序执行以下命令下载。所有模型将存放在 pretrained_models 目录中。

# 初始化 git lfs
git lfs install

# 1. 下载 Hallo 基础权重
git clone https://huggingface.co/fudan-generative-ai/hallo pretrained_models

# 2. 下载中文语音特征提取模型 (chinese-wav2vec2-base)
cd pretrained_models
git clone https://huggingface.co/TencentGameMate/chinese-wav2vec2-base 
cd ..

# 3. 下载 JoyHallo 主模型
git clone https://huggingface.co/jdh-algo/JoyHallo-v1 pretrained_models/joyhallo

注意：如果 Hugging Face 下载速度慢，国内用户可尝试使用镜像站（如 hf-mirror.com）或在命令前设置环境变量： export HF_ENDPOINT=https://hf-mirror.com

下载完成后，pretrained_models 目录结构应包含 hallo, joyhallo, chinese-wav2vec2-base, wav2vec, face_analysis 等文件夹。

3. 基本使用

3.1 数据准备

推理需要一张参考图片和一段音频文件：

• 图片 (ref_img): 正方形裁剪，人脸正对镜头，占比约 50%-70%。
• 音频 (audio): .wav 格式，支持普通话、英语或混合发音，声音清晰。

3.2 命令行推理

修改配置文件 configs/inference/inference.yaml，指定您的图片路径、音频路径及输出目录。主要参数说明：

• ref_img_path: 参考图片路径
• audio_path: 驱动音频路径
• output_dir: 结果保存目录
• exp_name: 输出文件夹名称

执行推理脚本：

sh joyhallo-infer.sh

生成的视频将保存在 opts/joyhallo 目录下。

加速技巧：若需提升推理速度，可编辑 configs/inference/inference.yaml，将 inference_steps 从 40 改为 15。这会显著减少耗时，但可能会轻微影响画质。

3.3 Web Demo 体验

如果您更喜欢图形化界面，可以启动本地 Web Demo：

sh joyhallo-app.sh

启动后，在浏览器访问 http://127.0.0.1:7860 即可上传素材并生成视频。