企业官网建设流程全解析

昇腾 CANN 分组矩阵乘量化算子样例集实战指南：MXFP4 / MXFP8 / HiFloat8 / MXA8W4

【免费下载链接】cann-samplesCANN高性能实战演进样例与体系化调优知识库项目地址: https://gitcode.com/cann/cann-samples

本篇文章围绕 CANN 高性能实战样例仓库cann-samples中grouped_matmul_recipes目录展开，系统介绍面向 MoE 等多专家推理/训练场景的分组矩阵乘（Grouped Matmul）量化算子在昇腾 AI 处理器（NPU ARCH 3510）上的典型实现样例：从目录结构、样例能力、使用约束、输入参数与数据生成方式，到构建、运行、结果校验的完整实操流程，并延伸到 MX 量化分组矩阵乘的性能建模与优化策略，帮助读者快速上手并深入理解昇腾平台上的分组量化矩阵乘编程实践。

一、样例集概览：什么是分组矩阵乘

分组矩阵乘（Grouped Matmul）是面向 MoE（Mixture of Experts）等包含多专家分组计算场景的算子形态。与普通矩阵乘不同，Grouped Matmul 按专家数进行分组，每组执行一次独立的矩阵乘计算：

• 输入矩阵A在M维按组拼接；
• 权重矩阵B按组独立存储；
• 每个分组的分组值由输入group_list指定，允许分组值为0，表示该专家未被选中。

grouped_matmul_recipes目录汇总了分组矩阵乘在昇腾 AI 处理器上的典型量化实现样例，每个样例提供完整的算子代码（.asc）、运行脚本与说明文档，可直接编译运行并做性能对比。该目录位于 Samples/2_Performance/grouped_matmul_story/grouped_matmul_recipes，是 grouped_matmul_story 主题下"算子实现与示例代码"部分的主体。

目录结构

grouped_matmul_recipes/ ├── CMakeLists.txt ├── README.md ├── common/ # 公共工具（host/kernel） ├── include/ # 共享头文件（block、kernel、tile、tiling 等） └── examples/ ├── quant_grouped_matmul_mxfp4/ # MXFP4 分组量化矩阵乘样例 ├── quant_grouped_matmul_mxfp8/ # MXFP8 分组量化矩阵乘样例 ├── quant_grouped_matmul_hif8/ # HiFloat8 分组量化矩阵乘样例 └── weight_quant_grouped_matmul_mxfp8fp4/ # MXA8W4 权重量化分组矩阵乘样例

• common/下分为host_utils/（acl_utils.h、common_utils.h、io_utils.h）与kernel_utils/（common_utils.h、layout_utils.h、tensor_utils.h），提供 host 侧算子启动与 kernel 侧通用工具；
• include/下按block/（MMA 计算块与调度器）、kernel/（kernel 主体）、policy/（dispatch 策略）、prologue/（prologue 处理）、tile/（GM↔UB↔L1 数据搬运与格式转换）、tiling/（tiling 结构与 tiling 数据）、utils/（常量与布局结构体）分层组织共享头文件。

二、样例列表：四种量化数据类型

从 性能优化指南 中的对比可知，MX 量化家族的主要差异在于：

其中 MX 量化的本质是 Microscaling 量化，即 pergroup-pergroup 量化模式（G-G 量化），是量化参数类型为FLOAT8_E8M0且 group size 为 32 的特例，详见 量化介绍。

三、样例能力与实现变体

每个样例目录下都包含若干可执行程序变体与配套脚本，覆盖不同分组轴、不同权重存储布局与不同流水深度：

MXFP4（quant_grouped_matmul_mxfp4）

• quant_grouped_matmul_mxfp4_split_m：基于 m 轴分组、权重按 ND（包括 NDExtLayout/DNExtLayout，统称 ND）逻辑组织的分组量化矩阵乘示例；
• quant_grouped_matmul_mxfp4_split_m_weight_nz：基于 m 轴分组、权重按 GM 上 NZ（包括 NZLayout/ZNLayout，统称 NZ）存储的分组量化矩阵乘示例；
• gen_data.py：生成 ND 权重输入数据和 CPU golden 结果；
• gen_data_weight_nz.py：生成 NZ 权重输入数据和 CPU golden 结果；
• verify_result.py：校验 NPU 输出与 CPU golden 是否一致。

