中文阅读

HunyuanVideo：大型视频生成模型的系统性框架

👋 欢迎加入我们的微信和Discord

---

本仓库包含我们探索HunyuanVideo论文中的PyTorch模型定义、预训练权重以及推理/采样代码。更多可视化内容请访问我们的项目页面。

HunyuanVideo：大型视频生成模型的系统性框架

🔥🔥🔥 最新消息！！

• 2025年11月21日：🎉 我们发布了HunyuanVideo-1.5，这是一款高效且强大的新型基础模型。
• 2025年5月28日：💃 我们发布了基于HunyuanVideo的音频驱动型人物动画模型HunyuanVideo-Avatar。
• 2025年5月9日：🙆 我们发布了基于HunyuanVideo的多模态驱动型定制化视频生成架构HunyuanCustom。
• 2025年3月6日：🌅 我们发布了基于HunyuanVideo的图像转视频模型HunyuanVideo-I2V。
• 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]，以节省更多显存。
• 2024年12月17日：🤗 HunyuanVideo已集成到Diffusers中。
• 2024年12月7日：🚀 我们发布了由xDiT支持的HunyuanVideo并行推理代码。
• 2024年12月3日：👋 我们发布了HunyuanVideo的推理代码和模型权重。下载。

🎥 示例

🧩 社区贡献

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

• ComfyUI-Kijai（FP8推理、V2V和IP2V生成）：由Kijai开发的ComfyUI-HunyuanVideoWrapper
• ComfyUI-Native（原生支持）：由ComfyUI官方开发的ComfyUI-HunyuanVideo
• FastVideo（一致性蒸馏模型和滑动块注意力）：由Hao AI Lab开发的FastVideo和滑动块注意力。
• HunyuanVideo-gguf（GGUF版本和量化）：由city96开发的HunyuanVideo-gguf。
• Enhance-A-Video（免费提升生成视频质量）：由NUS-HPC-AI-Lab开发的Enhance-A-Video。
• TeaCache（基于缓存的加速）：由Feng Liu开发的TeaCache。
• HunyuanVideoGP（低配GPU版本）：由DeepBeepMeep开发的HunyuanVideoGP。
• RIFLEx（视频长度外推）：由清华大学开发的RIFLEx。
• HunyuanVideo关键帧控制LoRA：由dashtoon开发的hunyuan-video-keyframe-control-lora。
• Sparse-VideoGen（以高像素级保真度加速视频生成）：由加州大学伯克利分校开发的Sparse-VideoGen。
• FramePack（在下一代帧预测模型中打包输入帧上下文以用于视频生成）：由Lvmin Zhang开发的FramePack。
• Jenga（通过动态标记切割实现无需训练的高效视频生成）：由DV Lab开发的Jenga。
• DCM（双专家一致性模型，用于高效且高质量的视频生成）：由Vchitect开发的DCM。

📑 开源计划

• HunyuanVideo（文本到视频模型）
  • 推理
  • 检查点
  • 多GPU序列并行推理（在更多GPU上实现更快的推理速度）
  • Web演示（Gradio）
  • Diffusers
  • FP8量化权重
  • Penguin Video Benchmark
  • ComfyUI
• HunyuanVideo（图像到视频模型）
  • 推理
  • 检查点

目录

• HunyuanVideo：大规模视频生成模型的系统性框架
  • 🎥 演示
  • 🔥🔥🔥 新闻！！
  • 🧩 社区贡献
  • 📑 开源计划
  • Contents
  • 摘要
  • HunyuanVideo 总体架构
  • 🎉 HunyuanVideo 主要特性
    • 统一的图像与视频生成架构
    • MLLM 文本编码器
    • 3D VAE
    • 提示重写
  • 📈 对比
  • 📜 系统要求
  • 🛠️ 依赖与安装
    • Linux 安装指南
  • 🧱 下载预训练模型
  • 🔑 单 GPU 推理
    • 使用命令行
    • 运行 Gradio 服务器
    • 更多配置
  • 🚀 使用 xDiT 在多 GPU 上并行推理
    • 使用命令行
  • 🚀 FP8 推理
    • 使用命令行
  • 🔗 BibTeX
  • 致谢
  • Star 历史

---

摘要

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

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

HunyuanVideo 总体架构

HunyuanVideo 是在一种时空压缩的潜在空间上进行训练的，该潜在空间通过因果 3D VAE 进行压缩。文本提示使用大型语言模型进行编码，并作为条件输入。以高斯噪声和条件作为输入，我们的生成模型会输出一个潜在表示，随后通过 3D VAE 解码器将其解码为图像或视频。

