HunyuanVideo-1.5

环境要求

• Python 环境，可执行 pip / torchrun 命令
• NVIDIA GPU（README 称仅 8.3B 参数、可在消费级 GPU 上流畅运行）
• 可访问 GitHub 与 PyPI 的网络（部分注意力库需从源码编译安装）
• 预先下载好的 HunyuanVideo-1.5 预训练模型权重路径

安装与启动步骤

1. 1获取项目代码

   把官方仓库克隆到本地并进入目录。README 正文的安装说明从 Step 2 开始，Step 1 未在节选中给出。

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

   复制

2. 2安装基础依赖

   安装 requirements.txt 中的全部依赖，并额外升级腾讯云 SDK 的 Python 包（README 指定了腾讯镜像源）。

   pip install -r requirements.txt
   pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python

   复制

3. 3安装 Flash Attention

   用于加速推理并降低显存占用。README 只给出官方仓库链接，未给出具体命令，请按该仓库说明安装。

4. 4安装 Flex-Block-Attent

   仅稀疏注意力（sparse attention）需要，可加快推理。需先克隆仓库并初始化子模块再编译安装。

   git clone https://github.com/Tencent-Hunyuan/flex-block-attn.git
   cd flex-block-attn
   git submodule update --init --recursive
   python3 setup.py install

   复制

5. 5安装 SageAttention

   启用 SageAttention 可加速推理，但会自动禁用 Flex-Block-Attention，二者不要同时指望生效。

   git clone https://github.com/cooper1637/SageAttention.git
   cd SageAttention
   export EXT_PARALLEL=4 NVCC_APPEND_FLAGS="--threads 8" MAX_JOBS=32
   python3 setup.py install

   复制

6. 6安装 SGL-Kernel

   用于在 transformer 中启用 fp8 gemm，README 指定了固定版本号 0.3.18。

   pip install sgl-kernel==0.3.18

   复制

7. 7运行推理生成视频

   用 torchrun 多卡并行执行 generate.py，通过环境变量控制加速与画质开关，需先准备好提示词、模型与输出路径。

   export N_INFERENCE_GPU=8
   export PROMPT="一只小猫在草地上奔跑"
   export IMAGE_PATH=/your/path/input.jpg
   export RESOLUTION=720p
   export ASPECT_RATIO=16:9
   export SEED=42
   export MODEL_PATH=/your/path/ckpts
   export OUTPUT_PATH=/your/path/outputs
   torchrun --nproc_per_node=$N_INFERENCE_GPU generate.py 
     --prompt "$PROMPT" 
     --image_path $IMAGE_PATH 
     --resolution $RESOLUTION 
     --aspect_ratio $ASPECT_RATIO 
     --seed $SEED 
     --rewrite $REWRITE 
     --cfg_distilled $CFG_DISTILLED 
     --enable_step_distill $ENABLE_STEP_DISTILL 
     --sparse_attn $SPARSE_ATTN --use_sageattn $SAGE_ATTN 
     --enable_cache $ENABLE_CACHE --cache_type $CACHE_TYPE 
     --overlap_group_offloading $OVERLAP_GROUP_OFFLOADING 
     --sr $ENABLE_SR --save_pre_sr_video 
     --output_path $OUTPUT_PATH 
     --model_path $MODEL_PATH

   复制

8. 8用 Diffusers 调用

   不跑本仓库脚本时，可直接用 Hugging Face Diffusers 的 HunyuanVideo15Pipeline 加载在线权重生成视频。

   import torch
   from diffusers import HunyuanVideo15Pipeline
   from diffusers.utils import export_to_video
   
   dtype = torch.bfloat16
   device = "cuda:0"
   prompt = "一只小猫在草地上奔跑"
   seed = 42
   
   pipe = HunyuanVideo15Pipeline.from_pretrained("hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v", torch_dtype=dtype)
   pipe.enable_model_cpu_offload()
   pipe.vae.enable_tiling()
   
   generator = torch.Generator(device=device).manual_seed(seed)
   
   video = pipe(
       prompt=prompt,
       generator=generator,
       num_frames=121,
       num_inference_steps=50,
   ).frames[0]
   
   export_to_video(video, "output.mp4", fps=24)

   复制

关键配置

如何确认成功

运行结束后，在 --output_path 指定目录可看到生成的视频文件；Diffusers 方式会导出 output.mp4。

常见问题

注意事项

• 不同模型的最优 CFG scale、flow shift、推理步数不同，请对照 README 的 Optimal Inference Configurations 表格设置。
• Flash Attention 只用于加速和降低显存，README 未给出安装命令，需按官方仓库文档自行安装。
• OVERLAP_GROUP_OFFLOADING 仅在启用 group offloading 时有效，会显著增加 CPU 内存占用但加快推理。
• 仓库还提供 train.py 训练脚本，支持单卡与 torchrun 多卡训练，可用 --pretrained_model_root 指定权重目录。