MXFP8（quant_grouped_matmul_mxfp8）

MXFP8 样例提供最丰富的变体集合：

• quant_grouped_matmul_mxfp8_split_m：基于 m 轴分组、权重按 ND 逻辑组织的分组量化矩阵乘示例；
• quant_grouped_matmul_mxfp8_split_m_3buffer：基于 m 轴分组、权重按 ND 逻辑组织的 3buffer 分组量化矩阵乘示例（其余示例均为 2buffer）；
• quant_grouped_matmul_mxfp8_split_m_weight_nz：基于 m 轴分组、权重按 GM 上 NZ 存储的分组量化矩阵乘示例；
• quant_grouped_matmul_mxfp8_split_m_scale_b_nz：基于 m 轴分组、权重按 ND 逻辑组织、ScaleB 按 GM 上 scaleB 私有格式（仅包括 NNLayout，形状为(N1, Kg, 16, 2)）存储的分组量化矩阵乘示例，其中N1=ceil(N/16)，Kg=ceil(K/64)，ScaleB 私有格式与 transB 无关，只有上述一种；
• quant_grouped_matmul_mxfp8_split_k：基于 K 轴分组、权重按 ND 逻辑组织的分组量化矩阵乘示例，仅支持transA=true, transB=false场景；
• gen_data.py/gen_data_weight_nz.py/gen_data_scale_b_nz.py：分别生成 ND 权重、NZ 权重、ND 权重 + NZ ScaleB 的输入数据与 CPU golden 结果；
• verify_result.py：校验 NPU 输出与 CPU golden 是否一致。

HiFloat8（quant_grouped_matmul_hif8）

• quant_grouped_matmul_hif8_split_m_tt：基于 M 轴分组、采用 T-T 量化模式的分组量化矩阵乘示例，每个 group 一组 FP32 标量pertoken_scale.bin+scale.bin；
• quant_grouped_matmul_hif8_split_m_tc：基于 M 轴分组、采用 T-C 量化模式的分组量化矩阵乘示例，每个 group 的 N 维uint64per-channelscale.bin；
• scripts/gen_data_tt.py/scripts/gen_data_tc.py：分别生成 T-T、T-C 量化模式输入数据和 CPU golden 结果；
• scripts/verify_result.py：校验 NPU 输出与 CPU golden 是否一致。

T-T 与 T-C 是量化介绍中"常见组合量化"的两种模式：T-T 即 pertensor-pertensor 量化（全量化的一种），T-C 即 pertensor-perchannel 量化，两者分别以组内共享标量或 per-channel 向量作为量化参数。

MXA8W4（weight_quant_grouped_matmul_mxfp8fp4）

• weight_quant_grouped_matmul_mxfp8fp4：基于 m 轴分组的权重量化 grouped matmul 执行程序，A 为 FP8(E4M3)、B 为 FP4(E2M1)、输出 BF16；
• scripts/gen_data.py：生成输入数据和 CPU golden 结果；
• scripts/verify_result.py：校验 NPU 输出与 CPU golden 是否一致；
• scripts/batch_test_accuracy.py：批量随机精度回归测试脚本。

四、输入参数与命令行约定

四个样例的算子执行文件与结果校验脚本的命令行参数格式一致（MXA8W4 样例仅支持默认转置组合，不包含 transA/transB 参数）：

<program> group_num m k n [transA transB]

参数含义：

• group_num：专家数，也就是分组数；
• group_value_list（由数据生成脚本生成）：表示每个专家对应的分组大小，例如128,128,0；
• m：总的M大小，要求满足m >= sum(group_value_list)（K 轴分组时改为对k的约束）；
• k：矩阵A的列数，同时也是每组矩阵B的列数（K 轴分组时要求k >= sum(group_value_list)）；
• n：每组矩阵B的行数，也是输出矩阵每组结果的列数；
• transA：可选参数，默认值为false；false表示 A 以[M, K]组织，true表示 A 以[K, M]组织（MXFP8 split_k 场景）；
• transB：可选参数，默认值为true；true表示 B 以[E, N, K]（NZ 为[E, K1, N1, N0, K0]）组织，false表示 B 以[E, K, N]（NZ 为[E, N1, K1, K0, N0]）组织。

