HunyuanVideo-1.5:仅8.3B参数的高效视频生成模型，采用先进DiT架构与SSTA机制，支持文本到视频和图像到视频，可在消费级NPU运行，还能超分至1080p，为开发者和创作者降低门槛。【此简介由AI生成】

HunyuanVideo-1.5 是一款仅使用 8.3B 参数就能提供顶级质量的视频生成模型，显著降低了使用门槛。它可以在消费级 NPU 上流畅运行，使得每位开发者和创作者都能轻松使用。这一成就基于几个关键组件，包括精心的数据整理、带有选择性和滑动块注意力（SSTA）的先进 DiT 架构、通过字形感知文本编码增强的双语理解、渐进式预训练和后训练以及高效的视频超分辨率网络。利用这些设计，开发了一个统一的框架，能够跨多个持续时间和分辨率生成高质量的文本到视频和图像到视频。广泛的实验表明，这个紧凑而高效的模型在开源模型中树立了新的标杆。

轻量级高性能架构: 一种高效的架构，将 83 亿参数的扩散变压器 (DiT) 与 3D 因果 VAE 结合起来，在空间维度上实现了 16 倍的压缩比，在时间轴上实现了 4 倍的压缩比。此外，创新的 SSTA（选择性和滑动块注意力）机制修剪了冗余的时空 kv 块，显著减少了长视频序列的计算开销并加速了推理，在 10 秒 720p 视频合成中相比 FlashAttention-3 实现了 1.87 倍的端到端速度提升。
视频超分辨率增强: 一个高效的超分辨率网络，可以将输出放大到1080p。它在提高清晰度的同时修正了失真，从而细化了细节和整体视觉纹理。

适配参考：https://modelers.cn/models/MindIE/HunyuanVideo-1.5/blob/main/README.md

一、版本配套表

表 1 版本配套表

配套	版本	环境准备指导
Python	3.11	-
torch	>=2.6.0	-

二、环境准备

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

2.1、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

2.2、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

2.3、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

三、下载权重

MLLM权重:

   hf download Qwen/Qwen2.5-VL-7B-Instruct --local-dir ./ckpts/text_encoder/llm

ByT5 encoder权重

   hf download google/byt5-small --local-dir ./ckpts/text_encoder/byt5-small
   modelscope download --model AI-ModelScope/Glyph-SDXL-v2 --local_dir ./ckpts/text_encoder/Glyph-SDXL-v2

Vision Encoder权重

   hf download black-forest-labs/FLUX.1-Redux-dev --local-dir ./ckpts/vision_encoder/siglip

HunYuan DiT和VAE权重链接：

   hf download tencent/HunyuanVideo-1.5 --local-dir ./ckpts

四、HunYuanVideo-1.5使用

4.1 下载到本地

   git clone https://modelers.cn/MindIE/HunyuanVideo-1.5.git
   cd HunyuanVideo-1.5

环境依赖安装

pip3 install -r requirements.txt

包含如下依赖：

tqdm==4.67.1
torch>=2.6.0
peft==0.17.0
openai==2.8.0
einops==0.8.0
loguru==0.7.3
numpy==1.26.4
pillow==11.3.0
imageio==2.37.0
angelslim==0.2.1
imageio-ffmpeg==0.6.0
omegaconf>=2.3.0
torchaudio==2.6.0
diffusers==0.35.0
safetensors>=0.5.3
torchvision>=0.21.0
qwen-vl-utils==0.0.8
huggingface-hub==0.34.0
huggingface_hub[cli]
transformers[accelerate,tiktoken]==4.57.1
wheel
psutil
setuptools
modelscope

4.2 16卡测试推理

执行命令：

#source /usr/local/Ascend/ascend-toolkit/set_env.sh
#source /usr/local/Ascend/ascend-toolkit/latest/toolkit/bin/setenv.bash

