HuggingFace镜像/hunyuan_video
模型介绍文件和版本分析
下载使用量0

注意

  • 本模型仓代码，是针对此开源链接进行的适配 https://github.com/Tencent-Hunyuan/HunyuanVideo

一、准备运行环境

表 1 版本配套表

配套版本环境准备指导
Python3.10/3.11-
torch2.9.0-

注意：

  • 该模型也支持torch 2.1.0等版本

1.1 获取CANN&MindIE安装包&环境准备

  • 设备支持 Atlas 800I A2(8*64G)推理设备：支持的卡数最小为1
  • Atlas 800I A2(8*64G)
  • 环境准备指导

1.2 CANN安装

# 增加软件包可执行权限，{version}表示软件版本号，{arch}表示CPU架构，{soc}表示昇腾AI处理器的版本。
chmod +x ./Ascend-cann-toolkit_{version}_linux-{arch}.run
chmod +x ./Ascend-cann-kernels-{soc}_{version}_linux.run
# 校验软件包安装文件的一致性和完整性
./Ascend-cann-toolkit_{version}_linux-{arch}.run --check
./Ascend-cann-kernels-{soc}_{version}_linux.run --check
# 安装
./Ascend-cann-toolkit_{version}_linux-{arch}.run --install
./Ascend-cann-kernels-{soc}_{version}_linux.run --install

# 设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh

1.3 MindIE安装

# 增加软件包可执行权限，{version}表示软件版本号，{arch}表示CPU架构。
chmod +x ./Ascend-mindie_${version}_linux-${arch}.run
./Ascend-mindie_${version}_linux-${arch}.run --check

# 方式一：默认路径安装
./Ascend-mindie_${version}_linux-${arch}.run --install
# 设置环境变量
cd /usr/local/Ascend/mindie && source set_env.sh

# 方式二：指定路径安装
./Ascend-mindie_${version}_linux-${arch}.run --install-path=${AieInstallPath}
# 设置环境变量
cd ${AieInstallPath}/mindie && source set_env.sh

1.4 Torch_npu安装

下载 pytorch_v{pytorchversion}_py{pythonversion}.tar.gz

tar -xzvf pytorch_v{pytorchversion}_py{pythonversion}.tar.gz
# 解压后，会有whl包
pip install torch_npu-{pytorchversion}.xxxx.{arch}.whl

二、下载权重

2.1 权重及配置文件说明

  1. text_encoder权重链接:
   https://huggingface.co/xtuner/llava-llama-3-8b-v1_1-transformers
  1. text_encoder_2权重链接
   https://huggingface.co/openai/clip-vit-large-patch14
  1. hunyuan-model权重链接：
   https://huggingface.co/tencent/HunyuanVideo
  1. 权重目录如下所示
HunyuanVideo
  ├──README.md
  ├──hunyuan-video-t2v-720p
  │  ├──transformers
  │  ├──vae
  ├──llava-llama-3-8b-v1_1-transformers
  ├──clip-vit-large-patch14

三、HunYuanVideo使用

当前支持的分辨率：

分辨率h/w=9:16h/w=9:16h/w=4:3h/w=3:4h/w=1:1
720P720x12801280x7201104x832832x1104960x960

当前支持的卡数：1、2、3、4、6、8、16

3.1 下载到本地

   git clone https://modelers.cn/MindIE/hunyuan_video.git
   cd hunyuan_video

3.2 修改text_encoder的权重

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

修改之后的权重目录如下所示：

HunyuanVideo
  ├──README.md
  ├──hunyuan-video-t2v-720p
  │  ├──transformers
  │  ├──vae
  ├──text_encoder
  ├──clip-vit-large-patch14

3.3 环境依赖安装

pip3 install -r requirements.txt

3.4 单卡性能测试

3.4.1 等价优化

执行命令：

export TOKENIZERS_PARALLELISM=false
export ALGO=0
python sample_video.py \
      --model-base HunyuanVideo \
      --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
      --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
      --text-encoder-path HunyuanVideo/text_encoder \
      --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
      --model-resolution "720p" \
      --video-size 720 1280 \
      --video-length 129 \
      --infer-steps 50 \
      --prompt "A cat walks on the grass, realistic style." \
      --seed 42 \
      --flow-reverse \
      --num-videos 1 \
      --device_id 0 \
      --save-path ./results