🎉 HunyuanVideo 主要特性

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

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

MLLM 文本编码器

一些先前的文本到视频模型通常使用预训练的 CLIP 和 T5-XXL 作为文本编码器，其中 CLIP 使用 Transformer 编码器，而 T5 则采用编码器-解码器结构。相比之下，我们则利用一个具有仅解码器结构的预训练多模态大型语言模型（MLLM）作为文本编码器，它具有以下优势：(i) 与 T5 相比，经过视觉指令微调后的 MLLM 在特征空间中具有更好的图像-文本对齐能力，这有助于缓解扩散模型中遵循指令的难度；(ii) 与 CLIP 相比，MLLM 在图像细节描述和复杂推理方面表现出更强的能力；(iii) MLLM 可以通过遵循用户提示前缀的系统指令，充当零样本学习者，帮助文本特征更好地关注关键信息。此外，MLLM 基于因果注意力机制，而 T5-XXL 则采用双向注意力机制，后者能为扩散模型提供更好的文本指导。因此，我们引入了一个额外的双向标记精炼器来增强文本特征。

3D VAE

HunyuanVideo 训练了一个带有 CausalConv3D 的 3D VAE，用于将像素空间中的视频和图像压缩到紧凑的潜在空间中。我们将视频长度、空间和通道的压缩比分别设置为 4、8 和 16。这可以显著减少后续扩散 Transformer 模型所需的标记数量，从而使我们能够在原始分辨率和帧率下训练视频。

提示重写

为应对用户提供的提示在语言风格和长度上的差异，我们基于Hunyuan-Large模型微调了一个提示重写模型，用于将原始用户提示调整为更适合模型的格式。

我们提供了两种重写模式：普通模式和大师模式，可通过不同的提示词调用。相关提示词请参见此处。普通模式旨在增强视频生成模型对用户意图的理解，从而更准确地解析用户指令；而大师模式则会进一步强化对构图、光照和镜头运动等方面的描述，以生成更高视觉质量的视频。不过，这种侧重有时可能会导致部分语义细节的丢失。

提示重写模型可以直接使用Hunyuan-Large原版代码进行部署和推理。我们已在此处发布了提示重写模型的权重文件：Hugging Face链接。

📈 对比结果

为了评估HunyuanVideo的性能，我们选取了五款闭源视频生成模型作为强基准。总共使用了1,533个文本提示，在一次运行中生成了相同数量的视频样本。为确保公平性，我们仅进行了一次推理，避免了挑选最佳结果的情况。与基准方法对比时，我们保持所有选定模型的默认设置，并统一视频分辨率。评价主要从三个方面展开：文本一致性、动作质量和视觉质量。超过60位专业评估者参与了此次评测。值得注意的是，HunyuanVideo在整体表现上最为出色，尤其在动作质量方面表现突出。需要说明的是，本次评测基于Hunyuan Video的高质量版本，与目前发布的快速版本有所不同。

模型	开源	时长	文本一致性	动作质量	视觉质量	综合得分	排名
		HunyuanVideo（我们的模型）	✔	5s				61.8%	66.5%	95.7%	41.3%	1
CNTopA（API）	✘	5s	62.6%	61.7%	95.6%	37.7%	2
CNTopB（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
CNTopC（Web）	✘	5s	48.4%	47.2%	96.3%	24.6%	6

📜 系统要求

下表展示了运行HunyuanVideo模型（批量大小=1）生成视频所需的硬件和软件要求：

模型	设置 (高/宽/帧率)	GPU峰值显存
HunyuanVideo	720px×1280px×129f	60GB
HunyuanVideo	544px×960px×129f	45GB

• 需要支持CUDA的NVIDIA显卡。
  • 该模型已在单块80G显卡上测试通过。
  • 最低要求：生成720px×1280px×129f视频时，GPU显存需至少60GB；生成544px×960px×129f视频时，需至少45GB。
  • 推荐配置：为获得更好的生成效果，建议使用80GB显存的GPU。
• 测试操作系统：Linux

🛠️ 依赖与安装

首先克隆仓库：

git clone https://github.com/Tencent-Hunyuan/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.6.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=11.8 -c pytorch -c nvidia
# 对于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. 安装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以支持并行推理（建议配合PyTorch 2.6.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.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

此外，HunyuanVideo还提供了预构建的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 推理

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

分辨率	高/宽=9:16	高/宽=16:9	高/宽=4:3	高/宽=3:4	高/宽=1:1
540p	544px960px129f	960px544px129f	624px832px129f	832px624px129f	720px720px129f
720p（推荐）	720px1280px129f	1280px720px129f	1104px832px129f	832px1104px129f	960px960px129f

