English

HunyuanVideo: A Systematic Framework For Large Video Generation Model

   

 

   

👋 加入我们的 <a href="https://github.com/Tencent-Hunyuan/HunyuanVideo/raw/main/assets/WECHAT.md" target="_blank">WeChat</a> 和 <a href="https://discord.gg/tv7FkG4Nwf" target="_blank">Discord</a>

---

本仓库包含了 HunyuanVideo 项目的 PyTorch 模型定义、预训练权重和推理/采样代码。参考我们的项目页面 project page 查看更多内容。

HunyuanVideo: A Systematic Framework For Large Video Generation Model

🔥🔥🔥 更新!!

• 2025年11月21日: 🎉 开源 HunyuanVideo-1.5, 新一代高效强大的视频基础模型。
• 2025年05月28日: 💃 开源 HunyuanVideo-Avatar, 腾讯混元语音数字人模型。
• 2025年05月09日: 🙆 开源 HunyuanCustom, 腾讯混元一致性视频生成模型。
• 2025年03月06日: 🌅 开源 HunyuanVideo-I2V, 支持高质量图生视频。
• 2025年01月13日: 📈 开源 Penguin Video 基准测试集 。
• 2024年12月18日: 🏃‍♂️ 开源 HunyuanVideo FP8 模型权重，节省更多 GPU 显存。
• 2024年12月17日: 🤗 HunyuanVideo已经集成到Diffusers中。
• 2024年12月03日: 🚀 开源 HunyuanVideo 多卡并行推理代码，由xDiT提供。
• 2024年12月03日: 👋 开源 HunyuanVideo 文生视频的推理代码和模型权重。

🎥 作品展示

🧩 社区贡献

如果您的项目中有开发或使用 HunyuanVideo，欢迎告知我们。

• ComfyUI (支持FP8推理、V2V和IP2V生成): ComfyUI-HunyuanVideoWrapper by Kijai

• ComfyUI-Native (ComfyUI官方原生支持): ComfyUI-HunyuanVideo by ComfyUI Official

• FastVideo (一致性蒸馏模型、滑动块注意力): FastVideo and Sliding Tile Attention by Hao AI Lab

• HunyuanVideo-gguf (GGUF、量化): HunyuanVideo-gguf by city96

• Enhance-A-Video (生成更高质量的视频): Enhance-A-Video by NUS-HPC-AI-Lab

• TeaCache (基于缓存的加速采样): TeaCache by Feng Liu

• HunyuanVideoGP (针对低性能GPU的版本): HunyuanVideoGP by DeepBeepMeep

• RIFLEx (视频时序外拓): RIFLEx by Tsinghua University

• HunyuanVideo Keyframe Control Lora (视频关键帧控制LoRA): hunyuan-video-keyframe-control-lora by dashtoon
• Sparse-VideoGen (基于高像素级保真度的视频加速生成): Sparse-VideoGen by University of California, Berkeley
• FramePack (将输入帧上下文打包到下一帧预测模型中用于视频生成): FramePack by Lvmin Zhang
• Jenga (加速采样): Jenga by DV Lab
• DCM (用于高效高质量视频生成的双专家一致性模型): DCM by Vchitect
• NaviCache (基于离线免校准的缓存加速采样): NaviCache by Zhejiang University

📑 开源计划

• HunyuanVideo (文生视频模型)
• [x] 推理代码
• [x] 模型权重
• [x] 多GPU序列并行推理（GPU 越多，推理速度越快）
• [x] Web Demo (Gradio)
• [x] Diffusers
• [x] FP8 量化版本
• [x] Penguin Video 基准测试集
• [x] ComfyUI
• HunyuanVideo (图生视频模型)
• [x] 推理代码
• [x] 模型权重

目录

• HunyuanVideo: A Systematic Framework For Large Video Generation Model
• 🎥 作品展示
• 🔥🔥🔥 更新!!
• 🧩 社区贡献
• 📑 开源计划
• 目录
• 摘要
• HunyuanVideo 的架构
• 🎉 亮点
  • 统一的图视频生成架构
  • MLLM 文本编码器
  • 3D VAE
  • Prompt 改写
• 📈 能力评估
• 📜 运行配置
• 🛠️ 安装和依赖
  • Linux 安装指引
