基于 PTO 的 Flash Attention 自定义 PyTorch 算子移植实战(Ascend A2/A3/A5)
基于 PTO 的 Flash Attention 自定义 PyTorch 算子移植实战(Ascend A2/A3/A5)
本篇技术指南围绕 CANN pto-isa 仓库中的 demos/baseline/flash_atten 示例展开,完整讲解如何用 PTO(Parallel Tile Operation)虚拟指令集实现 Flash Attention 内核,并通过 torch_npu 封装成可被 PyTorch 直接调用的自定义算子。读完本文,你将掌握从环境准备、构建 wheel 包、安装部署到运行验证的完整流程,理解其动态 Tiling 与跨架构(A2/A3/A5)支持的设计原理,并能对照源码定位内核启动、tile 调度与 workspace 管理的具体实现。
示例概览:为什么需要自定义 FA 算子
Flash Attention 是长序列注意力训练与推理中的关键算子,其核心思想是通过分块(tiling)计算 QK^T、Softmax 与 PV,避免在全局内存中物化完整的注意力矩阵,从而显著降低显存占用并提升带宽利用率。在 Ascend 平台上,将一个手工优化好的 Flash Attention 内核接入 PyTorch 计算图,通常需要解决三件事:内核本身的高效实现、与昇腾算力库(Cube/Vec 流水)的协同、以及宿主侧与 torch_npu 的自定义算子注册。
本示例(demos/baseline/flash_atten)给出了一条可复制的参考路径:
- 内核侧:基于 PTO 的 Tile 抽象编写 FA 内核(
csrc/kernel/fa_custom.cpp),内部为 Cube(矩阵乘)+ Vec(Softmax/更新)的跨核流水实现; - 宿主侧:编写算子入口
run_fa_custom(csrc/host/my_fa.cpp),完成动态 Tiling 选择、workspace 尺寸计算与内核启动; - 接入侧:通过
torch_npu的NpuExtension与TORCH_LIBRARY机制,将内核注册为torch.ops.npu.my_fa; - 验证侧:
test/test.py用 NumPy 在 FP32 下按分块方式模拟 FA 递推,生成黄金参考并与 NPU 输出比对。
支持的 AI 处理器为 A2/A3/A5,同一套代码通过构建期宏(如 PTO_NPU_ARCH_A2A3 与 PTO_NPU_ARCH_A5)与 SOC 分支完成跨架构适配。
1. 环境准备
示例要求先创建独立的 Python 虚拟环境并安装依赖(requirements.txt 中锁定了关键版本):
python -m venv virEnv
source virEnv/bin/activate
python3 -m pip install -r requirements.txt
requirements.txt 中的关键依赖及说明:
| 依赖 | 版本 | 说明 |
|---|---|---|
| torch | 2.8.0 | PyTorch 主框架 |
| torch-npu | 2.8.0.post2 | A2/A3 使用;A5 需改为 2.8.0.post3(注释中明确说明) |
| numpy | 1.26.0 | 黄金参考计算 |
| setuptools | 80.9.0 | wheel 构建 |
| wheel / pyyaml / expecttest / decorator / scipy / attrs / psutil | — | 构建与测试辅助 |
接着配置 Ascend Toolkit 与 PTO 库环境:
export ASCEND_HOME_PATH=[YOUR_ASCEND_PATH/SYSTEM_ASCEND_PATH]
source [YOUR_ASCEND_PATH/SYSTEM_ASCEND_PATH]/latest/bin/setenv.bash
export PTO_LIB_PATH=[YOUR_PATH]/pto-isa
其中 ASCEND_HOME_PATH 指向 CANN 安装目录(系统级或用户级均可),PTO_LIB_PATH 指向本仓库根目录。PTO_LIB_PATH 会被 CMakeLists.txt 读取并传入内核编译头文件搜索路径:
# set PTO_LIB_PATH before running cmake, for example:
# export PTO_LIB_PATH=[YOUR_PATH]/pto-tile-lib
set(PTO_LIB_PATH "$ENV{PTO_LIB_PATH}" CACHE STRING "PTO library path")
在 CMakeLists.txt 中,${PTO_LIB_PATH}/include 与 ${PTO_LIB_PATH}/include/common 被加入内核的 include 目录,因此该环境变量是构建成功的必要条件之一。
2. 构建 Wheel 包
示例采用 setup.py bdist_wheel 的方式构建,构建系统会根据 SOC_VERSION 环境变量自动配置正确的架构宏。
默认构建(A2 / A3):
python3 setup.py bdist_wheel
为特定 SOC 构建(例如 A5):
# Example for A5
SOC_VERSION=ascend910_9599 python3 setup.py bdist_wheel
2.1 构建流程的源码视角
setup.py 中自定义了 build_clib(CPPLibBuild)与 build_ext(Build)两个 setuptools 命令:
- 构建前会探测 cmake/cmake3 且要求版本不低于 3.18.0(
get_cmake_command); - 将
TORCH_PATH、TORCH_NPU_PATH与可选的SOC_VERSION透传给 CMake(setup.py); - 依据
torch.compiled_with_cxx11_abi()设置GLIBCXX_USE_CXX11_ABI,确保与已安装的 torch/torch_npu ABI 一致; - 支持
MAX_JOBS环境变量控制并行编译核数。
CMake 侧的 CMakeLists.txt 进一步说明了 SOC 与架构的映射关系:
SOC_VERSION默认值为ascend910b1(对应 A2/A3 目标);- 内核源文件
csrc/kernel/fa_custom.cpp通过ascendc_library(workspace_kernel STATIC ...)编译为静态库,并附加-DHAVE_WORKSPACE编译定义; - SOC 分支选择内核头文件目录:
ascend910b1时加入kernels/manual/a2a3/flash_atten,ascend910_9599时加入kernels/manual/a5/flash_atten(CMakeLists.txt)——这正是「统一代码库、构建期分架构」的实现位置; - 宿主侧
csrc/host/*.cpp编译为共享库libop_extension.so,并链接torch_npu、ascendcl、tiling_api、register、platform、ascendalog等昇腾运行库。
在内核源码 fa_custom.cpp 中,架构分派同样可见:__DAV_C220_CUBE__/__DAV_C220_VEC__ 对应 A2/A3,__DAV_C310_CUBE__/__DAV_C310_VEC__ 对应 A5,分别引入对应平台的 TSyncCVID.hpp 与 TSync_Custom.hpp。
3. 安装 Wheel 包
构建完成后,产物位于 dist/ 目录,使用 --force-reinstall 强制覆盖安装:
pip install dist/*.whl --force-reinstall
安装后的 Python 包为 op_extension。包内的 op_extension/_load.py 展示了加载逻辑:_load_opextension_so() 会定位包内 lib/libop_extension.so 并调用 torch.ops.load_library 加载。同时 setup.py 中通过 NpuExtension("op_extension._C", ...) 声明了 torch_npu 自定义扩展入口,因此测试脚本只需 import op_extension 即可完成注册(test.py)。
4. 运行测试
cd test
python3 test.py
test/test.py 的测试矩阵覆盖了:
- 序列长度:1024、2048、4096、8192、16384、32768(即 1k~32k);
- head_size:64 与 128;
- 是否 causal:
False与True两种掩码模式;
测试流程为:用 NumPy 在 FP32 精度下生成 Q/K/V 与黄金参考 → 将张量 .npu() 搬到 NPU → 调用 torch.ops.npu.my_fa(q_npu, k_npu, v_npu, is_causal) → 通过 assertRtolEqual(output, cpuout, prec=1.e-3) 校验。
值得注意的黄金参考实现细节:gen_case 并没有简单地做一次全量 Softmax,而是按 TILE_S1(默认 256)逐块模拟 FA 的递推过程——逐 tile 计算局部最大值 local_max、指数 exp((tile - max) * scale)、局部和 local_sum,再用 exp_max = exp((global_max - local_max) * scale) 做在线 rescale 并累加 global_sum,最后在最后一个 tile 处以 global_sum 归一化得到输出 O(test.py)。这与内核中 pto_macro_fa_gu 系列的运行期 rescale/update 语义一一对应,是验证「动态 tiling + 在线 Softmax」正确性的关键。
5. 算子入口与动态 Tiling
5.1 算子 Schema 与注册
宿主侧 my_fa.cpp 使用两段式 torch 扩展注册:
TORCH_LIBRARY_FRAGMENT(npu, m) {
// Declare the custom operator schema
m.def("my_fa(Tensor q, Tensor k, Tensor v, bool is_causal=False) -> Tensor");
}
TORCH_LIBRARY_IMPL(npu, PrivateUse1, m) {
// Register the custom operator implementation function
m.impl("my_fa", TORCH_FN(ascendc_path::run_fa_custom));
}
其中 PrivateUse1 是 torch_npu 在 PyTorch 中占用的后端设备类型(utils.h 中的 c10::DeviceType::PrivateUse1)。由此生成的调用入口即 torch.ops.npu.my_fa。
5.2 run_fa_custom:动态 Tiling 的选择逻辑
run_fa_custom(my_fa.cpp)是宿主侧的核心函数,其职责包括:
- 依据 Q 的 shape 解析
s0(行数)、s1(列数/序列长度)与head_size,并断言head_size必须为 64 或 128; - 依据块高
CUBE_S0 = 128断言s0 % CUBE_S0 == 0; - 执行动态 Tiling 选择(README 中所述「128 或 256」的实际源码为四档):
int tile_s1 = kFaTileS1; // Default (256)
if (s1 >= 256 && s1 <= 1024) {
tile_s1 = TILING_KEY_256;
} else if (s1 >= 1024 && s1 <= 8192) {
tile_s1 = TILING_KEY_512;
} else if (s1 >= 1024) {
tile_s1 = TILING_KEY_1K;
} else {
tile_s1 = TILING_KEY_128;
}
即默认 kFaTileS1 = 256(见 fa_custom.h),短序列(<256)回退到 128;256~1024 使用 256;1024~8192 使用 512;1024 以上落入 1024。注意区间存在重叠(1024 同时命中 512 与 1K 分支,最终取 1K),这是源码中的实际判定顺序。随后断言 s1 % tile_s1 == 0,保证序列长度可被 tile 整除。
- 按所选 tile 尺寸计算 workspace 各段大小,包括 QK FIFO、P FIFO(half/float 两份)、gsum、PV partial 输出、PV FIFO 等(my_fa.cpp),并叠加
platform_ascendc::PlatformAscendCManager提供的系统 workspace 大小; - 通过
EXEC_KERNEL_CMD(fa_custom, blockRow, ...)启动内核,blockRow = s0 / CUBE_S0作为 block 维度(my_fa.cpp)。
EXEC_KERNEL_CMD 宏(utils.h)将张量参数统一转换为裸指针,获取当前 NPU 流(c10_npu::getCurrentNPUStream()),并通过 ACLRT_LAUNCH_KERNEL 发起 fa_custom 内核启动,最后交由 at_npu::native::OpCommand::RunOpApi 以算子 API 方式入队执行。
5.3 内核侧的 Tiling 分派
内核入口 fa_custom(fa_custom.cpp)声明为 KERNEL_TASK_TYPE_DEFAULT(KERNEL_TYPE_MIX_AIC_1_2),即 1 个 Cube 核 + 2 个 Vec 核的混合任务类型。它会根据 causal_mask、head_size(64/128)与 tilingKey(128/256/512/1024)的组合,实例化对应的 fa_custom_impl<HEAD_SIZE, CAUSAL_MASK, CUBE_S0, CUBE_S1, TILE_S1> 模板。这解释了 README 中「自动 tiling 适配」在设备侧的落实方式:全部组合在编译期展开,运行期仅按参数分派。
6. 内核实现要点:Cube+Vec 跨核流水
6.1 四阶段流水
fa_custom.cpp 中的性能内核采用显式 FIFO 的跨核流水结构(源码注释见 fa_custom.cpp):
| 阶段 | 执行单元 | 计算内容 | 中间产物 |
|---|---|---|---|
| QK | Cube | compute_qk:Q·K^T 矩阵乘 |
qk_tile_fifo(fp32) |
| P | Vec | compute_p:Softmax(含 rescale) |
p_tile_fifo(fp16 exp)+ l1_exp_max |
| PV | Cube | compute_pv:P·V 矩阵乘 |
pv_tile_fifo(fp32) |
| GU | Vec | compute_gu:运行期 rescale/update |
o_out(fp32) |
各阶段之间通过 TSync_Custom(如 qk2smSync、sm2pvSync、pv2guSync,见 fa_custom.cpp)与跨核事件同步,FIFO 深度由 kFaCvFifoSize = 8 决定(fa_custom.h)。
6.2 性能调优旋钮
源码注释中明确列出了影响吞吐的关键参数(fa_custom.cpp):
CUBE_S0 / CUBE_S1:QK/PV 矩阵乘的 tile 尺寸,默认 128×128(kFaCubeS0/kFaCubeS1),决定计算强度与 buffer 压力;qkPreloadNum(QK_PRELOAD,默认 4,见 fa_custom.h):流水预热深度,越大 Cube/Vec 重叠越充分,但 FIFO 占用越大;预热循环见 fa_custom.cpp;*TNBuffers:Q/K/P/V 等 Mat tile 的 ping/pong 深度(K/P/V 为 2,Q 为 1),Vec 侧srcVecTNBuffers/xexpVecTNBuffers为 2;QKP_CV_FIFO / PV_CV_FIFO:级间 FIFO 深度,避免 backpressure;- 内存约束:Cube 侧 L1 tile buffer 总和不超 512KB(
MAX_TILE_L1_BYTES),Vec 侧 UB 分配不超 192KB(MAX_VEC_UB_BYTES),均由static_assert在编译期强制校验(fa_custom.cpp)。
6.3 Causal Mask 的优化
当 CAUSAL_MASK 开启时,compute_qk 会跳过 s1_index > s0_index 的右上三角块(fa_custom.cpp),compute_pv 与 compute_p 亦做同样剪枝;同时 num_tiles_s1 会按当前 block 的行位置收缩为 1 + (block_idx * CUBE_S0) / Tile_S1(fa_custom.cpp),从而避免对因果掩码下无意义的块发起计算。
6.4 与参考内核的关系
示例内核依赖的 pto_macro_matmul.hpp、pto_macro_fa_softmax.hpp、pto_macro_fa_gu.hpp 位于 kernels/manual/a2a3/flash_atten(A5 对应 kernels/manual/a5/flash_atten,CMake 按 SOC 选择 include 路径)。该目录下还包含 fa_pipeline.svg、fa_flows.svg 等流水示意图与可运行的 run.sh,可作为深入理解四阶段流水调度细节的补充资料。
7. 常见问题与约束
- 版本匹配:A5 目标需将
requirements.txt中的torch-npu改为2.8.0.post3,否则可能与 NPU 驱动/固件不兼容; - SOC 与架构:
SOC_VERSION不设置时默认ascend910b1(A2/A3);构建 A5 必须显式指定ascend910_9599,否则 include 的参考内核目录不匹配; - shape 约束:
head_size仅支持 64/128;s0必须为 128 的倍数;s1必须能被选中的tile_s1整除,否则宿主侧断言失败; - workspace:内核通过
-DHAVE_WORKSPACE编译,workspace 由宿主侧按 FIFO/累加段精确计算并以字节张量传入,容量不足会直接影响跨核同步正确性; - ABI:构建时
GLIBCXX_USE_CXX11_ABI自动跟随 torch/torch_npu,手动安装不同 ABI 的 torch 版本会导致链接失败。
8. 小结
demos/baseline/flash_atten 提供了一个端到端可复现的 PTO 自定义算子移植范例:宿主侧负责动态 Tiling 与 workspace 计算,内核侧以 Cube+Vec 四阶段流水实现高性能 Flash Attention,torch_npu 的扩展机制负责将其无缝接入 PyTorch 生态。从环境准备到 torch.ops.npu.my_fa 调用,再到 1k~32k 序列长度、64/128 head、causal/非 causal 的全面验证,这条链路既适合作为学习 PTO 编程模型的入门案例,也可作为在 A2/A3/A5 上快速落地自定义高性能算子的工程模板。