腾讯HunyuanVideo是一款强大的开源视频生成基础模型，拥有超过130亿参数，性能比肩甚至超越顶尖闭源模型。该模型框架全面，涵盖数据管理、图文视频联合训练及高效基础设施，旨在提升视觉质量、运动多样性、文本视频对齐和生成稳定性。文章详细介绍了HunyuanVideo的模型设计理念，并提供了从环境配置、代码克隆、依赖安装到模型下载和部署的详尽步骤，包括PyTorch、Flash Attention、xDiT的安装，以及MLLM和CLIP文本编码器的配置。最后，通过Gradio服务器展示了模型生成视频的效果和不同参数下的耗时与质量变化。

🌟 HunyuanVideo作为腾讯推出的开源视频生成基础模型，拥有130亿+参数，规模领先，其性能在多项评测中优于Runway Gen-3、Luma 1.6等先进模型，展现出高视觉质量、运动多样性、文本-视频对齐和生成稳定性。

🛠️ 模型部署流程详尽，包括配置Ubuntu22.04环境（cuda12.4, python3.10.9），安装Miniconda3，克隆HunyuanVideo仓库，创建并激活conda虚拟环境，安装PyTorch 2.4.0及相关依赖，以及Flash Attention v2和xDiT等关键组件。

📚 模型下载与配置涉及使用`huggingface-cli`下载HunyuanVideo主模型，并下载MLLM（如`llava-llama-3-8b`）和CLIP（`clip-vit-large-patch14`）作为文本编码器，通过`preprocess_text_encoder_tokenizer_utils.py`脚本进行预处理，以优化模型加载和推理效率。

🚀 通过运行`gradio_server.py --flow-reverse`可启动Gradio服务器，用户可通过修改提示词和调整步数、分辨率等参数来生成不同风格和质量的视频，文章展示了不同设置下的生成时间和文件大小，为实际应用提供了参考。

⚠️ 在部署过程中需注意PyTorch与torchvision版本匹配问题，并可能遇到“File name too long”错误，可通过优化提示词长度来规避。

一、模型介绍

HunyuanVideo 是腾讯推出的一款开源视频生成基础模型，拥有超过 130 亿个参数，是当前规模最大的开源视频生成模型。

它在视频生成方面表现出与领先的闭源模型相当甚至优于领先闭源模型的性能。HunyuanVideo 具有一个全面的框架，集成了多项关键贡献，包括数据管理、图像-视频联合模型训练以及旨在促进大规模模型训练和推理的高效基础设施。

团队进行了广泛的实验并实施了一系列有针对性的设计，以确保高视觉质量、运动多样性、文本-视频对齐和生成稳定性。根据专业的人体测评结果，混元视频的表现优于之前最先进的模型，包括 Runway Gen-3、Luma 1.6 和 3 款性能最好的中国视频生成模型。

HunyuanVideo 整体设计

HunyuanVideo 在时空上进行了训练 压缩的潜在空间，通过因果 3D VAE 进行压缩。

二、模型部署步骤

基础环境

Ubuntu	22.04
cuda	12.4
python	3.10.9
NVIDIA corporation	A100 SXM4

1.更新基础的软件包

查看系统版本信息

#查看系统的版本信息，包括ID（如ubuntu、centos等）、版本号、名称、版本号ID等cat /etc/os-release

配置国内源

apt 配置阿里源

将以下内容粘贴进文件中

deb http://mirrors.aliyun.com/debian/ bullseye main non-free contribdeb-src http://mirrors.aliyun.com/debian/ bullseye main non-free contribdeb http://mirrors.aliyun.com/debian-security/ bullseye-security maindeb-src http://mirrors.aliyun.com/debian-security/ bullseye-security maindeb http://mirrors.aliyun.com/debian/ bullseye-updates main non-free contribdeb-src http://mirrors.aliyun.com/debian/ bullseye-updates main non-free contribdeb http://mirrors.aliyun.com/debian/ bullseye-backports main non-free contribdeb-src http://mirrors.aliyun.com/debian/ bullseye-backports main non-free contrib

2.基础Miniconda3环境

查看系统是否有 miniconda 的环境

conda -V

显示如上输出，即安装了相应环境，若没有 miniconda 的环境，通过以下方法进行安装

#下载 Miniconda 安装脚本wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh#运行 Miniconda 安装脚本bash Miniconda3-latest-Linux-x86_64.sh#初次安装需要激活 base 环境source ~/.bashrc

按下回车键（enter）

输入 yes

输入 yes

安装成功如下图所示

