尧图网页设计 
人工智能大模型模型推理服务AscendCANN【免费下载链接】vllm-ascendCommunity maintained hardware plugin for vLLM on Huawei Ascend项目地址https://gitcode.com/gh_mirrors/vl/vllm-ascend点击查看免费下载本篇技术指南聚焦 vllm-ascend 开源仓库中稀疏注意力前处理算子 QuantLightningIndexerV2QLI_V2的 pytest 测试框架位于csrc/attention/quant_lightning_indexer_v2/tests/pytest。该框架以 CPU 侧 golden 复现 NPU 侧 TorchNPU 直调 精度对比为核心同时提供 single / batch / batch_exec / 批量隔离四种运行形态支持 eager 与 graphtorch.compile torchair双模式以及 msprof 性能采集。读完本文你将掌握该算子测试用例的完整运行方式、Excel 用例表格式、PT 生成与复跑机制并能对照源码理解框架的架构设计与实现细节。一、框架功能总览QuantLightningIndexerV2 是推理场景下稀疏 attention 的前处理算子从压缩后的 index key 中选出关键的稀疏 tokenTop-k并对输入 query/key 进行量化存 8 算 8其数学过程为$$out \text{Top-}k{[1]{1\times g}[(W[1]{1\times S_{k}})\odot\text{ReLU}((Scale_QScale_K^T)\odot(Q_{index}^{Quant}(K_{index}^{Quant})^T))]}$$关于算子本身的输入输出参数、量化模式约束与产品支持情况可进一步阅读 算子 README 与 aclnn 接口文档。围绕该算子tests/pytest目录下的测试框架实现了以下能力CPU 侧 golden 复现用 PyTorch 精确复刻算子功能生成 golden 数据NPU 侧算子直调通过 TorchNPU 直接调用算子获取实际输出精度对比对 CPU 与 NPU 结果进行逐项比对判定算子功能正确性双模式执行隔离支持直接 pytest 多进程执行与 shell 层进程隔离两种批量模式PT 复跑模式batch -P 目录直接执行已有 PT增加-E才会先生成 PT可控批跑-P统一指定 PT 生成和读取目录支持按结果路径、case 名和 1-based 序号选择性能采集挂载 msprof 采集算子性能数据并汇总输出到 Excel运行模式切换支持 eager 直接调用与 graphtorch.compile torchair两种算子调用模式。二、当前实现范围与约束2.1 参数限制维度支持取值query_layoutBSND、TNDkey_layoutPA_BBND、BSND、TNDqk_dtypeFLOAT8_E4M3FN、INT8、HIFLOAT8、FLOAT4_E2M1dequant_dtypeFP32Ascend950、FP16Ascend910_93、FLOAT8_E8M0MXFP8/MXFP4actual_seq_dtypeINT322.2 PyTorch MX 类型约定quant_mode为 3/5 时query_dequant_scale和key_dequant_scale必须为torch.float8_e8m0fnuquant_mode为 5 时query和key的算子逻辑数据类型为FLOAT4_E2M1文档简写float4_e2m1PyTorch 提供torch.float4_e2m1fn_x2时优先使用该原生打包类型名称中的x2表示每个物理字节打包两个 E2M1 逻辑元素PyTorch 未提供该类型时使用torch.uint8承载已打包数据封装层会将其按ACL_FLOAT4_E2M1传入算子。这些约定在 golden 实现 quant_lightning_indexer_v2_golden.py 中均有对应校验例如validate_mx_scale_dtype强制 MXFP8/MXFP4 场景 scale 为torch.float8_e8m0fnumake_mxfp4_tensor_pair负责生成 E2M1 打包数据packed raw[..., 0::2] | (raw[..., 1::2] 4)并要求head_dim必须为偶数。2.3 运行模式eager直接调用torch.ops.cann_ops_transformer.quant_lightning_indexergraph通过torch.compiletorchair后端编译执行需 torchair 支持。在 test_quant_lightning_indexer_v2_single.py 中可以看到两种模式的完整调用链eager 走quant_lightning_indexer_v2_golden.qliv2_output_single(test_data)graph 走quant_lightning_indexer_v2_acl_graph.qliv2_output_acl_graph(test_data)运行模式由环境变量QLIV2_RUN_MODE或参数中的run_mode字段决定。2.4 环境配置确认 TorchNPU 为最新版本激活 CANN 包和自定义算子包graph 模式需要安装 torchair 编译器后端支持 custom 包调用。三、文件结构与职责划分pytest 测试目录下各文件职责如下文件职责test_run.sh执行脚本支持 single / batch / batch_exec 三种命令batch_isolated_run.sh批量隔离执行脚本shell 层进程隔离 msprof 性能采集quant_lightning_indexer_v2_golden.pyCPU 侧算子 golden 实现quant_lightning_indexer_v2_acl_graph.pygraph 模式 torchair 后端实现result_compare_method.pyCPU golden 与 NPU 输出精度对比qliv2_test_utils.pycase 选择、稳定命名和结果表公共逻辑collect_perf_data.pymsprof 性能数据收集与汇总pytest.ini创建ci/graph测试标记test_quant_lightning_indexer_v2_single.pypytest 单用例运行主程序test_quant_lightning_indexer_v2_paramset.py单用例入参配置按芯片型号自动选择用例test_quant_lightning_indexer_v2_batch.py用例批量测试主程序并生成 Excel 保存结果batch/quant_lightning_indexer_v2_pt_loadprocess.py读取 pt 文件并调用算子获取 NPU 输出batch/quant_lightning_indexer_v2_pt_save.py读取 Excel 表格批量生成用例 pt 文件batch/list_pt_from_excel.py从 Excel 提取Testcase_Name并按名匹配 pt 文件batch_exec 模式用其中test_run.sh是统一入口源码中通过run_single/run_batch/run_batch_from_excel三个函数分别对应三种命令并借助QLIV2_TESTCASE_DIR、QLIV2_PT_FILE_LIST、QLIV2_CASE_NAMES、QLIV2_CASE_INDEXES、QLIV2_RESULT_PATH、QLIV2_RUN_MODE等环境变量把选择结果透传给 pytest 主程序。四、架构设计与数据流数据生成入口generate_qliv2_test_data复用原有 batch 数据链生成输入和 CPU golden不调用 metadata 或主算子参数准备仍可查询设备信息。single 模式直接执行配置用例指定--save-pt时保存并执行同一份实际输入避免二次随机生成。batch 模式-P是唯一 PT 目录有-E时先生成再执行无-E时直接执行已有 PT。batch_exec 模式按 Excel 的Testcase_Name筛选已有 PT仅执行 NPU 和精度对比。两路共用_qliv2_prepare_tensors_and_metadata和_qliv2_run_compiled_graph统一使用fullgraphFalse。结果表会先落盘index 或 return value 精度结果为Failed时pytest 随后以非零状态退出对应qliv2_test_utils.ensure_comparison_passed的抛错逻辑。4.1 批量执行内部调用链源码视角从源码看test_quant_lightning_indexer_v2_batch.py 的用例执行函数qliv2()完整覆盖了取参 → 跑 NPU → 比对 → 落盘的全过程依据QLIV2_RUN_MODE选择quant_lightning_indexer_v2_pt_loadprocess.test_qliv2_processeager或test_qliv2_process_graphgraph加载 PT 并执行调用result_compare_method.check_result比对cpu_result与npu_result得到result与fulfill_percentreturn_value1时额外调用check_result_return_value校验 value 输出通过QliV2ResultWriter.rowappend把结果写入result.xlsxensure_comparison_passed在精度失败时抛出AssertionError使 pytest 标记该用例失败。值得注意的是该文件同时支持两种隔离形态设置QLIV2_TESTCASE_PATH由batch_isolated_run.sh触发时进入隔离模式用例内部仅用ThreadPoolExecutor(max_workers1)未设置时则使用ProcessPoolExecutor(max_workers1)以子进程隔离防止单条用例崩溃影响整体执行。4.2 case 选择与稳定命名qliv2_test_utils.py 中的QliV2CaseSelector实现了三种选择方式显式文件列表explicit_files逗号分隔按 case 名case_names按 1-based 序号case_indexes支持3,1,5-7区间语法且基于自然排序natural_key如test2排在test10之前。QliV2ResultWriter.case_name则提供了稳定命名规则无显式名时生成形如QLI_B{batch}_S1{q_seq}_S2{k_seq}_N1{q_head_num}_N2{k_head_num}_D{head_dim}_{layout_query}_{layout_key}_{qk_dtype}_QM{quant_mode}_SM{sparse_mode}_CR{cmp_ratio}_K{sparse_count}_RV{return_value}的规范化名称非法文件名字符统一替换为_保证 PT 文件名的确定性。五、使用方法完整命令所有命令均在pytest目录csrc/attention/quant_lightning_indexer_v2/tests/pytest下执行。5.1 单用例调测手动配置 test_quant_lightning_indexer_v2_paramset.py 的ENABLED_PARAMS实际生效的是ENABLED_PARAMSETS源码中会通过torch.npu.get_device_properties()按芯片型号自动筛选Ascend910_93启用quant_li_default_a3等用例Ascend950启用quant_li_default_a5_*系列与wb_*白盒用例执行指令bash test_run.sh single bash test_run.sh single --save-pt ./single_pt -O ./result/single.xlsx bash test_run.sh single -M graph --save-pt ./single_pt其中--save-pt指定保存本次实际输入与 CPU golden 的目录single 下默认不保存-O指定结果 Excel 路径single 默认single_result.xlsx-M指定运行模式默认 eager。5.2 批量生成与测试方式 Atest_run.sh 批量执行-P同时指定 PT 的保存目录和读取目录默认是当前 pytest 目录下的pt_path。直接执行已有 PT不传-E时不读取 Excel、不重新生成 PT只执行 NPU 和 comparebash test_run.sh batch -P ./pt_path bash test_run.sh batch -P ./pt_path -O ./result/rerun.xlsx bash test_run.sh batch -P ./pt_path -C case_b,case_a # 按名称和给定顺序 bash test_run.sh batch -P ./pt_path -I 3,1,5-7 # 按自然排序后的序号 bash test_run.sh batch -P ./pt_path -M graph配置区默认值变量默认值命令行参数说明DEFAULT_EXCEL./excel/test_cases.xlsx-EExcel 用例表格路径必须指定具体文件名不支持通配符如./excel/*DEFAULT_PT_PATH./pt_path-Ppt 文件存放目录无Sheet1-SExcel Sheet 页名无eager-M运行模式eager/graphtest_run.sh源码中还包含以下校验逻辑--cases与--indexes不能同时使用-M仅接受 eager/graphbatch 模式传-E时会先校验 Excel 文件存在并调用quant_lightning_indexer_v2_pt_save.py生成 PT否则要求-P目录已存在。-C/-I的越界或未知名称会在QliV2CaseSelector中抛出ValueError。batch_exec根据 Excel 表格筛选已有 PT 批量执行仅重新执行 NPU 测试和精度对比不重新生成 pt 文件。适用于已有 pt 文件、只需更新精度结果的场景。增加-E后脚本先把 Excel 用例生成到-P再从同一个目录执行此为 batch 模式语义而batch_exec命令则是纯粹的筛选执行bash test_run.sh batch_exec -E ./excel/test_cases.xlsx -P ./pt_path bash test_run.sh batch_exec -E ./excel/test_cases.xlsx -S Sheet1 -P ./pt_path bash test_run.sh batch_exec -E ./excel/test_cases.xlsx -P ./pt_path -O ./result/batch.xlsx执行流程从 Excel 表格读取Testcase_Name列按Testcase_Name.pt在 pt_path 下匹配对应的 .pt 文件仅对匹配到的 .pt 文件执行 NPU 测试和精度对比生成result.xlsx测试结果表格如果 Excel 中某条用例无对应的 .pt 文件会输出警告并跳过该用例。源码层面batch_exec 由list_pt_from_excel.py输出匹配到的文件列表通过环境变量QLIV2_PT_FILE_LIST传入批量测试主程序。batch 与 batch_exec 的区别batchbatch_execpt 生成每次重新生成跳过执行速度较慢含 pt 生成较快适用场景首次运行 / 参数变更精度复测 / 仅 NPU 结果更新方式 B手工分步执行生成 pt 文件python3 batch/quant_lightning_indexer_v2_pt_save.py excel/test_cases.xlsx pt_path python3 batch/quant_lightning_indexer_v2_pt_save.py excel/test_cases.xlsx pt_path --sheet Sheet1 # 指定 Sheet 页替换测试脚本路径QLIV2_TESTCASE_DIRpt_path QLIV2_RESULT_PATHresult.xlsx \ python3 -m pytest -rA -s test_quant_lightning_indexer_v2_batch.py -v -m ci执行测试python3 -m pytest -rA -s test_quant_lightning_indexer_v2_batch.py -v -m ci -W ignore::UserWarning -W ignore::DeprecationWarning恢复测试脚本cp test_quant_lightning_indexer_v2_batch.py.bak test_quant_lightning_indexer_v2_batch.py方式 C批量隔离执行推荐用于性能采集对每条用例单独拉起一个 pytest 进程实现进程间完全隔离避免单条用例崩溃影响其他用例bash batch_isolated_run.sh ./pt_path 0 # 不采集性能 bash batch_isolated_run.sh ./pt_path 1 # 采集性能挂载msprof bash batch_isolated_run.sh ./pt_path 0 graph # graph模式 不采集性能 bash batch_isolated_run.sh ./pt_path 1 graph # graph模式 性能采集从 batch_isolated_run.sh 源码可以看到其实现细节三个位置参数依次为用例目录默认./pt_path、是否 msprof 采集0/1、运行模式eager/graph通过find $TESTCASE_DIR -maxdepth 1 -name *.pt | sort收集全部用例循环为每条用例设置QLIV2_TESTCASE_PATH并独立拉起 pytest 进程msprof python3 -m pytest ...进程间完全隔离每条用例跑完后立即调用collect_perf_data.py --incremental增量收集性能数据并将PROF_*目录重命名为PROF_*_case_name防止下一条用例的 msprof 覆盖支持SIGINT/SIGTERM中断清理递归杀死子进程与set -o pipefail严格错误传播执行结果逐条写入batch_summary.log失败用例同时追加到batch_fail_list.log最后汇总总计/通过/失败并以非零状态退出表示存在失败用例。性能数据解析由 collect_perf_data.py 完成从mindstudio_profiler_output/op_summary*.csv中提取Op Name QuantLightningIndexerV2的行将 msprof 原始数据合并进result_perf.xlsx与结果表按行号对齐并重命名重叠列加op_前缀。六、Excel 用例表格式excel/test_cases.xlsx需包含以下列Sheet1列名类型示例Testcase_Namestrtest_case_01batch_sizeint8q_seqint15k_seqint111q_t_sizeint8k_t_sizeint15q_head_numint64k_head_numint1head_dimint128block_sizeint512block_numint8qk_dtypestrFLOAT8_E4M3FN/INT8/HIFLOAT8/FLOAT4_E2M1dequant_dtypestrFP32/FP16/FLOAT8_E8M0actual_seq_dtypestrINT32cu_seqlens_qNone/strNone或[0, 1]cu_seqlens_kNone/strNone或[0, 1]seqused_qNone/strNone或[3,3,3,3,3,3,3,3]seqused_kstr[28,24,80,96,47,76,0,111]cmp_residual_kNone/strNone或[0,0,0,0,0,0,0,0]cmp_ratio1 时必填max_seqlen_qint-1quant_modeint1/2/4layout_querystrBSND/TNDlayout_keystrPA_BBNDsparse_countint512sparse_modeint0/3query_datarangestr[-448,448]key_datarangestr[-20,20]weights_datarangestr[-123,123]q_scale_datarangestr[0,255]k_scale_datarangestr[0,65504]cmp_ratioint1/4return_valueint0/1output_idx_offsetNone/strNone或列表字符串结合 golden 源码可以进一步理解若干列的含义与取值约束datarange系列列是数据生成范围而非直接数值golden 实现会在该范围内随机/循环生成元素其中q_scale_datarange/k_scale_datarange表示 scale 的真实取值范围MX 场景下会再转换为 E8M0 编码编码 e 对应 2^(e-127)见make_mx_e8m0_scale_paircmp_ratio表示 key 的压缩倍数源码注释标明支持 1/2/4/8/16/32/64/128cmp_residual_k为压缩场景下 Key 的残余长度需满足0 cmp_residual_k[i] cmp_ratiosparse_mode为 3 时golden 通过布尔 mask 把被屏蔽位置置为-inf后再做稳定排序sparse_mode为 0 时则直接对全序列排序block_size在 paramset 中取 16 的整数倍最大支持到 1024q_head_numN可小于k_head_num的整数倍形成 group源码中group_size q_head_num // k_head_num。注意事项dequant_dtypeAscend950 的quant_mode3/5仅支持FLOAT8_E8M0其他量化模式支持FP32Ascend910_93 支持FP16cmp_ratio 1且sparse_mode ! 0时cmp_residual_k必填长度 batch_size 的列表return_value1时output_idx_offset需提供有效值Ascend910_93 要求quant_mode2。七、输出文件文件说明result.xlsx测试结果精度、参数等result_perf.xlsx测试结果 性能数据仅 msprof 模式batch_summary.log批量执行详细日志batch_fail_list.log失败用例清单PROF_*/msprof 性能原始数据目录结果表由QliV2ResultWriter维护固定 schemacase_name加PARAM_NAMES定义的 33 个参数字段外加result、fulfill_percent、result_return_value、fulfill_percent_return_value四个结果字段追加写入时若与既有 Excel 列不一致会直接报错保证结果文件格式的稳定性。八、与算子实现的衔接测试框架的最终目的是验证算子本身的正确性相关实现可继续深入算子 host 侧shape 推导、tiling 策略位于 op_host 目录对应的 tiling / infershape 单元测试在 tests/ut 下test_quant_lightning_indexer_v2_tiling.cpp、test_quant_lightning_indexer_v2_infershape.cpp算子 kernel 侧按 arch22Atlas A2/A3 系列与 arch35Ascend 950 系列分目录实现其中 arch35 下还有专门的vftopk 向量实现子目录torch 侧封装含 eager 直调与 graph 转换位于 torch_extension对应算子 API 文档 aclnnQuantLightningIndexerV2若需了解算子在推理链路中的定位稀疏 attention 前处理、Top-k token 选择与 query/key 量化可结合 算子 README 中的计算公式与约束说明以及设计文档 qli_v2_two_level_topk_design.md。简言之这套 pytest 框架以CPU golden NPU 直调 精度对比为闭环通过 single / batch / batch_exec / 批量隔离四种执行形态覆盖从单用例调测到大规模回归、再到性能采集的完整测试场景是验证 QuantLightningIndexerV2 稀疏注意力算子在昇腾 NPU 上功能与性能正确性的标准工具链。赞分享人工智能大模型模型推理服务AscendCANN【免费下载链接】vllm-ascendCommunity maintained hardware plugin for vLLM on Huawei Ascend项目地址https://gitcode.com/gh_mirrors/vl/vllm-ascend点击查看免费下载相关推荐ops-transformer QuantCompressor 算子 Pytest 测试框架CPU Golden 对比、批量隔离执行与 msprof 性能采集实战指南ops transformer QuantCompressor 算子 Pytest 测试框架CPU Golden 对比、批量隔离执行与 msprof 性能采集算子库人工智能大模型深度学习CANNAscendRecurrentGatedDeltaRule 算子 pytest 测试框架实战从 golden 生成、随机泛化到 mssanitizer 检测RecurrentGatedDeltaRule 算子 pytest 测试框架实战从 golden 生成、随机泛化到 mssanitizer 检测 导读 本指南算子库人工智能大模型深度学习CANNAscendBaiduPCS-Go 百度网盘命令行客户端完整上手指南从登录到批量转存BaiduPCS Go 百度网盘命令行客户端完整上手指南从登录到批量转存 BaiduPCS Go 是一个用 Go 编写的百度网盘命令行客户端仿 LinuxCLI网络上一篇【Web UI】极速搭建AI浏览器代理环境从配置到启动的全面避坑指南下一篇83个公共Tracker实战指南如何5分钟内让BT下载速度提升300%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 vllm-ascend QuantLightningIndexerV2 算子 pytest 测试框架：golden 复现、可控批跑与 msprof 性能采集实战
人工智能大模型模型推理服务AscendCANN【免费下载链接】vllm-ascendCommunity maintained hardware plugin for vLLM on Huawei Ascend项目地址https://gitcode.com/gh_mirrors/vl/vllm-ascend点击查看免费下载本篇技术指南聚焦 vllm-ascend 开源仓库中稀疏注意力前处理算子 QuantLightningIndexerV2QLI_V2的 pytest 测试框架位于csrc/attention/quant_lightning_indexer_v2/tests/pytest。该框架以 CPU 侧 golden 复现 NPU 侧 TorchNPU 直调 精度对比为核心同时提供 single / batch / batch_exec / 批量隔离四种运行形态支持 eager 与 graphtorch.compile torchair双模式以及 msprof 性能采集。读完本文你将掌握该算子测试用例的完整运行方式、Excel 用例表格式、PT 生成与复跑机制并能对照源码理解框架的架构设计与实现细节。一、框架功能总览QuantLightningIndexerV2 是推理场景下稀疏 attention 的前处理算子从压缩后的 index key 中选出关键的稀疏 tokenTop-k并对输入 query/key 进行量化存 8 算 8其数学过程为$$out \text{Top-}k{[1]{1\times g}[(W[1]{1\times S_{k}})\odot\text{ReLU}((Scale_QScale_K^T)\odot(Q_{index}^{Quant}(K_{index}^{Quant})^T))]}$$关于算子本身的输入输出参数、量化模式约束与产品支持情况可进一步阅读 算子 README 与 aclnn 接口文档。围绕该算子tests/pytest目录下的测试框架实现了以下能力CPU 侧 golden 复现用 PyTorch 精确复刻算子功能生成 golden 数据NPU 侧算子直调通过 TorchNPU 直接调用算子获取实际输出精度对比对 CPU 与 NPU 结果进行逐项比对判定算子功能正确性双模式执行隔离支持直接 pytest 多进程执行与 shell 层进程隔离两种批量模式PT 复跑模式batch -P 目录直接执行已有 PT增加-E才会先生成 PT可控批跑-P统一指定 PT 生成和读取目录支持按结果路径、case 名和 1-based 序号选择性能采集挂载 msprof 采集算子性能数据并汇总输出到 Excel运行模式切换支持 eager 直接调用与 graphtorch.compile torchair两种算子调用模式。二、当前实现范围与约束2.1 参数限制维度支持取值query_layoutBSND、TNDkey_layoutPA_BBND、BSND、TNDqk_dtypeFLOAT8_E4M3FN、INT8、HIFLOAT8、FLOAT4_E2M1dequant_dtypeFP32Ascend950、FP16Ascend910_93、FLOAT8_E8M0MXFP8/MXFP4actual_seq_dtypeINT322.2 PyTorch MX 类型约定quant_mode为 3/5 时query_dequant_scale和key_dequant_scale必须为torch.float8_e8m0fnuquant_mode为 5 时query和key的算子逻辑数据类型为FLOAT4_E2M1文档简写float4_e2m1PyTorch 提供torch.float4_e2m1fn_x2时优先使用该原生打包类型名称中的x2表示每个物理字节打包两个 E2M1 逻辑元素PyTorch 未提供该类型时使用torch.uint8承载已打包数据封装层会将其按ACL_FLOAT4_E2M1传入算子。这些约定在 golden 实现 quant_lightning_indexer_v2_golden.py 中均有对应校验例如validate_mx_scale_dtype强制 MXFP8/MXFP4 场景 scale 为torch.float8_e8m0fnumake_mxfp4_tensor_pair负责生成 E2M1 打包数据packed raw[..., 0::2] | (raw[..., 1::2] 4)并要求head_dim必须为偶数。2.3 运行模式eager直接调用torch.ops.cann_ops_transformer.quant_lightning_indexergraph通过torch.compiletorchair后端编译执行需 torchair 支持。在 test_quant_lightning_indexer_v2_single.py 中可以看到两种模式的完整调用链eager 走quant_lightning_indexer_v2_golden.qliv2_output_single(test_data)graph 走quant_lightning_indexer_v2_acl_graph.qliv2_output_acl_graph(test_data)运行模式由环境变量QLIV2_RUN_MODE或参数中的run_mode字段决定。2.4 环境配置确认 TorchNPU 为最新版本激活 CANN 包和自定义算子包graph 模式需要安装 torchair 编译器后端支持 custom 包调用。三、文件结构与职责划分pytest 测试目录下各文件职责如下文件职责test_run.sh执行脚本支持 single / batch / batch_exec 三种命令batch_isolated_run.sh批量隔离执行脚本shell 层进程隔离 msprof 性能采集quant_lightning_indexer_v2_golden.pyCPU 侧算子 golden 实现quant_lightning_indexer_v2_acl_graph.pygraph 模式 torchair 后端实现result_compare_method.pyCPU golden 与 NPU 输出精度对比qliv2_test_utils.pycase 选择、稳定命名和结果表公共逻辑collect_perf_data.pymsprof 性能数据收集与汇总pytest.ini创建ci/graph测试标记test_quant_lightning_indexer_v2_single.pypytest 单用例运行主程序test_quant_lightning_indexer_v2_paramset.py单用例入参配置按芯片型号自动选择用例test_quant_lightning_indexer_v2_batch.py用例批量测试主程序并生成 Excel 保存结果batch/quant_lightning_indexer_v2_pt_loadprocess.py读取 pt 文件并调用算子获取 NPU 输出batch/quant_lightning_indexer_v2_pt_save.py读取 Excel 表格批量生成用例 pt 文件batch/list_pt_from_excel.py从 Excel 提取Testcase_Name并按名匹配 pt 文件batch_exec 模式用其中test_run.sh是统一入口源码中通过run_single/run_batch/run_batch_from_excel三个函数分别对应三种命令并借助QLIV2_TESTCASE_DIR、QLIV2_PT_FILE_LIST、QLIV2_CASE_NAMES、QLIV2_CASE_INDEXES、QLIV2_RESULT_PATH、QLIV2_RUN_MODE等环境变量把选择结果透传给 pytest 主程序。四、架构设计与数据流数据生成入口generate_qliv2_test_data复用原有 batch 数据链生成输入和 CPU golden不调用 metadata 或主算子参数准备仍可查询设备信息。single 模式直接执行配置用例指定--save-pt时保存并执行同一份实际输入避免二次随机生成。batch 模式-P是唯一 PT 目录有-E时先生成再执行无-E时直接执行已有 PT。batch_exec 模式按 Excel 的Testcase_Name筛选已有 PT仅执行 NPU 和精度对比。两路共用_qliv2_prepare_tensors_and_metadata和_qliv2_run_compiled_graph统一使用fullgraphFalse。结果表会先落盘index 或 return value 精度结果为Failed时pytest 随后以非零状态退出对应qliv2_test_utils.ensure_comparison_passed的抛错逻辑。4.1 批量执行内部调用链源码视角从源码看test_quant_lightning_indexer_v2_batch.py 的用例执行函数qliv2()完整覆盖了取参 → 跑 NPU → 比对 → 落盘的全过程依据QLIV2_RUN_MODE选择quant_lightning_indexer_v2_pt_loadprocess.test_qliv2_processeager或test_qliv2_process_graphgraph加载 PT 并执行调用result_compare_method.check_result比对cpu_result与npu_result得到result与fulfill_percentreturn_value1时额外调用check_result_return_value校验 value 输出通过QliV2ResultWriter.rowappend把结果写入result.xlsxensure_comparison_passed在精度失败时抛出AssertionError使 pytest 标记该用例失败。值得注意的是该文件同时支持两种隔离形态设置QLIV2_TESTCASE_PATH由batch_isolated_run.sh触发时进入隔离模式用例内部仅用ThreadPoolExecutor(max_workers1)未设置时则使用ProcessPoolExecutor(max_workers1)以子进程隔离防止单条用例崩溃影响整体执行。4.2 case 选择与稳定命名qliv2_test_utils.py 中的QliV2CaseSelector实现了三种选择方式显式文件列表explicit_files逗号分隔按 case 名case_names按 1-based 序号case_indexes支持3,1,5-7区间语法且基于自然排序natural_key如test2排在test10之前。QliV2ResultWriter.case_name则提供了稳定命名规则无显式名时生成形如QLI_B{batch}_S1{q_seq}_S2{k_seq}_N1{q_head_num}_N2{k_head_num}_D{head_dim}_{layout_query}_{layout_key}_{qk_dtype}_QM{quant_mode}_SM{sparse_mode}_CR{cmp_ratio}_K{sparse_count}_RV{return_value}的规范化名称非法文件名字符统一替换为_保证 PT 文件名的确定性。五、使用方法完整命令所有命令均在pytest目录csrc/attention/quant_lightning_indexer_v2/tests/pytest下执行。5.1 单用例调测手动配置 test_quant_lightning_indexer_v2_paramset.py 的ENABLED_PARAMS实际生效的是ENABLED_PARAMSETS源码中会通过torch.npu.get_device_properties()按芯片型号自动筛选Ascend910_93启用quant_li_default_a3等用例Ascend950启用quant_li_default_a5_*系列与wb_*白盒用例执行指令bash test_run.sh single bash test_run.sh single --save-pt ./single_pt -O ./result/single.xlsx bash test_run.sh single -M graph --save-pt ./single_pt其中--save-pt指定保存本次实际输入与 CPU golden 的目录single 下默认不保存-O指定结果 Excel 路径single 默认single_result.xlsx-M指定运行模式默认 eager。5.2 批量生成与测试方式 Atest_run.sh 批量执行-P同时指定 PT 的保存目录和读取目录默认是当前 pytest 目录下的pt_path。直接执行已有 PT不传-E时不读取 Excel、不重新生成 PT只执行 NPU 和 comparebash test_run.sh batch -P ./pt_path bash test_run.sh batch -P ./pt_path -O ./result/rerun.xlsx bash test_run.sh batch -P ./pt_path -C case_b,case_a # 按名称和给定顺序 bash test_run.sh batch -P ./pt_path -I 3,1,5-7 # 按自然排序后的序号 bash test_run.sh batch -P ./pt_path -M graph配置区默认值变量默认值命令行参数说明DEFAULT_EXCEL./excel/test_cases.xlsx-EExcel 用例表格路径必须指定具体文件名不支持通配符如./excel/*DEFAULT_PT_PATH./pt_path-Ppt 文件存放目录无Sheet1-SExcel Sheet 页名无eager-M运行模式eager/graphtest_run.sh源码中还包含以下校验逻辑--cases与--indexes不能同时使用-M仅接受 eager/graphbatch 模式传-E时会先校验 Excel 文件存在并调用quant_lightning_indexer_v2_pt_save.py生成 PT否则要求-P目录已存在。-C/-I的越界或未知名称会在QliV2CaseSelector中抛出ValueError。batch_exec根据 Excel 表格筛选已有 PT 批量执行仅重新执行 NPU 测试和精度对比不重新生成 pt 文件。适用于已有 pt 文件、只需更新精度结果的场景。增加-E后脚本先把 Excel 用例生成到-P再从同一个目录执行此为 batch 模式语义而batch_exec命令则是纯粹的筛选执行bash test_run.sh batch_exec -E ./excel/test_cases.xlsx -P ./pt_path bash test_run.sh batch_exec -E ./excel/test_cases.xlsx -S Sheet1 -P ./pt_path bash test_run.sh batch_exec -E ./excel/test_cases.xlsx -P ./pt_path -O ./result/batch.xlsx执行流程从 Excel 表格读取Testcase_Name列按Testcase_Name.pt在 pt_path 下匹配对应的 .pt 文件仅对匹配到的 .pt 文件执行 NPU 测试和精度对比生成result.xlsx测试结果表格如果 Excel 中某条用例无对应的 .pt 文件会输出警告并跳过该用例。源码层面batch_exec 由list_pt_from_excel.py输出匹配到的文件列表通过环境变量QLIV2_PT_FILE_LIST传入批量测试主程序。batch 与 batch_exec 的区别batchbatch_execpt 生成每次重新生成跳过执行速度较慢含 pt 生成较快适用场景首次运行 / 参数变更精度复测 / 仅 NPU 结果更新方式 B手工分步执行生成 pt 文件python3 batch/quant_lightning_indexer_v2_pt_save.py excel/test_cases.xlsx pt_path python3 batch/quant_lightning_indexer_v2_pt_save.py excel/test_cases.xlsx pt_path --sheet Sheet1 # 指定 Sheet 页替换测试脚本路径QLIV2_TESTCASE_DIRpt_path QLIV2_RESULT_PATHresult.xlsx \ python3 -m pytest -rA -s test_quant_lightning_indexer_v2_batch.py -v -m ci执行测试python3 -m pytest -rA -s test_quant_lightning_indexer_v2_batch.py -v -m ci -W ignore::UserWarning -W ignore::DeprecationWarning恢复测试脚本cp test_quant_lightning_indexer_v2_batch.py.bak test_quant_lightning_indexer_v2_batch.py方式 C批量隔离执行推荐用于性能采集对每条用例单独拉起一个 pytest 进程实现进程间完全隔离避免单条用例崩溃影响其他用例bash batch_isolated_run.sh ./pt_path 0 # 不采集性能 bash batch_isolated_run.sh ./pt_path 1 # 采集性能挂载msprof bash batch_isolated_run.sh ./pt_path 0 graph # graph模式 不采集性能 bash batch_isolated_run.sh ./pt_path 1 graph # graph模式 性能采集从 batch_isolated_run.sh 源码可以看到其实现细节三个位置参数依次为用例目录默认./pt_path、是否 msprof 采集0/1、运行模式eager/graph通过find $TESTCASE_DIR -maxdepth 1 -name *.pt | sort收集全部用例循环为每条用例设置QLIV2_TESTCASE_PATH并独立拉起 pytest 进程msprof python3 -m pytest ...进程间完全隔离每条用例跑完后立即调用collect_perf_data.py --incremental增量收集性能数据并将PROF_*目录重命名为PROF_*_case_name防止下一条用例的 msprof 覆盖支持SIGINT/SIGTERM中断清理递归杀死子进程与set -o pipefail严格错误传播执行结果逐条写入batch_summary.log失败用例同时追加到batch_fail_list.log最后汇总总计/通过/失败并以非零状态退出表示存在失败用例。性能数据解析由 collect_perf_data.py 完成从mindstudio_profiler_output/op_summary*.csv中提取Op Name QuantLightningIndexerV2的行将 msprof 原始数据合并进result_perf.xlsx与结果表按行号对齐并重命名重叠列加op_前缀。六、Excel 用例表格式excel/test_cases.xlsx需包含以下列Sheet1列名类型示例Testcase_Namestrtest_case_01batch_sizeint8q_seqint15k_seqint111q_t_sizeint8k_t_sizeint15q_head_numint64k_head_numint1head_dimint128block_sizeint512block_numint8qk_dtypestrFLOAT8_E4M3FN/INT8/HIFLOAT8/FLOAT4_E2M1dequant_dtypestrFP32/FP16/FLOAT8_E8M0actual_seq_dtypestrINT32cu_seqlens_qNone/strNone或[0, 1]cu_seqlens_kNone/strNone或[0, 1]seqused_qNone/strNone或[3,3,3,3,3,3,3,3]seqused_kstr[28,24,80,96,47,76,0,111]cmp_residual_kNone/strNone或[0,0,0,0,0,0,0,0]cmp_ratio1 时必填max_seqlen_qint-1quant_modeint1/2/4layout_querystrBSND/TNDlayout_keystrPA_BBNDsparse_countint512sparse_modeint0/3query_datarangestr[-448,448]key_datarangestr[-20,20]weights_datarangestr[-123,123]q_scale_datarangestr[0,255]k_scale_datarangestr[0,65504]cmp_ratioint1/4return_valueint0/1output_idx_offsetNone/strNone或列表字符串结合 golden 源码可以进一步理解若干列的含义与取值约束datarange系列列是数据生成范围而非直接数值golden 实现会在该范围内随机/循环生成元素其中q_scale_datarange/k_scale_datarange表示 scale 的真实取值范围MX 场景下会再转换为 E8M0 编码编码 e 对应 2^(e-127)见make_mx_e8m0_scale_paircmp_ratio表示 key 的压缩倍数源码注释标明支持 1/2/4/8/16/32/64/128cmp_residual_k为压缩场景下 Key 的残余长度需满足0 cmp_residual_k[i] cmp_ratiosparse_mode为 3 时golden 通过布尔 mask 把被屏蔽位置置为-inf后再做稳定排序sparse_mode为 0 时则直接对全序列排序block_size在 paramset 中取 16 的整数倍最大支持到 1024q_head_numN可小于k_head_num的整数倍形成 group源码中group_size q_head_num // k_head_num。注意事项dequant_dtypeAscend950 的quant_mode3/5仅支持FLOAT8_E8M0其他量化模式支持FP32Ascend910_93 支持FP16cmp_ratio 1且sparse_mode ! 0时cmp_residual_k必填长度 batch_size 的列表return_value1时output_idx_offset需提供有效值Ascend910_93 要求quant_mode2。七、输出文件文件说明result.xlsx测试结果精度、参数等result_perf.xlsx测试结果 性能数据仅 msprof 模式batch_summary.log批量执行详细日志batch_fail_list.log失败用例清单PROF_*/msprof 性能原始数据目录结果表由QliV2ResultWriter维护固定 schemacase_name加PARAM_NAMES定义的 33 个参数字段外加result、fulfill_percent、result_return_value、fulfill_percent_return_value四个结果字段追加写入时若与既有 Excel 列不一致会直接报错保证结果文件格式的稳定性。八、与算子实现的衔接测试框架的最终目的是验证算子本身的正确性相关实现可继续深入算子 host 侧shape 推导、tiling 策略位于 op_host 目录对应的 tiling / infershape 单元测试在 tests/ut 下test_quant_lightning_indexer_v2_tiling.cpp、test_quant_lightning_indexer_v2_infershape.cpp算子 kernel 侧按 arch22Atlas A2/A3 系列与 arch35Ascend 950 系列分目录实现其中 arch35 下还有专门的vftopk 向量实现子目录torch 侧封装含 eager 直调与 graph 转换位于 torch_extension对应算子 API 文档 aclnnQuantLightningIndexerV2若需了解算子在推理链路中的定位稀疏 attention 前处理、Top-k token 选择与 query/key 量化可结合 算子 README 中的计算公式与约束说明以及设计文档 qli_v2_two_level_topk_design.md。简言之这套 pytest 框架以CPU golden NPU 直调 精度对比为闭环通过 single / batch / batch_exec / 批量隔离四种执行形态覆盖从单用例调测到大规模回归、再到性能采集的完整测试场景是验证 QuantLightningIndexerV2 稀疏注意力算子在昇腾 NPU 上功能与性能正确性的标准工具链。赞分享人工智能大模型模型推理服务AscendCANN【免费下载链接】vllm-ascendCommunity maintained hardware plugin for vLLM on Huawei Ascend项目地址https://gitcode.com/gh_mirrors/vl/vllm-ascend点击查看免费下载相关推荐ops-transformer QuantCompressor 算子 Pytest 测试框架CPU Golden 对比、批量隔离执行与 msprof 性能采集实战指南ops transformer QuantCompressor 算子 Pytest 测试框架CPU Golden 对比、批量隔离执行与 msprof 性能采集算子库人工智能大模型深度学习CANNAscendRecurrentGatedDeltaRule 算子 pytest 测试框架实战从 golden 生成、随机泛化到 mssanitizer 检测RecurrentGatedDeltaRule 算子 pytest 测试框架实战从 golden 生成、随机泛化到 mssanitizer 检测 导读 本指南算子库人工智能大模型深度学习CANNAscendBaiduPCS-Go 百度网盘命令行客户端完整上手指南从登录到批量转存BaiduPCS Go 百度网盘命令行客户端完整上手指南从登录到批量转存 BaiduPCS Go 是一个用 Go 编写的百度网盘命令行客户端仿 LinuxCLI网络上一篇【Web UI】极速搭建AI浏览器代理环境从配置到启动的全面避坑指南下一篇83个公共Tracker实战指南如何5分钟内让BT下载速度提升300%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考