transA和transB需要同时省略或同时指定，取值支持0/1/true/false。实际参与计算的group_value_list由数据生成脚本生成，写入input/input_groupList.bin，该文件保存每个分组各自的M大小，允许某些组为0。

从数据生成脚本 scripts/gen_data.py 的源码可以印证这些约定的底层实现：脚本定义了GROUP_LIST_MODE = "group_list"与EXPECT_M_PER_GROUP_MODE = "expect_m_per_group"两种模式以及DEFAULT_TRANS_A = False、DEFAULT_TRANS_B = True默认值；parse_group_m_list()逐项解析逗号分隔的分组大小并拒绝负值，build_random_group_m_list()则校验group_num > 0并在m < group_num * floor(0.7 * expect_m_per_group)时直接报错。

五、数据生成方式

gen_data.py（ND 权重）、gen_data_weight_nz.py（NZ 权重）、gen_data_scale_b_nz.py（ND 权重 + NZ ScaleB，MXFP8）以及 HiFloat8 样例的gen_data_tt.py/gen_data_tc.py均支持以下两种调用方式，仅将脚本名替换即可：

方式一：显式指定group_value_list

python3 <gen_script>.py group_list group_value_list m k n [transA transB]

示例：

# ND权重 python3 gen_data.py group_list 128,128,0 384 256 256 false false # NZ权重 python3 gen_data_weight_nz.py group_list 128,128,0 384 256 256 false false # NZ ScaleB（仅支持M轴分组，权重仍为ND） python3 gen_data_scale_b_nz.py group_list 128,128,0 384 256 256 false false

• group_list：显式分组模式，直接传入每个专家的分组大小；
• group_value_list：每个专家对应的分组大小，例如128,128,0；
• m：矩阵乘的m维，要求m >= sum(group_value_list)；
• k：矩阵乘的k维；
• n：矩阵乘的n维。

方式二：按专家数和期望平均值随机生成group_value_list

python3 <gen_script>.py expect_m_per_group group_num expect_m_per_group m k n [transA transB]

示例：

python3 gen_data.py expect_m_per_group 3 128 384 256 256 false false

• expect_m_per_group：随机分组模式，按每组期望分组大小随机生成分组；
• group_num：专家数 / 分组数；
• expect_m_per_group：每组期望平均分组大小；
• m/k/n：同上。

在该模式下，脚本会随机生成长度为group_num的group_value_list，并保证：

• 每个分组大小均在[floor(0.7 * expect_m_per_group), ceil(1.3 * expect_m_per_group)]范围内；
• sum(group_value_list) <= m（源码中还会提前校验m >= group_num * floor(0.7 * expect_m_per_group)，不满足时直接抛出异常，避免生成无法满足总M上限的分组）。

golden 输入数据由对应的数据生成脚本生成，编译安装后请在build_out下的本示例目录中执行该脚本（ND 权重用gen_data.py，NZ 权重用gen_data_weight_nz.py，依此类推）。

六、使用约束与形状约定

MXFP4

• 仅支持transA=false, transB=true和transA=false, transB=false两种场景；
• 当transB=true时，A 形状为[M, K]，B ND/NZ 形状为[E, N, K]/[E, K1, N1, N0, K0]，其中N0=16、K0=64、N1=ceil(N/N0)、K1=ceil(K/K0)；
• 当transB=false时，A 形状为[M, K]，B ND/NZ 形状为[E, K, N]/[E, N1, K1, K0, N0]，其中K0=16、N0=64、K1=ceil(K/K0)、N1=ceil(N/N0)；
• 仅支持 m 轴分组；
• MXFP4 内轴K必须为偶数；当transB=false时，N也必须为偶数。

MXFP8

支持transA=false, transB=true、transA=false, transB=false和transA=true, transB=false三种转置组合，以及 M/K 轴分组，对应约束为：

