ops-transformer FlashAttentionScoreGrad 算子 Pytest 验证框架:CPU Golden、NPU 直调与精度对比实战

原创2026-09-17 10:00:101,865 阅读
文章标签:算子库人工智能深度学习大模型高性能计算CANNAscend

ops-transformer FlashAttentionScoreGrad 算子 Pytest 验证框架:CPU Golden、NPU 直调与精度对比实战

在 CANN 的 ops-transformer 算子库中,flash_attention_score_grad 是用于训练场景的注意力反向算子,其功能正确性的最终验证依赖一套位于 tests/pytest 目录下的 Pytest 测试框架。该框架的核心思路是:CPU 侧以纯 PyTorch 复现算子数学语义生成 Golden 数据,NPU 侧通过 TorchNPU 直调 npu_fusion_attention_grad_v2 接口获取实际输出,再按相对误差占比与绝对偏差双重阈值做精度对比。读懂这套框架,你就能掌握一个 NPU 算子端到端功能验证的完整工程方法:如何组织用例、如何构造 FP8 量化与 Dropout 场景下的标杆数据、如何比对两侧结果并定位偏差。

一、框架定位与测试体系

flash_attention_score_grad 算子实现了注意力的反向传播,其正向计算公式为:

  • pseType=1 时:Y = Dropout(Softmax(Mask((QK^T + pse)/sqrt(d)), atten_mask), keep_prob)V
  • pseType≠1 时:Y = Dropout(Softmax(Mask(QK^T/sqrt(d) + pse), atten_mask), keep_prob)V

对应的反向公式为 dV = P^TdY、dQ = (dS * K)/sqrt(d)、dK = (dS^T * Q)/sqrt(d),详见 算子 README。

从源码结构看,该算子的测试分为两层:

两者互补:C++ UT 验证接口与切分逻辑,Pytest 框架验证端到端数值行为。

二、目录结构与文件职责

Pytest 框架由 5 个 Python 文件组成(见 tests/pytest/README.md):

pytest/
- test_case.py              # 测试用例集
- test_main.py              # 执行主程序
- common.py                 # 公共定义文件
- cpu_impl.py               # cpu实现
- npu_impl.py               # npu实现

各文件职责与关键实现对应关系如下:

文件 职责 关键实现
common.py 公共常量与上下文数据类 CalculusContext 数据类、日志工具 log
test_case.py 用例参数定义 全局字典 TestCases,6 组用例
cpu_impl.py CPU Golden 数据生成 attentionScoreWithGrad(BNSD/BSND/BSH/SBH 布局)、run_unpad(TND 布局)、FP8 块量化、Philox 随机数
npu_impl.py NPU 算子直调 PTAtest,调用 torch_npu.npu_fusion_attention_grad_v2
test_main.py 测试入口与精度比对 checkResult、test_npu_flash_atten_grad

其中 common.py 定义了框架级全局配置:

gtype = torch.float32          # Golden 计算统一使用 fp32
PER_BLOCK_SIZE = 128            # FP8 块量化的块大小(S 方向)
PER_VCORE_BLOCK_SIZE = 64      # V 核分裂场景下的块大小
EPSILON = 1e-8                  # 量化 scale 计算的下限保护
DEVICE_ID = 0                    # 目标 NPU 设备号
pta_mode = "only_grad"          # 测试模式:only_grad 或 auto_grad

CalculusContext 是贯穿两侧的数据桥:它是一个 dataclass,持有输入用例字典 input_case 以及 cu_seqlens_q_npu、q_npu、k_npu、dx_npu、x_max_npu、x_sum_npu、dscale_q_npu 等字段。CPU 侧生成输入后写入这些字段,NPU 侧直接从中取数上卡,保证了两侧输入张量严格一致——这是精度对比有效性的前提。

log 函数(common.py)会同时打印到终端并追加写入 run_log.txt,便于事后回溯每个用例的比对结论。

三、环境配置与运行方式

tests/pytest/README.md 给出的前置要求与运行命令:

  1. 确认 TorchNPU 为最新版本(NPU 侧直调接口 npu_fusion_attention_grad_v2 依赖 TorchNPU 提供);
  2. source CANN 包环境变量;
  3. 支持 custom 包调用(即自行编译的算子包)。

在 pytest 文件夹路径下执行:

pytest -s

