Public

Code Issues Pull requests Events Packages Insights

main

HunyuanVideo-Avatar/README_zh.md

天宇

docs: 增加中文文档

e21db73a

PreviewCode viewBlame

Raw

HunyuanVideo-Avatar 🌅

腾讯HunyuanVideo-Avatar：多角色动态一致的音频驱动人物动画

🔥🔥🔥 最新消息！

2025年5月28日：👋 我们发布了HunyuanVideo-Avatar的推理代码和模型权重。下载。

📑 开源计划

HunyuanVideo-Avatar
- 推理代码
- 模型权重
- ComfyUI

摘要

近年来，音频驱动的人物动画取得了显著进展。然而，仍然存在一些关键挑战：(i) 在保持角色一致性的同时生成高度动态的视频，(ii) 实现角色与音频之间的精确情感对齐，以及 (iii) 实现多角色音频驱动动画。为了解决这些挑战，我们提出了HunyuanVideo-Avatar，这是一个基于多模态扩散变换器(MM-DiT)的模型，能够同时生成动态的、情感可控的和多角色对话视频。具体来说，HunyuanVideo-Avatar引入了三个关键创新：(i) 设计了一个角色图像注入模块来替代传统的基于加法的角色条件方案，消除了训练和推理之间固有的条件不匹配。这确保了动态运动和强大的角色一致性；(ii) 引入了音频情感模块(AEM)来提取和转移情感参考图像中的情感线索到目标生成视频，实现精细和准确的情感风格控制；(iii) 提出了面部感知音频适配器(FAA)，通过潜在级别的面部掩码来隔离音频驱动的角色，实现多角色场景下的独立音频注入。这些创新使HunyuanVideo-Avatar在基准数据集和新提出的野外数据集上超越了最先进的方法，在动态、沉浸式场景中生成逼真的头像。源代码和模型权重将公开发布。

HunyuanVideo-Avatar整体架构

我们提出的HunyuanVideo-Avatar是一个基于多模态扩散变换器(MM-DiT)的模型，能够生成动态、情感可控和多角色对话视频。

🎉 HunyuanVideo-Avatar主要特点

高动态和情感可控的视频生成

HunyuanVideo-Avatar支持将任何输入的头像图片通过简单的音频条件转换为高动态和情感可控的视频。具体来说，它可以接受多风格的头像图片，支持任意尺度和分辨率。系统支持包括真实照片、卡通、3D渲染和拟人化角色在内的多种风格头像。生成范围涵盖肖像、上半身和全身多种尺度。它生成的视频具有高动态的前景和背景，实现了卓越的真实感和自然度。此外，系统支持根据输入音频控制角色的面部表情。

多样化应用

HunyuanVideo-Avatar支持各种下游任务和应用。例如，系统生成的会说话的头像视频可以应用于电子商务、在线直播、社交媒体视频制作等。此外，其多角色动画功能扩展了应用范围，如视频内容创作、编辑等。

📜 系统要求

需要支持CUDA的NVIDIA GPU。
- 该模型在8GPU的机器上进行了测试。
- 最低配置：生成720px1280px129帧视频所需的最小GPU内存为24GB，但速度很慢。
- 推荐配置：我们建议使用80GB显存的GPU以获得更好的生成质量。
测试过的操作系统：Linux

🛠️ 依赖项和安装

首先克隆仓库：


git clone https://github.com/Tencent/HunyuanVideo-Avatar.git
cd HunyuanVideo-Avatar

Linux安装指南

我们推荐使用CUDA 12.4或11.8版本进行手动安装。

Conda的安装说明可在这里找到。


# 1. 创建conda环境
conda create -n HunyuanVideo-Avatar python==3.10.9

# 2. 激活环境
conda activate HunyuanVideo-Avatar

# 3. 使用conda安装PyTorch和其他依赖
# 对于CUDA 11.8
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=11.8 -c pytorch -c nvidia
# 对于CUDA 12.4
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia

# 4. 安装pip依赖
python -m pip install -r requirements.txt
# 5. 安装flash attention v2以加速（需要CUDA 11.8或更高版本）
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

如果在特定GPU类型上遇到浮点异常（核心转储），您可以尝试以下解决方案：


# 方案1：确保您已安装CUDA 12.4、CUBLAS>=12.4.5.8和CUDNN>=9.00（或直接使用我们的CUDA 12 docker镜像）
pip install nvidia-cublas-cu12==12.4.5.8
export LD_LIBRARY_PATH=/opt/conda/lib/python3.8/site-packages/nvidia/cublas/lib/