参数说明：

  • ALGO: A2环境设置为1；A3环境设置为0
  • model-base: 权重路径，包含vae、text_encoder、Tokenizer、Transformer和Scheduler五个模型的配置文件及权重。
  • dit-weight: dit的权重路径
  • vae-path: VAE的权重路径
  • text-encoder-path: text_encoder的权重路径
  • text-encoder-2-path: text_encoder_2的权重路径
  • model-resolution: 分辨率
  • video-size: 生成视频的高和宽
  • video-length: 总帧数
  • infer-steps: 推理步数
  • prompt: 文本提示词
  • seed: 随机种子
  • num-videos: 每个prompt生成多少个视频，该参数和batch有关，800I A2(64G)机器上，该参数的大小受显存限制
  • device_id：单卡推理时，可设置NPU id
  • save-path: 生成的视频的保存路径

3.4.2 算法优化

执行命令：

export TOKENIZERS_PARALLELISM=false
export ALGO=0
python sample_video.py \
      --model-base HunyuanVideo \
      --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
      --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
      --text-encoder-path HunyuanVideo/text_encoder \
      --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
      --model-resolution "720p" \
      --video-size 720 1280 \
      --video-length 129 \
      --infer-steps 50 \
      --prompt "A cat walks on the grass, realistic style." \
      --seed 42 \
      --flow-reverse \
      --num-videos 1 \
      --device_id 0 \
      --use_cache \
      --use_cache_double \
      --use-cpu-offload \
      --save-path ./results

参数说明：

  • ALGO: A2环境设置为1；A3环境设置为0
  • model-base: 权重路径，包含vae、text_encoder、Tokenizer、Transformer和Scheduler五个模型的配置文件及权重。
  • dit-weight: dit的权重路径
  • vae-path: VAE的权重路径
  • text-encoder-path: text_encoder的权重路径
  • text-encoder-2-path: text_encoder_2的权重路径
  • model-resolution: 分辨率
  • video-size: 生成视频的高和宽
  • video-length: 总帧数
  • infer-steps: 推理步数
  • prompt: 文本提示词
  • seed: 随机种子
  • num-videos: 每个prompt生成多少个视频，该参数和batch有关，800I A2(64G)机器上，该参数的大小受显存限制
  • device_id：单卡推理时，可设置NPU id
  • use_cache: 使能单流block算法优化
  • use_cache_double: 使能双流block算法优化
  • save-path: 生成的视频的保存路径

3.5 8卡性能测试

3.5.1 等价优化

执行命令：

export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export TASK_QUEUE_ENABLE=2
export CPU_AFFINITY_CONF=1
export TOKENIZERS_PARALLELISM=false
export ALGO=0
torchrun --nproc_per_node=8 sample_video.py \
      --model-base HunyuanVideo \
      --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
      --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
      --text-encoder-path HunyuanVideo/text_encoder \
      --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
      --model-resolution "720p" \
      --video-size 720 1280 \
      --video-length 129 \
      --infer-steps 50 \
      --prompt "A cat walks on the grass, realistic style." \
      --seed 42 \
      --flow-reverse \
      --ulysses-degree 8 \
      --ring-degree 1 \
      --vae-parallel \
      --num-videos 1 \
      --save-path ./results

参数说明：

  • ALGO: A2环境设置为1；A3环境设置为0
  • nproc_per_node: 并行推理的总进程数。
  • model-base: 权重路径，包含vae、text_encoder、Tokenizer、Transformer和Scheduler五个模型的配置文件及权重。
  • dit-weight: dit的权重路径
  • vae-path: VAE的权重路径
  • text-encoder-path: text_encoder的权重路径
  • text-encoder-2-path: text_encoder_2的权重路径
  • model-resolution: 分辨率
  • video-size: 生成视频的高和宽
  • video-length: 总帧数
  • infer-steps: 推理步数
  • prompt: 文本提示词
  • seed: 随机种子
  • vae-parallel: vae部分使能并行，目前只支持8卡、16卡并行时使用
  • num-videos: 每个prompt生成多少个视频，该参数和batch有关，800I A2(64G)机器上，该参数的大小受显存限制
  • save-path: 生成的视频的保存路径

