HunyuanVideo：腾讯开源的 130 亿参数视频生成基座模型｜部署与使用全指南

项目仓库： https://github.com/Tencent-Hunyuan/HunyuanVideo

技术报告：arXiv:2412.03603 · 维护方：腾讯混元 · 语言：Python · 框架：PyTorch · 形态：命令行推理 + Gradio + Diffusers · 最新版本：13B 开源文生视频模型

1 项目简介

HunyuanVideo（混元视频）是腾讯混元团队开源的大型视频生成基座模型，总参数超过 130 亿，是目前开源社区中规模最大的视频生成模型之一。官方在 1533 条提示词的一次性评测中，综合排名超过 Runway Gen-3、Luma 1.6 等闭源模型。

技术上，HunyuanVideo 采用统一的图像-视频生成架构（双流转单流混合 Transformer）、MLLM 文本编码器、Causal 3D VAE（时间/空间/通道压缩比 4/8/16），并提供 Prompt Rewrite 提示词改写模型。官方同时发布了 FP8 量化权重、多卡 xDiT 并行推理、Gradio Web 演示，以及 ComfyUI 原生集成。

1.1 核心信息一览

1.2 适用场景

• 研究开源视频生成模型，需要完整权重与推理代码。
• 在多卡 GPU 集群上跑 720p 文生视频。
• 通过 Diffusers / ComfyUI 把混元视频接入自己的生成工作流。
• 二次开发：HunyuanVideo-I2V（图生视频）、HunyuanCustom（自定义驱动）、HunyuanVideo-Avatar（数字人）等衍生模型。

1.3 能力边界（官方口径）

• 720p（1280×720，129 帧）单卡峰值显存 60 GB；544p（960×544，129 帧）约 45 GB。官方测试在 80 GB 显卡上，推荐 80 GB 显存。
• 视频长度固定 129 帧（约 5 秒）；分辨率档位见第 8 节表格。
• 仅支持 Linux；官方测试操作系统为 Linux。

2 功能特性

• 统一图像-视频架构：双流（视频/文本独立编码）+ 单流（融合）混合 Transformer。
• MLLM 文本编码器：用 Decoder-Only 多模态大模型替代 CLIP+T5，图文对齐更好。
• 3D VAE：CausalConv3D，时间压缩 4×、空间 8×、通道 16×。
• Prompt Rewrite：Normal / Master 两种模式，把用户提示词改写成模型偏好风格。
• FP8 权重：发布 FP8 量化版以节省显存。
• 多卡并行：基于 xDiT（USP 序列并行），8 卡可线性加速。
• Gradio Web：一行命令拉起本地 Web 界面。
• Diffusers / ComfyUI：官方已合入 Hugging Face Diffusers；ComfyUI 有原生支持与 Kijai 封装。

3 官方界面预览

项目提供 Gradio Web 界面与官方 Playground：

• 本地 Gradio：python3 gradio_server.py --flow-reverse
• 官方在线 Playground：video.hunyuan.tencent.com

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• CUDA 12.6 或 11.8（官方推荐）。
• conda、Python 3.10.9。
• PyTorch 2.7.1（cu118 或 cu126）。
• flash-attention v2.8.3、xfuser 0.4.0（多卡并行）。

5.2 硬件建议

5.3 端口

6 方式一：官方 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

7 方式二：源码安装与单卡推理

# 1. 克隆
git clone https://github.com/Tencent-Hunyuan/HunyuanVideo
cd HunyuanVideo

# 2. conda 环境
conda create -n HunyuanVideo python==3.10.9
conda activate HunyuanVideo

# 3. 安装 PyTorch（CUDA 11.8）
pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu118
# 或 CUDA 12.6
# pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu126

# 4. 依赖
python -m pip install -r requirements.txt

# 5. flash-attention v2
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.8.3

# 6. xDiT 多卡并行
python -m pip install xfuser==0.4.0

模型权重下载见仓库 ckpts/README.md，从 Hugging Face 拉取。

7.1 单卡推理

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

7.2 多卡并行（8 卡示例）

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

7.3 启动 Gradio

python3 gradio_server.py --flow-reverse
# 自定义端口
SERVER_NAME=0.0.0.0 SERVER_PORT=8081 python3 gradio_server.py --flow-reverse

8 支持的分辨率与关键参数

8.1 分辨率档位（129 帧）

8.2 命令行参数

9 常用运维命令

# 查看 GPU
nvidia-smi

# 查看已下载权重
ls -lh ckpts/

# 查看输出
ls -lh results/

# 查看容器
docker ps | grep hunyuanvideo
docker logs -f hunyuanvideo

10 常见故障排查

• 浮点异常 / core dump：官方给出两种方案：(1) 升级 CUDA 12.4 + CUBLAS≥12.4.5.8 + CUDNN≥9.0；(2) 强制用 CUDA 11.8 版 PyTorch 重装。也可直接用官方 Docker 镜像。
• 显存不足：加 --use-cpu-offload；降低分辨率到 544p；使用 FP8 权重。
• 多卡起不来：确认 --ulysses-degree × --ring-degree = --nproc_per_node，并与支持的并行配置表匹配。
• flash-attention 编译失败：需 CUDA 11.8 以上；可先不装 flash-attn 用基础注意力。
• 模型下载慢：从 Hugging Face 镜像或 ModelScope 拉取。

11 风险与合规说明

• 模型权重遵循仓库 LICENSE；商用前需核对腾讯混元模型许可与训练数据合规性。
• 生成视频内容责任由使用者承担；不得用于违法、侵权、深度伪造。
• 衍生模型（I2V、Avatar、Custom）各有独立仓库与许可，需分别核对。
• 官方 Playground 与开源自部署是两条线，开源版不提供 SLA。

本文基于官方 README 与技术报告整理，仅供学习与部署参考；以仓库最新说明为准。