CANN/cann-recipes-infer：HunyuanVideo昇腾推理适配

在昇腾Atlas A2环境上适配HunyuanVideo模型的推理

【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法，提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer

HunyuanVideo模型是一款多模态视频生成模型，提供了文生视频功能。本项目旨在提供HunyuanVideo的昇腾适配版本。

本项目基于NPU主要完成了以下优化点，具体内容可至NPU HunyuanVideo模型推理优化实践查看：

• 支持NPU npu_fused_infer_attention_score融合算子，npu_rms_norm融合算子，npu_rotary_mul融合算子；
• 支持ulysses序列并行；
• 支持ring attention序列并行和通算掩盖；
• 集成step-level Dit-Cache加速方案，支持FBCache和TeaCache；
• 集成TaylorSeer Dit-Cache加速方案，支持自定义DiT Cache方案，具备warmup、cutoff、offload功能；
• 支持VAE并行；
• 支持UAA: Ulysses Anything Attention；
• 支持950PR平台的量化加速特性，涵盖FP8 FA激活量化及MXFP8 A8W8全量化方案。
• 支持TopK，SVG稀疏attention算法；

执行样例

本样例支持Atlas A2环境的单卡、多卡推理。

CANN环境准备

1. 本样例的编译执行依赖CANN开发套件包（cann-toolkit）与CANN二进制算子包（cann-kernels），支持的CANN软件版本为CANN 8.5.0.alpha002。

   请从CANN软件包下载地址下载Ascend-cann-toolkit_${version}_linux-${arch}.run与Ascend-cann-kernels-${chip_type}_${version}_linux-${arch}.run软件包，并参考CANN安装文档进行安装。

2. 本样例依赖的torch及torch_npu版本为2.7.1，Python==3.11。

   #安装Pytorch pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1

   Ascend Extension for PyTorch插件的下载和安装，请参考二进制软件包安装。

   # 下载并安装torch_npu插件 wget https://gitcode.com/Ascend/pytorch/releases/download/v7.3.0-pytorch2.7.1/torch_npu-2.7.1.post2-cp311-cp311-manylinux_2_28_aarch64.whl pip3 install torch_npu-2.7.1.post2-cp311-cp311-manylinux_2_28_aarch64.whl

依赖安装

本仓库依赖于HunyuanVideo的开源仓库代码。

首先进入HunyuanVideo的仓库，下载开源仓库代码：

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

下载本仓库代码：

git clone https://gitcode.com/cann/cann-recipes-infer.git

将HunyuanVideo仓库的代码以非覆盖模式复制到本项目目录下：