• M 轴分组且transA=false, transB=true：A 形状[M, K]，B ND/NZ 形状[E, N, K]/[E, K1, N1, N0, K0]，N0=16、K0=32；ScaleB ND/NZ 形状[E, N, Kg, SCALE_C0=2]/[E, N1, Kg, N0, SCALE_C0=2]，N0=16、SCALE_C0=2、Kg=ceil(K/64)、N1=ceil(N/16)；
• M 轴分组且transA=false, transB=false：A 形状[M, K]，B ND/NZ 形状[E, K, N]/[E, N1, K1, K0, N0]，K0=16、N0=32；ScaleB ND/NZ 形状[E, Kg, N, SCALE_C0=2]/[E, N1, Kg, N0, SCALE_C0=2]；
• K 轴分组即transA=true, transB=false：A 形状[K, M]，B ND 形状[K, N]。

HiFloat8

• 仅支持 M 轴分组（split-M 路径），transA必须为false；
• 支持transB=true（B 形状[E, N, K]）与transB=false（B 形状[E, K, N]）两种场景，A 形状均为[M, K]；
• 输入数据类型为hifloat8，输出数据类型为bfloat16。

MXA8W4

• 仅支持A不转置、B转置场景，A 形状[M, K]，B 形状[E, N, K]；
• 仅支持 m 轴分组；
• k需为64的正整数倍（数据生成与校验脚本按该约束实现）；
• n需为32的正整数倍（精度回归脚本按该约束实现）；
• m需满足m >= sum(group_m_list)。

支持架构

以上样例均面向NPU ARCH 3510（构建时通过-DNPU_ARCH=dav-3510指定）。

七、构建与运行

在仓库根目录下执行全量编译与安装，并进入安装目录：

cmake -S . -B build -DNPU_ARCH=dav-3510 cmake --build build --parallel cmake --install build --prefix ./build_out cd build_out/2_Performance/grouped_matmul_story/grouped_matmul_recipes/quant_grouped_matmul_mxfp4

构建配置由 grouped_matmul_recipes/CMakeLists.txt 定义：add_grouped_matmul_recipe为每个.asc源文件生成可执行目标，链接m、dl、platform、tiling_api与cann_samples::tensor_api，并按样例子目录安装到grouped_matmul_recipes/${variant}下；同时会通过install(DIRECTORY ... FILES_MATCHING PATTERN "*.py" PATTERN "*.sh")将每个样例的scripts/辅助脚本安装到与可执行文件相同的目录，保证安装目录下可直接运行数据生成与结果校验脚本。

MXFP4 运行示例

ND 权重：

# 生成数据方式一：显式指定grouplist生成一组测试数据 python3 gen_data.py group_list 128,128,0 384 256 256 # 生成数据方式二：按专家数和平均M随机生成grouplist python3 gen_data.py expect_m_per_group 3 128 384 256 256 # 运行可执行文件并校验结果（默认transA=false, transB=true） ./quant_grouped_matmul_mxfp4_split_m 3 384 256 256 # 运行transB=false场景（显式指定transA/transB） python3 gen_data.py group_list 128,128,0 384 256 256 false false ./quant_grouped_matmul_mxfp4_split_m 3 384 256 256 false false

NZ 权重：

python3 gen_data_weight_nz.py group_list 128,128,0 384 256 256 ./quant_grouped_matmul_mxfp4_split_m_weight_nz 3 384 256 256 python3 gen_data_weight_nz.py group_list 128,128,0 384 256 256 false false ./quant_grouped_matmul_mxfp4_split_m_weight_nz 3 384 256 256 false false

MXFP8 运行示例

ND 权重（覆盖全部变体）：

# 默认场景 transA=false, transB=true python3 gen_data.py group_list 128,128,0 384 256 256 ./quant_grouped_matmul_mxfp8_split_m 3 384 256 256 # M轴分组: transA=false, transB=false python3 gen_data.py group_list 128,128,0 384 256 256 false false ./quant_grouped_matmul_mxfp8_split_m 3 384 256 256 false false # M轴分组3buffer场景 ./quant_grouped_matmul_mxfp8_split_m_3buffer 3 384 256 256 false false # K轴分组: transA=true, transB=false python3 gen_data.py group_list 128,128,0 384 384 256 true false ./quant_grouped_matmul_mxfp8_split_k 3 384 384 256 true false