# 方案2：强制显式使用CUDA 11.8编译版本的PyTorch和所有其他包
pip uninstall -r requirements.txt  # 卸载所有包
pip install torch==2.4.0 --index-url https://download.pytorch.org/whl/cu118
pip install -r requirements.txt
pip install ninja
pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

此外，您也可以使用混元视频Docker镜像。使用以下命令拉取并运行docker镜像。


# 对于CUDA 12.4（更新以避免浮点异常）
docker pull hunyuanvideo/hunyuanvideo:cuda_12
docker run -itd --gpus all --init --net=host --uts=host --ipc=host --name hunyuanvideo --security-opt=seccomp=unconfined --ulimit=stack=67108864 --ulimit=memlock=-1 --privileged hunyuanvideo/hunyuanvideo:cuda_12
pip install gradio==3.39.0 diffusers==0.33.0 transformers==4.41.2

# 对于CUDA 11.8
docker pull hunyuanvideo/hunyuanvideo:cuda_11
docker run -itd --gpus all --init --net=host --uts=host --ipc=host --name hunyuanvideo --security-opt=seccomp=unconfined --ulimit=stack=67108864 --ulimit=memlock=-1 --privileged hunyuanvideo/hunyuanvideo:cuda_11
pip install gradio==3.39.0 diffusers==0.33.0 transformers==4.41.2

🧱 下载预训练模型

预训练模型的下载详情请参见这里。

🚀 多GPU并行推理

例如，要使用8个GPU生成视频，可以使用以下命令：


cd HunyuanVideo-Avatar

JOBS_DIR=$(dirname $(dirname "$0"))
export PYTHONPATH=./
export MODEL_BASE="./weights"
checkpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt

torchrun --nnodes=1 --nproc_per_node=8 --master_port 29605 hymm_sp/sample_batch.py \
    --input 'assets/test.csv' \
    --ckpt ${checkpoint_path} \
    --sample-n-frames 129 \
    --seed 128 \
    --image-size 704 \
    --cfg-scale 7.5 \
    --infer-steps 50 \
    --use-deepcache 1 \
    --flow-shift-eval-video 5.0 \
    --save-path ${OUTPUT_BASEPATH}

🔑 单GPU推理

例如，要使用1个GPU生成视频，可以使用以下命令：


cd HunyuanVideo-Avatar

JOBS_DIR=$(dirname $(dirname "$0"))
export PYTHONPATH=./

export MODEL_BASE=./weights
OUTPUT_BASEPATH=./results-single
checkpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states_fp8.pt

export DISABLE_SP=1 
CUDA_VISIBLE_DEVICES=0 python3 hymm_sp/sample_gpu_poor.py \
    --input 'assets/test.csv' \
    --ckpt ${checkpoint_path} \
    --sample-n-frames 129 \
    --seed 128 \
    --image-size 704 \
    --cfg-scale 7.5 \
    --infer-steps 50 \
    --use-deepcache 1 \
    --flow-shift-eval-video 5.0 \
    --save-path ${OUTPUT_BASEPATH} \
    --use-fp8 \
    --infer-min

低显存运行方案


cd HunyuanVideo-Avatar

JOBS_DIR=$(dirname $(dirname "$0"))
export PYTHONPATH=./

export MODEL_BASE=./weights
OUTPUT_BASEPATH=./results-poor

checkpoint_path=${MODEL_BASE}/ckpts/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states_fp8.pt

export CPU_OFFLOAD=1
CUDA_VISIBLE_DEVICES=0 python3 hymm_sp/sample_gpu_poor.py \
    --input 'assets/test.csv' \
    --ckpt ${checkpoint_path} \
    --sample-n-frames 129 \
    --seed 128 \
    --image-size 704 \
    --cfg-scale 7.5 \
    --infer-steps 50 \
    --use-deepcache 1 \
    --flow-shift-eval-video 5.0 \
    --save-path ${OUTPUT_BASEPATH} \
    --use-fp8 \
    --cpu-offload \
    --infer-min

运行Gradio服务器


cd HunyuanVideo-Avatar

bash ./scripts/run_gradio.sh

🔗 引用

如果您发现HunyuanVideo-Avatar对您的研究和应用有帮助，请使用以下BibTeX进行引用：


@misc{hu2025HunyuanVideo-Avatar,
      title={HunyuanVideo-Avatar: High-Fidelity Audio-Driven Human Animation for Multiple Characters}, 
      author={Yi Chen and Sen Liang and Zixiang Zhou and Ziyao Huang and Yifeng Ma and Junshu Tang and Qin Lin and Yuan Zhou and Qinglin Lu},
      year={2025},
      eprint={2505.20156},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/pdf/2505.20156}, 
}