lightning_indexer 算子 pytest 测试框架实战:CPU Golden 生成、NPU 直调与精度对比全流程解析

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

lightning_indexer 算子 pytest 测试框架实战:CPU Golden 生成、NPU 直调与精度对比全流程解析

导读

本文以 CANN ops-transformer 仓库中 lightning_indexer 算子 pytest 测试框架 为核心,系统讲解该测试框架的三大支柱:CPU 侧 golden 复现、NPU 侧 TorchNPU 算子直调与CPU/NPU 结果精度对比。读完本文,你将掌握如何手动配置单用例参数完成算子单测,如何基于 Excel 用例表格批量生成 .pt 用例并执行回归测试,以及框架内部两级精度比较算法的具体判定逻辑,可直接复用于同仓库其他 attention 类算子的功能验证场景。

测试框架设计概述:为什么需要 "Golden + 直调 + 对比"

lightning_indexer 是 CANN ops-transformer 中用于大模型稀疏注意力的算子:它基于一系列操作得到每一个 token 对应的 Top-kk 个位置,其计算公式(见 lightning_indexer 算子说明)为:

Indices=Top-k{[1]1×g@[(W@[1]1×Sk)⊙ReLU(Qindex@KindexT)]}Indices=\text{Top-}k\left\{[1]_{1\times g}@\left[(W@[1]_{1\times S_{k}})\odot\text{ReLU}\left(Q_{index}@K_{index}^T\right)\right]\right\}

其中 Qindex∈Rg×dQ_{index}\in\R^{g\times d} 为某 token 对应的 Index Query,Kindex∈RSk×dK_{index}\in\R^{S_{k}\times d} 为上下文 Index Key,W∈Rg×1W\in\R^{g\times 1},gg 为 GQA 对应的 group size,dd 为每个头的维度,SkS_{k} 是上下文的长度。

为了在无标准第三方参考实现的条件下验证该算子,pytest 测试框架采用了经典的"双端对照"思路:

  • CPU 侧:用 PyTorch 原生算子(torch.bmm、torch.sort 等)在 CPU 上逐步复现算子计算逻辑,生成 golden 数据(真值);
  • NPU 侧:通过 TorchNPU 提供的 torch_npu.npu_lightning_indexer 接口对算子进行直调,获取 NPU 实际输出;
  • 精度对比:对 CPU golden 与 NPU 输出执行两级精度比较,验证算子功能正确性。

该流程的调用关系可从 test_lightning_indexer_single.py 中清晰看到:测试用例先经 lightning_indexer_golden.li_output_single(test_data) 同时得到 cpu_result(真值)与 npu_result(测试值),再交由 result_compare_method.check_result(...) 完成精度判定,失败时通过 pytest.fail 上报。

当前实现范围与参数限制

根据 pytest 测试框架 README,当前框架覆盖的算子场景为:

  • query_layout:BSND、TND(Query 的数据排布,对应算子属性 layout_query);
  • key_layout:PA_BSND(Key 的数据排布,对应算子属性 layout_key,即 PageAttention 场景下的 KV Cache block 排布)。

从 test_lightning_indexer_paramset.py 的默认用例 li_default_a2 可见实际测试的组合形态:batch_size=18、q_seq=3、k_seq=3072、q_head_num=16、k_head_num=1(K_N 仅支持 1)、head_dim=128、block_size=128、block_num=469、sparse_count=2048、sparse_mode=3,数据精度为 bfloat16,随机数据范围 query/key 为 [-1,1]、weights 为 [-130,130]。这与算子约束(K_N 仅支持 1、headdim 支持 128、block_size 取 16 的整数倍且最大 1024)保持一致。

文件结构与职责划分

测试目录 attention/lightning_indexer/tests/pytest 下的文件按"执行入口—golden 实现—对比方法—用例配置"四个层次组织:

文件 职责
test_run.sh 统一执行脚本,封装单用例调测与批量测试两条链路
lightning_indexer_golden.py CPU 侧算子 golden 实现(含 PA 场景数据与 block table 构建)
result_compare_method.py CPU golden 与 NPU 输出精度对比
pytest.ini 声明 pytest 标记 ci、graph
test_lightning_indexer_single.py 单用例 pytest 主程序(参数化驱动)
test_lightning_indexer_paramset.py 单用例入参配置
test_lightning_indexer_batch.py 批量测试主程序,生成 Excel 结果
batch/lightning_indexer_pt_loadprocess.py 读取 .pt 文件并调用算子获取 NPU 输出
batch/lightning_indexer_pt_save.py 读取 Excel 表格批量生成用例 .pt 文件
batch/replace_path.py 批量测试中 __PATH__ 占位符替换
lightning_indexer_acl_graph.py (可选)图模式编译调用示例

环境准备与前置要求

运行测试前需完成两步准备(详见 环境部署):

  1. 环境安装与环境变量配置:按仓库提供的安装指南完成 CANN 算子开发运行环境、PyTorch 与 TorchNPU(torch_npu)的安装,并正确配置环境变量,保证 torch_npu.npu_lightning_indexer 接口可被导入调用;
  2. TorchNPU 安装包下载:参考 Attention 融合算子 Experimental 使用说明 获取与当前环境匹配的 TorchNPU 安装包,注意及时更换为最新版本。