3.克隆仓库并进入项目

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

4.创建虚拟环境

创建并激活虚拟环境

# 1. Create conda environmentconda create -n HunyuanVideo python==3.10.9# 2. Activate the environmentconda activate HunyuanVideo

5.安装pytorch环境

conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia

6.下载依赖

python -m pip install -r requirements.txt

7.装 Flash Attention v2 （版本 2.6.3）

python -m pip install ninja

出现successfully installed 为安装成功

python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

8.安装xDiT以进行并行推理（建议使用torch 2.4.0和flash-attn 2.6.3）

python -m pip install xfuser==0.4.0

9.下载HunyuanVideo模型

要下载 HunyuanVideo 模型，请先安装 huggingface-cli。

python -m pip install "huggingface_hub[cli]"

然后使用以下命令下载模型：

# Switch to the directory named 'HunyuanVideo'cd HunyuanVideo# Use the huggingface-cli tool to download HunyuanVideo model in HunyuanVideo/ckpts dir.# The download time may vary from 10 minutes to 1 hour depending on network conditions.hf download tencent/HunyuanVideo --local-dir ./ckpts

出现下载拒绝是因为没有加载密钥

vim download.py

from huggingface_hub import snapshot_download, loginimport osdef download_hunyuan_video(local_dir="./ckpts", token="替换为实际密钥"):    try:        # 使用提供的密钥登录        login(token=token)          # 下载模型仓库到指定目录        print(f"开始下载 tencent/HunyuanVideo 到 {local_dir}...")        snapshot_download(            repo_id="tencent/HunyuanVideo",            local_dir=local_dir,            local_dir_use_symlinks=False,  # 避免使用符号链接，直接下载文件            max_workers=4  # 并发下载线程数        )        print("下载完成！")      except Exception as e:        print(f"下载过程中出现错误: {str(e)}")    finally:        # 退出登录（可选）        login(token=None)if __name__ == "__main__":    # 调用下载函数    download_hunyuan_video()

下载完成

10.下载文本编码器

混元视频使用 MLLM 模型和 CLIP 模型作为文本编码器。

1.MLLM模型（text_encoder文件夹）

混元视频支持不同的 MLLM（包括混元 MLLM 和开源 MLLM 模型）。现阶段，我们还没有发布混元 MLLM。我们建议社区用户使用 Xtuer 提供的 llava-llama-3-8b，可以通过以下命令下载

cd HunyuanVideo/ckptshuggingface-cli download xtuner/llava-llama-3-8b-v1_1-transformers --local-dir ./llava-llama-3-8b-v1_1-transformers

下载完成会显示匹配所有文件100%

以及出现文件下载目录

为了节省模型加载的 GPU 内存资源，我们将语言模型的各个部分分离成 llava-llama-3-8b和text_encoder

cd HunyuanVideopython hyvideo/utils/preprocess_text_encoder_tokenizer_utils.py --input_dir ckpts/llava-llama-3-8b-v1_1-transformers --output_dir ckpts/text_encoder

加载完成会显示Loading checkpoint shards: 100%

如果显示 no nms 则是torch 与torchvision版本不匹配

首先检查 PyTorch 和 torchvision 的安装情况：

pip list | grep torchpip list | grep torchvision

卸载当前版本

# 若用 condaconda uninstall -y torchvision# 若用 pippip uninstall -y torchvision

安装0.21.0版本

# conda 安装（需匹配 CUDA 版本，以 12.4 为例）conda install torchvision==0.21.0 -c pytorch -c nvidia# 或 pip 安装（更稳定，避免 conda 源问题）pip install torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cu124

2.CLIP模型（text_encoder_2文件夹）

我们使用 OpenAI 提供的 CLIP 作为另一个文本编码器，社区中的用户可以通过以下命令下载该模型

cd HunyuanVideo/ckptshuggingface-cli download openai/clip-vit-large-patch14 --local-dir ./text_encoder_2

运行Gradio服务器

python3 gradio_server.py --flow-reverse

三、模型页面

通过开放端口来直接访问页面

通过选择不同的提示词来生成不同的视频

提示词：A cat walks on the grass, realistic style.步数设置为10步

参数设置

生成的结果显示，以及耗费时间

花费时间约1:15分钟 ，大小为809KB

步数设置为50步时间约为6分钟 ，大小为953.22KB

修改参数为最高1280x720 (16:9, 720p)，5s(129f)，50步

时间约为50分钟，大小为2.64MB

提示词不要设置太长，会导致错误File name too long错误