ATB测试框架使用指南-CSDN博客

测试框架指南

【免费下载链接】ascend-transformer-boost 本项目是CANN提供的是一款高效、可靠的Transformer加速库，基于华为Ascend AI处理器，提供Transformer定制化场景的高性能融合算子。项目地址: https://gitcode.com/cann/ascend-transformer-boost

概述

ATB测试框架是一套数据驱动的算子测试系统，支持通过CSV文件声明式定义测试用例，自动完成张量生成、算子执行、golden对比和精度/性能验证。框架分为两层：

Python层（CsvOpsTestTool）：CSV驱动的测试入口，负责用例解析、数据生成、结果验证
C++层（atb_torch）：PyTorch自定义类，桥接ATB算子与PyTorch张量，供Python层调用

环境依赖

编译依赖

以下依赖在编译测试框架（bash scripts/build.sh testframework）时必须存在，提供头文件和链接库：

依赖	用途	验证命令
CANN toolkit	ATB编译基础	`echo $ASCEND_HOME_PATH`
PyTorch	C++层编译链接`torch/script.h`等头文件及`libtorch.so`	`python3 -c "import torch; print(torch.__file__)"`
torch_npu	C++层编译链接`torch_npu`头文件及`libtorch_npu.so`	`pip show torch-npu`

PyTorch及torch_npu的安装请参考昇腾PyTorch安装指南。

运行依赖

运行CSV测试时需要以下Python库（PyTorch和torch_npu同时也是编译依赖）：

依赖	用途	验证命令
PyTorch	张量创建、golden计算、算子调用	`python3 -c "import torch"`
torch_npu	NPU设备访问	`python3 -c "import torch_npu"`
pandas	CSV解析	`python3 -c "import pandas"`
numpy	数据生成与golden计算	`python3 -c "import numpy"`
ml_dtypes	BF16等自定义数据类型支持	`python3 -c "import ml_dtypes"`
en_dtypes	hifloat8数据类型支持	`python3 -c "from en_dtypes import hifloat8"`
openpyxl	Excel格式输出支持	`python3 -c "import openpyxl"`
scipy	golden计算中的科学计算	`python3 -c "import scipy"`

其他Python三方库依赖见tests/framework/python/CsvOpsTestTool/requirements.txt。

CXX ABI版本确定

testframework编译产物路径依赖正确的ABI版本（cxx_abi_0或cxx_abi_1），判断方法：

python3 -c "import torch; print(torch.compiled_with_cxx11_abi())"

输出True或torch未安装 → 使用--cxx_abi=1（--use_cxx11_abi=1）
输出False → 使用--cxx_abi=0（--use_cxx11_abi=0）

常见编译失败

错误信息	原因	解决方法
`torch/script.h: No such file or directory`	环境中未安装PyTorch	安装PyTorch：`pip install torch`
`torch_npu/csrc/core/npu/NPUStream.h: No such file`	环境中未安装torch_npu	安装torch_npu
`libatb.so: undefined reference`	ABI版本不匹配	确认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无法自动检测内核文件变更。

编译产物

编译完成后，关键产物位于：

路径	说明
`output/atb/cxx_abi_{0\\|1}/lib/libatb.so`	ATB核心库
`output/atb/cxx_abi_{0\\|1}/lib/libatb_test_framework.so`	测试框架动态库（含OperationTorch）
`tests/framework/python/CsvOpsTestTool/`	Python测试工具（安装到output）

如何编写测试用例

CSV用例格式

测试用例以CSV文件形式存放在tests/apitest/opstest/csv/目录下，以|作为分隔符。

表头字段说明

字段	说明	示例
CaseNum	用例编号	`1`
CaseName	用例名称	`MatmulElewiseAdd`
OpName	算子名称	`LinearOperation`
OpParam	算子参数（JSON）	`{"transposeA":true}`
InNum	输入张量数量	`3`
InDType	输入数据类型（`;`分隔）	`float16;float16;float16`
InFormat	输入格式（`;`分隔）	`nd;nd;nd`
InShape	输入形状（`;`分隔，维度用`,`）	`2,3;4,3;4`
OutNum	输出张量数量	`1`
OutDType	输出数据类型	`float16`
OutFormat	输出格式	`nd`
OutShape	输出形状	`2,4`
DataGenType	数据生成方式	`customize;customize;customize`
DataGenRange	数据范围	`-2,2;-2,2;-2,2`
InTensorFile	输入张量文件路径（可选）	空
OutTensorFile	输出张量文件路径（可选）	空
TestType	测试类型（可选）	`Function`或`Performance`
TestLevel	测试级别（可选）	`Level0`/`Level1`/`Level2`
FromModel	来源模型（可选）	`LLaMA-65B`
SocVersion	支持的芯片型号	`Ascend910B,Ascend310P`
ExpectedError	期望的错误码	`NO_ERROR`或错误码

数据类型枚举