NZ 权重与 NZ ScaleB（仅支持 M 轴分组）：

python3 gen_data_weight_nz.py group_list 128,128,0 384 256 256 ./quant_grouped_matmul_mxfp8_split_m_weight_nz 3 384 256 256 python3 gen_data_scale_b_nz.py group_list 128,128,0 384 256 256 ./quant_grouped_matmul_mxfp8_split_m_scale_b_nz 3 384 256 256

HiFloat8 运行示例

# T-T量化模式 python3 scripts/gen_data_tt.py group_list 64,80,96 256 128 256 ./quant_grouped_matmul_hif8_split_m_tt 3 256 128 256 # T-C量化模式（transB=false 需显式指定） python3 scripts/gen_data_tc.py group_list 64,80,96 256 128 256 false false ./quant_grouped_matmul_hif8_split_m_tc 3 256 128 256 false false

MXA8W4 运行示例

python3 gen_data.py group_list 128,128,0 384 256 256 ./weight_quant_grouped_matmul_mxfp8fp4 3 384 256 256

MXA8W4 的程序在执行完成后会自动调用verify_result.py进行结果校验。四个样例均支持可选的手动复核：

python3 verify_result.py 3 384 256 256

gen_data.py生成的文件清单（以 MXA8W4 为例，其余样例类似）：

CPU golden: output/output_cpu.bin input/input_a.bin input/input_b.bin input/input_scaleA.bin input/input_scaleB.bin input/input_groupList.bin

运行可执行文件后额外生成：

NPU output: output/output_npu.bin

八、性能优化指南：分组矩阵乘的性能建模与优化

样例的模板实现与优化策略详见 MX 量化分组矩阵乘算子性能优化指南。推荐先从quant_grouped_matmul_mxfp4开始，便于快速验证脚本与可执行文件的配套流程。

分组原理：M 轴分组与 K 轴分组

GroupedMatmul 由 E 个单 Matmul 组成，按分组更新A/B/ScaleA/ScaleB/C的 GM 基址偏移：

• M 轴分组：将当前组的(M_e, N, K)视作单个 MX 矩阵乘，以行维度 M 为划分依据，将整体矩阵乘拆分为多个行维度 M 分片子矩阵乘，A(M, K)、B(E, N, K)或(E, K, N)，各组 B 矩阵大小一致，各组输出沿 M 维度拼接。

• K 轴分组：将当前组的(M, N, K_e)视作单个 MX 矩阵乘，以内积收缩维度 K 为划分依据，A(K, M)、B(K, N)，将 K 维度切分为多个子通道块，各组输出大小一致，各组在对应 K 分片上独立计算并拼接结果。

分组内的 MX 矩阵乘实现与约束和 quant matmul MX 矩阵乘一致，可参考 quant_matmul_mx_performance.md。

性能瓶颈分析

单 MX Matmul 的性能瓶颈分为两类：

1. CUBE Bound：算子性能受限于硬件算力规格，本身已实现连续的 MMAD 计算，此时需重点关注多核计算负载是否均衡，避免单核 Cube Bound 而整体 Cube 利用率偏低；
2. Memory Bound：算子性能受限于数据搬运能力，按瓶颈所在流水进一步区分为MTE2 Bound、MTE1 Bound与FIXPIPE Bound。

在单 MX Matmul 的 Bound 分类之上，分组场景额外引入组间切换与负载不均：每个分组的数据不能组间复用，各分组值不同可能导致每个分组 MX Matmul 的性能瓶颈不同。若每个 Matmul 都是同种 Bound（如都是 CUBE Bound），则 GroupedMatmul 是该种 Bound；否则性能瓶颈需按各组时间加权估算，而非由单次 Matmul 的(M,N,K)决定。

优化手段清单