export T2V_REWRITE_BASE_URL="<your_vllm_server_base_url>"
export T2V_REWRITE_MODEL_NAME="<your_model_name>"
export I2V_REWRITE_BASE_URL="<your_vllm_server_base_url>"
export I2V_REWRITE_MODEL_NAME="<your_model_name>"

export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True"
export HCCL_OP_EXPANSION_MODE="AIV"
export TASK_QUEUE_ENABLE=2
export CPU_AFFINITY_CONF=1

export ASCEND_LAUNCH_BLOCKING=0

export ENABLE_ASYNC_COMMUNICATION=1 # 是否启用通算掩盖
export ENABLE_RAINFUSION=1 # 是否开启稀疏
export SPARSITY=0.85 # 稀疏度
export SKIP_TIMESTEP=10 # 跳过前面step不做稀疏

#export HCCL_INTRA_ROCE_ENABLE=1 # A2 A+X机器跨8卡时开启
#export HCCL_INTRA_PCIE_ENABLE=0 # A2 A+X机器跨8卡时开启 

PROMPT='A girl holding a paper with words "Hello, world!"'

IMAGE_PATH=none # 可选，none 或 <图像路径> 以启用 i2v 模式
SEED=1
ASPECT_RATIO=16:9
RESOLUTION=480p
OUTPUT_PATH=./outputs/output.mp4

# 配置
REWRITE=false # 启用提示词重写。请确保 rewrite vLLM server 已部署和配置。
N_INFERENCE_GPU=16  # 并行推理 GPU 数量
CFG_DISTILLED=true # 使用 CFG 蒸馏模型进行推理，2倍加速
SPARSE_ATTN=false # 使用稀疏注意力进行推理（仅 720p 模型配备了稀疏注意力）。请确保 flex-block-attn 已安装
SAGE_ATTN=false # 使用 SageAttention 进行推理
ENCODER_FSDP=true # 当显存不够时，优先启用该参数降低显存占用
OFFLOADING=false # 开启时会对所有encoder、dit、vae模块做offload，可以降低显存占用，但是增加推理耗时
GROUP_OFFLOADING=false # 开启时会对所有dit的block做offload，可以降低显存占用，但是增加推理耗时
OVERLAP_GROUP_OFFLOADING=false # 仅在组卸载启用时有效，会显著增加 CPU 内存占用，但能够提速
ENABLE_CACHE=true # 启用特征缓存进行推理。显著提升推理速度
CACHE_TYPE=deepcache # 支持：deepcache, teacache, taylorcache
ENABLE_SR=false # 启用超分辨率
MODEL_PATH=/home/nvme0/hunyuan/model # 预训练模型路径

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 \
  --sparse_attn $SPARSE_ATTN --use_sageattn $SAGE_ATTN \
  --enable_cache $ENABLE_CACHE --cache_type $CACHE_TYPE \
  --encoder_fsdp $ENCODER_FSDP \
  --offloading $OFFLOADING \
  --group_offloading $GROUP_OFFLOADING \
  --overlap_group_offloading $OVERLAP_GROUP_OFFLOADING \
  --sr $ENABLE_SR --save_pre_sr_video \
  --output_path $OUTPUT_PATH \
  --model_path $MODEL_PATH

