企业官网建设流程全解析

腾讯混元 Hy3 在 CANN NPU 上的高性能推理部署与优化实战

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

本文基于 cann-recipes-infer 仓库中的 Hy3 推理样例，系统讲解腾讯混元 Hy3（295B MoE）在 Atlas A3 与 Ascend 950PR/DT 平台上的完整部署流程：从硬件环境、权重准备、YAML 配置到多卡推理拉起，并深入剖析 Attention SP+TP、MoE EP、MXFP8/MXFP4 量化与融合 Kernel 等优化原理。读者读完可独立完成 Hy3 在昇腾 NPU 上的端到端推理部署，并掌握针对 GQA+MoE 大模型的并行切分与图模式加速方法论。

一、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 MoE：80 层，首层为 Dense FFN，后续 79 层为 MoE（另有 1 层 MTP 预测层，约 3.8B 参数）。
• Attention：GQA（Grouped Query Attention），64 个 Q heads / 8 个 KV heads，head_dim 为 128，支持 QK Norm 与 RoPE（RoPE theta 为 11,158,840）。
• MoE：192 个 routed experts，top-8 sigmoid routing，包含 1 个 shared expert；专家 FFN 中间维度 1536。
• 词表大小：120832；最大上下文长度：262144（256K）。

从 models/hy3/models/configuration_hy_v3.py 的HYV3Config默认值可以看到更多关键参数：hidden_size=4096、intermediate_size=13312（首层 Dense FFN）、rms_norm_eps=1e-5、router_scaling_factor=2.826、num_experts_per_tok=8、first_k_dense_replace=1、qk_norm=True、route_norm=True、moe_router_use_sigmoid=True等。其中mlp_layer_types默认按["dense"] + ["sparse"] * 79构造，与"首层 Dense、后续 MoE"的结构一致；MTP 层权重通过_keys_to_ignore_on_load_unexpected = [r"model\.layers\.80.*"]在加载时忽略，确保推理只走主干 80 层。

该样例的优化方案与性能数据可参考 Hy3 推理优化实践，Atlas A3 平台端到端基础优化闭环记录见 models/hy3/agentic/optimization_report.md。

二、硬件与软件环境要求

说明：执行前可通过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-infer

3.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 配置。

• BF16：Tencent-Hunyuan/Hy3→/data/models/Hy3-BF16
• FP8：Tencent-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 的 MXFP8+MXFP4 权重需从 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 PyTorch（torch_npu）

本样例支持的 torch_npu 版本为v26.0.0，PyTorch 版本为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.txt

models/hy3/requirements.txt 中固定了关键依赖版本，包括torch==2.8.0、transformers==5.0.0、compressed-tensors==0.6.0、accelerate==1.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_path：CANN 软件包安装路径，例如/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 nproc=65535:65535 --ipc=host \ --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 \ --net=host \ --shm-size=128g \ --privileged \ cann9.1.0.pt2.9.0_hy3_x86_image:v1 /bin/bash

3. 进入容器

在各个节点上通过如下命令进入容器：

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_name：AMCT 内部模型适配器名称，HY3 使用hy_v3；device：权重转换使用的 NPU 设备；granularity：转换粒度，HY3 tensorwise 权重转换使用tensor；quant_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 配置如下：

说明：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_tp>1 须 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 prefill）：

model_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_size=16（8 卡 × 2 die/卡）、attn_tp_size=4、moe_tp_size=1，与 models/hy3/agentic/optimization_report.md 记录的并行策略一致：Attention 按 8 个 KV 头的约束做 TP=4 切分，MoE 专家按全卡 EP 分布（192/16=12 experts/rank），专家 FFN 中间维度（1536）较小、TP 会造成碎矩阵，因此moe_tp_size=1；大词表（120K）的 Embedding 与 LM Head 均按 TP=4 切分以节省显存。

除框架统一配置外，Hy3 还支持以下特性，放置在 YAML 文件model_config的custom_params字段下：

