Hunyuanvideo

🚀 混元视频（HunyuanVideo）

混元视频（HunyuanVideo）是一个用于大视频生成模型训练的系统框架，它能够生成高质量的视频，在视频生成领域具有卓越的性能，为开源视频生成模型的发展提供了有力支持。

本仓库包含用于探索混元视频（HunyuanVideo）的PyTorch模型定义、预训练权重以及推理/采样代码。你可以在我们的项目页面上查看更多可视化效果。

HunyuanVideo: A Systematic Framework For Large Video Generation Model Training

✨ 主要特性

统一的图像和视频生成架构

混元视频（HunyuanVideo）引入了Transformer设计，并采用全注意力机制进行统一的图像和视频生成。具体而言，我们使用“双流到单流”的混合模型设计进行视频生成。在双流阶段，视频和文本令牌通过多个Transformer块独立处理，使每个模态能够在不干扰的情况下学习自己合适的调制机制。在单流阶段，我们将视频和文本令牌连接起来，并将它们输入到后续的Transformer块中，以实现有效的多模态信息融合。这种设计捕捉了视觉和语义信息之间的复杂交互，提高了整体模型性能。

多模态大语言模型（MLLM）文本编码器

一些先前的文本到视频模型通常使用预训练的CLIP和T5 - XXL作为文本编码器，其中CLIP使用Transformer编码器，T5使用编码器 - 解码器结构。相比之下，我们使用具有仅解码器结构的预训练多模态大语言模型（MLLM）作为文本编码器，这具有以下优点：

1. 与T5相比，经过视觉指令微调的MLLM在特征空间中具有更好的图像 - 文本对齐，这减轻了扩散模型中指令遵循的难度。
2. 与CLIP相比，MLLM在图像细节描述和复杂推理方面表现出更出色的能力。
3. MLLM可以通过遵循用户提示前的系统指令作为零样本学习器，帮助文本特征更加关注关键信息。此外，MLLM基于因果注意力，而T5 - XXL使用双向注意力，这为扩散模型提供了更好的文本指导。因此，我们引入了一个额外的双向令牌精炼器来增强文本特征。

3D变分自编码器（VAE）

混元视频（HunyuanVideo）使用因果3D卷积（CausalConv3D）训练了一个3D变分自编码器（VAE），将像素空间的视频和图像压缩到一个紧凑的潜在空间中。我们分别将视频长度、空间和通道的压缩比设置为4、8和16。这可以显著减少后续扩散Transformer模型的令牌数量，使我们能够在原始分辨率和帧率下训练视频。

提示重写