此外,测试框架支持 custom 包调用,即算子可以以 custom operator 包的形式注册后供 torch_npu 接口直调,便于在未合入官方版本的场景下先行验证。

单用例调测:参数配置与执行

第一步:配置用例参数

单用例的参数集中在 test_lightning_indexer_paramset.py 的 TEST_PARAMS 字典中。框架通过 torch.npu.get_device_properties() 读取当前设备名并映射到对应配置:

  • Ascend910_93 → li_default_a3
  • Ascend950 → li_default_a5
  • Ascend910B → li_default_a2

设备不在映射表中时回退到默认配置 li_default_a2 并打印提示。每个参数均为列表类型,支持传入多个候选值,后续在 test_lightning_indexer_single.py 中通过 itertools.product 生成全部笛卡尔积组合,再以 @pytest.mark.parametrize 逐组驱动测试,从而实现"一次配置、全组合覆盖"。

核心配置字段(与算子 参数说明 一一对应):

字段 含义
batch_size / q_seq / k_seq Batch Size、Query/Key 的 Sequence Length
q_t_size / k_t_size TND 布局下 Query/Key 的 Total Tokens
q_head_num / k_head_num Query/Key 的 Head Num(K_N 仅支持 1)
head_dim Head Dim(支持 128)
block_size / block_num PageAttention 下每个 block 的 token 数与 block 总数
qk_dtype / weight_dtype / actual_seq_dtype Query/Key、Weights、序列长度张量的数据类型
act_seq_q / act_seq_k 每个 Batch 的实际有效 token 数(PA 场景下非前缀和)
layout_query / layout_key 数据排布(BSND/TND、PA_BSND 等)
sparse_count topK 阶段保留的索引个数
sparse_mode sparse 模式(0=defaultMask,3=rightDownCausal)
query_datarange / key_datarange / weights_datarange 各输入随机数生成区间

第二步:执行单用例

在 pytest 目录下执行:

bash test_run.sh single

该命令实际运行 python3 -m pytest -rA -s test_lightning_indexer_single.py -v -m ci -W ignore::UserWarning -W ignore::DeprecationWarning,其中:

  • -m ci 仅执行标记为 ci 的用例(标记定义见 pytest.ini);
  • -rA 输出所有用例的完整汇总;
  • -s 关闭输出捕获,便于观察 golden 计算与对比过程中的打印信息。

单用例执行链路为:test_li 中组装 test_data → lightning_indexer_golden.li_output_single 同时产出 CPU 真值与 NPU 输出(内部执行 torch.npu.synchronize() 并 torch.sort 对齐输出)→ result_compare_method.check_result 判定 → 非 "Pass" 则 pytest.fail。若需验证图模式,可将 test_lightning_indexer_single.py 中注释掉的 lightning_indexer_acl_graph.li_output_acl_graph(test_data) 分支启用,该分支基于 torchair 的 CompilerConfig 构建图编译调用。

批量测试:Excel 用例生成、执行与结果落盘

批量测试三步流水线

批量测试由 bash test_run.sh batch 一键驱动,其内部实现(见 test_run.sh)分为三步,每一步都有失败即退出的校验:

  1. 生成 .pt 用例:python3 batch/lightning_indexer_pt_save.py <excel路径> <pt路径>。脚本 lightning_indexer_pt_save.py 读取 Excel 中每个测试用例行(Testcase_Name 及 23 个参数列,缺列会 pytest.skip),将字符串型 dtype(FP16/BF16/INT32)转换为 torch 类型、解析 datarange,随机生成输入张量,调用 GeneralizedLI.forward 计算 CPU golden,最后以 torch.save 将 {params, cpu_result, topk_value, query, key, weights, ...} 整体存为 <用例名>.pt;
  2. 路径占位符替换:python3 batch/replace_path.py test_lightning_indexer_batch.py <pt路径>。脚本 replace_path.py 通过 fileinput 以 inplace=True、backup='.bak' 方式把 test_lightning_indexer_batch.py 中的 __PATH__ 占位符替换为实际 pt 目录;
  3. 执行 pytest 并还原:python3 -m pytest -rA -s test_lightning_indexer_batch.py -v -m ci,结束后用 .bak 备份恢复原文件,保证脚本可重复执行。

批量执行的实现要点

test_lightning_indexer_batch.py 启动时会扫描 pt 目录下所有 .pt 文件并动态生成参数化用例;每个用例经 ProcessPoolExecutor(max_workers=1) 放入独立子进程执行(隔离算子调用与设备状态),内部调用 lightning_indexer_pt_loadprocess.py 的 test_li_process:torch.load 加载数据 → 转移至 NPU → 以 pre_tokens=(1<<63)-1、next_tokens=(1<<63)-1、return_value 等完整属性调用 torch_npu.npu_lightning_indexer → torch.npu.synchronize() → 对 sparse_value 降序排序后返回。

每个用例结束后,结果(Testcase_Name、全部入参、result、fulfill_percent)追加写入 result.xlsx(文件不存在则新建,列名不匹配会告警),实现用例维度、可追溯、可归档的回归报告。

精度对比原理:两级比较算法详解

result_compare_method.py 是精度判定的核心,其 check_result 采用"先集合、后数值"的两级策略:

第一级:有效值集合等价比较。 将 NPU 输出与 CPU golden 按行 reshape 为 [total_rows, sparse_count],以 -1 作为无效填充标记(cpu_reshape != -1 计算有效长度 valid_lens),对每行排序后判断 cpu_output_sorted != npu_output_sorted 是否存在差异行;若完全一致直接通过,存在差异的行才进入第二级,并打印需要进行二级比较的行数。

第二级:Top-k 位置与误差精细比较。 对差异行调用 compare_topk_valid:

  • 先做集合等价判断(npu_set == cpu_set);
  • 若集合不一致,对仅在 NPU 或仅在 CPU 中出现的候选位置,以 CPU 输出中最后一个有效位置的分数 value_bm 为基准计算相对误差 |value - value_bm| / value_bm,阈值 thres = 0.0001;
  • 当 return_value 开启时,还会联动 judge_value_by_isclose 对输出 value 做 np.isclose 校验(bfloat16 使用 atol=0.0001,其余使用 atol=2.5e-05、rtol=0.005)。

整体判定:对所有元素执行 np.isclose(real_data, data_compe, rtol=0.005, atol=0.000025, equal_nan=True),统计满足比例 fulfill_percent,通过阈值 pct_thd = 0.05(即通过率需 ≥ 95%),满足 npu_pass or topk_precision 时判为 "Pass",否则 "Failed" 并打印错误明细(前 10 条、尾部条目及 Max-RE 行)。当 return_value 为真时,还会额外将 golden 的完整注意力分数 topk_value(BNSD 布局,float32)排序取前 sparse_count 后转换为输出 layout,与 NPU 输出的 sparse_value 做同样的 value 精度比较,任一环节失败则整体判为 Failed。

Golden 实现源码解析:从公式到 CPU 复现

lightning_indexer_golden.py 中的 GeneralizedLI 类完整复现了算子公式,关键计算链在 cal_atten_per_batch_b16 中:

  1. QK^T:torch.bmm(Q, K.permute(0,1,3,2)),并将输入转为 float32 计算以保证精度;
  2. ReLU:qk_relu_out = qk_bmm_res.clamp_min(0.0);
  3. 加权融合:torch.bmm(W, relu_out) 实现公式中的 [1]@[(W@[1])⊙ReLU(QK^T)],再 reshape 到 [B, N2, S1, S2];
  4. Mask 置位:sparse_mode == 3(rightDownCausal)时,由 create_mask_right_down/create_mask 生成下三角掩码(next_tokens = S2 - S1),将布尔掩码对应位置置为 -inf;
  5. 稳定排序取 Top-k:对每行用 torch.sort(stable=True) 按 (-score, index) 双键稳定排序,取前 actual_selected_count = min(当前batch的K_S, sparse_count) 个位置作为 sparse_indices,其余填充 -1。

同时该文件承担了测试数据与输入构造职责:generate_li_test_data 依据 datarange 随机生成 query/key/weights;PA_BSND 场景下按各 batch 有效长度计算所需 block 数(ceil(act_k / block_size),校验 block_num 足够),随机打乱 block id 构建 block_table,再按 block 映射把连续 key 数据写入 [block_num, block_size, K_N, D] 的 KV Cache 张量;并支持通过 ENABLE_DISCONTIGUOUS_KEY/KEY_D_EXPAND 开关构造 KV Cache 0 轴非连续场景(将 key 融合进 blockFusion 后切片取视图),用于验证算子的非连续支持能力。TND 布局下 act_seq 以前缀和形式给出,trans_tnd_actseq 会将其还原为各 batch 实际长度并校验非递减性。

测试覆盖范围与扩展建议

从源码结构与默认配置可以推断,该框架具备良好的可扩展性:

  • 设备适配:TEST_PARAMS 预留了 li_default_a2/a3/a5 三套配置,通过设备名自动选择,新增硬件平台只需补充对应配置字典与设备映射;
  • 场景覆盖:layout 组合可扩展至 BSND/TND query 与 PA_BSND/BSND/TND key 的全组合(golden 的 trans_shape_to_bnsd 与 trans_bnsd_to_layout 已实现全部布局互转);
  • 模式覆盖:sparse_mode 0/3 均已实现,return_value 分支可单独验证稀疏分数输出;
  • 图模式:lightning_indexer_acl_graph.py 提供 torchair 图编译调用示例,可在单测中切换验证。

若需将本框架复用于 ops-transformer 中其他 attention 类算子,可参照其"golden 复现 + TorchNPU 直调 + 两级精度比较 + Excel 批量驱动"的完整范式,替换 lightning_indexer_golden.py 中的算子计算链与 test_lightning_indexer_paramset.py 的参数模板即可。算子本身的 aclnn 接口调用方式可进一步参考 aclnnLightningIndexer 接口文档 与 示例程序。

登录后查看全文
ops-transformer