HunyuanImage-3.0 MoE 多流变体实战在 CANN 上为共享 MLP 创建独立 NPU Stream【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer导读本文剖析 CANN 生态推理样例仓库cann-recipes-infer中一个典型的 NPU 多流优化案例针对 HunyuanImage-3.0 这类带 MoE 结构的原生多模态模型将「共享 MLPshared MLP与路由专家路径串行执行」的问题通过在模型初始化阶段显式创建share_mlp_stream并注入 MoE 模块的方式解决让共享分支与 MoE 主路径形成 overlap。读完本文你将掌握这种「初始化注入 stream」的多流实现风格的关键代码形态、同步编排方式event 记录与等待、适用边界与验证方法并能在自己的多模态 MoE 模型推理优化中复用同样的思路。案例定位多模态链路中的 MoE 多流在cann-recipes-infer的 NPU 多流优化案例库中案例手册按「每次优化算一个案例」组织HunyuanImage-3.0 MoE 多流变体被归类在MoE 多流分类下与 MoE 共享专家双流并行、Qwen3-Next Patch 形态的 MoE 双流 并列是共享专家/共享 MLP 双流思路在多模态模型上的特化变体。与纯文本 LLM 不同HunyuanImage-3.0 的优化不只落在 LLM 路径还要兼顾多模态整体链路文本生成、图像 token 生成、CFG 并行、VAE 并行等。它的 MoE 层采用「混合 MLP MoE」结构当配置use_mixed_mlp_moe开启时每层除了路由专家外还有一个shared_mlp分支其计算结果与路由专家输出相加。如果仍然按单流顺序执行共享 MLP 的计算会完整暴露在关键路径上影响整网时延。核心思路初始化注入而非前向临时切流从源码结构看这个案例与通用 LLM 的「共享专家双流」思想一致但实现风格更偏「显式创建共享流并把它注入模块」而不是在每次前向里临时切上下文。核心思路分四步在模型初始化阶段就创建share_mlp_stream在 MoE 模块中把这条流当作 shared MLP 的执行流路由专家主路径继续按原逻辑执行通过这种方式把多模态模型里的共享分支从主流剥离出去与主路径形成 overlap。也就是说多流能力在模块构造期就成为模块能力的一部分而不是后期局部插入。这一点也正是该案例在案例手册快速选型表中被标注为「多模态变体」的原因共享流在模块初始化阶段就作为能力注入而不是在前向里临时加 scope因此不能简单拷贝一段前向代码初始化和分布式上下文要一起看。执行编排图以下编排图展示了主流路由专家路径与share_mlp_stream共享 MLP之间的数据流与汇合关系共享输入hidden_states同时被主流与副流消费两条流的结果在「汇合输出」处通过事件同步后相加。源码级实现拆解1. 模块持有共享流MoE 初始化在 adaptor_patches/hunyuan.py 的moe_init中HunyuanMoE模块会持有一条共享流并通过kwargs传入未传入时以当前设备上的默认流兜底self.share_mlp_stream kwargs.get( share_mlp_stream, torch.npu.Stream(devicetorch.device(fnpu:{torch.npu.current_device()})) )同时use_mixed_mlp_moe配置决定了是否实例化shared_mlpHunyuanMLP(..., is_shared_mlpTrue)而_moe_impl npu_grouped_matmul时路由专家使用FusedMoEGMM融合实现if config.use_mixed_mlp_moe: self.shared_mlp HunyuanMLP(config, layer_idxlayer_idx, is_shared_mlpTrue) self.gate HunyuanTopKGate(config, layer_idxlayer_idx) ... if self._moe_impl npu_grouped_matmul: self.experts FusedMoEGMM( num_expertsself.num_experts, hidden_sizeself.config.hidden_size, intermediate_sizeself.config.intermediate_size, ... )2. 初始化时把流传给所有层模型初始化在model_init中模型初始化时直接把这条流传给各层。注意这里 stream 绑定的设备是local_rank对应的 NPU保证每条流落在正确的设备上kwargs[share_mlp_stream] torch.npu.Stream(devicetorch.device(fnpu:{local_rank})) self.layers nn.ModuleList( [HunyuanImage3DecoderLayer(config, layer_idx, **kwargs) for layer_idx in range(config.num_hidden_layers)] )HunyuanImage3DecoderLayer在decoder_layer_init中再把**kwargs透传给HunyuanMoE与 attention 模块因此这条流经由「模型 → 各 decoder layer → MoE 模块」的构造链逐层注入形成全模型共享的一条副流。这种写法说明多流不是后期局部插入而是初始化阶段就把「共享流」作为模块能力的一部分。3. 前向中的流同步编排event 记录与等待真正让 overlap 成立的是moe_forward中的同步编排。以 EP 路径moe_ep_size 1为例关键代码分三段第一段主流记录输入就绪事件副流等待后执行 shared MLPif self.moe_ep_size 1: if self.config.use_mixed_mlp_moe: input_ready_event torch.npu.Event() input_ready_event.record(torch.npu.current_stream()) with torch.npu.stream(self.share_mlp_stream): input_ready_event.wait() hidden_states_mlp self.shared_mlp(shared_mlp_input) combined_output self.moe_infer_double_routing(gate_input, expert_index, topk_weight) combined_output combined_output.reshape(bsz, seq_len, hidden_size)主流执行input_ready_event.record(torch.npu.current_stream())记录「共享 MLP 的输入已就绪」随后通过with torch.npu.stream(self.share_mlp_stream)切到副流在副流中input_ready_event.wait()等待输入就绪后执行self.shared_mlp(shared_mlp_input)主流并不等待副流而是继续进入moe_infer_double_routinggate → 两次 all_to_all dispatch →npu_moe_re_routing→ 专家 GMM 计算 → 第三次 all_to_all →npu_moe_finalize_routing由此共享 MLP 与路由专家主路径形成重叠窗口。非 EP 路径moe_ep_size 1在npu_moe_finalize_routing之后、all_reduce之前用同样的input_ready_event模式启动副流if self.config.use_mixed_mlp_moe: input_ready_event torch.npu.Event() input_ready_event.record(torch.npu.current_stream()) with torch.npu.stream(self.share_mlp_stream): input_ready_event.wait() hidden_states_mlp self.shared_mlp(shared_mlp_input)第二段汇合点等待副流完成再相加输出if self.config.use_mixed_mlp_moe: if self._moe_impl npu_grouped_matmul: mlp_done_event torch.npu.Event() mlp_done_event.record(self.share_mlp_stream) mlp_done_event.wait(torch.npu.current_stream()) output hidden_states_mlp combined_output # noqa else: output combined_output在副流self.share_mlp_stream上mlp_done_event.record(...)标记 shared MLP 完成主流在汇合处mlp_done_event.wait(torch.npu.current_stream())等待该事件确保hidden_states_mlp combined_output读到的是完整结果。这正是多流实现中最关键的「先证明正确再追性能」的体现跨流依赖通过 event 显式表达而不是依赖隐式同步。4. 与通用实现风格的对比对比通用 LLM 案例 MoE 共享专家双流并行后者在 decode 前向中使用npu_stream_switch(enable_multi_streams, 11)的 with-block 临时切流并可叠加tagged_event与 superkernelstream-fusion而本案例全程使用显式的torch.npu.Streamtorch.npu.Event原语record/wait/with torch.npu.stream(...)在初始化阶段完成流注入属于npugraph_ex / aclgraph 风格的显式 stream / event 生命周期管理两者 API 与约束不能混用。运行环境与配置前提环境与权重准备该案例依托models/hunyuan-image-3.0样例目录运行模型 README 给出的运行前提包括CANN 开发套件包与二进制算子包样例声明支持CANN 9.0.0-beta.1Atlas A2/A3 系列产品Ascend Extension for PyTorchtorch_npuv7.3.1与 PyTorch2.7.1依赖 HunyuanImage-3.0 开源仓库代码以非覆盖模式拷贝进models/hunyuan-image-3.0/并安装requirements.txt权重通过models/hunyuan-image-3.0/utils/convert_model.py转换--tp-attn、--tp-moe、--ep参数MoE 的 TP 与 EP 只能二选一且 Attention 部分目前仅支持 TP 切分。推理配置推理参数集中在 config/ep8_cfg.yaml预置为 Attn TP8 MoE EP8 CFG 并行 VAE 并行共 16 卡。与多流直接相关的配置要点model_args: model-id: ./ckpts/weight_ep8 attn-impl: npu # [sdpa, flash_attention_2, npu] moe-impl: npu_grouped_matmul # [eager, flashinfer, npu_grouped_matmul] moe-ep: true # [false, true] env_vars: CFG_PARALLEL: 1 # [0, 1] USE_VAE_PARALLEL: 1 # [0, 1] CPU_AFFINITY_CONF: 2moe-impl: npu_grouped_matmul使能 NPU 上的 MoE 实现走FusedMoEGMMnpu_moe_init_routing_v2等昇腾算子use_mixed_mlp_moe开启后即出现 shared MLP 分支是本案例多流优化的前提条件。多流实现本身在 adaptor_patches/hunyuan.py 末尾通过 monkey-patch 挂载如HunyuanMoE.__init__ moe_init、HunyuanMoE.forward moe_forward、HunyuanImage3Model.__init__ model_init由 model_adaptor.py 统一引入。注意事项与资源竞争初始化与分布式上下文一起看这类案例的多流设计更深地进入模块初始化share_mlp_stream绑定的设备是local_rank且 MoE 并行依赖hccl_comm_dictattn_tp / moe_tp / moe_ep / cfg_parallel 各通信组在init_parallel_comm_group中建立不适合简单拷贝一段前向代码多模态路径的资源竞争多模态链路中还有 CFG 并行CFG_PARALLEL1时 batch 翻倍、VAE 并行USE_VAE_PARALLEL1等其他优化若共享 MLP 已经吃满计算资源或与 CFG/VAE 并行争抢算力多流 overlap 成立也可能不降 wall需要继续评估资源争抢与拖尾同步点必须显式跨流依赖必须用 event 显式表达汇合点不能依赖隐式同步否则hidden_states_mlp combined_output会读到未完成结果出现精度或偶发错误验证而非猜测切流之后不能只凭 Stream ID 断言方案成立需要结合 profiler 时间线验证物理执行层面是否真的并行可参考多流技能 SKILL.md 中的「Stream ID 落点检查 overlap_pct 时间线验证」双重验证方法。复用参考代表实现HunyuanImage-3.0models/hunyuan-image-3.0/adaptor_patches/hunyuan.py相似实现与通用 LLM 的共享专家双流思想一致如 MoE 共享专家双流并行 对应的 DeepSeek-V3.2-Exp / GLM-5 等特化实现实现风格更偏「初始化注入 stream」而不是临时切上下文属于显式 stream/event 管理风格。关键词torch.npu.Streamshare_mlp_streamHunyuanImage-3.0MoEshared mlp多流stream overlapnpu_streamevent 同步【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HunyuanImage-3.0 MoE 多流变体实战：在 CANN 上为共享 MLP 创建独立 NPU Stream
HunyuanImage-3.0 MoE 多流变体实战在 CANN 上为共享 MLP 创建独立 NPU Stream【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer导读本文剖析 CANN 生态推理样例仓库cann-recipes-infer中一个典型的 NPU 多流优化案例针对 HunyuanImage-3.0 这类带 MoE 结构的原生多模态模型将「共享 MLPshared MLP与路由专家路径串行执行」的问题通过在模型初始化阶段显式创建share_mlp_stream并注入 MoE 模块的方式解决让共享分支与 MoE 主路径形成 overlap。读完本文你将掌握这种「初始化注入 stream」的多流实现风格的关键代码形态、同步编排方式event 记录与等待、适用边界与验证方法并能在自己的多模态 MoE 模型推理优化中复用同样的思路。案例定位多模态链路中的 MoE 多流在cann-recipes-infer的 NPU 多流优化案例库中案例手册按「每次优化算一个案例」组织HunyuanImage-3.0 MoE 多流变体被归类在MoE 多流分类下与 MoE 共享专家双流并行、Qwen3-Next Patch 形态的 MoE 双流 并列是共享专家/共享 MLP 双流思路在多模态模型上的特化变体。与纯文本 LLM 不同HunyuanImage-3.0 的优化不只落在 LLM 路径还要兼顾多模态整体链路文本生成、图像 token 生成、CFG 并行、VAE 并行等。它的 MoE 层采用「混合 MLP MoE」结构当配置use_mixed_mlp_moe开启时每层除了路由专家外还有一个shared_mlp分支其计算结果与路由专家输出相加。如果仍然按单流顺序执行共享 MLP 的计算会完整暴露在关键路径上影响整网时延。核心思路初始化注入而非前向临时切流从源码结构看这个案例与通用 LLM 的「共享专家双流」思想一致但实现风格更偏「显式创建共享流并把它注入模块」而不是在每次前向里临时切上下文。核心思路分四步在模型初始化阶段就创建share_mlp_stream在 MoE 模块中把这条流当作 shared MLP 的执行流路由专家主路径继续按原逻辑执行通过这种方式把多模态模型里的共享分支从主流剥离出去与主路径形成 overlap。也就是说多流能力在模块构造期就成为模块能力的一部分而不是后期局部插入。这一点也正是该案例在案例手册快速选型表中被标注为「多模态变体」的原因共享流在模块初始化阶段就作为能力注入而不是在前向里临时加 scope因此不能简单拷贝一段前向代码初始化和分布式上下文要一起看。执行编排图以下编排图展示了主流路由专家路径与share_mlp_stream共享 MLP之间的数据流与汇合关系共享输入hidden_states同时被主流与副流消费两条流的结果在「汇合输出」处通过事件同步后相加。源码级实现拆解1. 模块持有共享流MoE 初始化在 adaptor_patches/hunyuan.py 的moe_init中HunyuanMoE模块会持有一条共享流并通过kwargs传入未传入时以当前设备上的默认流兜底self.share_mlp_stream kwargs.get( share_mlp_stream, torch.npu.Stream(devicetorch.device(fnpu:{torch.npu.current_device()})) )同时use_mixed_mlp_moe配置决定了是否实例化shared_mlpHunyuanMLP(..., is_shared_mlpTrue)而_moe_impl npu_grouped_matmul时路由专家使用FusedMoEGMM融合实现if config.use_mixed_mlp_moe: self.shared_mlp HunyuanMLP(config, layer_idxlayer_idx, is_shared_mlpTrue) self.gate HunyuanTopKGate(config, layer_idxlayer_idx) ... if self._moe_impl npu_grouped_matmul: self.experts FusedMoEGMM( num_expertsself.num_experts, hidden_sizeself.config.hidden_size, intermediate_sizeself.config.intermediate_size, ... )2. 初始化时把流传给所有层模型初始化在model_init中模型初始化时直接把这条流传给各层。注意这里 stream 绑定的设备是local_rank对应的 NPU保证每条流落在正确的设备上kwargs[share_mlp_stream] torch.npu.Stream(devicetorch.device(fnpu:{local_rank})) self.layers nn.ModuleList( [HunyuanImage3DecoderLayer(config, layer_idx, **kwargs) for layer_idx in range(config.num_hidden_layers)] )HunyuanImage3DecoderLayer在decoder_layer_init中再把**kwargs透传给HunyuanMoE与 attention 模块因此这条流经由「模型 → 各 decoder layer → MoE 模块」的构造链逐层注入形成全模型共享的一条副流。这种写法说明多流不是后期局部插入而是初始化阶段就把「共享流」作为模块能力的一部分。3. 前向中的流同步编排event 记录与等待真正让 overlap 成立的是moe_forward中的同步编排。以 EP 路径moe_ep_size 1为例关键代码分三段第一段主流记录输入就绪事件副流等待后执行 shared MLPif self.moe_ep_size 1: if self.config.use_mixed_mlp_moe: input_ready_event torch.npu.Event() input_ready_event.record(torch.npu.current_stream()) with torch.npu.stream(self.share_mlp_stream): input_ready_event.wait() hidden_states_mlp self.shared_mlp(shared_mlp_input) combined_output self.moe_infer_double_routing(gate_input, expert_index, topk_weight) combined_output combined_output.reshape(bsz, seq_len, hidden_size)主流执行input_ready_event.record(torch.npu.current_stream())记录「共享 MLP 的输入已就绪」随后通过with torch.npu.stream(self.share_mlp_stream)切到副流在副流中input_ready_event.wait()等待输入就绪后执行self.shared_mlp(shared_mlp_input)主流并不等待副流而是继续进入moe_infer_double_routinggate → 两次 all_to_all dispatch →npu_moe_re_routing→ 专家 GMM 计算 → 第三次 all_to_all →npu_moe_finalize_routing由此共享 MLP 与路由专家主路径形成重叠窗口。非 EP 路径moe_ep_size 1在npu_moe_finalize_routing之后、all_reduce之前用同样的input_ready_event模式启动副流if self.config.use_mixed_mlp_moe: input_ready_event torch.npu.Event() input_ready_event.record(torch.npu.current_stream()) with torch.npu.stream(self.share_mlp_stream): input_ready_event.wait() hidden_states_mlp self.shared_mlp(shared_mlp_input)第二段汇合点等待副流完成再相加输出if self.config.use_mixed_mlp_moe: if self._moe_impl npu_grouped_matmul: mlp_done_event torch.npu.Event() mlp_done_event.record(self.share_mlp_stream) mlp_done_event.wait(torch.npu.current_stream()) output hidden_states_mlp combined_output # noqa else: output combined_output在副流self.share_mlp_stream上mlp_done_event.record(...)标记 shared MLP 完成主流在汇合处mlp_done_event.wait(torch.npu.current_stream())等待该事件确保hidden_states_mlp combined_output读到的是完整结果。这正是多流实现中最关键的「先证明正确再追性能」的体现跨流依赖通过 event 显式表达而不是依赖隐式同步。4. 与通用实现风格的对比对比通用 LLM 案例 MoE 共享专家双流并行后者在 decode 前向中使用npu_stream_switch(enable_multi_streams, 11)的 with-block 临时切流并可叠加tagged_event与 superkernelstream-fusion而本案例全程使用显式的torch.npu.Streamtorch.npu.Event原语record/wait/with torch.npu.stream(...)在初始化阶段完成流注入属于npugraph_ex / aclgraph 风格的显式 stream / event 生命周期管理两者 API 与约束不能混用。运行环境与配置前提环境与权重准备该案例依托models/hunyuan-image-3.0样例目录运行模型 README 给出的运行前提包括CANN 开发套件包与二进制算子包样例声明支持CANN 9.0.0-beta.1Atlas A2/A3 系列产品Ascend Extension for PyTorchtorch_npuv7.3.1与 PyTorch2.7.1依赖 HunyuanImage-3.0 开源仓库代码以非覆盖模式拷贝进models/hunyuan-image-3.0/并安装requirements.txt权重通过models/hunyuan-image-3.0/utils/convert_model.py转换--tp-attn、--tp-moe、--ep参数MoE 的 TP 与 EP 只能二选一且 Attention 部分目前仅支持 TP 切分。推理配置推理参数集中在 config/ep8_cfg.yaml预置为 Attn TP8 MoE EP8 CFG 并行 VAE 并行共 16 卡。与多流直接相关的配置要点model_args: model-id: ./ckpts/weight_ep8 attn-impl: npu # [sdpa, flash_attention_2, npu] moe-impl: npu_grouped_matmul # [eager, flashinfer, npu_grouped_matmul] moe-ep: true # [false, true] env_vars: CFG_PARALLEL: 1 # [0, 1] USE_VAE_PARALLEL: 1 # [0, 1] CPU_AFFINITY_CONF: 2moe-impl: npu_grouped_matmul使能 NPU 上的 MoE 实现走FusedMoEGMMnpu_moe_init_routing_v2等昇腾算子use_mixed_mlp_moe开启后即出现 shared MLP 分支是本案例多流优化的前提条件。多流实现本身在 adaptor_patches/hunyuan.py 末尾通过 monkey-patch 挂载如HunyuanMoE.__init__ moe_init、HunyuanMoE.forward moe_forward、HunyuanImage3Model.__init__ model_init由 model_adaptor.py 统一引入。注意事项与资源竞争初始化与分布式上下文一起看这类案例的多流设计更深地进入模块初始化share_mlp_stream绑定的设备是local_rank且 MoE 并行依赖hccl_comm_dictattn_tp / moe_tp / moe_ep / cfg_parallel 各通信组在init_parallel_comm_group中建立不适合简单拷贝一段前向代码多模态路径的资源竞争多模态链路中还有 CFG 并行CFG_PARALLEL1时 batch 翻倍、VAE 并行USE_VAE_PARALLEL1等其他优化若共享 MLP 已经吃满计算资源或与 CFG/VAE 并行争抢算力多流 overlap 成立也可能不降 wall需要继续评估资源争抢与拖尾同步点必须显式跨流依赖必须用 event 显式表达汇合点不能依赖隐式同步否则hidden_states_mlp combined_output会读到未完成结果出现精度或偶发错误验证而非猜测切流之后不能只凭 Stream ID 断言方案成立需要结合 profiler 时间线验证物理执行层面是否真的并行可参考多流技能 SKILL.md 中的「Stream ID 落点检查 overlap_pct 时间线验证」双重验证方法。复用参考代表实现HunyuanImage-3.0models/hunyuan-image-3.0/adaptor_patches/hunyuan.py相似实现与通用 LLM 的共享专家双流思想一致如 MoE 共享专家双流并行 对应的 DeepSeek-V3.2-Exp / GLM-5 等特化实现实现风格更偏「初始化注入 stream」而不是临时切上下文属于显式 stream/event 管理风格。关键词torch.npu.Streamshare_mlp_streamHunyuanImage-3.0MoEshared mlp多流stream overlapnpu_streamevent 同步【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考