使用命令行

cd HunyuanVideo

python3 sample_video.py \
    --video-size 720 1280 \
    --video-length 129 \
    --infer-steps 50 \
    --prompt "一只猫在草地上行走，写实风格。" \
    --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

更多配置

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

参数	默认值	描述
--prompt	无	视频生成的文本提示
--video-size	720 1280	生成视频的尺寸
--video-length	129	生成视频的时长
--infer-steps	50	采样步数
--embedded-cfg-scale	6.0	内置分类器自由引导尺度
--flow-shift	7.0	流匹配调度器的偏移因子
--flow-reverse	假	如果为真，则从 t=1 到 t=0 进行学习/采样
--seed	无	用于生成视频的随机种子，若未指定则自动初始化随机种子
--use-cpu-offload	假	使用 CPU offload 加载模型以节省更多内存，对于高分辨率视频生成是必要的
--save-path	./results	保存生成视频的路径

🚀 xDiT 在多 GPU 上的并行推理

xDiT 是一个用于多 GPU 集群上的扩散 Transformer (DiT) 的可扩展推理引擎。 它已成功为多种 DiT 模型提供了低延迟的并行推理解决方案，包括 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 "一只猫在草地上行走，写实风格。" \
    --flow-reverse \
    --seed 42 \
    --ulysses-degree 8 \
    --ring-degree 1 \
    --save-path ./results

您可以调整 --ulysses-degree 和 --ring-degree 来控制并行配置，以获得最佳性能。有效的并行配置如下表所示。

支持的并行配置（点击展开）

--video-size	--video-length	--ulysses-degree x --ring-degree	--nproc_per_node
1280 720 或 720 1280	129	8x1,4x2,2x4,1x8	8
1280 720 或 720 1280	129	1x5	5
1280 720 或 720 1280	129	4x1,2x2,1x4	4
1280 720 或 720 1280	129	3x1,1x3	3
1280 720 或 720 1280	129	2x1,1x2	2
1104 832 或 832 1104	129	4x1,2x2,1x4	4
1104 832 或 832 1104	129	3x1,1x3	3
1104 832 或 832 1104	129	2x1,1x2	2
960 960	129	6x1,3x2,2x3,1x6	6
960 960	129	4x1,2x2,1x4	4
960 960	129	3x1,1x3	3
960 960	129	1x2,2x1	2
960 544 或 544 960	129	6x1,3x2,2x3,1x6	6
960 544 或 544 960	129	4x1,2x2,1x4	4
960 544 或 544 960	129	3x1,1x3	3
960 544 或 544 960	129	1x2,2x1	2
832 624 或 624 832	129	4x1,2x2,1x4	4
624 832 或 624 832	129	3x1,1x3	3
832 624 或 624 832	129	2x1,1x2	2
720 720	129	1x5	5
720 720	129	3x1,1x3	3

1280x720（129 帧，50 步）在 8xGPU 上的延迟（秒）
1	2	4	8
1904.08	934.09（2.04倍）	514.08（3.70倍）	337.58（5.64倍）

🚀 FP8 推理

使用 FP8 量化权重的 HunyuanVideo 可以节省约 10GB 的 GPU 内存。您可以从 Huggingface 下载 权重 和 权重缩放值。

使用命令行

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

cd HunyuanVideo

DIT_CKPT_PATH={FP8权重路径}/{权重名称}_fp8.pt

python3 sample_video.py \
    --dit-weight ${DIT_CKPT_PATH} \
    --video-size 1280 720 \
    --video-length 129 \
    --infer-steps 50 \
    --prompt "一只猫在草地上行走，写实风格。" \
    --seed 42 \
    --embedded-cfg-scale 6.0 \
    --flow-shift 7.0 \
    --flow-reverse \
    --use-cpu-offload \
    --use-fp8 \
    --save-path ./results

🔗 BibTeX

如果您发现 HunyuanVideo 对您的研究和应用有所帮助，请使用以下 BibTeX 格式引用：

@article{kong2024hunyuanvideo,
  title={Hunyuanvideo: 大规模视频生成模型的系统性框架},
  author={Kong, Weijie and Tian, Qi and Zhang, Zijian and Min, Rox and Dai, Zuozhuo and Zhou, Jin and Xiong, Jiangfeng and Li, Xin and Wu, Bo and Zhang, Jianwei and others},
  journal={arXiv 预印本 arXiv:2412.03603},
  year={2024}
}

致谢