cp -rn HunyuanVideo/* cann-recipes-infer/models/hunyuan-video

# 安装Python依赖，仅支持python 3.11 cd models/hunyuan-video pip install -r requirements.txt

准备模型权重

权重下载依赖huggingface_hub[cli]，安装方式如下：

python -m pip install "huggingface_hub[cli]"

准备HunyuanVideo模型权重，默认本地路径在ckpts：

huggingface-cli download tencent/HunyuanVideo --local-dir ./ckpts

国内用户可以考虑使用hf-mirror镜像：

HF_ENDPOINT=https://hf-mirror.com huggingface-cli download tencent/HunyuanVideo --local-dir ./ckpts

准备text_encoder模型权重:

cd models/hunyuan-video/ckpts huggingface-cli download xtuner/llava-llama-3-8b-v1_1-transformers --local-dir ./llava-llama-3-8b-v1_1-transformers

为了节省npu内存，将llama3中的llm部分切分到text_encoder目录：

cd models/hunyuan-video/ python hyvideo/utils/preprocess_text_encoder_tokenizer_utils.py --input_dir ckpts/llava-llama-3-8b-v1_1-transformers --output_dir ckpts/text_encoder

准备text_encoder2模型权重:

cd models/hunyuan-video/ckpts huggingface-cli download openai/clip-vit-large-patch14 --local-dir ./text_encoder_2

hunyuan-video/ ├── hyvideo/ | └──... ├── scripts/ │ └──... ├── ckpts/ │ ├──README.md │ ├──hunyuan-video-t2v-720p │ │ ├──transformers │ │ │ ├──mp_rank_00_model_states.pt │ │ │ ├──mp_rank_00_model_states_fp8.pt │ │ │ ├──mp_rank_00_model_states_fp8_map.pt ├ │ ├──vae │ ├──text_encoder │ ├──text_encoder_2 ├──... └──...

自定义模型权重路径

所有预置 YAML 的model_args.model-base默认写为"ckpts"（相对models/hunyuan-video/），如需自定义权重路径，直接修改该字段即可——mm_function.sh会同时把这个值自动 export 为MODEL_BASE环境变量，覆盖hyvideo/constants.py里VAE_PATH/TEXT_ENCODER_PATH/TOKENIZER_PATH三套默认路径（这三者在 import 时就 freeze，必须通过 env 控制）。DiT 权重默认按hunyuan-video-t2v-720p/transformers/mp_rank_00_model_states.pt在model-base下自动定位（--dit-weight相对路径会与--model-base自动拼接，绝对路径则按原样使用）。如需单独指定 DiT 权重（例如使用 FP8 checkpoint），在model_args中增补dit-weight: "/abs/path/to/ckpt.pt"——single_fp8.yaml即为该用法的参考样例。如确需把MODEL_BASE指向与model-base不同的目录，在env_vars中显式写MODEL_BASE: "..."即可覆盖自动派生。

快速启动

本样例通过bash infer.sh拉起，推理参数集中在config/*.yaml维护。

1. 配置 CANN 环境变量

执行推理前先完成 CANN 环境变量配置（参考 Ascend 社区）：

source /usr/local/Ascend/ascend-toolkit/set_env.sh

注意：PYTHONPATH不会也不应全局设置项目根路径，mm_function.sh会在torchrun子进程中按需注入，避免影响 CANN TBE 编译器的内置 Python 解释器。

2. 选择推理配置

config/目录下已预置以下 YAML，分别对应不同的推理场景：

3. 修改模型权重路径与提示词

打开所选 YAML，按需修改model_args中的prompt、video-size、video-length、seed等字段；多卡 YAML 通过ulysses-degree / ring-degree控制序列并行，通过use-vae-parallel启用 VAE 并行；FP8 YAML 通过dit-weight指定量化权重路径。

YAML 中model_args会按以下规则透传给sample_video.py：

4. 切换要使用的 YAML

infer.sh中仅需指定一行YAML_FILE_NAME：

# 默认：8 卡多卡推理 export YAML_FILE_NAME=sp8.yaml # 单卡（通过 dit_cache.method 切换 FBCache / TeaCache / TaylorSeer） # export YAML_FILE_NAME=single.yaml

5. 拉起推理

bash infer.sh

拉起过程会自动：

• 解析 YAML 中的world_size、master_port、entry_script、env_vars、dit_cache、model_args；
• 设置通用 NPU 优化环境变量（PYTORCH_NPU_ALLOC_CONF、TASK_QUEUE_ENABLE、CPU_AFFINITY_CONF、TOKENIZERS_PARALLELISM）以及 HCCL 通信配置；
• 在res/<YYYYMMDD>/<model_name>/下自动创建日志目录，并将推理输出tee到log_<timestamp>.log；
• 调用torchrun --nproc_per_node=<world_size>启动sample_video.py，并将 YAML 中的dit_cache段通过--cache-config <yaml>透传给 Python 侧的CacheManager。

Dit-Cache 说明

本样例集成了多种 Dit-Cache 方案（FBCache、TeaCache、TaylorSeer），通过 YAML 的dit_cache段配置：

dit_cache: method: "TeaCache" # [NoCache, FBCache, TeaCache, TaylorSeer] enable_separate_cfg: true params: # 方法特有参数（覆盖内置默认值） rel_l1_thresh: 0.15 coefficients: [733.226126, -401.131952, 67.5869174, -3.149879, 0.0961237896] warmup: 2

常用调参：

• FBCacherel_l1_thresh：L1 差异阈值。rel_l1_thresh=0.1时 DiT 加速比约 2.0；阈值越大越快，精度损失越大。
• TeaCacherel_l1_thresh / coefficients / warmup：累积 L1 阈值、多项式重缩放系数、前 N 步强制完整计算。rel_l1_thresh=0.1约 1.6 倍加速，rel_l1_thresh=0.15约 2.1 倍加速。
• TaylorSeern_derivatives / skip_interval_steps / warmup / cutoff_steps / offload：Taylor 展开阶数、跳算间隔、前后强制完整计算步数、是否 offload 到 CPU。720*1280*129规格开启 offload 需保证 400GB 以上主机内存。

内存提示：开启 Dit-Cache 后内存占用会略增。若剩余可用内存过低（如不足 100MB），可在 YAML 的env_vars中移除/改写PYTORCH_NPU_ALLOC_CONF，并在model_args中启用use-cpu-offload: true。

量化

通过单卡 FP8 YAML（single_fp8.yaml）直接启用；也可向任意 YAML 的model_args添加：

• fa-perblock-fp8: true：启用 FP8 FA 量化（per-block，Q block=128，KV block=256）；
• mm-mxfp8: true：启用 MXFP8 A8W8 量化（per-channel 直转）。

量化支持多卡推理，仅支持 950PR。

块稀疏 Attention

在启动 YAML 顶层加sparse:段即可启用（单卡参考config/single_sparse.yaml，多卡参考config/sp8_sparse.yaml），sparse.method可选no_sparse / TopK / SVG；无sparse:段或method: no_sparse时稀疏分支关闭。block_size_Q/K、model、以及params.TopK / params.SVG各自的策略参数全部内联到同一份 yaml 中，不再依赖独立的sparse_config.yaml。

约束与注意事项：

• 支持单卡和 Ulysses 多卡：hyvideo/sparse/sparse_block.py已适配 Ulysses 序列并行的 all-to-all 通信，sample_video.py在ulysses_degree > 1时会自动调用apply_head_reorder_for_load_balance做 head 级负载均衡（详见优化文档Ulysses + TopK/SVG 联合优化章节）。
• 不支持 Ring Attention：sample_video.py在ring_degree > 1时会直接抛ValueError；多卡 sparse 仅可与 Ulysses 组合（ring-degree: 1），不可与 Ring 组合。
• 与 Dit-Cache 互斥：sample_video.py启用 sparse 时会替换所有double/single block 的 forward，会覆盖 FBCache / TeaCache / TaylorSeer 设置的 block forward；同时启用时只有 sparse 生效，故single_sparse.yaml/sp8_sparse.yaml都固定dit_cache.method: NoCache。
• 算子依赖：基于blitz_sparse_attention 算子实现，运行前需依据参考文档编译算子库。
• TopK 前置：选择TopK时需先运行module/blockwise_sparse/offline_profiling/offline_profiling_hyvideo.py生成 sparsity 文件（路径由 yaml 中sparse.params.TopK.sparsity_files_path指定，规格须与video-size / video-length一致——单卡默认320*480*65，多卡默认720*1280*129），详见优化文档TopK章节。

性能分析

本样例支持 Ascend PyTorch Profiler 接口采集并分析模型性能，在 YAML 的model_args中添加prof-dit: true即可启用性能分析，分析文件默认保存在.prof路径。具体使用方法请参考 CANN 社区文档性能分析。支持多卡推理。

多卡推理约束与并行配置组合

本样例适配了 Ulysses / Ring Attention 两种序列并行方法，原生 HunyuanVideo 在 8 卡 Atlas 800I A2 上支持720*1280*129及以上规格。多卡推理需满足以下约束：

1. 混合并行策略约束：world_size == ulysses-degree * ring-degree（由 YAML 中world_size与ulysses-degree / ring-degree共同决定，mm_function.sh会将world_size映射为torchrun --nproc_per_node）；
2. 视频规格约束：H % 16 % <SP number> == 0 or W % 16 % <SP number> == 0；
3. 序列并行度约束：<head num> % <SP number> == 0，其中<head num> = 24。

要使用不同的并行配置组合时，复制sp8.yaml并修改world_size / ulysses-degree / ring-degree / video-size / video-length即可：

VAE 并行：在多卡 YAML 中置use-vae-parallel: true即可启用。

UAA（Ulysses Anything Attention）：在 YAML 中置ulysses-anything: true可启用。开启后解除对视频规格H, W的整除约束，解除<head num> % <SP number> == 0的约束，支持<head num>大于<SP number>（<head num> = 24）。UAA 仅支持纯 Ulysses，不支持 Ulysses + Ring Attention 混合序列并行策略。

附录：公共环境变量说明

以下环境变量由executor/scripts/mm_function.sh在启动时统一设置（作为默认值，可通过 YAML 的env_vars覆盖）：

• PYTORCH_NPU_ALLOC_CONF='expandable_segments:True'：PyTorch 针对昇腾 NPU 的内存分配配置，启用"可扩展内存段"减少 OOM 风险；
• TASK_QUEUE_ENABLE=2：开启 task_queue 算子下发队列 Level 2 优化；
• CPU_AFFINITY_CONF=1：开启粗粒度绑核；
• TOKENIZERS_PARALLELISM=false：禁用 tokenizers 并行化；
• 自动设置 HCCL 通信相关的HCCL_IF_IP / HCCL_IF_BASE_PORT / HCCL_CONNECT_TIMEOUT / HCCL_EXEC_TIMEOUT。

指定参与推理的设备：export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7后再执行bash infer.sh。

【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法，提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer