lightning_indexer 算子 pytest 测试框架实战:CPU Golden 生成、NPU 直调与精度对比全流程解析
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- 个位置,其计算公式(见 lightning_indexer 算子说明)为:
其中 为某 token 对应的 Index Query, 为上下文 Index Key,, 为 GQA 对应的 group size, 为每个头的维度, 是上下文的长度。
为了在无标准第三方参考实现的条件下验证该算子,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 | (可选)图模式编译调用示例 |
环境准备与前置要求
运行测试前需完成两步准备(详见 环境部署):
- 环境安装与环境变量配置:按仓库提供的安装指南完成 CANN 算子开发运行环境、PyTorch 与 TorchNPU(
torch_npu)的安装,并正确配置环境变量,保证torch_npu.npu_lightning_indexer接口可被导入调用; - 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_a3Ascend950→li_default_a5Ascend910B→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)分为三步,每一步都有失败即退出的校验:
- 生成
.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; - 路径占位符替换:
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 目录; - 执行 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 中:
- QK^T:
torch.bmm(Q, K.permute(0,1,3,2)),并将输入转为 float32 计算以保证精度; - ReLU:
qk_relu_out = qk_bmm_res.clamp_min(0.0); - 加权融合:
torch.bmm(W, relu_out)实现公式中的[1]@[(W@[1])⊙ReLU(QK^T)],再 reshape 到[B, N2, S1, S2]; - Mask 置位:
sparse_mode == 3(rightDownCausal)时,由create_mask_right_down/create_mask生成下三角掩码(next_tokens = S2 - S1),将布尔掩码对应位置置为-inf; - 稳定排序取 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_mode0/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 接口文档 与 示例程序。