3.5.2 算法优化

一、使用attentioncache 执行命令：

export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export TASK_QUEUE_ENABLE=2
export CPU_AFFINITY_CONF=1
export TOKENIZERS_PARALLELISM=false
export ALGO=0
torchrun --nproc_per_node=8 sample_video.py \
      --model-base HunyuanVideo \
      --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
      --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
      --text-encoder-path HunyuanVideo/text_encoder \
      --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
      --model-resolution "720p" \
      --video-size 720 1280 \
      --video-length 129 \
      --infer-steps 50 \
      --prompt "A cat walks on the grass, realistic style." \
      --seed 42 \
      --flow-reverse \
      --ulysses-degree 8 \
      --ring-degree 1 \
      --vae-parallel \
      --use_attentioncache \
      --num-videos 1 \
      --save-path ./results

参数说明：

  • ALGO: A2环境设置为1；A3环境设置为0
  • nproc_per_node: 并行推理的总进程数。
  • model-base: 权重路径，包含vae、text_encoder、Tokenizer、Transformer和Scheduler五个模型的配置文件及权重。
  • dit-weight: dit的权重路径
  • vae-path: VAE的权重路径
  • text-encoder-path: text_encoder的权重路径
  • text-encoder-2-path: text_encoder_2的权重路径
  • model-resolution: 分辨率
  • video-size: 生成视频的高和宽
  • video-length: 总帧数
  • infer-steps: 推理步数
  • prompt: 文本提示词
  • seed: 随机种子
  • vae-parallel: vae部分使能并行
  • use_attentioncache: 使能attentioncache策略
  • num-videos: 每个prompt生成多少个视频，该参数和batch有关，800I A2(64G)机器上，该参数的大小受显存限制
  • save-path: 生成的视频的保存路径

3.6 16卡性能测试

3.6.1 等价优化

执行命令：

export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export TASK_QUEUE_ENABLE=2
export CPU_AFFINITY_CONF=1
export TOKENIZERS_PARALLELISM=false
export ALGO=0
torchrun --nproc_per_node=16 sample_video.py \
      --model-base HunyuanVideo \
      --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
      --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
      --text-encoder-path HunyuanVideo/text_encoder \
      --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
      --model-resolution "720p" \
      --video-size 720 1280 \
      --video-length 129 \
      --infer-steps 50 \
      --prompt "A cat walks on the grass, realistic style." \
      --seed 42 \
      --flow-reverse \
      --ulysses-degree 8 \
      --ring-degree 2 \
      --vae-parallel \
      --save-path ./results

参数说明：

  • ALGO: A2环境设置为1；A3环境设置为0
  • nproc_per_node: 并行推理的总进程数。
  • model-base: 权重路径，包含vae、text_encoder、Tokenizer、Transformer和Scheduler五个模型的配置文件及权重。
  • dit-weight: dit的权重路径
  • vae-path: VAE的权重路径
  • text-encoder-path: text_encoder的权重路径
  • text-encoder-2-path: text_encoder_2的权重路径
  • model-resolution: 分辨率
  • video-size: 生成视频的高和宽
  • video-length: 总帧数
  • infer-steps: 推理步数
  • prompt: 文本提示词
  • seed: 随机种子
  • vae-parallel: vae部分使能并行，目前只支持8卡、16卡并行时使用
  • save-path: 生成的视频的保存路径

3.6.2 算法优化

执行命令：

export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export TASK_QUEUE_ENABLE=2
export CPU_AFFINITY_CONF=1
export TOKENIZERS_PARALLELISM=false
export ALGO=0
torchrun --nproc_per_node=16 sample_video.py \
      --model-base HunyuanVideo \
      --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
      --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
      --text-encoder-path HunyuanVideo/text_encoder \
      --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
      --model-resolution "720p" \
      --video-size 720 1280 \
      --video-length 129 \
      --infer-steps 50 \
      --prompt "A cat walks on the grass, realistic style." \
      --seed 42 \
      --flow-reverse \
      --ulysses-degree 8 \
      --ring-degree 2 \
      --vae-parallel \
      --use_attentioncache \
      --save-path ./results