参数	类型	是否必需	默认值	描述
`--prompt`	str	是	-	用于视频生成的文本提示
`--negative_prompt`	str	否	`''`	用于视频生成的负向提示词
`--resolution`	str	是	-	视频分辨率：`480p` 或 `720p`
`--model_path`	str	是	-	预训练模型目录的路径
`--aspect_ratio`	str	否	`16:9`	输出视频的宽高比
`--num_inference_steps`	int	否	`50`	推理步数
`--video_length`	int	否	`121`	要生成的帧数
`--seed`	int	否	`123`	随机种子，用于可复现性
`--image_path`	str	否	`None`	参考图像的路径（启用图生视频模式）。使用 `none` 或 `None` 可明确使用文生视频模式
`--output_path`	str	否	`None`	输出文件路径（如果未提供，则保存到 `./outputs/output_{transformer_version}_{timestamp}.mp4`）
`--sr`	bool	否	`true`	启用超分辨率（使用 `--sr false` 或 `--sr 0` 来禁用）
`--save_pre_sr_video`	bool	否	`false`	保存超分辨率处理前的原始视频（使用 `--save_pre_sr_video` 或 `--save_pre_sr_video true` 来启用，仅在启用超分辨率时有效）
`--rewrite`	bool	否	`true`	启用提示词重写（使用 `--rewrite false` 或 `--rewrite 0` 来禁用，禁用可能导致视频生成质量降低）
`--cfg_distilled`	bool	否	`false`	启用 CFG 蒸馏模型以加速推理（约 2 倍加速，使用 `--cfg_distilled` 或 `--cfg_distilled true` 来启用）
`--enable_step_distill`	bool	否	`false`	启用 480p I2V 步数蒸馏模型（推荐 8 或 12 步，在 RTX 4090 上可提速约 75%，使用 `--enable_step_distill` 或 `--enable_step_distill true` 来启用）
`--sparse_attn`	bool	否	`false`	启用稀疏注意力以加速推理（约 1.5-2 倍加速，需要 H 系列 GPU，会自动启用 CFG 蒸馏，使用 `--sparse_attn` 或 `--sparse_attn true` 来启用）
`--offloading`	bool	否	`true`	启用 CPU 卸载（使用 `--offloading false` 或 `--offloading 0` 来禁用，如果 GPU 内存允许，禁用后速度会更快）
`--group_offloading`	bool	否	`None`	启用组卸载（默认：None，如果启用了 offloading 则自动启用。使用 `--group_offloading` 或 `--group_offloading true/1` 来启用，`--group_offloading false/0` 来禁用）
`--overlap_group_offloading`	bool	否	`true`	启用重叠组卸载（默认：true）。会显著增加 CPU 内存占用，但能够提速。使用 `--overlap_group_offloading` 或 `--overlap_group_offloading true/1` 来启用，`--overlap_group_offloading false/0` 来禁用
`--dtype`	str	否	`bf16`	Transformer 的数据类型：`bf16`（更快，内存占用更低）或 `fp32`（质量更好，速度更慢，内存占用更高）
`--use_sageattn`	bool	否	`false`	启用 SageAttention（使用 `--use_sageattn` 或 `--use_sageattn true/1` 来启用，`--use_sageattn false/0` 来禁用）
`--sage_blocks_range`	str	否	`0-53`	SageAttention 块范围（例如：`0-5` 或 `0,1,2,3,4,5`）
`--enable_torch_compile`	bool	否	`false`	启用 torch compile 以优化 transformer（使用 `--enable_torch_compile` 或 `--enable_torch_compile true/1` 来启用，`--enable_torch_compile false/0` 来禁用）
`--enable_cache`	bool	否	`false`	启用 transformer 缓存（使用 `--enable_cache` 或 `--enable_cache true/1` 来启用，`--enable_cache false/0` 来禁用）
`--cache_type`	str	否	`deepcache`	Transformer 的缓存类型（例如：`deepcache, teacache, taylorcache`）
`--no_cache_block_id`	str	否	`53`	从 deepcache 中排除的块（例如：`0-5` 或 `0,1,2,3,4,5`）
`--cache_start_step`	int	否	`11`	使用缓存时跳过的起始步数
`--cache_end_step`	int	否	`45`	使用缓存时跳过的结束步数
`--total_steps`	int	否	`50`	总推理步数
`--cache_step_interval`	int	否	`4`	使用缓存时跳过的步数间隔

配套

版本

环境准备指导

Python

3.11

torch

>=2.6.0

# 增加软件包可执行权限，{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

# 增加软件包可执行权限，{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

