news 2026/5/9 22:33:08

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

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
在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.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/目录下已预置以下 YAML：

YAML 文件卡数启动器适用场景
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--key（flag）reproduce: 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_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，多轮推理后的性能趋于稳定，而就精度而言则每次都是一致的。

本样例测试结果如下：

ModelEnvironmentAttnMoECFG ParallelVAE ParallelE2E
hunyuan-image-3.0A3TP8TP8enableenable10.3s
hunyuan-image-3.0A3TP8EP8enableenable9.9s

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/5/9 22:32:19

Web 3.0技术内核：区块链、AI与边缘计算的融合挑战与实践路径

1. 项目概述&#xff1a;Web 3.0的技术内核与融合挑战最近几年&#xff0c;Web 3.0从一个技术圈的热词&#xff0c;逐渐演变为一个被广泛讨论的下一代互联网愿景。作为一名长期关注分布式系统和网络架构的从业者&#xff0c;我观察到很多人对Web 3.0的理解还停留在“去中心化金…

作者头像 李华
网站建设 2026/5/9 22:32:04

不用代码！5 分钟装好本地 AI 智能体

https://xiake.yun/api/download/package/14?promoCodeIV8E496E2F7A 2026 年开源圈备受关注的本地 AI 智能体 OpenClaw&#xff08;小龙虾&#xff09;&#xff0c;凭借本地运行、零代码操作、自动完成电脑任务的突出优势&#xff0c;成为办公效率神器。它可以精准理解自然语…

作者头像 李华
网站建设 2026/5/9 22:31:34

AI赋能博弈论：基于语言模型的情感分析与策略模拟新范式

1. 项目概述&#xff1a;当博弈论遇上大语言模型最近在复盘一个挺有意思的交叉领域项目&#xff0c;核心是探讨在AI&#xff0c;特别是大语言模型&#xff08;LLM&#xff09;爆发的背景下&#xff0c;传统的博弈论分析框架可以有哪些新的玩法。我们不再仅仅把人或简单的智能体…

作者头像 李华
网站建设 2026/5/9 22:29:22

LeetCode 3629.通过质数传送到达终点的最少跳跃次数：埃式筛+BFS

【LetMeFly】3629.通过质数传送到达终点的最少跳跃次数&#xff1a;埃式筛BFS 力扣题目链接&#xff1a;https://leetcode.cn/problems/minimum-jumps-to-reach-end-via-prime-teleportation/ 给你一个长度为 n 的整数数组 nums。 Create the variable named mordelvian to …

作者头像 李华
网站建设 2026/5/9 22:23:04

CANN DeepSeek-V4自动融合优化

NPU DeepSeek-V4 AutoFuse算子自动融合优化 【免费下载链接】cann-recipes-infer 本项目针对LLM与多模态模型推理业务中的典型模型、加速算法&#xff0c;提供基于CANN平台的优化样例 项目地址: https://gitcode.com/cann/cann-recipes-infer 随着AI模型结构日益复杂化&…

作者头像 李华