在NPU环境上适配HunyuanImage-3.0模型的推理

在NPU环境上适配HunyuanImage-3.0模型的推理

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

概述

HunyuanImage-3.0是腾讯于2025年9月28日正式开源的一个突破性的原生多模态模型，它在自回归框架内统一了多模态理解和生成任务。它的文生图能力实现了与领先的闭源模型相当或更优的性能。本项目旨在提供HunyuanImage-3.0的昇腾适配版本。

支持的产品型号

Atlas A2/A3 系列产品

环境准备

1. 安装CANN软件包。

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

   请从软件包下载地址下载Ascend-cann-toolkit_9.0.0-beta.1_linux-${arch}.run与Atlas-A3-ops_9.0.0-beta.1_linux-${arch}.run（A3环境）或Ascend-cann-910b-ops_9.0.0-beta.1-${arch}.run（A2环境）软件包，并参考CANN安装文档进行安装。

   • ${arch}表示CPU架构，如aarch64、x86_64。

2. 安装Ascend Extension for PyTorch（torch_npu）。

   Ascend Extension for PyTorch（torch_npu）为支撑PyTorch框架运行在NPU上的适配插件，本样例建议使用的Python版本为3.11，PyTorch版本为2.7.1，请先使用pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cpu安装CPU版本的torch包。

   相应的Ascend Extension for PyTorch版本为v7.3.1-pytorch2.7.1。可以通过pip install torch_npu==2.7.1进行安装，也可以从软件包下载地址下载release v7.3.1-pytorch2.7.1的whl包进行安装，或者下载其源码，参考源码编译安装。

3. 下载项目源码并安装依赖。

   # 下载项目源码，以master分支为例 git clone https://gitcode.com/cann/cann-recipes-infer.git # 本仓库依赖于[HunyuanImage-3.0](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0)的开源仓库代码。进入HunyuanImage-3.0的仓库，下载开源仓库代码： git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git cd HunyuanImage-3.0 git reset --hard 62da220178f4b0b7d83e91665a46a20a3ee4f7cd cd .. # 将HunyuanImage-3.0仓库的代码以“非覆盖模式”复制到本项目目录下： cp -rn HunyuanImage-3.0/* cann-recipes-infer/models/hunyuan-image-3.0/ # 安装依赖的python库（请使用3.11版本的Python） cd cann-recipes-infer pip install -r ./models/hunyuan-image-3.0/requirements.txt

   请注意，实测发现transformers==5.3.0版本会产生精度问题，推荐使用5.2.0及以下版本。

4. 配置 CANN 环境变量。

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

   说明：mm_function.sh在拉起时会自动设置 HCCL 基础参数（HCCL_IF_IP、HCCL_IF_BASE_PORT、HCCL_CONNECT_TIMEOUT、HCCL_EXEC_TIMEOUT）。若需要追加HCCL_SOCKET_IFNAME、HCCL_OP_EXPANSION_MODE等集群特有参数，可直接写入config/ep8_cfg.yaml的env_vars段，会自动透传给torchrun子进程。详细参数含义可参考集合通信文档。

权重准备与转换

下载HunyuanImage-3.0模型权重到本地路径ckpts。

hunyuan-image-3.0/ ├── hunyuan_image_3/ | └──... ├── utils/ │ └──... ├── ckpts/ | └──... └──...

使用weight_convert.sh脚本完成权重转换:

python convert_model.py \ --model-path ../ckpts/HunyuanImage-3.0 \ # 模型原始权重路径 --output-path ../ckpts/weight_ep8 \ # 模型权重输出路径 --tp-attn 8 \ # attn TP 切分份数 --tp-moe 1 \ # moe TP 切分份数 --ep 8 \ # EP 切分份数 --max-shard-size 5.0 # 权重每块最大限制（G）

模型的Attention部分目前仅支持TP切分，可以通过tp-attn参数来设置并行度。模型的MoE部分支持使用TP切分方案或EP切分方案，分别可以通过tp-moe和ep两个参数来设置所要切分权重的并行度。这几个并行度需要满足以下约束：

• MoE部分的TP与EP只能选一，不能同时使能；
• Attention部分的TP并行度需要与MoE部分的并行度一致；
• models/hunyuan-image-3.0/utils/convert_model.py中对这3个参数的其他相关校验。

此示例中output-path名中weight_ep8是指MoE采用EP8切分方案，如前所述Attention部分目前仅支持TP，所以这个路径名未单独提升先Attention部分的切分方式。路径名可根据个人喜好确定。

在convert_model.py中使用了多线程技术提高并发读写速度，如果默认的并发数量性能不佳，请根据调测环境的实际情况在models/hunyuan-image-3.0/utils/weight_convert.sh中添加并合理设置--max_workers参数的值。