-s 参数用于放行 print 输出,使各用例的进度与比对日志直接可见。此外,从 cpu_impl.py 与 npu_impl.py 的 import 语句可以确认,运行环境还需要 torch、torch_npu、numpy、einops、ml_dtypes 等依赖。

四、测试用例的组织方式

用例全部集中在 test_case.py 的全局字典 TestCases 中,每个用例是一个参数字典。当前仓库内置 6 组用例,覆盖 GQA、MLA、FP8、FP32 与 TND 变长等场景:

用例名 B N1/N2 S1/S2 D/D_V dtype out_dtype input_layout 特点
GQA_01 1 2/1 128/128 177/177 fp16 fp16 BNSD 非对齐 D,rope=0
MLA_02 1 2/1 128/128 192/128 fp16 fp16 BNSD MLA 形态(D≠D_V),rope=1,Q/K 后 128 维做 RoPE
FP8E5_03 2 2/1 125/125 128/128 fp8_e5m2 fp16 BSND FP8 块量化
FP8E4_04 2 2/1 129/125 128/128 fp8_e4m3fn bp16* SBH FP8 + 非对齐 S
FP32_05 9 8/2 80/80 167/167 fp32 fp32 BSND pse_type=3(Alibi)、atten_mask 为 uint8 的 B1SS
TND_06 4 16/16 287/287 128/128 fp16 fp16 TND 变长序列 [114,132,14,287]、sparse_mode=3、dropout=0.9

* 该用例的 out_dtype 字段在 test_case.py 中写作 bp16,而 npu_impl.py 的 getOutDtype 只映射 fp16/bf16/fp32,从源码结构看该字段取值需与映射函数保持一致。

每个用例字典包含的关键字段可分四类:

  1. 形状类:B(batch)、N1/N2(Q 头数 / KV 头数,其比值 G 即 GQA 分组数)、S1/S2(Q/KV 序列长)、D/D_V(K/Q 维与 V 维)、TND 布局下另有 actual_seq_qlen/actual_seq_kvlen 变长列表;
  2. 数据类:dtype(fp16/bf16/fp32/fp8_e5m2/fp8_e4m3fn)、out_dtype、seed、offset;
  3. 语义类:sparse_mode(稀疏/掩码模式)、pre_tockens_input/next_tockens_input(带 attention window 时的窗口边界)、drop_out_possibility(keep_prob)、pse_type/pse_shape(位置编码类型与布局)、atten_mask_dtype/atten_mask_shape(掩码类型与形状,如 SS/B1SS/BNSS)、rope(是否分离 RoPE 分量);
  4. 布局类:input_layout,支持 BNSD、BSND、BSH、SBH、TND 五种。

新增用例只需在 TestCases 中追加一个字典,test_main.py 的测试入口会自动遍历所有键值对执行,无需改动其他文件。

五、CPU 侧:Golden 数据如何生成

cpu_impl.py 是框架中篇幅最大的文件,核心入口有两个,由布局决定走哪一条(见 test_main.py):

func = run_unpad if test_data["input_layout"] == "TND" else attentionScoreWithGrad

5.1 输入生成(DataGen)

DataGen 按 [B, Nkv, G, S, D] 的“分头展开”形状随机生成 Q/K/V/dX(其中 K/V 的 G 维为 1,供 GQA 广播),并同步生成三类辅助数据:

  • 位置编码 pse:pse_type in (0,1) 时支持 BN1S/1NSS/BNSS 随机值与 BNHS/1NHS 的 Alibi 风格逐头斜率(get_slopes 按 2^(-8/n) 几何级数生成);pse_type in (2,3) 时由 get_all_alibi 生成 Alibi 偏置,且 pse_type=3 时距离项取平方根;
  • 注意力掩码:get_atten_mask 按 sparse_mode 生成——mode 0 用 pre_tocken/next_tocken 构造窗口带、mode 2/3 生成上/下三角因果掩码、mode 5/6 生成带 prefix 的掩码,掩码统一以 uint8 的 0/1 表示;
  • FP8 量化 scale:dtype 为 fp8 时,get_block_quant_scale 按 128 大小的块(PER_BLOCK_SIZE)对 S 方向分块,取块内绝对值最大值计算 scale = FP8_MAX / max_val(e5m2 的 FP8_MAX 为 57344,e4m3fn 为 448),并支持 V 核 64 元素分裂(PER_VCORE_BLOCK_SIZE)与尾块处理。

5.2 前向/反向数学复现

Golden 的数学核心是 tforward 与 tbackward,它们用 fp32(gtype)逐张量复现算子语义,与算子 README 中的公式一一对应:

# pseType=1 时先 add 再 mul;否则先 mul 再 add(与算子语义严格对齐)
if pse_type == 1:
    qk = torch.matmul(q, k.permute(0, 1, 2, 4, 3)).add(pse).mul(scale)
else:
    qk = torch.matmul(q, k.permute(0, 1, 2, 4, 3)).mul(scale).add(pse)
qk = qk.masked_fill(atten_mask.bool(), value=torch.tensor(-40000.0))
softmax_res, x_max, x_sum = tsoftmax(qk)
drop_res = softmax_res * drop_mask * (1.0 / keep_prob)
y = torch.matmul(drop_res, v)

反向部分按 FlashAttention 反向的推导实现(tsoftmax_grad):

drop_res = softmax_res.mul(drop_mask).mul(1.0 / keep_prob)
dv = torch.matmul(drop_res.permute(0, 1, 2, 4, 3), dx)
dp = torch.matmul(dx, v.permute(0, 1, 2, 4, 3))
dp_drop = dp * drop_mask * (1.0 / keep_prob)
softmax_grad_res = tsoftmax_grad(dp_drop, softmax_res) * scale   # (dp - (dp*P).sum) * P
dq = torch.matmul(softmax_grad_res, k)
dk = torch.matmul(softmax_grad_res.permute(0, 1, 2, 4, 3), q)
dk = torch.sum(dk, dim=2, keepdim=True)   # GQA:组内求和回 Nkv
dv = torch.sum(dv, dim=2, keepdim=True)

注意 tsoftmax 会额外返回 x_max/x_sum——这正是反向算子必需的中间量(对应算子接口的 softmax_max/softmax_sum),attentionScoreWithGrad 将它们广播为 [B, Nq, S, 8] 后写入 ctx.x_max_npu/ctx.x_sum_npu 供 NPU 侧消费。

FP8 用例还完整模拟了量化-反量化链路:block_quant_or_dequant_single 按 128 块乘 scale 模拟量化,chunked_matmul_with_quant 等分块 matmul 函数模拟硬件按块反量化累加的行为,使 Golden 与 NPU 硬件的数值行为处于同一“模拟层次”。

5.3 Dropout 掩码:与硬件同源随机数

训练算子的 Dropout 掩码必须与硬件生成的完全一致,否则对比无意义。cpu_impl.py 在 CPU 上纯 Python 实现了 Philox4_32 随机数生成器(philox_random/philox4_32/philox4_bumpkey),get_drop_mask 用用例中的 seed 拆成高/低 32 位作为 key、offset/16 作为 counter 起点,逐字节比较 philox_uint8 <= keep_prob*255 生成 0/1 掩码。这与 NPU 侧 seed/offset 参数(见 5.4 节直调代码)构成同一随机流,保证两侧掩码逐位相同。所有内置用例 drop_out_possibility=1 时掩码退化为标量 1(不做丢弃),TND_06 用 0.9 覆盖真实丢弃路径。

5.4 输出整形

