在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 系列产品环境准备安装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}.runA3环境或Ascend-cann-910b-ops_9.0.0-beta.1-${arch}.runA2环境软件包并参考CANN安装文档进行安装。${arch}表示CPU架构如aarch64、x86_64。安装Ascend Extension for PyTorchtorch_npu。Ascend Extension for PyTorchtorch_npu为支撑PyTorch框架运行在NPU上的适配插件本样例建议使用的Python版本为3.11PyTorch版本为2.7.1请先使用pip install torch2.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_npu2.7.1进行安装也可以从软件包下载地址下载release v7.3.1-pytorch2.7.1的whl包进行安装或者下载其源码参考源码编译安装。下载项目源码并安装依赖。# 下载项目源码以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请注意实测发现transformers5.3.0版本会产生精度问题推荐使用5.2.0及以下版本。配置 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.0HunyuanImage-3.0下载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/目录下已预置以下 YAMLYAML 文件卡数启动器适用场景ep8_cfg.yaml16torchrunAttn TP8 MoE EP8 CFG 并行 VAE 并行预置 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 → 命令行透传规则YAML 类型命令行效果示例字符串/数字--key valueseed: 42→--seed 42布尔true--keyflagreproduce: true→--reproduce布尔false忽略moe-ep: false→ 不添加列表--key v1 v2 …video-size: [720, 1280]→--video-size 720 1280完整参数说明详见 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_PARALLEL1开启 CFG 并行推理性能提升但需要将world_size相对于原 TP 规模翻倍。例如 Attn TP8 时若关闭 CFG 则world_size: 8开启 CFG 则需要world_size: 16USE_VAE_PARALLEL1开启 VAE 并行推理性能提升CPU_AFFINITY_CONF2开启自动绑核避免 CPU 核心抢占。通过export ASCEND_RT_VISIBLE_DEVICES0,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_portmaster_port --nproc_per_nodeworld_size run_image_gen.py model_args。在run_image_gen.py中以循环的形式对model.generate_image()调用了多次前面几次可以视为 warmup多轮推理后的性能趋于稳定而就精度而言则每次都是一致的。本样例测试结果如下ModelEnvironmentAttnMoECFG ParallelVAE ParallelE2Ehunyuan-image-3.0A3TP8TP8enableenable10.3shunyuan-image-3.0A3TP8EP8enableenable9.9s4. 性能分析如果需要分析 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考