tqdm==4.67.1 torch>=2.6.0 peft==0.17.0 openai==2.8.0 einops==0.8.0 loguru==0.7.3 numpy==1.26.4 pillow==11.3.0 imageio==2.37.0 angelslim==0.2.1 imageio-ffmpeg==0.6.0 omegaconf>=2.3.0 torchaudio==2.6.0 diffusers==0.35.0 safetensors>=0.5.3 torchvision>=0.21.0 qwen-vl-utils==0.0.8 huggingface-hub==0.34.0 huggingface_hub[cli] transformers[accelerate,tiktoken]==4.57.1 wheel psutil setuptools modelscope

#source /usr/local/Ascend/ascend-toolkit/set_env.sh #source /usr/local/Ascend/ascend-toolkit/latest/toolkit/bin/setenv.bash export T2V_REWRITE_BASE_URL="<your_vllm_server_base_url>" export T2V_REWRITE_MODEL_NAME="<your_model_name>" export I2V_REWRITE_BASE_URL="<your_vllm_server_base_url>" export I2V_REWRITE_MODEL_NAME="<your_model_name>" export PYTORCH_NPU_ALLOC_CONF="expandable_segments:True" export HCCL_OP_EXPANSION_MODE="AIV" export TASK_QUEUE_ENABLE=2 export CPU_AFFINITY_CONF=1 export ASCEND_LAUNCH_BLOCKING=0 export ENABLE_ASYNC_COMMUNICATION=1 # 是否启用通算掩盖 export ENABLE_RAINFUSION=1 # 是否开启稀疏 export SPARSITY=0.85 # 稀疏度 export SKIP_TIMESTEP=10 # 跳过前面step不做稀疏 #export HCCL_INTRA_ROCE_ENABLE=1 # A2 A+X机器跨8卡时开启 #export HCCL_INTRA_PCIE_ENABLE=0 # A2 A+X机器跨8卡时开启 PROMPT='A girl holding a paper with words "Hello, world!"' IMAGE_PATH=none # 可选，none 或 <图像路径> 以启用 i2v 模式 SEED=1 ASPECT_RATIO=16:9 RESOLUTION=480p OUTPUT_PATH=./outputs/output.mp4 # 配置 REWRITE=false # 启用提示词重写。请确保 rewrite vLLM server 已部署和配置。 N_INFERENCE_GPU=16 # 并行推理 GPU 数量 CFG_DISTILLED=true # 使用 CFG 蒸馏模型进行推理，2倍加速 SPARSE_ATTN=false # 使用稀疏注意力进行推理（仅 720p 模型配备了稀疏注意力）。请确保 flex-block-attn 已安装 SAGE_ATTN=false # 使用 SageAttention 进行推理 ENCODER_FSDP=true # 当显存不够时，优先启用该参数降低显存占用 OFFLOADING=false # 开启时会对所有encoder、dit、vae模块做offload，可以降低显存占用，但是增加推理耗时 GROUP_OFFLOADING=false # 开启时会对所有dit的block做offload，可以降低显存占用，但是增加推理耗时 OVERLAP_GROUP_OFFLOADING=false # 仅在组卸载启用时有效，会显著增加 CPU 内存占用，但能够提速 ENABLE_CACHE=true # 启用特征缓存进行推理。显著提升推理速度 CACHE_TYPE=deepcache # 支持：deepcache, teacache, taylorcache ENABLE_SR=false # 启用超分辨率 MODEL_PATH=/home/nvme0/hunyuan/model # 预训练模型路径 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 \ --sparse_attn $SPARSE_ATTN --use_sageattn $SAGE_ATTN \ --enable_cache $ENABLE_CACHE --cache_type $CACHE_TYPE \ --encoder_fsdp $ENCODER_FSDP \ --offloading $OFFLOADING \ --group_offloading $GROUP_OFFLOADING \ --overlap_group_offloading $OVERLAP_GROUP_OFFLOADING \ --sr $ENABLE_SR --save_pre_sr_video \ --output_path $OUTPUT_PATH \ --model_path $MODEL_PATH