为了解决用户提供提示的语言风格和长度的可变性问题，我们对[混元大模型（Hunyuan - Large）](https://github.com/Tencent/Tencent - Hunyuan - Large)进行微调，作为提示重写模型，以将原始用户提示调整为模型偏好的提示。

我们提供两种重写模式：普通模式和专家模式，可以使用不同的提示调用。提示信息见此处。普通模式旨在增强视频生成模型对用户意图的理解，便于更准确地解释提供的指令。专家模式增强了对构图、照明和相机运动等方面的描述，倾向于生成具有更高视觉质量的视频。然而，这种强调有时可能会导致一些语义细节的丢失。

提示重写模型可以使用[混元大模型（Hunyuan - Large）的原始代码](https://github.com/Tencent/Tencent - Hunyuan - Large)直接部署和推理。我们在[此处](https://huggingface.co/Tencent/HunyuanVideo - PromptRewrite)发布了提示重写模型的权重。

📦 安装指南

克隆仓库

首先，克隆本仓库：

git clone https://github.com/tencent/HunyuanVideo
cd HunyuanVideo

Linux安装指南

我们建议手动安装时使用CUDA 12.4或11.8版本。Conda的安装说明见此处。

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

# 2. 激活环境
conda activate HunyuanVideo

# 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

# 6. 安装xDiT以进行并行推理（建议使用torch 2.4.0和flash - attn 2.6.3）
python -m pip install xfuser==0.4.0

如果在特定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 uninstall -y xfuser
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
pip install xfuser==0.4.0

此外，混元视频（HunyuanVideo）还提供了预构建的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

# 对于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

💻 使用示例

单GPU推理

支持的分辨率设置

我们支持的高度/宽度/帧数设置如下表所示：

使用命令行

cd HunyuanVideo

python3 sample_video.py \
    --video - size 720 1280 \
    --video - length 129 \
    --infer - steps 50 \
    --prompt "A cat walks on the grass, realistic style." \
    --flow - reverse \
    --use - cpu - offload \
    --save - path ./results

运行Gradio服务器

python3 gradio_server.py --flow - reverse

# 手动设置SERVER_NAME和SERVER_PORT
# SERVER_NAME=0.0.0.0 SERVER_PORT=8081 python3 gradio_server.py --flow - reverse

更多配置

我们列出了一些更有用的配置，方便使用：

多GPU并行推理（使用xDiT）

[xDiT](https://github.com/xdit - project/xDiT)是一个用于多GPU集群上扩散Transformer（DiTs）的可扩展推理引擎。它已成功为多种DiTs模型提供了低延迟并行推理解决方案，包括mochi - 1、CogVideoX、Flux.1、SD3等。本仓库采用了统一序列并行性（USP） API进行混元视频（HunyuanVideo）模型的并行推理。

使用命令行

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

cd HunyuanVideo

torchrun --nproc_per_node=8 sample_video.py \
    --video - size 1280 720 \
    --video - length 129 \
    --infer - steps 50 \
    --prompt "A cat walks on the grass, realistic style." \
    --flow - reverse \
    --seed 42 \
    --ulysses - degree 8 \
    --ring - degree 1 \
    --save - path ./results

你可以更改--ulysses - degree和--ring - degree来控制并行配置，以获得最佳性能。支持的并行配置如下表所示：

FP8推理

使用具有FP8量化权重的混元视频（HunyuanVideo），可以节省约10GB的GPU内存。你可以从Huggingface下载[权重](https://huggingface.co/tencent/HunyuanVideo/blob/main/hunyuan - video - t2v - 720p/transformers/mp_rank_00_model_states_fp8.pt)和[权重缩放](https://huggingface.co/tencent/HunyuanVideo/blob/main/hunyuan - video - t2v - 720p/transformers/mp_rank_00_model_states_fp8_map.pt)。

使用命令行

这里，你必须显式指定FP8权重路径。例如，使用FP8权重生成视频，可以使用以下命令：

cd HunyuanVideo

DIT_CKPT_PATH={PATH_TO_FP8_WEIGHTS}/{WEIGHT_NAME}_fp8.pt

python3 sample_video.py \
    --dit - weight ${DIT_CKPT_PATH} \
    --video - size 1280 720 \
    --video - length 129 \
    --infer - steps 50 \
    --prompt "A cat walks on the grass, realistic style." \
    --seed 42 \
    --embedded - cfg - scale 6.0 \
    --flow - shift 7.0 \
    --flow - reverse \
    --use - cpu - offload \
    --use - fp8 \
    --save - path ./results

📚 详细文档

摘要

我们推出了混元视频（HunyuanVideo），这是一个新颖的开源视频基础模型，在视频生成方面的性能与领先的闭源模型相当，甚至更优。为了训练混元视频（HunyuanVideo）模型，我们采用了几种关键技术进行模型学习，包括数据整理、图像 - 视频联合模型训练，以及旨在促进大规模模型训练和推理的高效基础设施。此外，通过有效的模型架构和数据集扩展策略，我们成功训练了一个参数超过130亿的视频生成模型，使其成为所有开源模型中规模最大的模型。

我们进行了广泛的实验，并实施了一系列有针对性的设计，以确保高视觉质量、运动多样性、文本 - 视频对齐和生成稳定性。根据专业人工评估结果，混元视频（HunyuanVideo）优于之前的最先进模型，包括Runway Gen - 3、Luma 1.6和3个表现出色的中文视频生成模型。通过发布基础模型及其应用的代码和权重，我们旨在缩小闭源和开源视频基础模型之间的差距。这一举措将使社区中的每个人都能够尝试他们的想法，促进一个更加动态和活跃的视频生成生态系统。

混元视频（HunyuanVideo）整体架构

混元视频（HunyuanVideo）在时空压缩的潜在空间中进行训练，该空间通过因果3D变分自编码器（VAE）进行压缩。文本提示使用大语言模型进行编码，并用作条件。以高斯噪声和条件作为输入，我们的生成模型产生一个输出潜在表示，然后通过3D变分自编码器（VAE）解码器解码为图像或视频。

比较

为了评估混元视频（HunyuanVideo）的性能，我们从闭源视频生成模型中选择了五个强大的基线模型。总共使用了1533个文本提示，一次运行中使用混元视频（HunyuanVideo）生成了相同数量的视频样本。为了进行公平比较，我们只进行了一次推理，避免挑选结果。与基线方法比较时，我们对所有选定模型保持默认设置，确保视频分辨率一致。根据三个标准评估视频：文本对齐、运动质量和视觉质量。超过60名专业评估人员进行了评估。值得注意的是，混元视频（HunyuanVideo）表现出最佳的整体性能，尤其在运动质量方面表现出色。请注意，评估基于混元视频（HunyuanVideo）的高质量版本，这与当前发布的快速版本不同。

要求

以下表格显示了运行混元视频（HunyuanVideo）模型（批量大小 = 1）生成视频的要求：

• 需要支持CUDA的NVIDIA GPU。
  • 该模型在单个80G GPU上进行了测试。
  • 最低要求：720px1280px129f分辨率下，最低需要60GB的GPU内存；544px960px129f分辨率下，最低需要45GB的GPU内存。
  • 推荐配置：为了获得更好的生成质量，建议使用80GB内存的GPU。
• 测试的操作系统：Linux

下载预训练模型

下载预训练模型的详细信息见此处。

🔧 技术细节

新闻动态

• 2025年1月13日：📈 我们发布了企鹅视频基准测试（Penguin Video Benchmark）。
• 2024年12月18日：🏃‍♂️ 我们发布了混元视频（HunyuanVideo）的[FP8模型权重](https://huggingface.co/tencent/HunyuanVideo/blob/main/hunyuan - video - t2v - 720p/transformers/mp_rank_00_model_states_fp8.pt)，以节省更多的GPU内存。
• 2024年12月17日：🤗 混元视频（HunyuanVideo）已集成到Diffusers中。
• 2024年12月7日：🚀 我们发布了由[xDiT](https://github.com/xdit - project/xDiT)支持的混元视频（HunyuanVideo）并行推理代码。
• 2024年12月3日：👋 我们发布了混元视频（HunyuanVideo）的推理代码和模型权重。下载

开源计划

• 混元视频（文本到视频模型）
  • [x] 推理
  • [x] 检查点
  • [x] 多GPU序列并行推理（在更多GPU上实现更快的推理速度）
  • [x] Web演示（Gradio）
  • [x] Diffusers
  • [x] FP8量化权重
  • [x] 企鹅视频基准测试
  • [x] ComfyUI
• [混元视频（图像到视频模型）](https://github.com/Tencent/HunyuanVideo - I2V)
  • [x] 推理
  • [x] 检查点

📄 许可证

本项目采用腾讯混元社区许可证（tencent - hunyuan - community）。

BibTeX

如果你发现混元视频（HunyuanVideo）对你的研究和应用有用，请使用以下BibTeX进行引用：

@misc{kong2024hunyuanvideo,
      title={HunyuanVideo: A Systematic Framework For Large Video Generative Models}, 
      author={Weijie Kong, Qi Tian, Zijian Zhang, Rox Min, Zuozhuo Dai, Jin Zhou, Jiangfeng Xiong, Xin Li, Bo Wu, Jianwei Zhang, Kathrina Wu, Qin Lin, Aladdin Wang, Andong Wang, Changlin Li, Duojun Huang, Fang Yang, Hao Tan, Hongmei Wang, Jacob Song, Jiawang Bai, Jianbing Wu, Jinbao Xue, Joey Wang, Junkun Yuan, Kai Wang, Mengyang Liu, Pengyu Li, Shuai Li, Weiyan Wang, Wenqing Yu, Xinchi Deng, Yang Li, Yanxin Long, Yi Chen, Yutao Cui, Yuanbo Peng, Zhentao Yu, Zhiyu He, Zhiyong Xu, Zixiang Zhou, Zunnan Xu, Yangyu Tao, Qinglin Lu, Songtao Liu, Dax Zhou, Hongfa Wang, Yong Yang, Di Wang, Yuhong Liu, and Jie Jiang, along with Caesar Zhong},
      year={2024},
      archivePrefix={arXiv preprint arXiv:2412.03603},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2412.03603}, 
}

致谢

我们感谢[SD3](https://huggingface.co/stabilityai/stable - diffusion - 3 - medium)、[FLUX](https://github.com/black - forest - labs/flux)、[Llama](https://github.com/meta - llama/llama)、[LLaVA](https://github.com/haotian - liu/LLaVA)、Xtuner、diffusers和HuggingFace仓库的贡献者，感谢他们的开放研究和探索。此外，我们也感谢腾讯混元多模态团队在文本编码器方面提供的帮助。