CANN ascend-transformer-boost 测试框架指南：CSV 数据驱动算子测试与 C++ 单元测试实战

CANN ascend-transformer-boost 测试框架指南CSV 数据驱动算子测试与 C 单元测试实战【免费下载链接】ascend-transformer-boost本项目是CANN提供的是一款高效、可靠的Transformer加速库基于华为Ascend AI处理器提供Transformer定制化场景的高性能融合算子。项目地址: https://gitcode.com/cann/ascend-transformer-boost导读本文面向在 CANN ascend-transformer-boost 仓库中开发、验证高性能融合算子的开发者系统讲解仓库内置的测试框架以 CSV 文件声明式定义测试用例、自动完成张量生成、算子执行、golden 对比与精度/性能验证的 Python 层CsvOpsTestTool以及桥接 ATB 算子与 PyTorch 张量的 C 层atb_torchOperationTorch。读完本文你将掌握测试框架的编译与运行环境、CSV 用例的完整字段格式与编写规范、golden 函数注册方法、单卡/多卡/性能测试的 CLI 用法、精度判定标准以及基于 gtest 的 C 单元测试atb_unittest、kernels_unittest的构建与执行方式。测试框架总体架构ATB 测试框架是一套数据驱动的算子测试系统分为两层协同工作Python 层CsvOpsTestToolCSV 驱动的测试入口负责用例解析、数据生成、算子调用编排、结果验证与报告输出。入口脚本为 atb_csv_ops_test.pygolden 计算逻辑集中在 data_generation.py。C 层atb_torch基于 PyTorchtorch::CustomClassHolder实现的OperationTorch自定义类将 ATB 算子封装为可被 Python 直接调用的 PyTorch 扩展类型负责完成 PyTorch 张量与 ATBTensorDesc/VariantPack之间的转换。核心实现在 operation_torch.h 与 operation_torch.cpp。两层之间的调用关系非常直接Python 侧通过torch.classes.OperationTorch.OperationTorch(opName)创建算子对象随后依次调用set_param、infer_shape、setup、execute_sync完成一次完整的算子执行周期见 atb_csv_ops_test.py这些方法通过 C 侧的TORCH_LIBRARY(OperationTorch, m)宏注册为 TorchScript 自定义类接口见 operation_torch.cpp。运行时由torch_load_framework()依据环境变量ATB_HOME_PATH动态加载libatb_test_framework.so见 atb_csv_ops_test.py。除 CSV 数据驱动测试外仓库还提供基于 gtest 的 C 单元测试atb_unittest、kernels_unittest等其构建与运行方式参见下文「运行 C 单元测试」章节。环境依赖与常见编译失败编译依赖编译测试框架bash scripts/build.sh testframework时必须具备以下依赖用于提供头文件与链接库依赖用途验证命令CANN toolkitATB 编译基础echo $ASCEND_HOME_PATHPyTorchC 层编译链接torch/script.h等头文件及libtorch.sopython3 -c import torch; print(torch.__file__)TorchNPUC 层编译链接torch_npu头文件及libtorch_npu.sopip show torch-npuPyTorch 及 TorchNPU 的安装请参考昇腾官方 PyTorch 安装指南hiascend.com文档中心的「昇腾PyTorch安装指南」。运行依赖运行 CSV 测试时需要以下 Python 库PyTorch 和 TorchNPU 同时也是编译依赖依赖用途验证命令PyTorch张量创建、golden 计算、算子调用python3 -c import torchTorchNPUNPU 设备访问python3 -c import torch_npupandasCSV 解析python3 -c import pandasnumpy数据生成与 golden 计算python3 -c import numpyml_dtypesBF16 等自定义数据类型支持python3 -c import ml_dtypesen_dtypeshifloat8 数据类型支持python3 -c from en_dtypes import hifloat8openpyxlExcel 格式输出支持python3 -c import openpyxlscipygolden 计算中的科学计算如 KS 检验python3 -c import scipy其余 Python 三方库依赖见 requirements.txt。若运行时报ModuleNotFoundError入口脚本的 argparse 描述中已提示可执行pip3 install -r requirements.txt补齐依赖。常见编译失败错误信息原因解决方法torch/script.h: No such file or directory环境中未安装 PyTorch安装 PyTorchpip install torchtorch_npu/csrc/core/npu/NPUStream.h: No such file环境中未安装 TorchNPU安装 TorchNPUlibatb.so: undefined referenceABI 版本不匹配确认 CXX ABI 版本与已编译的 ATB 核心库一致注意build.sh在 torch 未安装时仅输出Warning: Torch is not installed!但仍继续编译最终在 C 编译阶段报头文件缺失错误。若无需运行 CSV 测试框架可使用bash scripts/build.sh default仅编译 ATB 核心库。编译测试框架完整编译流程cd ascend-transformer-boost # 1. 设置CANN环境变量根据实际安装路径 source /usr/local/Ascend/ascend-toolkit/set_env.sh # 2. 编译测试框架包含ATB核心库 C测试框架 Python测试工具 bash scripts/build.sh testframework # 3. 设置ATB运行环境 source output/atb/set_env.sh增量编译日常开发中修改代码后无需全量重编译直接再次执行bash scripts/build.sh testframework注意不要删除build/目录不要加--clean-first增量编译即可。仅在 CMake 配置变更或算子内核文件.cce变动时才需要--clean-first因为 CMake 无法自动检测内核文件变更。特别地若环境发生变动如安装或更换 PyTorch 版本导致 ABI 判别结果改变例如从未装 PyTorch 的cxx_abi_1变为已装旧 ABI PyTorch 的cxx_abi_0需重新设置ATB_BUILD_DEPENDENCY_PATH为匹配的 ABI 路径并执行bash scripts/build.sh --clean-first testframework全量重编译。编译产物编译完成后关键产物位于路径说明output/atb/cxx_abi_{0\|1}/lib/libatb.soATB 核心库output/atb/cxx_abi_{0\|1}/lib/libatb_test_framework.so测试框架动态库含 OperationTorchtests/framework/python/CsvOpsTestTool/Python 测试工具安装到 output如何编写 CSV 测试用例CSV 用例格式测试用例以 CSV 文件形式存放在 tests/apitest/opstest/csv/ 目录下以|作为分隔符。从源码看入口脚本使用pd.read_csv(..., sep|, skipinitialspaceTrue)解析文件且运行前会先剔除文件中的空格与空行见 atb_csv_ops_test.py 与rm_space_from_input_file实现因此各列之间的空格仅用于排版美观不影响解析。表头字段说明字段说明示例CaseNum用例编号1CaseName用例名称ElewiseAddOpName算子名称ElewiseOperationOpParam算子参数JSON{elewiseType:8}InNum输入张量数量3InDType输入数据类型;分隔float16;float16;float16InFormat输入格式;分隔nd;nd;ndInShape输入形状;分隔维度用,2,3;4,3;4OutNum输出张量数量1OutDType输出数据类型float16OutFormat输出格式ndOutShape输出形状2,4DataGenType数据生成方式customize;customize;customizeDataGenRange数据范围-2,2;-2,2;-2,2InTensorFile输入张量文件路径可选空OutTensorFile输出张量文件路径可选空ExpectedError期望的错误码NO_ERROR或错误码TestType测试类型可选Function或PerformanceTestLevel测试级别可选Level0/Level1/Level2FromModel来源模型可选LLaMA-65BSocVersion支持的芯片型号Ascend910B,Ascend310P其中TestType字段在源码中额外支持Generalization类型该类型下输出张量信息OutNum/OutDType/OutShape/OutFormat不取自 CSV而是由infer_shape的返回结果动态填充见 atb_csv_ops_test.py适合输出形状由输入推导的泛化用例。InTensorFile/OutTensorFile支持从预置文件加载输入张量此时可通过-nf参数跳过文件加载。数据类型枚举值含义float16FP16bf16BF16floatFP32int8INT8int32INT32int64INT64uint64UINT64源码中的dtype_dict还支持uint8、int16、uint16、uint32、double、bool、complex64、complex128、hifloat8、float8_e5m2、float8_e4m3fn等更多类型映射见 data_generation.py其中hifloat8依赖en_dtypes包。格式枚举值含义ndN 维通用格式fractal_nz华为 NZ 分形格式format_dict中还映射了nchw、nhwc、nc1hwc0、fractal_z、hwcn、ndhwc、ncdhw、ndc1hwc0、fractal_z_3d等格式见 data_generation.py。错误码格式格式为阶段前缀:错误码框架在每个阶段都会将实际错误码与期望错误码比对前缀阶段示例C:CreateOperation创建算子C:ERROR_INVALID_PARAMI:InferShape维度推导I:ERROR_INVALID_TENSOR_DIM_NUMS:SetupCANN 调用S:ERROR_CANN_ERROR无前缀正例NO_ERROR错误码字符串与整型的映射关系定义在入口脚本的err_enum_dict中见 atb_csv_ops_test.py例如13对应ERROR_INVALID_TENSOR_INI_MATCH、16对应ERROR_INVALID_TENSOR_DIM_NUM。反例判定的核心逻辑是当ExpectedError不为NO_ERROR且以某个阶段前缀开头时只有实际错误发生在该阶段且错误码与期望一致用例才算通过见get_json_result与compute_result。用例示例正例逐元素加法22|ElewiseAdd|ElewiseOperation|{elewiseType:8}|2|float16;float16|nd;nd|3,3;3,3|1|float16|nd|3,3|random;random|0,10;0,10|||NO_ERROR||||Ascend910B,Ascend310P,Ascend310B反例数据类型校验错误23|ElewiseAddWrongDtype0|ElewiseOperation|{elewiseType:8}|2|bool;float16|nd;nd|3,3;3,3|1|float16|nd|3,3|random;random|0,10;0,10|||I:ERROR_INVALID_TENSOR_INI_MATCH||||Ascend910B,Ascend310P,Ascend310B真实仓库中的 elewise.csv 即采用「每个功能点一个正例 多个针对性反例」的组织方式例如ElewiseAdd正例行 22之后紧跟着ElewiseAddWrongDtype0/1输入 dtype 错误与ElewiseAddWrongFormat0/1输入 format 错误两个维度的反例每个反例均标注期望阶段前缀I:与错误码ERROR_INVALID_TENSOR_INI_MATCH同时通过SocVersion字段标注适用的芯片型号。这种「一正多反」的结构值得作为编写新算子用例的模板。编写 golden 函数每个算子需在 data_generation.py 中注册一个与算子同名的DataGen子类框架通过eval(data_generation. operation_name .golden)动态调用其golden静态方法计算 CPU 真值通过get_op_type静态方法告知框架该算子属于哪一类计算用于选择合适的精度判定标准class ElewiseOperation(DataGen): staticmethod def golden(in_tensors, op_params): # in_tensors: list[torch.Tensor]输入张量 # op_params: str从CSV的OpParam字段传入的JSON字符串 import json elewise_type json.loads(op_params)[elewiseType] if elewise_type 8: # ELEWISE_ADD return [in_tensors[0] in_tensors[1]] ... staticmethod def get_op_type(op_params): import json elewise_type json.loads(op_params)[elewiseType] if elewise_type in [8, 2, 3, 4, 5, 9, 10, 15]: # 浮点计算类 return OpTypes.COMPUTE_FLOAT ...OpTypes枚举决定了精度判定策略见 atb_csv_ops_test.py 与__precision_eb_percent例如COMPUTE_FLOAT/COMPUTE_FLOAT_HIGH_PRECISION/VECTOR_FUSION类算子计算前会把 FP16/BF16 提升到 FP32 再比较RAND类算子如采样类使用 scipy 的 KS 检验统计判断分布一致性CV_FUSION类如自注意力融合算子需要额外的 GPU golden 参考通过-gpu ip:port参数连接 RPC 服务端见 rpc_server_for_gpu_golden.py 与入口脚本中的RPCProxy获取 GPU 实现输出再以 MARE/MERE/RMSE/EB 等指标做相对误差比较。除golden与get_op_type外DataGen子类还可注册one/zero/random/customize等数据生成函数、load_tensor_from_file文件加载函数、case_preprocess/case_postprocess前后置钩子以及performance_threshold性能阈值函数框架均通过eval按名动态分发。用例设计原则覆盖所有支持的输入格式组合ND、NZ覆盖所有支持的数据类型float16、bf16、int8 等覆盖边界 shape对齐/非对齐、batch1/batch1包含参数校验反例验证错误码正确性反例的InNum/OutNum可为 0不需要构造张量SocVersion字段标注该用例适用的芯片型号如何运行 CSV 测试基本命令运行前需先编译测试框架参见上文「编译测试框架」。以下命令假设已执行source output/atb/set_env.sh。cd ascend-transformer-boost source output/atb/set_env.sh # 运行某个算子的全部用例 python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \ -i tests/apitest/opstest/csv/elewise.csv # 运行指定范围的用例1-based行号 python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \ -i tests/apitest/opstest/csv/elewise.csv -n 1:10 # 运行单个用例 python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \ -i tests/apitest/opstest/csv/elewise.csv -n 22-i参数既支持单个 CSV 文件也支持目录——传入目录时框架会遍历目录下所有*.csv文件依次执行见get_abs_path_files_from_dir。未指定-s时框架会自动通过torch.npu.get_device_name()探测本机芯片型号支持 Ascend910A/910B/310P/310B/950 等并据此过滤用例见get_device_properties。常用参数参数说明示例-i输入 CSV 文件或目录-i tests/apitest/opstest/csv/elewise.csv-n用例行号1-based单个或范围-n 22或-n 1:100表示全部-t执行次数性能测试用-t 100-ll日志级别-ll debug-op按算子名正则过滤-op ElewiseOperation-s指定芯片型号-s Ascend910B-tt按测试类型过滤-tt Function或-tt Performance-sv跳过精度验证-sv-o结果输出路径-o ./result.csv-f结果附加导出格式-f excel或-f html-tl按测试级别过滤-tl Level0-m按来源模型过滤-m LLaMA-65B-ws多卡测试卡数-ws 4-st保存张量数据到结果目录csvopstest/-st-ps精度判定标准版本-ps old或-ps new默认 new-gpuGPU golden RPC 服务地址-gpu 127.0.0.1:8888-ea全部用例跑完再退出-ea-nf不从 InTensorFile 加载输入-nf性能测试python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \ -i tests/apitest/opstest/csv/elewise.csv \ -tt Performance -t 400性能测试的执行语义与功能测试不同框架默认对 Performance 类型用例运行 400 次CsvOpsTestUtil.PERFORMANCE_RUNNING_TIMES并忽略前 200 次用于规避首次执行的初始化开销对剩余次数取 SetupTime/ExecuteTime/SyncTime/TotalTime 的平均值写入结果。此外若用例所在DataGen子类实现了performance_threshold函数框架会按阶段对耗时阈值做校验超时则判为不通过见__performance_check。多卡测试对于需要多卡的算子如 AllGather使用-ws指定卡数python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \ -i tests/apitest/opstest/csv/all_gather.csv -ws 4多卡执行通过torch.multiprocessing.spawn为每个 rank 启动独立进程每个进程通过torch_npu.npu.set_device(rank)绑定对应 NPU 设备并用sed将临时 CSV 副本中的rank/rankSize/rankRoot字段替换为当前进程的取值见main_worker。框架对单卡/多卡用例会自动分流AllGatherOperation、AllReduceOperation、BroadcastOperation、ReduceScatterOperation、LinearParallelOperation、AllToAllVOperation等通信类算子走多卡分支其余算子走单卡分支见need_to_run_caseOpParam中的rankSize必须与-ws一致否则该用例会被跳过。关于-n参数的注意事项-n匹配的是CSV 数据行号1-based不是CaseNum字段的值。删除中间用例后后续行号会前移建议通过实际文件行数确认目标用例。传入0表示运行全部用例。日志排查测试失败时可通过以下方式排查# 查看ATB运行日志 strings $ASCEND_PROCESS_LOG_PATH/atb/atb_*.log | grep -i error # 查看CANN底层错误 grep -a ERROR $ASCEND_PROCESS_LOG_PATH/debug/plog/plog-*.log此外-ll debug会打印每个阶段的 JSON 返回含 result、setup_time、workspace_size、execute_time、sync_time与精度对比明细-st可将每个用例的 input/golden/output/diff/tolerance 张量以.pt和.txt形式落盘到结果目录下的csvopstest/子目录便于离线分析。精度判定标准与结果输出两种精度标准旧标准-ps old按元素统计误差占比输出Error0.1‰、Error0.5‰、Error1‰、Error4‰、Error5‰、Error/-1六档指标每档表示在对应 atol/rtol 容差下的通过元素百分比。最终判定按数据类型取对应档位float16要求Error1‰ ≥ 99.9%bf16要求Error4‰ ≥ 99.6%int8要求Error/-1 ≥ 99.9%float/int32等要求Error0.1‰ ≥ 99.99%见CsvOpsResult.precision_standard。新标准-ps new默认框架按get_precision_and_eb_threshold返回的精度阈值precision_threshold与误差均衡阈值EB threshold逐元素判定输出PrecisionPercent精度达标百分比与EBPercent误差均衡百分比两列FP16/BF16 计算前会提升到 FP32 以消除低精度舍入影响。结果输出每轮执行后框架会生成*_csvopstest_result.csv结果文件在-o指定目录或输入文件同目录追加ActualError、Result、CasePassed、各阶段耗时与精度指标列-f excel/-f html可额外导出.xlsx/.html报告。结束时日志汇总Case pass result summary: Yes:x No:y并在有失败用例时列出失败的CaseNum。运行 C 单元测试C 单元测试基于 gtest用例以 C 编写位于 tests/unittest/、tests/cinterface/ 目录不依赖上文 CSV 测试框架及其 Python 运行依赖所需依赖由构建命令自动准备。测试通过以下命令构建并执行测试二进制由命令自动运行请勿手动直接执行命令构建并自动运行的测试对应二进制bash scripts/build.sh unittest内核接口测试、单元测试atb_cinterface、atb_unittestbash scripts/build.sh kernelunittest内核单元测试kernels_unittest命令执行时会自动完成运行测试所需的环境配置包括将 PyTorch 的 lib 目录加入LD_LIBRARY_PATH等无需手动设置。说明日常增量运行直接使用上述命令即可无需加--clean-first仅在 CMake 配置变更或 ABI 变化时才需要首次执行上述命令完成测试二进制atb_cinterface、atb_unittest或kernels_unittest的构建与安装后后续仅需运行测试时可追加--skip_build跳过编译bash scripts/build.sh unittest --skip_build bash scripts/build.sh kernelunittest --skip_build从目录组织看atb_unittest的用例覆盖 tests/unittest/core框架核心功能、tests/unittest/normal常规功能与 tests/unittest/ops算子三类kernels_unittest则对应 tests/unittest/kernels聚焦内核实现层面的单元测试。附录Python 测试方式非 CSV对于不适合 CSV 格式的复杂场景如需要动态构造张量、编写循环逻辑或依赖外部计算图的用例可直接编写 Python 测试类继承tests/apitest/opstest/python/operations/下的测试基类operation_test.py。以下以逐元素加法为例import sys import os import unittest import torch import torch_npu sys.path.append(os.path.join(os.path.dirname(__file__), ../)) import operation_test # NOQA: E402 OP_NAME ElewiseOperation class TestElewiseAdd(operation_test.OperationTest): def golden_calc(self, in_tensors): return [in_tensors[0] in_tensors[1]] def test_2d_half(self): self.execute(OP_NAME, {elewiseType: 8}, [torch.randn( 1024, 1024).npu().half(), torch.randn(1024, 1024).npu().half()]) def test_broadcast_half(self): self.execute(OP_NAME, {elewiseType: 8}, [torch.randn( 1024, 1024).npu().half(), torch.randn(1024).npu().half()]) if __name__ __main__: unittest.main()执行运行前需先编译测试框架参见上文「编译测试框架」# 将上述代码保存为 tests/apitest/opstest/python/operations/my_elewise_op/test_my_op.py然后运行 source output/atb/set_env.sh python tests/apitest/opstest/python/operations/my_elewise_op/test_my_op.py这种方式的execute内部同样经由OperationTorch完成 set_param → infer_shape → setup → execute_sync 的完整调用链因此与 CSV 测试共享同一套 C 桥接层与底层算子实现只是用例编写方式从声明式 CSV 换成了命令式 Python。总结ATB 测试框架通过「CSV 声明用例 Python 数据生成与 golden 计算 C OperationTorch 桥接」的分层设计将算子测试的输入构造、执行编排、精度判定与性能统计标准化、自动化。编写新算子用例时推荐遵循「一正多反」的 CSV 组织模式并补齐 golden/get_op_type 注册即可同时获得功能、错误码、精度与性能四方面的自动化验证能力。【免费下载链接】ascend-transformer-boost本项目是CANN提供的是一款高效、可靠的Transformer加速库基于华为Ascend AI处理器提供Transformer定制化场景的高性能融合算子。项目地址: https://gitcode.com/cann/ascend-transformer-boost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考