参数

类型

是否必需

默认值

描述

--prompt

str

是

用于视频生成的文本提示

--negative_prompt

str

否

''

用于视频生成的负向提示词

--resolution

str

是

视频分辨率：480p 或 720p

--model_path

str

是

预训练模型目录的路径

--aspect_ratio

str

否

16:9

输出视频的宽高比

--num_inference_steps

int

否

50

推理步数

--video_length

int

否

121

要生成的帧数

--seed

int

否

123

随机种子，用于可复现性

--image_path

str

否

None

参考图像的路径（启用图生视频模式）。使用 none 或 None 可明确使用文生视频模式

--output_path

str

否

None

输出文件路径（如果未提供，则保存到 ./outputs/output_{transformer_version}_{timestamp}.mp4）

--sr

bool

否

true

启用超分辨率（使用 --sr false 或 --sr 0 来禁用）

--save_pre_sr_video

bool

否

false

保存超分辨率处理前的原始视频（使用 --save_pre_sr_video 或 --save_pre_sr_video true 来启用，仅在启用超分辨率时有效）

--rewrite

bool

否

true

启用提示词重写（使用 --rewrite false 或 --rewrite 0 来禁用，禁用可能导致视频生成质量降低）

--cfg_distilled

bool

否

false

启用 CFG 蒸馏模型以加速推理（约 2 倍加速，使用 --cfg_distilled 或 --cfg_distilled true 来启用）

--enable_step_distill

bool

否

false

启用 480p I2V 步数蒸馏模型（推荐 8 或 12 步，在 RTX 4090 上可提速约 75%，使用 --enable_step_distill 或 --enable_step_distill true 来启用）

--sparse_attn

bool

否

false

启用稀疏注意力以加速推理（约 1.5-2 倍加速，需要 H 系列 GPU，会自动启用 CFG 蒸馏，使用 --sparse_attn 或 --sparse_attn true 来启用）

--offloading

bool

否

true

启用 CPU 卸载（使用 --offloading false 或 --offloading 0 来禁用，如果 GPU 内存允许，禁用后速度会更快）

--group_offloading

bool

否

None

启用组卸载（默认：None，如果启用了 offloading 则自动启用。使用 --group_offloading 或 --group_offloading true/1 来启用，--group_offloading false/0 来禁用）

--overlap_group_offloading

bool

否

true

启用重叠组卸载（默认：true）。会显著增加 CPU 内存占用，但能够提速。使用 --overlap_group_offloading 或 --overlap_group_offloading true/1 来启用，--overlap_group_offloading false/0 来禁用

--dtype

str

否

bf16

Transformer 的数据类型：bf16（更快，内存占用更低）或 fp32（质量更好，速度更慢，内存占用更高）

--use_sageattn

bool

否

false

启用 SageAttention（使用 --use_sageattn 或 --use_sageattn true/1 来启用，--use_sageattn false/0 来禁用）

--sage_blocks_range

str

否

0-53

SageAttention 块范围（例如：0-5 或 0,1,2,3,4,5）

--enable_torch_compile

bool

否

false

启用 torch compile 以优化 transformer（使用 --enable_torch_compile 或 --enable_torch_compile true/1 来启用，--enable_torch_compile false/0 来禁用）

--enable_cache

bool

否

false

启用 transformer 缓存（使用 --enable_cache 或 --enable_cache true/1 来启用，--enable_cache false/0 来禁用）

--cache_type

str

否

deepcache

Transformer 的缓存类型（例如：deepcache, teacache, taylorcache）

--no_cache_block_id

str

否

53

从 deepcache 中排除的块（例如：0-5 或 0,1,2,3,4,5）

--cache_start_step

int

否

11

使用缓存时跳过的起始步数

--cache_end_step

int

否

45

使用缓存时跳过的结束步数

--total_steps

int

否

50

总推理步数

--cache_step_interval

int

否

4

使用缓存时跳过的步数间隔