• Double Buffer（双缓冲）：两个缓冲区交替工作，用计算与数据准备的叠加隐藏内存访问延迟。2-Buffer 覆盖基本重叠关系、资源开销小；3-Buffer 仅在 L1 侧增加第三份阶段缓冲（A/B 数据），L0 层仍为 2-Buffer，用于减少搬运抖动、带宽瞬时不足造成的断流风险。3-Buffer 需满足 L1 容量约束：A1 + B1 + scaleA + scaleB + A3 <= HALF_L1_SIZE且A2 + B2 + scaleA + scaleB + B3 <= HALF_L1_SIZE，不满足时建议回退 2-Buffer 并结合 SWAT/Bank 冲突优化。
• UnitFlag（单元标志）：为 MMAD 计算指令与 FIXPIPE 数据搬运指令提供 512B 粒度的基于内存访问的细粒度同步，在无法开启 L0C Double-Buffer 时有效提高计算与搬出流水并行度。
• SWAT（自适应滑动窗口模板）：通过提升多核单次访问的 L2 命中率提高 MTE2 搬运效率，在 M 轴上设定固定窗口、根据尾块大小灵活调整并沿 N 方向"Z"型滑动，使首轮搬运即可做到 MMAD 指令不断流。
• L1 Bank 冲突优化：L1 缓冲区以 256KB 粒度分为两个 Bank，开启 L1 Double Buffer 时将两份缓存放置于不同 Bank，避免读写冲突导致的 MTE1 带宽下降。
• Scale 缓存优化：Scale 数据量仅为输入矩阵的 1/32，输入矩阵较小时可提前载入后续所需 Scale 并在 L1 上缓存，减少搬运次数、缓解带宽利用率低的问题。
• WeightNZ 优化：NZ/ZN 格式的 weight 数据可通过普通DataCopy搬运，相比带格式转换的ND2NZ指令带宽利用率更高，能显著降低 MTE2 耗时。
• 双页表：当分组 matmul 的 m 较小（<=baseM）时，weight 数据只使用一次，可将 weight 从 HBM 直接加载进 L1 缓冲区，避免 L2 有效数据回写 HBM 造成的额外 MTE2 耗时。
• group 间核负载均衡（GroupedMatmul 独有）：下一个分组 Matmul 接着上一个分组结束的核数往下分配核，避免每个分组均从 0 核开始计算。
• M 轴分组 M 计算负载均衡（GroupedMatmul 独有）：group_list 是 device tensor，M 轴分组时每分组M_e在 host 侧未知，需避免某些核 M 轴计算量偏大导致的快慢核性能劣化（K 轴分组不做该均衡，实现模板暂不切 K）。
• 尾轮负载均衡：将最后一轮未完全分配的基本块进行二次切分，均匀分配到多核，消除算力浪费。

优化策略选择指南

调优实践遵循"性能分析（Profiling + 性能建模定位 Bound）→ 瓶颈识别 → 策略选择 → 参数调优（tiling 参数与缓冲区使用）→ 效果验证 → 迭代优化"的闭环流程。从性能优化指南的模板归纳看，SWAT 模板作为基础模板覆盖了上述全部优化手段，其具体实现对应本样例集中的 MXFP4 splitM、MXFP4 splitM + WeightNZ、MXFP8 splitM、MXFP8 splitM + 3Buffer、MXFP8 splitM + WeightNZ、MXFP8 splitK 等.asc文件。

九、总结

grouped_matmul_recipes提供了昇腾 AI 处理器上分组矩阵乘量化算子的完整实战样例矩阵：从数据维度覆盖 MXFP4 / MXFP8 / HiFloat8 / MXA8W4 四种量化数据类型，从实现维度覆盖 M 轴 / K 轴分组、ND / NZ / ScaleB-NZ 权重布局、2-Buffer / 3-Buffer 流水与 T-T / T-C 量化模式，从工具链维度覆盖数据生成、编译构建、运行校验与精度回归。配合 量化介绍 与 性能优化指南，开发者可以按"选定数据类型样例 → 理解参数与约束 → 生成数据 → 构建运行 → 性能建模定位 Bound → 按策略选择指南迭代调优"的路径，系统掌握昇腾平台上 MoE 等分组计算场景的高性能量化矩阵乘开发方法。

【免费下载链接】cann-samplesCANN高性能实战演进样例与体系化调优知识库项目地址: https://gitcode.com/cann/cann-samples