值	含义
`float16`	FP16
`bf16`	BF16
`float`	FP32
`int8`	INT8
`int32`	INT32
`int64`	INT64
`uint64`	UINT64

格式枚举

值	含义
`nd`	N维通用格式
`fractal_nz`	华为NZ分形格式

错误码格式

格式为阶段前缀:错误码：

前缀	阶段	示例
`C:`	CreateOperation（创建算子）	`C:ERROR_INVALID_PARAM`
`I:`	InferShape（维度推导）	`I:ERROR_INVALID_TENSOR_DIM_NUM`
`S:`	Setup（CANN调用）	`S:ERROR_CANN_ERROR`
无前缀	正例	`NO_ERROR`

用例示例

正例（基本矩阵乘）

1|MatmulElewiseAdd|LinearOperation|{}|3|float16;float16;float16|nd;nd;nd|2,3;4,3;4|1|float16|nd|2,4|customize;customize;customize|-2,2;-2,2;-2,2||||||Ascend910B,Ascend310P|NO_ERROR

正例（带转置参数）

23|MatmulTransposeA|LinearOperation|{"transposeA":true,"transposeB":false}|3|float16;float16;float16|nd;nd;nd|3,2;3,4;1,4|1|float16|nd|2,4|customize;customize;customize|-2,2;-2,2;-2,2||||||Ascend910B,Ascend310P|NO_ERROR

反例（参数校验错误）

146|MatmulCError|LinearOperation|{"hasBias":false,"enAccum":true}|0||||0|||||||||||Ascend310P|C:ERROR_INVALID_PARAM

编写golden函数

每个算子需在tests/framework/python/CsvOpsTestTool/data_generation.py中注册golden函数：

class LinearOperation(DataGen):
    @staticmethod
    def golden(in_tensors, op_params):
        # in_tensors: list[torch.Tensor]，输入张量
        # op_params: dict，从CSV的OpParam字段解析
        input_data = in_tensors[0]
        weight = in_tensors[1]
        bias = in_tensors[2] if len(in_tensors) > 2 else None

        result = torch.matmul(input_data, weight.T)
        if bias is not None:
            result = result + bias
        return [result]

    @staticmethod
    def get_op_type(op_params):
        return OpTypes.COMPUTE_FLOAT

用例设计原则

覆盖所有支持的输入格式组合（ND、NZ）
覆盖所有支持的数据类型（float16、bf16、int8等）
覆盖边界shape（对齐/非对齐、batch=1/batch>1）
包含参数校验反例，验证错误码正确性
反例的InNum/OutNum可为0（不需要构造张量）
SocVersion字段标注该用例适用的芯片型号

如何运行测试

基本命令

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/linear.csv

# 运行指定范围的用例（1-based行号）
python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \
    -i tests/apitest/opstest/csv/linear.csv -n 1:10

# 运行单个用例
python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \
    -i tests/apitest/opstest/csv/linear.csv -n 5

常用参数

参数	说明	示例
`-i`	输入CSV文件或目录	`-i tests/apitest/opstest/csv/linear.csv`
`-n`	用例行号（1-based，单个或范围）	`-n 5` 或 `-n 1:10`，`0`表示全部
`-t`	执行次数（性能测试用）	`-t 100`
`-ll`	日志级别	`-ll debug`
`-op`	按算子名正则过滤	`-op LinearOperation`
`-s`	指定芯片型号	`-s Ascend910B`
`-tt`	按测试类型过滤	`-tt Function` 或 `-tt Performance`
`-sv`	跳过精度验证	`-sv`
`-o`	结果输出路径	`-o ./result.csv`

性能测试

python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \
    -i tests/apitest/opstest/csv/linear.csv \
    -tt Performance -t 400

多卡测试

对于需要多卡的算子（如AllGather），使用-ws指定卡数：

python tests/framework/python/CsvOpsTestTool/atb_csv_ops_test.py \
    -i tests/apitest/opstest/csv/all_gather.csv -ws 4

关于`-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

附录：Python测试方式（非CSV）

对于不适合CSV格式的复杂场景，可直接编写Python测试类：

import unittest
from tests.framework.python import op_test

class TestMyOp(op_test.OpTest):
    def golden_calc(self, in_tensors):
        # 计算预期结果
        return [expected_output]

    def golden_compare(self, out_tensors, golden_out_tensors):
        return torch.allclose(out_tensors[0].float(),
                              golden_out_tensors[0].float(),
                              rtol=0.001, atol=0.001)

    def test_case1(self):
        in_tensors = [torch.randn(2, 3).to(torch.float16)]
        out_tensors = [torch.zeros(2, 3).to(torch.float16)]
        self.set_param("MyOperation", {"param1": 1})
        self.execute(in_tensors, out_tensors)

if __name__ == '__main__':
    unittest.main()

执行：

python tests/apitest/kernelstest/mix/test_my_op.py

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ATB测试框架使用指南