CANN pto-isa 手工调优 Kernel 实战指南(A5 平台):Flash-Attention 与 MXFP4/MXFP8 矩阵乘法性能优化
CANN pto-isa 手工调优 Kernel 实战指南(A5 平台):Flash-Attention 与 MXFP4/MXFP8 矩阵乘法性能优化
本文围绕仓库 kernels/manual/a5 目录中的手工调优 kernel 示例展开,面向 Ascend A5 平台讲解三类偏性能实现:Flash-Attention 混合精度算子、MXFP4 与 MXFP8 高精度矩阵乘法。读完本文,你将掌握 A5 环境下 manual kernel 的 CANN 环境准备、
run.sh构建运行全流程、Flash-Attention 的 FA2.0 分阶段流水线实现思路,以及 MX 系列 MatMul 的"多核划分 + 基块选择 + L1 缓存 + 双缓冲"四件套优化方法论,并能读懂仓库中的性能参考数据。
一、目录定位:A5 手工调优 Kernel 是什么
在 CANN pto-isa 仓库中,kernels/manual/a5 是专门面向 Ascend A5 平台的手工调优(manual、performance-oriented)kernel 示例集。与 automode 等自动调度路径不同,这里的 kernel 通过手写 PTO 指令/宏来精确控制数据搬运(TLOAD/TSTORE/TEXTRACT)、矩阵乘(TMATMUL/TMATMUL_ACC)与向量计算(如 TSOFTMAXFA)的流水编排,以换取更高性能。
该目录下被 README.md 正式收录的三个核心示例为:
- flash_atten:基于 PTO 的混合精度 Flash-Attention(FA)算子;
- matmul_mxfp4_performance:面向非对齐场景的高性能 MXFP4 矩阵乘法;
- matmul_mxfp8_performance:MXFP8 高性能矩阵乘法。
此外目录中还有 allgather_gemm、gemm_ar、moe_combine、moe_dispatch、dispatch_mega_combine、engram_simt 等更多手工示例,可自行按需查看(均遵循同样的目录结构与运行约定)。
二、通用环境准备:构建运行的前置条件
三个示例的运行前提一致:必须先 source CANN 环境,再进入各示例目录按 run.sh 执行。README 给出的标准做法是:
source ${ASCEND_INSTALL_PATH}/bin/setenv.bash
随后按各示例目录内 README / run.sh 的说明操作。从 run.sh 脚本可以看到,构建时还会用到 ${ASCEND_HOME_PATH}/tools/simulator/${SOC_VERSION}/lib 下的模拟器库,并通过 cmake -DRUN_MODE=... -DSOC_VERSION=... 与 make -j16 完成编译(参见 flash_atten/run.sh、matmul_mxfp8_performance/run.sh)。因此请确保 ${ASCEND_INSTALL_PATH}、${ASCEND_HOME_PATH} 已正确配置到对应版本的 CANN 安装路径。
三、Flash-Attention 性能 Kernel(flash_atten)
3.1 功能概述与目录结构
该示例演示如何在 Ascend A5 上使用 PTO 实现混合精度 Flash Attention(FA)算子,覆盖工程搭建、编译构建与执行全流程。算子级详细说明、数学公式、切分策略与流水编排请见公共版本文档 kernels/manual/common/flash_atten/README.md,A5 版在该基础上针对 A5 架构做了专项适配。
目录结构如下(来自示例 README):
kernels/manual/a5/flash_atten/
├── scripts/
│ ├── gen_data.py # 生成输入与 golden 输出
│ ├── generate_cases.py # 生成测试用例
│ ├── pipeline_log_analysis.py # 流水线日志分析
│ ├── pipeline_schedule_gen.py # 流水线调度生成
│ └── run_timeline.sh # timeline 分析脚本
├── CMakeLists.txt # 构建配置
├── fa_performance_kernel.cpp # kernel 实现
├── fa_performance_kernel.h # kernel 头文件
├── main.cpp # Host 侧入口
├── pto_macro_fa_gu.hpp # FA GU 宏定义
├── pto_macro_fa_softmax.hpp # FA Softmax 宏定义
├── pto_macro_matmul.hpp # Matmul 宏定义
└── run.sh # 一键运行脚本
3.2 构建与运行:run.sh 的完整用法
进入示例目录后,可执行如下命令(${git_clone_path} 指仓库克隆路径):
cd ${git_clone_path}/kernels/manual/a5/flash_atten
# 运行默认用例(与 generated_cases.* 中内置的用例集一致)
bash run.sh -r npu -v Ascend910_9599
# 只运行生成用例集中的单个用例
bash run.sh -r npu -v Ascend910_9599 -c case_float_H_128_S0_128_S1_1024
# 提供自定义用例(分号分隔:HEAD_SIZE,S0,S1,CUBE_S0,TILE_S1)
# TILE_S1 支持 128(=CUBE_S1)、256、512
bash run.sh -r npu -v Ascend910_9599 --cases "128,128,1024,128,128;128,2048,2048,128,512"
# 提供自定义用例并只运行其中一个
bash run.sh -r npu -v Ascend910_9599 --cases "128,128,1024,128,128;128,512,2048,128,128" \
-c case_float_H_128_S0_128_S1_1024
运行成功时,终端会打印:
test success
注意 -v/--soc-version 参数在 run.sh 中有硬性校验:SOC_VERSION 必须以 Ascend910_9599 开头,否则脚本直接报 [ERROR] Unsupported SocVersion: ${SOC_VERSION}, this folder only support A5. 并退出。这正是"仅支持 A5"在脚本层的落地体现。
3.3 run.sh 支持的完整参数(源码级)
从 run.sh 的 getopt 定义可以整理出完整参数表:
| 短选项 | 长选项 | 含义 | 说明 |
|---|---|---|---|
-r |
--run-mode |
运行模式 | 如 npu(真实设备) |
-v |
--soc-version |
SoC 版本 | 仅支持 Ascend910_9599(A5) |
-n |
--npu |
NPU 设备号 | 默认 0 |
-c |
--case |
用例筛选 | 如 case_float_H_128_S0_128_S1_1024 |
-a |
--cases |
自定义用例列表 | 分号分隔的 HEAD_SIZE,S0,S1,CUBE_S0,TILE_S1 |
-p |
--qk-preload |
QK 预取深度 | 默认 2 |
-m |
--mode |
FIFO 模式 | 默认 1:0=ALL_GM_PATH,1=ALL_UB_PATH,2=QK_PV_UB_ONLY |
-i |
--intermediate |
输出中间结果 | 透传 --intermediate 给可执行文件 |
-d |
--debug |
调试构建 | 追加 -DDEBUG_MODE=ON |
-k |
--mask |
因果掩码 | 传给 generate_cases.py --causal-mask |
--mode_dn |
DN 数据布局模式 | 追加 -DMODE_DN=ON,运行 fa_performance_dn |
脚本内部流程为:调用 generate_cases.py 生成用例 → 调用 validate_buffer_usage.py(--mode nd/--mode dn)校验缓冲区用量 → cmake + make -j16 构建 → 调用 gen_data.py 生成数据 → 运行 fa_performance(或 fa_performance_dn)并附加 --sys_cnt_multiple=1.0。其中 -DCMAKE_LINK_DEPENDS_USE_LINKER=OFF 是为了规避 CMake 3.27+ 的 linker 依赖文件选项不被 cce-ld 接受的问题,属于 A5 工具链的兼容性处理。
3.4 算子描述:FlashAttention 2.0 的四阶段流水
A5 版 Flash-Attention 的完整数学描述、各阶段张量形状演变、实现与优化细节均以 kernels/manual/common/flash_atten/README.md 为准,核心要点如下:
- 计算流程(FlashAttention 2.0):设 Q∈ℝ^{S0×H}、K∈ℝ^{H×S1}、V∈ℝ^{S1×H}(H 为
HEAD_SIZE),标准注意力积为 QK=QKᵀ,P=softmax(QK/τ),O=PV。kernel 将 QK 与 P 的计算按 (S0,S1) 切块,并维护滚动部分和 O。缩放因子 s=1/√HEAD_SIZE。 - 四阶段划分:
compute_qk(Cube 流水):计算单个 S1 tile 的 Q·Kᵀ,Q tile 在tile_idx==0时只加载一次(leftTile stationary),后续仅加载 K tile,配合assign_running_acc_tile对 accTile 做双缓冲;compute_p(向量软最大化,TSOFTMAXFA):实现数值稳定的分块 softmax 递推,存储每 tile 的l1_exp_max与l2_global_sum供 GU 阶段使用,利用TROWMAX/TROWSUM静态 tile 尺寸、TROWEXPANDSUB原地计算减少 UB 占用;compute_pv(Cube 流水):P tile 与 V tile 相乘得到部分 PV 累加结果,写入pv_tile_fifo(乒乓全局缓冲);compute_gu(向量归约):基于TGU_ND/TGU_LAST_ND宏把各 tile 的部分 PV 累加进runningOTile,最后一个 tile 触发除以l2_global_sum的最终归一化。
- Cube/Vector 并行与流水编排:kernel 将矩阵工作与向量工作拆到不同流水,通过
qkPreloadNum(默认 4)让 Cube 侧提前生产 QK tile,qkp_tile_fifo_size = 1 + qkPreloadNum控制 QK/P FIFO 深度,pv_tile_fifo_size镜像控制 PV 与 GU 的重叠;同步使用轻量 device flag 以降低停顿。 - 多核切分与负载均衡:BNSD 输入下沿 (B, N, S/CUBE_S0) 维度切分(S1 是归约轴);因果掩码引入的稀疏性会造成 S0 轴负载不均,当前通过"块数大于物理核数"的多块 launch 缓解。
3.5 A5 平台专项优化
与 A2/A3 版本相比,A5 版针对 A5 架构特征做了三方面适配(README 明确列出的):
- 针对 A5 内存层次调整了缓冲区分配策略;
- 优化了 Cube 与 Vector 核之间的同步机制;
- 按 A5 硬件特性调优了流水线深度参数。
具体调参数值与对应性能数据将在后续版本中持续更新。
3.6 性能参考数据与指标定义
A5 版 README 给出的性能指标定义:
S0:query 序列长度(Q/O 的行数);S1:key/value 序列长度(K/V 的行数);Total task time (us):单个任务的端到端 kernel 耗时(微秒);GOps:任务统计的总操作数;TFLOPS:GOps / time。
参考测量表(Ascend A5 采集,TBD 表示待测):
| Cores | S0 | S1 | Total task time (us) | GOps | TFLOPS |
|---|---|---|---|---|---|
| 1 | 128 | 1024 | TBD | 67.11 | TBD |
| 1 | 128 | 2048 | TBD | 134.22 | TBD |
| 1 | 128 | 4096 | TBD | 268.44 | TBD |
其中 GOps 随 S1 翻倍而翻倍(67.11 → 134.22 → 268.44),符合注意力计算量随 S1 线性增长的预期。
四、MXFP4 矩阵乘法性能 Kernel(matmul_mxfp4_performance)
4.1 功能与数学表达
该示例基于 PTO 框架实现高性能 MXFP4 矩阵乘法,系统性集成了多核并行划分、基块(base block)选择、L1 缓存优化与双缓冲等核心优化手段,在保证计算精度的前提下最大化硬件算力与存储带宽利用率,并适配高性能计算中的非对齐矩阵乘法场景(详见 matmul_mxfp4_performance/README.md)。
算子逻辑:先对左右量化系数矩阵与对应输入矩阵做广播乘法,再对两组乘积结果执行矩阵乘法。数学表达式为:
其中 ⊗ 为广播乘法,* 为矩阵乘法。各矩阵形状:A 为 m×k,scaleA 为 m×scaleK,B 为 k×n,scaleB 为 scaleK×n,C 为 m×n。
main.cpp 中默认参考配置为 m=2040, k=8192, n=8100,scaleK=k/32=256(量化系数矩阵的 k 维是数据矩阵 k 维的 1/32)。
4.2 算子规格
| Item | Value |
|---|---|
| OpType | MxMatmul |
| Data Inputs | a: m×k, float8_e5m2, ND; b: n×k, float8_e5m2, DN |
| Scale Inputs | scaleA: m×scaleK, float8_e8m0, ND; scaleB: n×scaleK, float8_e8m0, DN |
| Output | c: m×n, bfloat16, ND |
| Kernel name | MxMatmulPerformance |
注意 b/scaleB 使用 DN 布局(与 a/scaleA 的 ND 不同),输入输出数据类型为 fp8(e5m2)/ 量化系数(e8m0)→ bf16 输出,属典型的 MX 格式低比特混合精度计算。
4.3 四大优化手段
- Core Partitioning(多核划分):目标是充分利用多核并行算力、把整体计算任务均匀摊到各 Cube 核。对于
m=2040, k=8192, n=8100,一般不推荐在单核内切分k维,而应切分m、n维;全局任务按 4×8 方式划分,单核负责singleCoreM=512、singleCoreK=8192、singleCoreN=1024的子矩阵,保证核间负载均衡、最大化并行度。 - Base Block Selection(基块选择):选择计算/访存比最高的基块。对 FP16 而言,常见选择是
[baseM, baseN, baseK] = [256, 256, 256],该基本块计算访存比最高,且更有利于 GM 写回保持 512 字节对齐。 - L1 Caching(L1 缓存):
- 批量缓存策略:每次搬运将多个基块从 GM 移到 L1 以提高带宽利用率,本示例设置
stepKa=stepKb=2,一次缓存四个k块; - 独立缓存:Scale 与数据在 L1 上独立缓存,引入
mxScalePara参数表示两者缓存比例。
- 批量缓存策略:每次搬运将多个基块从 GM 移到 L1 以提高带宽利用率,本示例设置
- Double Buffering(双缓冲):在 L1、L0A、L0B、L0ScaleA、L0ScaleB 上开启双缓冲,使 DMA 搬运与计算重叠。
4.4 切分参数表
| 参数 | 值 |
|---|---|
m |
2040 |
k |
8192 |
n |
8100 |
singleCoreM |
512 |
singleCoreK |
8192 |
singleCoreN |
1024 |
baseM |
256 |
baseK |
256 |
baseN |
256 |
stepM |
1 |
stepKa |
2 |
stepKb |
2 |
stepN |
1 |
mxScalePara |
4 |
4.5 性能参考数据(Ascend A5 采集,fp8 输入 → fp16 输出)
| 参数 | TMATMUL (Cube) Ratio | TEXTRACT Ratio | TLOAD Ratio | TSTORE Ratio | Execution time (ms) |
|---|---|---|---|---|---|
m=2048 k=2048 n=2048 |
44.7% | 46.6% | 22.1% | 25.6% | 0.0425 |
m=2048 k=4096 n=4096 |
77.4% | 76.7% | 38.5% | 7.7% | 0.1003 |
m=4096 k=1024 n=8192 |
64.9% | 58.4% | 29.3% | 25.7% | 0.1226 |
m=1024 k=12288 n=4096 |
84.9% | 87.4% | 43.4% | 2.8% | 0.1377 |
m=2048 k=8192 n=8192 |
90.7% | 88.1% | 45.8% | 4.6% | 0.3489 |
m=2040 k=8192 n=8100 |
83.0% | 83.0% | 42.1% | 12.3% | 0.3773 |
表中各 Ratio 指标含义与优化方案详见 kernels/manual/a2a3/gemm_performance/README.md#measured-performance-reference。
4.6 构建与运行
# 1. 配置 CANN 环境
source ${ASCEND_INSTALL_PATH}/bin/setenv.bash
# 2. 生成输入 + golden 输出
cd ${git_clone_path}/kernels/manual/a5/matmul_mxfp4_performance
python3 scripts/gen_data.py
# 3. 运行示例
bash run.sh -r npu -v Ascend950
运行成功输出:
test success
run.sh 内部会执行 cmake -DRUN_MODE=npu -DSOC_VERSION=Ascend950 .. 构建后直接运行 ./mxmatmul_performance(参见同目录 run.sh 与 main.cpp 的默认尺寸定义)。
五、MXFP8 矩阵乘法性能 Kernel(matmul_mxfp8_performance)
MXFP8 版本与 MXFP4 版本结构完全同构(同一套 mxmatmul_performance_kernel.cpp / main.cpp / gen_data.py 工程骨架,详见 matmul_mxfp8_performance/README.md),两者差异集中在默认配置与切分策略上:
- 默认尺寸:
m=k=n=6144,scaleK=k/32=192; - 基块选择:
[baseM, baseN, baseK] = [128, 256, 128](与 MXFP4 的 256³ 不同); - 多核划分:同样是 4×8 划分,单核负责
singleCoreM=1536、singleCoreK=6144、singleCoreN=768; - L1 批量缓存:
stepKa=stepKb=4,一次缓存四个k块;mxScalePara=8(MXFP4 为 2/4)。
5.1 切分参数表
| 参数 | 值 |
|---|---|
m |
6144 |
k |
6144 |
n |
6144 |
singleCoreM |
1536 |
singleCoreK |
6144 |
singleCoreN |
768 |
baseM |
128 |
baseK |
128 |
baseN |
256 |
stepM |
1 |
stepKa |
4 |
stepKb |
4 |
stepN |
1 |
mxScalePara |
8 |
5.2 性能参考数据(Ascend A5 采集,fp8 输入 → fp16 输出)
| 参数 | TMATMUL (Cube) Ratio | TEXTRACT Ratio | TLOAD Ratio | TSTORE Ratio | Execution time (ms) |
|---|---|---|---|---|---|
m=2048 k=2048 n=2048 |
58.2% | 35.1% | 84.6% | 7.3% | 0.0383 |
m=4096 k=4096 n=4096 |
87.7% | 54.2% | 96.3% | 5.3% | 0.1879 |
m=6144 k=6144 n=6144 |
91.6% | 57.3% | 98.2% | 3.5% | 0.6020 |
m=8192 k=8192 n=8192 |
90.1% | 56.2% | 99.6% | 2.6% | 1.4749 |
5.3 构建与运行
source ${ASCEND_INSTALL_PATH}/bin/setenv.bash
cd ${git_clone_path}/kernels/manual/a5/matmul_mxfp8_performance
python3 scripts/gen_data.py
bash run.sh -r npu -v Ascend950
同样以 test success 表示运行成功。
六、读懂性能表:TMATMUL / TEXTRACT / TLOAD / TSTORE Ratio 的含义
MXFP4/MXFP8 性能表中的四个 Ratio 指标,其定义与判读方法在 kernels/manual/a2a3/gemm_performance/README.md 中有明确说明。这些指标回答的核心问题是:端到端流水线到底被哪个引擎拖住。
- TMATMUL (Cube) Ratio:Cube 矩阵乘单元的活跃度。规模增大时该比例通常先升后降——问题变大时流水摊薄、利用率提升,但当访存成为瓶颈后 TMATMUL 反而不饱和(如 MXFP8 在
8192³时从 91.6% 回落到 90.1%)。 - TEXTRACT Ratio:L1→L0A/L0B 的抽取(extract/布局转换)开销。MXFP4 数据中该比例普遍偏高(46.6%~88.1%),说明这部分对整体性能影响不小,优化抽取阶段(并干净地做重叠)能直接改善性能。
- TLOAD Ratio:GM→L1 的搬运活跃度。当 TLOAD Ratio 逼近 100%(如 MXFP8 大尺寸下的 99.6%),说明已经处于访存供给受限状态,此时即使 TMATMUL 看起来"很忙",进一步提速也要从减少每 FLOP 搬运字节数、改进重叠入手。
- TSTORE Ratio:L0C→GM 写回占比。对 GEMM 类算子而言写回占比很小且随规模缩小(MXFP8 中从 7.3% 降到 2.6%),即"一次写回对应大量乘加"。
整体上,执行时间随 m=k=n 呈超线性增长(O(n³) 工作量所致),中等规模利用率最佳、规模更大后访存成为主要限制——这也是 MXFP4/MXFP8 示例中"单核不切 k、只切 m/n + 批量 L1 缓存 + 双缓冲"设计思路的直接动机。
七、小结与延伸阅读
kernels/manual/a5 提供了三套可直接构建运行的 A5 手工调优 kernel 范式:Flash-Attention 侧重Cube/Vector 异构流水编排与 FA2.0 数值稳定递推;MXFP4/MXFP8 MatMul 则集中展示 多核划分 → 基块选择 → L1 批量/独立缓存 → 多级双缓冲的完整性能优化链路,且以 scaleK=k/32 的 MX 量化格式同时覆盖了非对齐(2040×8100)与方阵(6144³)两类实战场景。
如需进一步深入,建议继续阅读:
- 算子级细节与优化策略:kernels/manual/common/flash_atten/README.md(含 FA 各阶段实现、流水编排、成本模型
fa_cost_model.py与 A2/A3 性能基线,可对照理解 A5 的适配点); - 性能指标判读方法论:kernels/manual/a2a3/gemm_performance/README.md(TLOAD/TEXTRACT/TMATMUL/TSTORE 四阶段 GEMM 流水与调优指引);
- 脚本级证据:flash_atten/run.sh(A5 SoC 校验、FIFO 模式与用例生成)、matmul_mxfp4_performance/main.cpp(默认尺寸
m=2040, k=8192, n=8100的定义位置); - 相关 ISA 指令说明可参考 docs/isa/TMATMUL.md、docs/isa/TLOAD.md、docs/isa/TEXTRACT.md 等文档。
提示:文中
Ascend910_9599(Flash-Attention)与Ascend950(MX MatMul)为示例脚本中实际使用的 A5 SoC 版本串;请在真实环境中以本机安装的 CANN/SoC 版本为准。