参数说明：

  • ALGO: A2环境设置为1;A3环境设置为0
  • nproc_per_node: 并行推理的总进程数。
  • model-base: 权重路径，包含vae、text_encoder、Tokenizer、Transformer和Scheduler五个模型的配置文件及权重。
  • dit-weight: dit的权重路径
  • vae-path: VAE的权重路径
  • text-encoder-path: text_encoder的权重路径
  • text-encoder-2-path: text_encoder_2的权重路径
  • model-resolution: 分辨率
  • video-size: 生成视频的高和宽
  • video-length: 总帧数
  • infer-steps: 推理步数
  • prompt: 文本提示词
  • seed: 随机种子
  • vae-parallel: vae部分使能并行，目前只支持8卡、16卡并行时使用
  • use_attentioncache: 使能cache算法
  • save-path: 生成的视频的保存路径

四、量化功能支持

本项目新增量化功能，支持权重 8 位（w8）与激活 8 位 / 16 位（a8/a16）的量化组合，可减少模型显存占用并保持推理性能

4.1 安装量化工具msModelSlim

参考官方README

  1. git clone下载msit仓代码
  2. 进入到msit/msmodelslim的目录 cd msit/msmodelslim；并在进入的msmodelslim目录下，运行安装脚本 bash install.sh

4.2 生成量化模型

4.2.1 量化参数说明

参数含义可选值默认值
--quant_save_dir量化模型保存目录-./hunyuan_quant_weights
--quant_mode量化模式w8a8（权重8位+激活8位）、w8a16（权重8位+激活16位）w8a8
--is_dynamic是否启用动态量化（激活值动态计算量化参数）（默认False，加此参数表示启用）
--w_sym权重是否使用对称量化（默认False，加此参数表示启用）
--act_method激活量化方法（Label-Free场景）1（min-max）、2（histogram）、3（auto-mixed，LLM推荐）3
--disable_quant_layers不量化的层名称列表-["time_in.mlp.0", "time_in.mlp.2"]

4.2.2 生成命令示例（w8a8动态量化）

export TOKENIZERS_PARALLELISM=false
export ALGO=0

python quantization/quant.py \
    --model-base HunyuanVideo \
    --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
    --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
    --text-encoder-path HunyuanVideo/text_encoder \
    --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
    --quant_save_dir ./quant_w8a8_dynamic \
    --quant_mode w8a8 \
    --is_dynamic \
    --w_sym \
    --device_id 0 # 指定0卡

执行后，quant_w8a8_dynamic目录下会生成两个文件：

  • quant_model_description_w8a8_dynamic.json：量化配置描述文件（包含量化位宽、层映射等元信息）
  • quant_model_weight_w8a8_dynamic.safetensors：量化后的权重文件（采用safe tensor格式，兼容Hugging Face生态）

4.3 安装量化模型推理工具NNAL神经网络加速库和torch_atb

4.3.1 获取安装包

  • 支持设备：Atlas 800I A2
  • 环境准备指导

4.3.2 安装

# 增加软件包可执行权限，{version}表示软件版本号，{arch}表示CPU架构。
chmod +x Ascend-cann-nnal_<version>_linux-<arch>.run
# 默认路径安装:
./Ascend-cann-nnal_<version>_linux-<arch>.run --install --torch_atb
# 配置环境变量:
source ${HOME}/Ascend/nnal/atb/set_env.sh

4.4 使用量化模型推理

使用量化模型进行推理时，需在原有sample_video.py命令中添加--quant_desc_path参数，指向量化描述文件（quant_model_description_*.json）路径，该路径需要是绝对路径，其余参数与原生模型推理一致。

4.4.1 单卡量化推理示例（以等价优化为例）

export TOKENIZERS_PARALLELISM=false
export ALGO=0
export file_absolute_path="your local quant description file absolute path"

python sample_video.py \
      --model-base HunyuanVideo \
      --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
      --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
      --text-encoder-path HunyuanVideo/text_encoder \
      --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
      --model-resolution "720p" \
      --video-size 720 1280 \
      --video-length 129 \
      --infer-steps 50 \
      --prompt "A cat walks on the grass, realistic style." \
      --seed 42 \
      --flow-reverse \
      --num-videos 1 \
      --device_id 0 \
      --save-path ./t2v_w8a8_dynamic_results
      --quant_desc_path ${file_absolute_path}

