14001ccc创建于 2月6日历史提交

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

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。

执行样例

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

CANN环境准备

本样例的编译执行依赖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安装文档进行安装。

本样例依赖的torch及torch_npu版本为2.7.1。

请从Ascend Extension for PyTorch插件下载v2.7.1-7.3.0源码，参考源码编译安装。

依赖安装

本仓库依赖于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依赖
pip install -r requirements.txt

准备模型权重

模型	版本
HunyuanVideo	HunyuanVideo

下载HunyuanVideo模型权重到本地路径ckpts。

HunyuanVideo/
├── hyvideo/
|   └──...
├── scripts/
│   └──...
├── ckpts/
|   └──...
└──...

对Python依赖的补充修改

xfuser仓和yunchang仓已经对npu进行了适配，访问github仓库将xfuser目录和yunchang目录放到HunyuanVideo/目录下。当前支持yunchang7a52abd669efb35e550680a239e1745b620b2baecommit之后的版本，xfusere559fe8f07c7cfdd02a73ed03c00b8b128de682acommit之后的版本。如果版本不匹配，请参考附录修改。

快速启动

本样例在scripts文件夹中准备了单卡和多卡的推理脚本。

首先参考依赖按照准备环境和代码。

执行测试脚本前，请参考Ascend社区中的CANN安装软件教程，配置环境变量：

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

启用torch_npu环境, 添加PYTHONPATH：

source scripts/set_env.sh

单卡推理: 通过设置环境变量export ASCEND_RT_VISIBLE_DEVICES=0指定启用第0卡推理，更多环境变量相关问题，请参考CANN社区。原生hunyuanVideo模型在单块Atlas 800I A2上，支持生成视频规格780*1280*129。

bash scripts/test.sh

多卡推理: 本样例适配了Ulysses/Ring Attention两种序列并行方法，用于多卡并行推理，减少显存占用，提高推理速率，通过传入参数--ulysses-degree=<SP number>或者--ring-degree=<SP number>启用序列并行。请满足序列并行约束条件nproc_per_node == ulysses-degree * ring-degree，以及视频规格约束条件H % 16 % <SP number> == 0 or W % 16 % <SP number> == 0，其中H, W, T 分别是视频帧的高、宽、数量。原生hunyuanVideo模型在8块Atlas 800I A2上，支持生成视频规格780*1280*649。

执行以下脚本启用多卡序列并行，环境变量的详细信息请参考CANN社区。

bash scripts/test_sp.sh

Dit-Cache：本样例集成了step-level Dit-Cache方案，集成了FBCache和TeaCache和FBCache加速方案，当前仅支持单机单卡。

通过读取配置文件hyvideo/cache/cache_config.json初始化Dit-Cache，用户可自定义配置文件，通过传入参数--cache-config来自定义配置文件地址。

用户可修改配置文件中的以下几项自定义cache方案，其他配置信息详见HunyuanVideo优化文档：

cache_forward: 选择Dit-Cache方案，设为FBCache启用FBCache，设为TeaCache启用TeaCache，其他情况不启用Dit-Cache。默认不启用Dit-Cache。

rel_l1_thresh: 控制加速比，当Dit-Cache为FBCache时，rel_l1_thresh=0.1时DiT模型加速比为2.0；当Dit-Cache为TeaCache时，rel_l1_thresh=0.1时DiT模型加速比为1.6，rel_l1_thresh=0.15时DiT模型加速比为2.1。请注意，更大的阈值可以获得更高的加速比，但也会带来更高的精度损失。

性能分析：本样例支持Ascend PyTorch Profiler接口采集并分析模型性能，具体使用方法请参考CANN社区文档性能分析。

在脚本中传入参数--prof-dit，启用性能分析，分析文件默认保存在.prof路径。

附录

侵入式修改外部依赖库

HunyuanVideo使用xdit框架实现序列并行，核心的库是xfuser和yunchang。需要手动消除其内部的cuda版本检查，并适配npu的fa算子。本仓库通过try: import torch_npu的方式代替npu检查，走npu方案。

如果使用xfuser<=0.4.4和yunchang<=0.6.3.post1的版本，需要按照以下方式手动修改代码，具体代码可参考appendix/xfuser和appendix/yunchang。

在site-packages目录下找到xfuser包，xfuser/envs.py的PackagesEncChecker.initialize()（L154），改为：

def initialize(self):
    try:
        import torch_npu
        self.packages_info = {
            "has_flash_attn": False,
            "has_long_ctx_attn": self.check_long_ctx_attn(),
            "diffusers_version": self.check_diffusers_version(),
        }
    except ImportError:
        self.packages_info = {
            "has_flash_attn": self.check_flash_attn(),
            "has_long_ctx_attn": self.check_long_ctx_attn(),
            "diffusers_version": self.check_diffusers_version(),
        }

在site-packages目录下找到xfuser包，xfuser/config/config.py的L11，改为：

try:
    import torch_npu
    from xfuser.envs import TORCH_VERSION, PACKAGES_CHECKER
except ImportError:
    from xfuser.envs import CUDA_VERSION, TORCH_VERSION, PACKAGES_CHECKER

在site-packages目录下找到yunchang包，yunchang/ring/ring_flashinfer_attn.py的L9，改为：

try:
    import torch_npu
except ImportError:
    torch_cpp_ext._get_cuda_arch_flags()