HunyuanVideo：腾讯混元开源视频生成大模型安装与使用指南

官方信息

项目背景

HunyuanVideo 是腾讯混元大模型团队于2024年11月开源的视频生成模型，参数量达130亿（13B），是当时全球规模最大的开源视频生成模型。在公开评测中，HunyuanVideo 在画面质量、运动连贯性、提示词遵循度等方面全面超越了此前的Open-Sora、Mochi、CogVideoX等开源模型，成为开源视频生成的新标杆。

与闭源的Sora、Runway相比，HunyuanVideo虽然在超长视频（60秒以上）和复杂物理模拟上还有差距，但在5-15秒的短视频生成上已经非常接近商用水平。更重要的是，它完全开源（采用Tencent Hunyuan Community License），支持本地部署、微调、二次开发，这对视频创作者和研究者来说价值巨大。

HunyuanVideo 采用 3D VAE + 双文本编码器（LLaMA + CLIP）+ DiT 架构，原生支持720p分辨率生成，最长可生成15秒视频（129帧）。同时支持文生视频（T2V）和图生视频（I2V）两种模式，社区已经有了ComfyUI节点、Diffusers Pipeline、量化版本等多种部署方式。

核心特性

• 130亿参数：当前开源视频模型中参数量最大，画面细节丰富
• 720p高清输出：原生支持1280×720分辨率，是开源模型中少数能出高清视频的
• 最长15秒视频：支持129帧生成，远超多数开源模型的4-5秒
• 文生视频+图生视频：两种模式都支持，可从图片出发做动态化
• 双文本编码器：LLaMA-2 + CLIP联合编码，中英文提示词都理解
• 运动残影优化：采用3D VAE和时序注意力，运动模糊比其他开源模型少
• 多种部署方案：官方源码、Diffusers、ComfyUI、FP8/GGUF量化版齐全

环境要求

详细部署步骤

方式一：官方源码部署（推荐研究用途）

1. 系统依赖

   sudo apt update
   sudo apt install git python3.10 ffmpeg libsm6 libxext6 -y

2. 克隆仓库

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

3. 创建虚拟环境

   conda create -n hunyuan python=3.10 -y
   conda activate hunyuan
   # 或venv
   python -m venv venv && source venv/bin/activate

4. 安装PyTorch 2.4+

   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

5. 安装项目依赖

   pip install -r requirements.txt
   pip install flash-attn --no-build-isolation  # 可选，但能加速

6. 下载模型权重
   从HuggingFace或ModelScope下载：

   # 创建目录
   mkdir -p ckpts/hunyuan-video-t2i-128px
   
   # 方式A：HuggingFace
   pip install "huggingface_hub[cli]"
   huggingface-cli download tencent/HunyuanVideo --local-dir ckpts/hunyuan-video-t2i-128px
   
   # 方式B：ModelScope（国内推荐）
   pip install modelscope
   modelscope download --model tencent/HunyuanVideo --local_dir ckpts/hunyuan-video-t2i-128px

   总下载量约60GB，包括DiT权重、VAE、文本编码器等。

7. 文生视频推理

   python sample_video.py \
     --video_size 1280 720 \
     --video_length 129 \
     --infer_steps 50 \
     --prompt "一只熊猫在竹林中吃竹子，阳光透过树叶洒下，电影级画面" \
     --save_path ./results/panda.mp4 \
     --denoise_type "flow_uniform" \
     --seed 42

   参数说明：

   • --video_size 1280 720：分辨率
   • --video_length 129：帧数（129帧约5秒@25fps）
   • --infer_steps 50：采样步数，越高越精细但越慢
   • --save_path：输出路径
8. 图生视频推理

   python sample_i2v.py \
     --video_size 848 480 \
     --video_length 121 \
     --infer_steps 50 \
     --prompt "海浪轻轻拍打沙滩，夕阳西下" \
     --img_path ./input_photo.jpg \
     --save_path ./results/wave.mp4

方式二：Diffusers Pipeline（最简洁）

1. 安装依赖

   pip install -U diffusers transformers accelerate ftfy sentencepiece

2. FP8量化推理（24GB显存可跑）

   import torch
   from diffusers import HunyuanVideoPipeline, HunyuanVideoTransformer3DModel
   from diffusers.utils import export_to_video
   
   # 加载FP8量化版Transformer
   transformer = HunyuanVideoTransformer3DModel.from_pretrained(
       "tencent/HunyuanVideo",
       subfolder="transformer",
       torch_dtype=torch.bfloat16,
       variant="fp8"
   )
   
   pipe = HunyuanVideoPipeline.from_pretrained(
       "tencent/HunyuanVideo",
       transformer=transformer,
       torch_dtype=torch.bfloat16
   )
   pipe.enable_model_cpu_offload()  # 24GB显存必开
   
   # 生成视频
   output = pipe(
       prompt="A cat wearing sunglasses, surfing on a ocean wave, cinematic",
       height=720,
       width=1280,
       num_frames=129,
       num_inference_steps=30,
       generator=torch.Generator("cuda").manual_seed(42)
   ).frames[0]
   
   export_to_video(output, "output.mp4", fps=25)

方式三：ComfyUI 部署（推荐GUI方式）

1. 安装ComfyUI-HunyuanVideo节点

   cd ComfyUI/custom_nodes
   git clone https://github.com/kijai/ComfyUI-HunyuanVideoWrapper.git
   cd ComfyUI-HunyuanVideoWrapper
   pip install -r requirements.txt

2. 下载模型到ComfyUI对应目录

   # DiT模型 → ComfyUI/models/diffusion_models/
   # VAE → ComfyUI/models/vae/
   # 文本编码器（LLaMA+CLIP）→ ComfyUI/models/text_encoders/

3. 重启ComfyUI，加载官方工作流模板即可出视频。

方式四：多卡推理（80GB显存不够时）

# 自动模型并行，跨多张GPU
pip install accelerate
python sample_video.py \
  --video_size 1280 720 \
  --video_length 129 \
  --prompt "..." \
  --save_path result.mp4 \
  --parallel \  # 自动数据并行
  --gpus 0,1   # 用两张GPU

使用方法

提示词技巧

• 用自然语言描述场景，不要堆砌关键词
• 加上镜头语言："镜头推进"、"航拍视角"、"慢动作"、"环绕拍摄"
• 加上风格："电影质感"、"吉卜力风格"、"纪录片风格"、"赛博朋克"
• 描述运动："树叶随风飘动"、"水流缓缓"、"人物微笑着转头"
• 中文提示词支持良好，可直接用中文描述

生成时间参考

常见问题（FAQ）

Q1: 24GB显存能跑HunyuanVideo吗？

可以，但必须用FP8量化版+CPU offload，且分辨率降到480p（848×480），帧数81-121帧。单条视频生成约15-20分钟。如果要跑720p原版，需要至少80GB显存（A100）。

Q2: 生成的视频闪烁/不连贯怎么办？

1）增加采样步数到50步以上；2）提示词中减少剧烈运动描述；3）使用更稳定的seed；4）VAE解码后可加帧插值（RIFE）做平滑。

Q3: 模型下载太慢怎么办？

国内用户用ModelScope下载，速度可达10MB/s以上。也可以用hf-mirror.com镜像站。

Q4: 支持多长的视频？

官方最长支持15秒（129帧@25fps）。社区有扩展到161帧甚至更长的方案，但会增加显存占用和生成时间。

Q5: 可以商用吗？

HunyuanVideo采用Tencent Hunyuan Community License，非商用免费，商用需要联系腾讯授权。个人学习和研究完全免费。

跳转链接

• GitHub 仓库：https://github.com/Tencent-Hunyuan/HunyuanVideo
• HuggingFace模型页：https://huggingface.co/tencent/HunyuanVideo
• ModelScope模型页：https://modelscope.cn/models/tencent/HunyuanVideo
• 混元官网：https://hunyuan.tencent.com
• ComfyUI节点：https://github.com/kijai/ComfyUI-HunyuanVideoWrapper