4.4.2 多卡量化推理示例（以8卡等价优化为例）

export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export TASK_QUEUE_ENABLE=2
export CPU_AFFINITY_CONF=1
export TOKENIZERS_PARALLELISM=false
export ALGO=0

export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
torchrun --nproc_per_node=8 --master-port 29503 sample_video.py \
      --model-base /HunyuanVideo \
      --dit-weight HunyuanVideo/hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt \
      --vae-path HunyuanVideo/hunyuan-video-t2v-720p/vae \
      --text-encoder-path HunyuanVideo/text_encoder \
      --text-encoder-2-path HunyuanVideo/clip-vit-large-patch14 \
      --model-resolution "720p" \
      --video-size 720 1280 \
      --video-length 81 \
      --infer-steps 50 \
      --prompt "A cat walks on the grass, realistic style." \
      --seed 42 \
      --flow-reverse \
      --ulysses-degree 8 \
      --ring-degree 1 \
      --vae-parallel \
      --num-videos 1 \
      --save-path ./t2v_w8a8_dynamic_results \
      --quant_desc_path ${file_absolute_path}

4.4.3 量化推理参数说明

  • --quant_desc_path：量化描述文件路径（指定该参数后自动启用量化推理）
  • 其他参数与原生模型推理一致（见3.3~3.5节）

4.5 量化功能注意事项

  1. 量化模型仅支持NPU设备，需确保环境已正确安装CANN和MindIE（见1.1~1.4节）。
  2. 动态量化（--is_dynamic True）适用于激活值分布波动较大的场景，静态量化（--is_dynamic False）需提前通过校准数据计算激活范围。
  3. 若需调整量化层范围，可通过--disable_quant_layers参数指定不量化的层（如对精度敏感的时间嵌入层）。
  4. 量化模型的精度指标（如VBench得分）与原生模型略有差异，具体请以实际推理结果为准。

五、精度指标

我们使用prompts.txt测试了seed42-46五组种子的视频，并测试了vbench并取平均值，6个指标如下：

分辨率h*wdynamic_degreesubject_consistencyimaging_qualityaesthetic_qualityoverall_consistencymotion_smoothness
720*12800.15160.97740.52830.60480.2910.9931

注：量化模型的精度指标可参考上述数据，实际偏差在±5%以内。

六、支持的并行配置

当前支持的并行参数：

--video-size--ulysses-degree x --ring-degree--nproc_per_node--video-length
720 1280 or 1280 7208x216129
1104 832 or 832 11048x216129
960 9608x216129
720 1280 or 1280 7208x18129
1104 832 or 832 11048x18129
960 9608x18129
720 1280 or 1280 7206x16129
1104 832 or 832 11046x16129
960 9606x16129
720 1280 or 1280 7204x14129
1104 832 or 832 11044x14129
960 9604x14129
720 1280 or 1280 7203x13129
1104 832 or 832 11043x13129
960 9603x13129
720 1280 or 1280 7202x12129
1104 832 or 832 11042x12129
960 9602x12129

七、注意

  1. 在并行场景下，使用算法优化时，使用attention_cache有爆显存风险，我们建议在不同场景使用不同的算法优化：
并行度参数配置
2--use_cache --use_cache_double
3--use_cache --use_cache_double
4--use_cache --use_cache_double
8--use_attentioncache
16--use_attentioncache
  1. 量化模型推理时，需确保quant_model_description.json与quant_model_weight.safetensors文件路径对应，且文件名一致（仅后缀不同）。

八、优化指南

本模型使用的优化手段如下：

  • 等价优化：FA、ROPE、RmsNorm、SP并行
  • 算法优化：FA、ROPE、RmsNorm、SP并行、cache
  • 量化优化：支持w8a8/w8a16量化模式，动态/静态量化可选

声明

  • 本代码仓提到的数据集和模型仅作为示例，这些数据集和模型仅供您用于非商业目的，如您使用这些数据集和模型来完成示例，请您特别注意应遵守对应数据集和模型的License，如您因使用数据集或模型而产生侵权纠纷，华为不承担任何责任。
  • 如您在使用本代码仓的过程中，发现任何问题（包括但不限于功能问题、合规问题），请在本代码仓提交issue，我们将及时审视并解答。