• 🧱 下载预训练模型
• 🔑 单卡推理
  • 使用命令行
  • 运行gradio服务
  • 更多配置
• 🚀 使用 xDiT 实现多卡并行推理
  • 使用命令行
• 🚀 FP8 Inference
  • Using Command Line
• 🔗 BibTeX
• 致谢
• Star 趋势

---

摘要

HunyuanVideo 是一个全新的开源视频生成大模型，具有与领先的闭源模型相媲美甚至更优的视频生成表现。为了训练 HunyuanVideo，我们采用了一个全面的框架，集成了数据整理、图像-视频联合模型训练和高效的基础设施以支持大规模模型训练和推理。此外，通过有效的模型架构和数据集扩展策略，我们成功地训练了一个拥有超过 130 亿参数的视频生成模型，使其成为最大的开源视频生成模型之一。

我们在模型结构的设计上做了大量的实验以确保其能拥有高质量的视觉效果、多样的运动、文本-视频对齐和生成稳定性。根据专业人员的评估结果，HunyuanVideo 在综合指标上优于以往的最先进模型，包括 Runway Gen-3、Luma 1.6 和 3 个中文社区表现最好的视频生成模型。通过开源基础模型和应用模型的代码和权重，我们旨在弥合闭源和开源视频基础模型之间的差距，帮助社区中的每个人都能够尝试自己的想法，促进更加动态和活跃的视频生成生态。

HunyuanVideo 的架构

HunyuanVideo 是一个隐空间模型，训练时它采用了 3D VAE 压缩时间维度和空间维度的特征。文本提示通过一个大语言模型编码后作为条件输入模型，引导模型通过对高斯噪声的多步去噪，输出一个视频的隐空间表示。最后，推理时通过 3D VAE 解码器将隐空间表示解码为视频。

🎉 亮点

统一的图视频生成架构

HunyuanVideo 采用了 Transformer 和 Full Attention 的设计用于视频生成。具体来说，我们使用了一个“双流到单流”的混合模型设计用于视频生成。在双流阶段，视频和文本 token 通过并行的 Transformer Block 独立处理，使得每个模态可以学习适合自己的调制机制而不会相互干扰。在单流阶段，我们将视频和文本 token 连接起来并将它们输入到后续的 Transformer Block 中进行有效的多模态信息融合。这种设计捕捉了视觉和语义信息之间的复杂交互，增强了整体模型性能。

MLLM 文本编码器

过去的视频生成模型通常使用预训练的 CLIP 和 T5-XXL 作为文本编码器，其中 CLIP 使用 Transformer Encoder，T5 使用 Encoder-Decoder 结构。HunyuanVideo 使用了一个预训练的 Multimodal Large Language Model (MLLM) 作为文本编码器，它具有以下优势： * 与 T5 相比，MLLM 基于图文数据指令微调后在特征空间中具有更好的图像-文本对齐能力，这减轻了扩散模型中的图文对齐的难度； * 与 CLIP 相比，MLLM 在图像的细节描述和复杂推理方面表现出更强的能力； * MLLM 可以通过遵循系统指令实现零样本生成，帮助文本特征更多地关注关键信息。

由于 MLLM 是基于 Causal Attention 的，而 T5-XXL 使用了 Bidirectional Attention 为扩散模型提供更好的文本引导。因此，我们引入了一个额外的 token 优化器来增强文本特征。

3D VAE

我们的 VAE 采用了 CausalConv3D 作为 HunyuanVideo 的编码器和解码器，用于压缩视频的时间维度和空间维度，其中时间维度压缩 4 倍，空间维度压缩 8 倍，压缩为 16 channels。这样可以显著减少后续 Transformer 模型的 token 数量，使我们能够在原始分辨率和帧率下训练视频生成模型。

Prompt 改写

为了解决用户输入文本提示的多样性和不一致性的困难，我们微调了 Hunyuan-Large model 模型作为我们的 prompt 改写模型，将用户输入的提示词改写为更适合模型偏好的写法。

我们提供了两个改写模式：正常模式和导演模式。两种模式的提示词见这里。正常模式旨在增强视频生成模型对用户意图的理解，从而更准确地解释提供的指令。导演模式增强了诸如构图、光照和摄像机移动等方面的描述，倾向于生成视觉质量更高的视频。注意，这种增强有时可能会导致一些语义细节的丢失。