我们衷心感谢 SD3、FLUX、Llama、LLaVA、Xtuner、diffusers 和 HuggingFace 等开源项目的所有贡献者，感谢他们开放的研究与探索。

此外，我们还要感谢腾讯混元多模态团队在文本编码器方面的帮助。

GitHub 星标历史

HunyuanVideo 快速上手指南

HunyuanVideo 是腾讯混元团队开源的大型视频生成基础模型，支持文生视频（Text-to-Video），在视觉质量、运动多样性和文本对齐方面表现卓越。本指南将帮助开发者快速完成环境配置并运行推理。

环境准备

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

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• Python: 3.8 或更高版本
• GPU: NVIDIA 显卡，显存建议 24GB 及以上（生成 720p 视频）。若显存不足，可使用 FP8 量化版本或多卡并行推理。
• CUDA: 11.8 或 12.x
• Git & Git LFS: 用于克隆代码库和下载大模型文件

安装步骤

1. 克隆项目代码

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

2. 创建虚拟环境并安装依赖

推荐使用 Conda 管理环境。为方便国内用户，这里提供使用清华源加速安装的方案。

# 创建虚拟环境
conda create -n hunyuan python=3.10 -y
conda activate hunyuan

# 安装 PyTorch (根据实际 CUDA 版本调整，此处以 12.1 为例)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 安装其他依赖 (使用国内镜像源加速)
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：如果项目中未直接提供 requirements.txt，请参考仓库根目录下的安装说明手动安装列出的核心库（如 transformers, diffusers, accelerate 等）。目前该模型已集成到 diffusers 库中，也可直接通过 pip install diffusers 使用。

3. 下载预训练模型

模型权重较大，请使用 Git LFS 下载或通过 Hugging Face 镜像站下载。

方式 A：使用 Git LFS (需配置代理或镜像)

# 确保已安装 git-lfs
git lfs install
git lfs pull

注：模型文件通常位于 ckpts 目录，具体下载链接请参考 ckpts/README.md。

方式 B：手动下载 (推荐国内用户) 访问 Hugging Face 模型页 或使用国内镜像站（如 ModelScope）下载 hunyuan-video-t2v-720p 文件夹，并将其放置在项目指定的目录下（通常为 ckpts/）。

若使用 FP8 量化版本（节省显存），请下载 mp_rank_00_model_states_fp8.pt。

基本使用

方式一：命令行推理 (单卡)

这是最基础的用法，适合测试模型是否正常运行。

python infer.py \
    --ckpt_path ./ckpts/hunyuan-video-t2v-720p \
    --prompt "A cat walking on the street, realistic style, high quality" \
    --save_path ./outputs/sample.mp4 \
    --height 720 \
    --width 1280 \
    --num_frames 129

• --ckpt_path: 模型权重文件夹路径。
• --prompt: 生成视频的描述词（支持英文，建议使用详细描述）。
• --height / --width: 输出分辨率。
• --num_frames: 生成帧数（通常为 129 帧，对应约 5 秒视频）。

显存优化提示：如果您的显存小于 24GB，请添加 --use_fp8 参数（需提前下载 FP8 权重）或减少 --height 和 --num_frames。

方式二：启动 Web 演示界面 (Gradio)

项目提供了基于 Gradio 的本地 Web 界面，方便直观地调整参数和生成视频。

python gradio_server.py \
    --ckpt_path ./ckpts/hunyuan-video-t2v-720p

运行后，终端会显示一个本地地址（如 http://127.0.0.1:7860），在浏览器中打开即可使用。

方式三：使用 Diffusers 库 (Python API)

由于 HunyuanVideo 已集成至 diffusers，您可以直接使用 Python 代码调用：

import torch
from diffusers import HunyuanVideoPipeline

# 加载管道
pipe = HunyuanVideoPipeline.from_pretrained(
    "tencent/HunyuanVideo", 
    torch_dtype=torch.bfloat16
).to("cuda")

# 生成视频
prompt = "A drone view of a snowy mountain landscape, cinematic lighting"
output = pipe(
    prompt=prompt,
    height=720,
    width=1280,
    num_frames=129,
    guidance_scale=7.5,
    num_inference_steps=50
).frames[0]

# 保存视频
from diffusers.utils import export_to_video
export_to_video(output, "output.mp4", fps=24)

---

进阶提示：

• 多卡并行加速：若拥有多张 GPU，可使用 xDiT 进行并行推理以提升速度，参考命令：python parallel_inference.py ...。
• 提示词优化：模型内置了 Prompt Rewrite 功能，若生成的视频效果不佳，可尝试启用提示词重写模块自动优化描述。