这两个参数在源码中有直接对应实现：models/hy3/models/modules/common.py 中的is_sequence_parallel_enabled会读取custom_params.enable_sp；quantize_sequence_parallel_transport负责对 SP 传输中的激活做量化（MXFP4 路径用torch_npu.npu_dynamic_mx_quant产出动态 MXFP8 值，FP8 路径用目标 Linear 的静态 per-tensor input scale 量化）；equal_all_to_all实现了可被 npugraph_ex 捕获的等分 AllToAll；build_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、--mode（offline/online）、--pd-role等参数，先通过validate_infer_args.py校验参数，再调用launch启动推理。

A3 BF16 + MTP 示例：

cd /home/code/cann-recipes-infer/models/hy3 export ASCEND_RT_VISIBLE_DEVICES=0,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.yaml

A5/950 MXFP8+MXFP4 + MTP 示例。该命令仅在已准备对应量化权重，并将 YAML 中的model_path修改为真实路径后执行：

cd /home/code/cann-recipes-infer/models/hy3 export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3 bash ../../executor/scripts/infer.sh --model hy3 --yaml ci_950/hy3_rank4_mxfp8_mtp.yaml

A5/950 FP8 + MTP 示例。该命令仅在已准备 FP8 权重，并将 YAML 中的model_path修改为真实路径后执行：

cd /home/code/cann-recipes-infer/models/hy3 export ASCEND_RT_VISIBLE_DEVICES=0,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 SP+TP，MoE EP

• Attention SP+TP：Hy3 为 GQA 结构（q_head:kv_head = 64:8），TP 并行是自然选择；在 TP 基础上对 FA 前后算子增加序列并行（SP）。最终采用组合方案：FA 前用 AllGather 将各 rank 子序列聚合成完整序列（配合 FP8/MXFP8 量化减小通信数据量），FA 后经 o_proj 后用 AllToAll 按序列维度重新分发（相对纯 TP 的 ReduceScatter 进一步减少通信耗时）。allgather 与 alltoall 通信均为量化后的 8bit 数据，有效减少通信总量。
• MoE EP：MoE 支持 TP 与 EP 两种并行。TP 会把 GMM 的 K/N 轴切得过小导致计算性能下降；EP 下每个 rank 持有部分专家，通过 InitRouting 完成 token 与专家的路由匹配。EP 又分为AG-RS（AllGather-ReduceScatter）与Double Routing（AlltoAll）两种方案：

当前模型top_k=8，在ep_size=4时top_k > ep_size，AG-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 整体量化策略如下：

• Attention：q_proj、k_proj、v_proj、o_proj 使用 W8A8 量化（W8 与 A8 均指 MXFP8）；KV Cache 采用 C8 量化——QK 使用动态 Per-Token-Head FP8 量化（Scale 为 FP32），V Cache 使用动态 Per-Head FP8 量化（Scale 为 FP32）。
• MoE：路由专家的 Linear 使用 W4A8 量化（W4 指 MXFP4），共享专家的 Linear 使用 W8A8 量化。
• LMHead：不量化。

8.3 融合 Kernel：QKV 前处理融合算子与 FP8 全量化 GQA

针对 Hy3 的 GQA 推理架构，重点完成了FA 全 FP8 量化优化，实现两个融合算子：

• QKV 前处理融合算子（qkv_rms_norm_rope_cache_with_k_scale）：融合 QKV split、RMSNorm（QK 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_dir=cache_dir, dynamic=True, options=compile_options)

8.5 MoE 共享专家多流并行（Prefill）

Hy3 的 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/die（BF16 295B 参数 EP+TP 分布后），详见 models/hy3/agentic/optimization_report.md。

Hy3 推理优化实践 给出的 Ascend 950PR 平台 Benchmark（Offline 推理模式采集，不包含 Serving 调度和框架负载均衡影响）如下：

十、相关资源汇总

• 模型推理代码与部署说明：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