腾讯混元 Hy3 在 CANN NPU 上的高性能推理部署与优化实战【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer本文基于 cann-recipes-infer 仓库中的 Hy3 推理样例系统讲解腾讯混元 Hy3295B MoE在 Atlas A3 与 Ascend 950PR/DT 平台上的完整部署流程从硬件环境、权重准备、YAML 配置到多卡推理拉起并深入剖析 Attention SPTP、MoE EP、MXFP8/MXFP4 量化与融合 Kernel 等优化原理。读者读完可独立完成 Hy3 在昇腾 NPU 上的端到端推理部署并掌握针对 GQAMoE 大模型的并行切分与图模式加速方法论。一、Hy3 模型概览腾讯混元 Hy3 是一款大规模 MoE 语言模型总参数量 295B、每 token 激活参数量约 21B原生支持 256K 上下文。cann-recipes-infer 基于 Hy3 开源实现完成 NPU 推理适配接入统一推理框架可在 Atlas A3 和 Ascend 950PR/DT 平台上运行对应的模型实现位于 models/hy3/models/modeling_hy_v3.py配置类位于 models/hy3/models/configuration_hy_v3.py。模型主要结构如下Decoder-only MoE80 层首层为 Dense FFN后续 79 层为 MoE另有 1 层 MTP 预测层约 3.8B 参数。AttentionGQAGrouped Query Attention64 个 Q heads / 8 个 KV headshead_dim 为 128支持 QK Norm 与 RoPERoPE theta 为 11,158,840。MoE192 个 routed expertstop-8 sigmoid routing包含 1 个 shared expert专家 FFN 中间维度 1536。词表大小120832最大上下文长度262144256K。从 models/hy3/models/configuration_hy_v3.py 的HYV3Config默认值可以看到更多关键参数hidden_size4096、intermediate_size13312首层 Dense FFN、rms_norm_eps1e-5、router_scaling_factor2.826、num_experts_per_tok8、first_k_dense_replace1、qk_normTrue、route_normTrue、moe_router_use_sigmoidTrue等。其中mlp_layer_types默认按[dense] [sparse] * 79构造与首层 Dense、后续 MoE的结构一致MTP 层权重通过_keys_to_ignore_on_load_unexpected [rmodel\.layers\.80.*]在加载时忽略确保推理只走主干 80 层。该样例的优化方案与性能数据可参考 Hy3 推理优化实践Atlas A3 平台端到端基础优化闭环记录见 models/hy3/agentic/optimization_report.md。二、硬件与软件环境要求平台产品型号配置Atlas A3Atlas A3 系列产品ci_a3/hy3_rank16_bf16_mtp.yamlAtlas A5Ascend 950PR/DT 系列产品ci_950/hy3_rank4_mxfp8_mtp.yamlAtlas A5Ascend 950PR/DT 系列产品ci_950/hy3_rank4_fp8_mtp.yaml说明执行前可通过npu-smi info检查 Ascend NPU 固件和驱动是否正确安装。基础软件版本A3 手动部署CANN 9.1.0.beta.1、PyTorch 2.8.0、torch_npu v26.0.0。A5 Docker 部署支持 x86 操作系统使用cann9.1.0.pt2.9.0_hy3_x86_image_v1.tar镜像。三、快速启动3.1 下载源码在各个节点上执行如下命令下载 cann-recipes-infer 源码mkdir -p /home/code cd /home/code git clone https://gitcode.com/cann/cann-recipes-infer.git cd cann-recipes-infer3.2 下载数据集Hy3 样例默认使用dataset/default_prompt.json中的内置 prompt。如需使用 LongBench 长序列数据集请在各个节点上准备dataset/LongBench目录mkdir -p dataset/LongBench huggingface-cli download --repo-type dataset THUDM/LongBench --local-dir dataset/LongBench使用 LongBench 时将 YAML 中的data_config.dataset修改为LongBench。若本地不存在dataset/LongBench框架会尝试在线读取THUDM/LongBench。说明LongBench 或自定义数据集默认走文本摘要 prompt 模板可在 executor/utils/data_utils.py 的build_dataset_input中按需修改。3.3 下载权重请下载 Hy3 权重并上传到各节点相同路径。BF16 原始权重用于 A3 bf16 配置及量化权重转换输入FP8 W8A8 量化权重可直接用于 A5/950 fp8 配置。BF16Tencent-Hunyuan/Hy3→/data/models/Hy3-BF16FP8Tencent-Hunyuan/Hy3-FP8→/data/models/Hy3-FP8示例下载命令pip install modelscope modelscope download --model Tencent-Hunyuan/Hy3 --local_dir /data/models/Hy3-BF16 modelscope download --model Tencent-Hunyuan/Hy3-FP8 --local_dir /data/models/Hy3-FP8说明A5/950 的 MXFP8MXFP4 权重需从 BF16 转换见下文转换权重章节。四、环境准备4.1 Atlas A3 部署手动1. 安装 CANN 软件包本样例依赖 CANN 开发套件包与 CANN 二进制算子包支持的 CANN 软件版本为CANN 9.1.0.beta.1。请从软件包下载地址下载Ascend-cann-toolkit_${version}_linux-${arch}.run与Ascend-cann-A3-ops_${version}_linux-${arch}.run软件包并参考 CANN 安装文档进行安装。${version}表示 CANN 包版本号如9.1.0.beta.1。${arch}表示 CPU 架构如aarch64、x86_64。2. 安装 Ascend Extension for PyTorchtorch_npu本样例支持的 torch_npu 版本为v26.0.0PyTorch 版本为2.8.0。请下载torch_npu-2.8.0.post4-cp311-cp311-manylinux_2_28_${arch}.whl安装包并参考 torch_npu 安装文档进行安装。3. 安装 Python 依赖cd /home/code/cann-recipes-infer pip3 install -r ./models/hy3/requirements.txtmodels/hy3/requirements.txt 中固定了关键依赖版本包括torch2.8.0、transformers5.0.0、compressed-tensors0.6.0、accelerate1.0.1等其中compressed-tensors用于解析 FP8/MXFP8 量化权重元数据quantization_config。4. 配置运行环境修改 executor/scripts/set_env.sh 中的如下字段IPs配置所有节点的 IP按照 rank id 排序多个节点的 IP 通过空格分开例如(xxx.xxx.xxx.xxx xxx.xxx.xxx.xxx)。cann_pathCANN 软件包安装路径例如/usr/local/Ascend/ascend-toolkit/latest。说明HCCL 相关配置如HCCL_SOCKET_IFNAME、HCCL_OP_EXPANSION_MODE可以参考集合通信文档并在 executor/scripts/function.sh 中自定义配置。4.2 Atlas A5 Docker 部署1. 获取 Docker 镜像从 x86 镜像地址下载 docker 镜像然后上传到 A5 服务器的每个节点上并通过命令导入镜像docker load -i cann9.1.0.pt2.9.0_hy3_x86_image_v1.tar。2. 拉起 Docker 容器在各个节点上通过如下脚本拉起容器默认容器名为cann_recipes_infer。注意需要将权重路径和源码路径挂载到容器里。以下示例挂载 8 个 NPU 设备并挂载源码与权重目录docker run -u root -itd --name cann_recipes_infer --ulimit nproc65535:65535 --ipchost \ --device/dev/davinci0 \ --device/dev/davinci1 \ --device/dev/davinci2 \ --device/dev/davinci3 \ --device/dev/davinci4 \ --device/dev/davinci5 \ --device/dev/davinci6 \ --device/dev/davinci7 \ --device/dev/davinci_manager --device/dev/devmm_svm \ --device/dev/hisi_hdc \ -v /home/:/home \ -v /data:/data \ -v /etc/localtime:/etc/localtime \ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \ -v /etc/ascend_install.info:/etc/ascend_install.info -v /var/log/npu/:/usr/slog \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi -v /sys/fs/cgroup:/sys/fs/cgroup:ro \ -v /usr/local/dcmi:/usr/local/dcmi -v /usr/local/sbin:/usr/local/sbin \ -v /etc/hccn.conf:/etc/hccn.conf -v /root/.pip:/root/.pip -v /etc/hosts:/etc/hosts \ -v /usr/bin/hostname:/usr/bin/hostname \ --nethost \ --shm-size128g \ --privileged \ cann9.1.0.pt2.9.0_hy3_x86_image:v1 /bin/bash3. 进入容器在各个节点上通过如下命令进入容器docker attach cann_recipes_infer cd /home/code/cann-recipes-infer同步修改 executor/scripts/set_env.sh 中的IPs和cann_path。五、转换权重HY3 权重转换过程中会同步完成权重文件和config.json的转换因此无需单独执行config.json转换步骤。转换前请先拉取 AMCT 仓库并使用其中的权重转换工具git clone https://gitcode.com/cann/amct.git cd amct如果权重转换的运行环境为 NPU需要先执行cann_path/usr/local/Ascend/cann # cann包安装路径 source ${cann_path}/bin/setenv.bash入参介绍model原始权重路径model_nameAMCT 内部模型适配器名称HY3 使用hy_v3device权重转换使用的 NPU 设备granularity转换粒度HY3 tensorwise 权重转换使用tensorquant_target量化目标模块quant_dtype量化数据类型bit_config量化位宽配置文件output_dir转换后输出的权重路径。权重转换拉起示例python3 amct_pytorch/cli/llm/deploy.py \ --trust_remote_code \ --model ./Hy3-BF16 \ --model_name hy_v3 \ --device npu:0 \ --granularity tensor \ --quant_target moe attn-linear mlp \ --quant_dtype mxfp \ --bit_config amct_pytorch/configs/w8a8.yaml \ --output_dir /data/models/Hy3-MXFP8转换产出的 MXFP8 权重同时可进一步派生 MXFP4 格式对应ci_950/hy3_rank4_mxfp4_mtp.yaml配置其默认model_path为/data/models/Hy3-MXFP4。从源码看models/hy3/models/modeling_hy_v3.py 中引入了W4A8MxFp4MoEGMMMethod来自module.quantization.mxfp4作为路由专家的量化执行方法说明 MXFP4 路径针对 MoE GMM 计算做了专门的量化实现。六、修改配置在各个节点上修改需要执行的 YAML 文件将model_config.model_path设置为权重实际路径。YAML 通用参数说明可参考 YAML 参数描述。当前仓内提供的 Hy3 MTP 配置如下平台YAML 文件默认model_path精度/特性说明A3ci_a3/hy3_rank16_bf16_mtp.yaml/data/models/Hy3-BF16BF16 MTP8卡 16ranknext_n1A5/950ci_950/hy3_rank4_mxfp8_mtp.yaml/data/models/Hy3-MXFP8MXFP8 MTP4卡next_n1A5/950ci_950/hy3_rank4_fp8_mtp.yaml/data/models/Hy3-FP8FP8 MTP4卡next_n1说明A5/950 配置当前面向量化权重快速启动阶段只下载 BF16 权重量化权重准备方式见转换权重章节。以 models/hy3/config/ci_a3/hy3_rank16_bf16_mtp.yaml 为例完整的并行与调度配置为model_config: model_name: hy3 model_path: /data/models/Hy3-BF16 platform_version: A3 exe_mode: npugraph_ex # [ge_graph, eager, npugraph_ex] with_ckpt: True # [False, True] enable_profiler: False # [False, True] enable_cache_compile: False # [False, True] next_n: 1 custom_params: enable_multi_streams: False # [False, True] enable_sp: False # [False, True]; A3 dense_tp1 须 False data_config: dataset: default # [default, LongBench] input_truncated_len: 400 parallel_config: world_size: 16 attn_tp_size: 4 dense_tp_size: 4 moe_tp_size: 1 embed_tp_size: 4 lmhead_tp_size: 4 scheduler_config: max_new_tokens: 128 batch_size: 4而 models/hy3/config/ci_950/hy3_rank4_mxfp4_mtp.yaml 展示了 950 长序列场景的配置差异enable_multi_streams: True、enable_sp: True、dataset: InfiniteBench、input_truncated_len: 65536、max_prefill_tokens: 65536覆盖 64K prefillmodel_config: model_name: hy3 model_path: /data/models/Hy3-MXFP4 platform_version: 950 exe_mode: npugraph_ex # [ge_graph, eager, npugraph_ex] with_ckpt: True # [False, True] enable_profiler: False # [False, True] enable_cache_compile: False # [False, True] next_n: 1 custom_params: enable_multi_streams: True # [False, True] enable_sp: True # [False, True] data_config: dataset: InfiniteBench # [default, LongBench, InfiniteBench] input_truncated_len: 65536 # 64K long-context input length for InfiniteBench parallel_config: world_size: 4 attn_tp_size: 4 dense_tp_size: 1 moe_tp_size: 1 embed_tp_size: 4 lmhead_tp_size: 4 scheduler_config: max_new_tokens: 128 max_prefill_tokens: 65536 # Match input_truncated_len to cover 64K prefill batch_size: 4从并行切分看A3 配置采用world_size168 卡 × 2 die/卡、attn_tp_size4、moe_tp_size1与 models/hy3/agentic/optimization_report.md 记录的并行策略一致Attention 按 8 个 KV 头的约束做 TP4 切分MoE 专家按全卡 EP 分布192/1612 experts/rank专家 FFN 中间维度1536较小、TP 会造成碎矩阵因此moe_tp_size1大词表120K的 Embedding 与 LM Head 均按 TP4 切分以节省显存。除框架统一配置外Hy3 还支持以下特性放置在 YAML 文件model_config的custom_params字段下参数名类型默认值含义enable_multi_streamsboolTrue启用多流并行重叠计算与通信以提升推理性能。enable_spboolTrue启用序列并行Sequence Parallelattn_tp_size1时按 token 切分。这两个参数在源码中有直接对应实现models/hy3/models/modules/common.py 中的is_sequence_parallel_enabled会读取custom_params.enable_spquantize_sequence_parallel_transport负责对 SP 传输中的激活做量化MXFP4 路径用torch_npu.npu_dynamic_mx_quant产出动态 MXFP8 值FP8 路径用目标 Linear 的静态 per-tensor input scale 量化equal_all_to_all实现了可被 npugraph_ex 捕获的等分 AllToAllbuild_pad_aware_prefill_metadata则为 SP 对齐补零追加一个虚拟请求段写入 block pool 保留的空块 0保证长序列 prefill 的序列切分对齐。当权重目录的config.json中quantization_config.kv_cache_scheme表示 float8 KV cache 时Hy3 会自动启用对应路径对应 FP8/MXFP8 配置下的 C8 KV Cache 量化路径。七、拉起多卡推理请先进入模型目录再执行统一推理入口避免日志输出到错误目录。统一入口脚本 executor/scripts/infer.sh 支持--model、--yaml、--modeoffline/online、--pd-role等参数先通过validate_infer_args.py校验参数再调用launch启动推理。A3 BF16 MTP 示例cd /home/code/cann-recipes-infer/models/hy3 export ASCEND_RT_VISIBLE_DEVICES0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15 bash ../../executor/scripts/infer.sh --model hy3 --yaml ci_a3/hy3_rank16_bf16_mtp.yamlA5/950 MXFP8MXFP4 MTP 示例。该命令仅在已准备对应量化权重并将 YAML 中的model_path修改为真实路径后执行cd /home/code/cann-recipes-infer/models/hy3 export ASCEND_RT_VISIBLE_DEVICES0,1,2,3 bash ../../executor/scripts/infer.sh --model hy3 --yaml ci_950/hy3_rank4_mxfp8_mtp.yamlA5/950 FP8 MTP 示例。该命令仅在已准备 FP8 权重并将 YAML 中的model_path修改为真实路径后执行cd /home/code/cann-recipes-infer/models/hy3 export ASCEND_RT_VISIBLE_DEVICES0,1,2,3 bash ../../executor/scripts/infer.sh --model hy3 --yaml ci_950/hy3_rank4_fp8_mtp.yaml说明多机环境需要在每个节点上执行同一条推理命令。脚本会根据 YAML 中的world_size与 executor/scripts/set_env.sh 中的 IP 列表计算各节点 rank 信息。推理输出会打印在 rank 0 日志中日志保存到models/hy3/res/${DATE}/${CASE_NAME}/log_*.log。八、推理优化实践深度解析除了端到端部署Hy3 样例还沉淀了面向 950PR/DT 平台 Prefill 场景的完整优化方案详见 Hy3 推理优化实践。Prefill 阶段需一次性处理完整输入序列属于计算密集compute-bound场景因此优化核心是在 TTFT 时延约束下最大化吞吐。8.1 并行策略Attention SPTPMoE EPAttention SPTPHy3 为 GQA 结构q_head:kv_head 64:8TP 并行是自然选择在 TP 基础上对 FA 前后算子增加序列并行SP。最终采用组合方案FA 前用 AllGather 将各 rank 子序列聚合成完整序列配合 FP8/MXFP8 量化减小通信数据量FA 后经 o_proj 后用 AllToAll 按序列维度重新分发相对纯 TP 的 ReduceScatter 进一步减少通信耗时。allgather 与 alltoall 通信均为量化后的 8bit 数据有效减少通信总量。MoE EPMoE 支持 TP 与 EP 两种并行。TP 会把 GMM 的 K/N 轴切得过小导致计算性能下降EP 下每个 rank 持有部分专家通过 InitRouting 完成 token 与专家的路由匹配。EP 又分为AG-RSAllGather-ReduceScatter与Double RoutingAlltoAll两种方案并行策略通信算子通信数据量适用场景EP (AG-RS)AllGather ReduceScatter(B,S,H) × 2ep_size较小、top_k ep_size时数据量更小EP (Double Routing)AlltoAll AlltoAll(BS×top_k/ep_size, H) × 2大EP场景、ep top_k时数据量更小当前模型top_k8在ep_size4时top_k ep_sizeAG-RS 方案通信数据量更小为默认优选方案。这一选择逻辑在源码 models/hy3/models/modeling_hy_v3.py 的_use_moe_ag_dispatch中有完整实现当moe_ep_size 1、SP 开启且attn_tp_size moe_ep_size、num_experts_per_tok moe_ep_size三个条件同时成立时启用 AG dispatch否则退回 AllToAll 定向投递方案。8.2 量化策略FP8 / Hybrid MXFP8-MXFP4本实践支持原生 FP8 量化同时支持用 MXFP8 替换原生 FP8 的 Linear 模块MoE 部分替换 MXFP4进一步提高整体性能。Hybrid MXFP8-MXFP4 整体量化策略如下Attentionq_proj、k_proj、v_proj、o_proj 使用 W8A8 量化W8 与 A8 均指 MXFP8KV Cache 采用 C8 量化——QK 使用动态 Per-Token-Head FP8 量化Scale 为 FP32V Cache 使用动态 Per-Head FP8 量化Scale 为 FP32。MoE路由专家的 Linear 使用 W4A8 量化W4 指 MXFP4共享专家的 Linear 使用 W8A8 量化。LMHead不量化。8.3 融合 KernelQKV 前处理融合算子与 FP8 全量化 GQA针对 Hy3 的 GQA 推理架构重点完成了FA 全 FP8 量化优化实现两个融合算子QKV 前处理融合算子qkv_rms_norm_rope_cache_with_k_scale融合 QKV split、RMSNormQK Norm、RoPE、rotation、动态量化、Cache 写回等操作拿到访存收益与计算流水收益。源码侧 models/hy3/models/modules/common.py 中的ensure_qkv_fused_kscale_registered会在首次使用时导入cann_ops_transformer.ops中的该算子以触发注册。FP8 全量化 GQA 融合算子fused_infer_attention_score包含 FP8 全量化 flash attention 计算过程。8.4 图编译缓存在模型推理场景下使能图编译缓存enable_cache_compile: True可以缓存编译后的静态图避免每次推理都重新编译模型从而提高推理性能。首次执行时经历 Dynamo 编译、Guards 检查、aclgraph Capture、Input 处理与 Replay 全流程开启缓存后后续执行跳过编译阶段Time save直接复用缓存的 aclgraph。接口调用形式如下if enable_cache_compile: compiled torch.npu.npugraph_ex.inference.cache_compile(model_forward, cache_dircache_dir, dynamicTrue, optionscompile_options)8.5 MoE 共享专家多流并行PrefillHy3 的 MoE 层中每个 token 除了走 top-8 路由专家还要过一个共享专家shared expert。共享专家只依赖 MoE 输入、不依赖 Gating 结果与路由专家的 dispatch、分组 GMM 之间没有数据依赖。Prefill 阶段据此把两者拆到两条流主流依次执行 Gating、路由专家路径默认 AG-RS 方案即 AllGather → InitRouting → 分组 GMM → FinalizeRouting → ReduceScatter、最后的 combine 相加共享专家下发到次流其启动同步点排在主流 Gating 之后。路由专家路径是 MoE 块的耗时主体共享专家与之并发、被其掩盖几乎不额外增加时延。多流机制在 models/hy3/models/modeling_hy_v3.py 中通过create_stream/npu_stream_switch/record_event/wait_event来自executor.utils.stream_utils实现。九、性能参考Hy3 在 Atlas A3 平台完成并行化部署、尚未引入算子融合或图模式优化时的基线性能eager 模式16 die为Prefill 1024 tokens 约 2070 ms、Decode 单步约 293 ms/token、显存占用约 54.5 GB/dieBF16 295B 参数 EPTP 分布后详见 models/hy3/agentic/optimization_report.md。Hy3 推理优化实践 给出的 Ascend 950PR 平台 BenchmarkOffline 推理模式采集不包含 Serving 调度和框架负载均衡影响如下Global Batch SizeChipsSeq LengthTTFT (ms)1432K2330.231464K7023.11十、相关资源汇总模型推理代码与部署说明models/hy3/README.md模型实现models/hy3/models/modeling_hy_v3.py、models/hy3/models/configuration_hy_v3.py、models/hy3/models/modules/common.py推理配置models/hy3/config/ci_a3/hy3_rank16_bf16_mtp.yaml、models/hy3/config/ci_950/hy3_rank4_mxfp4_mtp.yaml、models/hy3/config/ci_950/hy3_rank4_fp8_mtp.yaml优化实践与性能报告docs/models/hy3/hy3_optimization.md、models/hy3/agentic/optimization_report.md统一推理入口与公共配置executor/scripts/infer.sh、docs/common/inference_config_guide.md【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考