简介

CANN开发套件包中提供了ST测试工具：msopst，用于生成算子的ST测试用例并在硬件环境中执行。该工具的存放路径在CANN软件安装后文件存储路径中的“python/site-packages/bin”，详细使用可参考msopst工具使用。

具体功能如下：

根据算子测试用例定义文件生成ST测试数据及测试用例执行代码，在硬件环境上执行算子测试用例。
自动生成运行报表（st_report.json）功能，报表记录了测试用例信息及各阶段运行情况。
根据用户定义并配置的算子期望数据生成函数，回显期望算子输出和实际算子输出的对比测试结果。

使用此工具生成算子测试用例前，需要将要测试的算子部署到当前环境中。

执行ST测试用例

获取待测试host侧算子的实现文件（.cpp文件），具体路径可参考步骤3。
进入msopst工具所在目录，执行如下命令生成算子测试用例定义文件，参数说明请参见表1。
```
./msopst create -i Op_implementation/add_custom.cpp -out ./output
```
请将Op_implementation更换为host侧算子的实现文件所在路径。

命令执行成功后，会在当前路径的output目录下生成算子测试用例定义文件：AddCustom_case_timestamp.json。

修改测试用例定义模板文件“AddCustom_case_timestamp.json”。

步骤2生成的json文件为模板文件，不满足直接作为ST测试用例生成输入的要求，所以用户需要参考此步骤，修改算子测试用例定义文件（*.json），构造测试用例，以满足ST测试覆盖的范围。“*.json”文件支持的全量字段说明参见表2。不同场景下的测试用例定义文件的样例可参见测试用例定义文件配置样例。

[
    {
        "case_name": "Test_AddCustom_001",    
        "op": "AddCustom",      
        "input_desc": [       
            {
                "format": [      
                    "ND"
                ],
                "type": [      
                    "float16"
                ],
                "shape": [16],      
                "data_distribute": [      
                    "uniform"
                ],
                "value_range": [       
                    [
                        0.1,
                        1.0
                    ]
                ],
                "name": "x"
            },
            {           
                "format": [
                    "ND"
                ],
                "type": [
                    "float16"
                ],
                "shape": [16],       
                "data_distribute": [
                    "uniform"
                ],
                "value_range": [
                    [
                        0.1,
                        1.0
                    ]
                ],
                "name": "y"
            }
        ],
        "output_desc": [       
            {
                "format": [
                    "ND"
                ],
                "type": [
                    "float16"
                ],
                "shape": [16],
                "name": "z"
            }
        ]
    }
]

（可选）如果您需要得到实际算子输出与期望输出的比对结果，需要参考此步骤自定义期望数据生成函数。
1. 自定义实现add算子期望数据生成函数。
  在Python文件中实现算子期望数据生成函数，文件目录和文件名称可自定义，如“/home/test/test_add_st.py”。
  
  例如Add算子的期望数据生成函数实现如下：
```
def calc_expect_func(x1, x2, y):    
    res = x1["value"] + x2["value"]
    return [res, ]
```
  用户需根据开发的自定义算子完成算子期望数据生成函数。测试用例定义文件中的全部Input、Output、Attr的name作为算子期望数据生成函数的输入参数，若Input是可选输入，请将该输入指定默认值传参。
  
  例如，某算子输入中的x3为可选输入时，定义该算子的期望数据生成函数如下。
```
def calc_expect_func(x1, x2, x3=None, y=None)
```
2. 在ST测试用例定义文件“OpType_xx.json”中增加比对函数。配置算子测试用例定义文件。
  在步骤2中的算子测试用例定义文件AddCustom_case_timestamp.json增加"calc_expect_func_file"参数，参数值为"/home/test/test_add_st.py:calc_expect_func"。
```
[
    {
        "case_name":"Test_AddCustom_001",         
        "op": "AddCustom",                             
        "calc_expect_func_file": "/home/test/test_add_st.py:calc_expect_func",   //配置生成算子期望输出数据的实现文件
        "input_desc": [...]
        ...
        ...
    }
]
```
ST测试用例执行时，会使用AscendCL接口加载单算子模型文件并执行，所以需要配置AscendCL应用编译所需其他环境变量，如下所示。
```
export DDK_PATH=${INSTALL_DIR}
export NPU_HOST_LIB=${INSTALL_DIR}/{arch-os}/devlib
```
- ${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。例如，若安装的Ascend-cann-toolkit软件包，则安装后文件存储路径为：$HOME/Ascend/ascend-toolkit/latest。
- {arch-os}中arch表示操作系统架构，os表示操作系统。
进入msopst工具所在目录，执行如下命令生成/执行测试用例。
```
./msopst run -i xx/AddCustom_case_timestamp.json -soc <soc_version> -out ./output -c Test_AddCustom_001 -d {device id} -conf {msopst.ini path} -err_thr "[0.01,0.05]"
```
参数说明如下，更详细的参数说明请参考表1：
- run（必选）：用于执行算子的ST测试用例。
- -i，--input（必选）：算子测试用例定义文件（*.json）的路径，可配置为绝对路径或者相对路径。
- -soc，--soc_version（必选）：昇腾AI处理器的型号，请根据实际环境进行替换。
  
  如果无法确定具体的<soc_version>，则在安装昇腾AI处理器的服务器执行npu-smi info命令进行查询，在查询到的“Name”前增加Ascend信息，例如“Name”对应取值为xxxyy，实际配置的<soc_version>值为Ascendxxxyy。
- -out，--output（可选）：生成文件所在路径。
- -c，--case_name（可选）：需要执行的case的名字。
- -d，--device_id（可选）：NPU设备ID，设置运行ST测试用例的昇腾AI处理器的ID。
- -err_thr，--error_threshold（可选）：配置自定义精度标准。
- -conf，--config_file（可选）：ST测试高级功能配置文件（msopst.ini）存储路径。
查看执行结果。
命令运行成功后会生成报表st_report.json，如图1保存在“The st_report saved in”路径下，记录了测试的信息以及各阶段运行情况。

同时，st_report.json报表可以对比测试结果，如果用户运行出问题，也可基于报表查询运行信息，以便问题定位。

图1 运行结果示例

算子ST测试

简介

执行ST测试用例