CPU 侧最后按用例的 input_layout 用 einops.rearrange 把 <a href="https://link.gitcode.com/i/1c8ce134958d8e11bf12d067cdbbb7ec" target="_blank">B, Nkv, G, S, D] 的中间表示重排为算子实际输入布局(BNSD 合并 GQA 头、BSH/SBH 合并头维、BSND/TND 保留头维),TND 布局还通过 [unpad_input 把 padding 掉的变长序列压回紧凑 [S1, N, D],并计算 cu_seqlens 前缀和写入上下文。RoPE 场景(rope=1)则将 Q/K 的 [:128] 与 [128:] 分量拆开,分别作为 query/query_rope 输入。

六、NPU 侧:TorchNPU 直调实现

npu_impl.py 的 PTAtest 从 CalculusContext 取出 CPU 生成的全部输入,搬到 npu:{DEVICE_ID} 后直调 TorchNPU 融合接口。当前 common.py 固定 pta_mode = "only_grad",走如下调用(npu_impl.py):

dq, dk, dv, *_ = torch_npu.npu_fusion_attention_grad_v2(
    q, k, v, dx, Nq,
    pse=pse1,
    padding_mask=None,
    atten_mask=atten_masks,
    softmax_max=x_max.float().to(device),
    softmax_sum=x_sum.float().to(device),
    softmax_in=None,
    attention_in=out.to(pttype).to(device),
    scale_value=scalar,
    keep_prob=keep_prob,
    input_layout=input_layout,
    pre_tokens=pre_tockens,
    next_tokens=next_tockens,
    seed=seed,
    offset=offset,
    numels=B * Nq * S * Skv,
    inner_precise=0,
    prefix=prefix,
    sparse_mode=ctx.input_case["sparse_mode"],
    pse_type=pse_type)

几个值得注意的实现细节:

  • 正向结果作为反向输入:attention_in 传的是 CPU 侧 tforward 得到的输出 out,softmax_max/softmax_sum 传 CPU 侧的 x_max/x_sum——即反向算子的全部输入都来自 Golden 前向,隔离了正向误差,使精度对比只检验反向路径;
  • 随机流对齐:seed/offset 与 CPU 侧 Philox 生成器使用同一组参数,numels 按 B*Nq*S*Skv(TND 下为实际变长序列乘积之和)确定掩码数量;
  • FP8 专用参数:npu_impl.py 在 fp8 场景额外传入 d_scale_q/d_scale_k/d_scale_v/d_scale_dy/d_scale_o(即 CPU 侧 dscale_* = 1/scale,布局固定重排为 BNSD)与 out_dtype(0 表示 fp16,1 表示 bf16,见 getOutDtypeZeroOrOne),输入张量先转换为 torch.float8_e4m3fn/torch.float8_e5m2 再上卡;
  • auto_grad 备选路径:npu_impl.py 还实现了 auto_grad 模式——对 q/k/v 设置 requires_grad=True,调用正向 npu_fusion_attention(rope 场景用 npu_fusion_attention_v2)后 npu_out.backward(dx),由框架自动求导。该模式在代码注释中明确说明 FP8 场景暂不支持,且当前配置下默认不启用。

七、精度比对标准

比对逻辑集中在 test_main.py 的 checkResult 函数中,逐输出张量(dq/dk/dv,rope 场景另有 dq_rope/dk_rope)执行:

  1. Shape 校验:NPU 结果与 Golden 形状不一致直接判失败;
  2. 逐元素阈值:偏差门限取 max(|a|, |b|) * 0.005 与 2.5e-5 的较大者(ratio_threshold = 0.005,test_main.py),统计超出门限的元素个数与占比;
  3. 绝对偏差护栏:若 max(diff) > 0.1,无论占比多少都判为用例执行失败(error: ... 用例执行失败!!!);否则仅记录 info 级别的占比统计。

每个用例执行完毕后,终端与 run_log.txt 中会留下 diff_max/diff_sum 及占比结论,例如:

GQA_01 dq diff_max : 0.00048828
GQA_01 dq diff_sum : 0.001332

主测试函数 test_npu_flash_atten_grad 的完整流程即:遍历 TestCases → 构造 CalculusContext → 按布局选择 run_unpad 或 attentionScoreWithGrad 生成 Golden 与全部 NPU 输入 → 调用 PTAtest 获取 NPU 输出 → 逐张量 checkResult。

八、框架设计要点小结

从这套框架的实现中,可以提炼出 NPU 训练类算子精度验证的几个通用工程实践:

  • 两侧共享同一个上下文对象(CalculusContext),CPU 侧生产数据、NPU 侧消费数据,从机制上杜绝“两侧输入不一致”这一最常见的对比失真来源;
  • Golden 与硬件行为同层模拟:FP8 场景不直接对比“理想数学值”,而是模拟块量化/反量化、按块反量化累加,使 Golden 落在与硬件相同的数值行为层级上;
  • 随机性显式可控:Dropout 掩码用 Philox4_32 在 CPU 复现硬件随机流,seed/offset 成为用例参数而非隐式状态;
  • 比对阈值双层设计:相对占比阈值容纳浮点噪声,绝对偏差上限(0.1)拦截量级错误;
  • 用例即数据:所有场景差异(布局、精度、稀疏模式、变长序列、RoPE)都参数化在 TestCases 字典中,扩展新场景零代码侵入。

如果你需要验证该算子在某个新布局、新精度或新稀疏模式下的行为,最短路径就是:在 test_case.py 追加一个用例字典 → 在配置好 TorchNPU 与 CANN 环境变量的机器上进入 tests/pytest 执行 pytest -s → 查看 run_log.txt 中该用例的 diff_max、diff_sum 与偏差占比结论。

登录后查看全文
ops-transformer