Prompt 改写模型可以直接使用 Hunyuan-Large 部署和推理. 我们开源了 prompt 改写模型的权重，见这里.

📈 能力评估

为了评估 HunyuanVideo 的能力，我们选择了四个闭源视频生成模型作为对比。我们总共使用了 1,533 个 prompt，每个 prompt 通过一次推理生成了相同数量的视频样本。为了公平比较，我们只进行了一次推理以避免任何挑选。在与其他方法比较时，我们保持了所有选择模型的默认设置，并确保了视频分辨率的一致性。视频根据三个标准进行评估：文本对齐、运动质量和视觉质量。在 60 多名专业评估人员评估后，HunyuanVideo 在综合指标上表现最好，特别是在运动质量方面表现较为突出。

模型	是否开源	时长	文本对齐	运动质量	视觉质量	综合评价	排序
HunyuanVideo (Ours)	✔	5s	61.8%	66.5%	95.7%	41.3%	1
国内模型 A (API)	✘	5s	62.6%	61.7%	95.6%	37.7%	2
国内模型 B (Web)	✘	5s	60.1%	62.9%	97.7%	37.5%	3
GEN-3 alpha (Web)	✘	6s	47.7%	54.7%	97.5%	27.4%	4
Luma1.6 (API)	✘	5s	57.6%	44.2%	94.1%	24.8%	5

📜 运行配置

下表列出了运行 HunyuanVideo 模型使用文本生成视频的推荐配置（batch size = 1）：

| 模型 | 分辨率

(height/width/frame) | 峰值显存 | |:--------------:|:--------------------------------:|:----------------:| | HunyuanVideo | 720px1280px129f | 60G | | HunyuanVideo | 544px960px129f | 45G |

• 本项目适用于使用 NVIDIA GPU 和支持 CUDA 的设备
• 模型在单张 80G GPU 上测试
• 运行 720px1280px129f 的最小显存要求是 60GB，544px960px129f 的最小显存要求是 45GB。
• 测试操作系统：Linux

🛠️ 安装和依赖

首先克隆 git 仓库:

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

Linux 安装指引

我们推荐使用 CUDA 12.4 或 11.8 的版本。

Conda 的安装指南可以参考这里。

# 1. Create conda environment
conda create -n HunyuanVideo python==3.10.9

# 2. Activate the environment
conda activate HunyuanVideo

# 3. Install PyTorch and other dependencies using conda
# For CUDA 11.8
conda install pytorch==2.6.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=11.8 -c pytorch -c nvidia
# For CUDA 12.4
conda install pytorch==2.6.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia

# 4. Install pip dependencies
python -m pip install -r requirements.txt

# 5. Install flash attention v2 for acceleration (requires CUDA 11.8 or above)
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

# 6. Install xDiT for parallel inference (It is recommended to use torch 2.6.0 and flash-attn 2.6.3)
python -m pip install xfuser==0.4.0

如果在特定 GPU 型号上遭遇 float point exception(core dump) 问题，可尝试以下方案修复：

#选项1：确保已正确安装 CUDA 12.4, CUBLAS>=12.4.5.8, 和 CUDNN>=9.00 (或直接使用我们提供的CUDA12镜像)
pip install nvidia-cublas-cu12==12.4.5.8
export LD_LIBRARY_PATH=/opt/conda/lib/python3.8/site-packages/nvidia/cublas/lib/

#选项2：强制显式使用 CUDA11.8 编译的 Pytorch 版本以及其他所有软件包
pip uninstall -r requirements.txt  # 确保卸载所有依赖包
pip uninstall -y xfuser
pip install torch==2.6.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

另外，我们提供了一个预构建的 Docker 镜像，可以使用如下命令进行拉取和运行。

# 用于 CUDA 12.4 (已更新避免 float point exception)
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

🧱 下载预训练模型

下载预训练模型参考这里。

🔑 单卡推理

我们在下表中列出了支持的高度/宽度/帧数设置。

分辨率	h/w=9:16	h/w=16:9	h/w=4:3	h/w=3:4	h/w=1:1
540p	544px960px129f	960px544px129f	624px832px129f	832px624px129f	720px720px129f
720p (推荐)	720p