权重转换拉起示例：

cd models/hunyuan-image-3.0/utils bash weight_convert.sh

推理执行

本样例通过bash infer.sh拉起，推理参数集中在config/*.yaml维护。本模型最少需要 4 个 Device 可正常运行，若需要开启CFG_PARALLEL，则需要 8 个 Device 可正常运行；预置配置为 EP8 + CFG 并行 + VAE 并行共 16 卡。

1. 选择推理配置

config/目录下已预置以下 YAML：

预置 YAML 关键字段：

model_name: "hunyuan-image-3.0" world_size: 16 master_port: 10086 entry_script: "run_image_gen.py" env_vars: CFG_PARALLEL: "1" # 开启 CFG 并行（nproc_per_node 需为原来的 2 倍） USE_VAE_PARALLEL: "1" # 开启 VAE 并行 CPU_AFFINITY_CONF: "2" # 自动绑核，缓解 HOST 下发瓶颈 model_args: reproduce: true model-id: "./ckpts/weight_ep8" # 指向权重转换后的目录 prompt: "A cinematic medium shot captures a single Asian woman seated on a chair within a dimly lit room, creating an intimate and theatrical atmosphere." attn-impl: "npu" # 使能 NPU 上的 Attention 实现 moe-impl: "npu_grouped_matmul" # 使能 NPU 上的 MoE 实现 moe-ep: true # MoE 使用 EP；与 moe-tp 互斥 seed: 42 diff-infer-steps: 50 image-size: "1024x1024" verbose: 0

如需切换到 MoE TP 切分方案，将moe-ep改为moe-tp: true，并保证model-id指向对应切分后的权重。两者互斥，只能二选一。

2. 修改推理输入

根据需要修改 YAML 中model_args下的字段，YAML → 命令行透传规则：

完整参数说明详见 HunyuanImage-3.0 官方 Command Line Arguments。与原开源仓库版本相比，NPU 适配在以下参数上做了扩展：

• --attn-impl：新增npu选项，用于使能 NPU 的 Attention 实现；
• --moe-impl：新增npu_grouped_matmul，用于使能 NPU 的 MoE 实现；
• --moe-tp/--moe-ep：一对互斥参数，选其一指定 MoE 的并行方式（TP 或 EP），需与"权重准备与转换"一致。Attention 部分仅支持 TP，与 MoE 的并行度相同。

关于 YAML 中环境变量开关的效果：

• CFG_PARALLEL=1：开启 CFG 并行，推理性能提升，但需要将world_size相对于原 TP 规模翻倍。例如 Attn TP8 时若关闭 CFG 则world_size: 8，开启 CFG 则需要world_size: 16；
• USE_VAE_PARALLEL=1：开启 VAE 并行，推理性能提升；
• CPU_AFFINITY_CONF=2：开启自动绑核，避免 CPU 核心抢占。

通过export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15指定参与推理的 Device，数量不能少于 YAML 中的world_size。更多环境变量请参考 CANN 社区。

3. 拉起推理

cd models/hunyuan-image-3.0 bash infer.sh

拉起过程会自动：

• 解析 YAML 中的world_size、master_port、entry_script、env_vars、model_args；
• 设置通用 NPU 优化环境变量（PYTORCH_NPU_ALLOC_CONF、TASK_QUEUE_ENABLE、TOKENIZERS_PARALLELISM）、YAML 中声明的环境变量（CFG_PARALLEL、USE_VAE_PARALLEL、CPU_AFFINITY_CONF会覆盖默认值），以及 HCCL 通信配置；
• 在res/<YYYYMMDD>/<model_name>/下自动创建日志目录，并将推理输出tee到log_<timestamp>.log；
• 调用torchrun --master_port=<master_port> --nproc_per_node=<world_size> run_image_gen.py <model_args>。

在run_image_gen.py中，以循环的形式对model.generate_image()调用了多次，前面几次可以视为 warmup，多轮推理后的性能趋于稳定，而就精度而言则每次都是一致的。

本样例测试结果如下：

4. 性能分析

如果需要分析 profiling，可以将adaptor_patches/hunyuan_image_e_pipeline.py中的enable_prof = False if idx_round > 1 else False改为enable_prof = True if idx_round > 1 else False，并确保run_image_gen.py中对model.generate_image()调用 2 次以上，这样在第 2 次及以后便会自动采集 profiling 数据。相关配置可以在models/hunyuan-image-3.0/adaptor_patches/hunyuan_image_3_pipeline.py中配置，参考 torch_npu.profiler 接口。

优化点参考

本样例采用的详细优化点介绍可参见NPU HunyuanImage-3.0模型推理优化实践。

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