MindStudio Kernel Launcher API接口文档¶

接口列表¶

msKL工具提供的接口可以调用msOpGen工程中的tiling函数以及用户自定义的Kernel函数，同时提供了autotune系列接口支持开发者可以高效地针对多个调优点进行代码替换、编译、运行以及性能对比。

表 1 msKL工具接口列表

分类	接口	简介
调用msOpGen工程	tiling_func	调用用户的tiling函数。
调用msOpGen工程	get_kernel_from_binary	生成一个可以调用用户Kernel函数的实例。
自动调优	autotune	遍历搜索空间，尝试不同参数组合，展示每个组合的运行耗时与最优组合。
	code_gen	根据输入的模板库Kernel信息，生成Kernel下发代码。
	compile	编译Kernel下发代码，返回一个可执行的Kernel对象。
	autotune_v2	遍历搜索空间，尝试不同参数组合，展示每个组合的运行耗时与最优组合。
	compile_executable	编译代码，返回一个可执行的executable对象。

接口详情¶

tiling_func¶

功能说明

调用用户的tiling函数。

[!NOTE]
tiling_func不支持调用《基础数据结构和接口参考》中的GetCompileInfo接口。

函数原型

def tiling_func(op_type: str, inputs: list, outputs: list, lib_path: str,
                inputs_info: list = None, outputs_info: list = None, attr=None, soc_version: str = None) -> TilingOutput

参数说明

参数名	输入/输出	是否必选	说明
op_type	输入	必选参数。	需根据tiling函数的实现填写，例如AddCustom、 MatmulLeakyreluCustom等。msKL工具查找tiling函数的唯一依据，查找逻辑请参见lib_path参数。数据类型：str。说明：若CANN中曾经部署过相同类型的算子（op_type），用户修改了tiling函数并重新编译，则需要在CANN环境中重新部署该算子。
inputs	输入	可选参数。	按Kernel函数入参顺序填入tensor信息，不使用某个参数的情况，对应位置请传入None占位。数据类型为list，每个元素必须是tensor或者list[tensor]，不在inputs_info中显式指定format或者ori_format时，所有tensor默认为ND格式。
outputs	输入	可选参数。	按Kernel函数入参顺序填入tensor信息，不使用某个参数的情况，对应位置请传入None占位。数据类型：list，每个元素必须是tensor或者list[tensor]，不在inputs_info中显式指定format或者ori_format时，所有tensor默认为ND格式。
inputs_info	输入	可选参数。	按Kernel函数入参顺序填写info信息，不使用某个参数的情况，对应位置请传入空dict或者None占位。数据类型为list，inputs_info参数中元素的数据类型为dict或list[dict]，每个dict的元素说明如下： ori_shape：输入tensor的原始维度信息。 shape：输入tensor运行时的维度信息。 dtype：输入tensor的数据类型，具体请参见《TBE&AI CPU算子开发接口》的“AI CPU API > 数据类型描述 > DataType”。 ori_format：输入tensor的原始数据排布格式，默认为ND，具体请参见《TBE&AI CPU算子开发接口》的“AI CPU API > 数据类型描述 > Format”。 format：输入tensor的数据排布格式，默认为ND，具体请参见《TBE&AI CPU算子开发接口》的“AI CPU API > 数据类型描述 > Format”。 data_path：值依赖场景下，输入tensor的bin文件路径。举例如下： [{"ori_shape": [8, 2048], "shape": [8, 2048], "dtype": "float16", "ori_format": "ND", "format": "ND"}, {"ori_shape": [8, 2048], "shape": [8, 2048], "dtype": "float16", "ori_format": "ND", "format": "ND"}] 说明：该输入参数和inputs存在约束关系： inputs为tensor时，inputs_info必须是dict。 inputs为list[tensor]时，inputs_info必须是list[dict]。 inputs为None时，inputs_info每个元素至少包含[shape, dtype]。
outputs_info	输入	可选参数。	存放输出的信息，不使用某个参数的情况，对应位置请传入空dict占位。数据类型为list，outputs_info参数中元素的数据类型为dict或list[dict]，每个dict的元素说明如下： ori_shape：输出tensor的原始维度信息。 shape：输出tensor的维度信息。 dtype：输出tensor的数据类型，具体请参见《TBE&AI CPU算子开发接口》的“AI CPU API > 数据类型描述 > DataType”。 ori_format：输出tensor的原始数据排布格式，默认为ND，具体请参见《TBE&AI CPU算子开发接口》的“AI CPU API > 数据类型描述 > Format”。 format：输出tensor的数据排布格式，默认为ND，具体请参见《TBE&AI CPU算子开发接口》的“AI CPU API > 数据类型描述 > Format”。 data_path：保留参数，不生效。举例如下： [{"shape": [8, 2048], "dtype": "float16", "format": "ND"}, {"shape": [8, 2048], "dtype": "float16", "format": "ND"}] 说明：该输入参数和inputs存在约束关系： outputs为tensor时，outputs_info必须是dict。 outputs为list[tensor]时，outputs_info必须是list[dict]。 outputs为None时，outputs_info每个元素至少包含[shape, dtype]。
attr	输入	可选参数。	tiling函数使用到的算子属性。数据类型：dict或者list。说明： dict格式键值只能包含大小写英文字母、数字、下划线。 { "a1": 1, "a2": False, "a3": "ssss", "a4": 1.2, "a5": [111, 222, 333], "a6": [111.111, 111.222, 111.333], "a7": [True, False], "a8": ["asdf", "zxcv"], "a9": [[1, 2, 3, 4], [5, 6, 7, 8], [5646, 2345]], } list格式，推荐使用。若某个attr需要传空列表时，必须用这种格式（例如下面的"a10"）。 "name"和"value"的值只能包含大小写英文字母、数字、下划线。 "dtype"：输入tensor的数据类型。 [ {"name": "a1", "dtype": "int", "value": 1}, {"name": "a2", "dtype": "bool", "value": False}, {"name": "a3", "dtype": "str", "value": "ssss"}, {"name": "a4", "dtype": "float", "value": 1.2}, {"name": "a5", "dtype": "list_float", "value": [111.111, 111.222, 111.333]}, {"name": "a6", "dtype": "list_bool", "value": [True, False]}, {"name": "a7", "dtype": "list_str", "value": ["asdf", "zxcv"]}, {"name": "a8", "dtype": "list_list_int", "value": [[1, 2, 3, 4], [5, 6, 7, 8], [5646, 2345]]}, {"name": "a9", "dtype": "list_int", "value": [111, 222, 333]}, {"name": "a10", "dtype": "list_int", "value": []}, {"name": "a11", "dtype": "int64", "value": 2}, {"name": "a12", "dtype": "float32", "value": 1.3}, {"name": "a13", "dtype": "string", "value": "ssss"}, {"name": "a14", "dtype": "list_string", "value": ["asdf", "zxcv"]}, ]
lib_path	输入	可选参数。	msOpGen工程编译生成的liboptiling.so文件的路径，可在工程目录下通过find . -name 'liboptiling.so'进行查找。msKL工具会按已部署算子、.so文件的查找顺序获取用户tiling函数。数据类型：str。
soc_version	输入	可选参数。	配置为昇腾AI处理器的类型。说明：非 Atlas A3 训练系列产品/Atlas A3 推理系列产品：在安装昇腾AI处理器的服务器执行npu-smi info命令进行查询，获取Chip Name信息。实际配置值为AscendChip Name，例如Chip Name取值为xxxyy，实际配置值为Ascend xxxyy。当Ascendxxxyy为代码样例的路径时，需要配置为ascend xxxyy。 Atlas A3 训练系列产品/Atlas A3 推理系列产品：在安装昇腾AI处理器的服务器执行npu-smi info -t board -i id -c chip_id命令进行查询，获取Chip Name和NPU Name信息，实际配置值为Chip Name_NPU Name。例如Chip Name取值为Ascend xxx，NPU Name取值为1234，实际配置值为Ascend xxx _1234。当Ascend xxx _1234为代码样例的路径时，需要配置为ascend xxx _1234。其中： id：设备id，通过npu-smi info -l命令查出的NPU ID即为设备id。 chip_id：芯片id，通过npu-smi info -m命令查出的Chip ID即为芯片id。

返回值说明

参数名	说明
blockdim	用户tiling函数配置的核数。数据类型：int。
workspace_size	该值为用户自行申请的workspace大小加上 msKL工具预留的78,643,200Byte。数据类型：int。
workspace	msKL工具为用户申请的workspace空间，大小为workspace_size。数据类型：numpy.array。
tiling_data	存放tiling_data，用于调用Kernel函数。数据类型：numpy.array。
tiling_key	用户tiling函数配置的tiling_key，若用户未设置，msKL工具会默认设置为0。数据类型：int。

调用示例

M = 1024
N = 640
K = 256
input_a = np.random.randint(1, 10, [M, K]).astype(np.float16)
input_b = np.random.randint(1, 10, [K, N]).astype(np.float16)
input_bias = np.random.randint(1, 10, [N]).astype(np.float32)
output = np.zeros([M, N]).astype(np.float32)
# tiling data
tiling_output = mskl.tiling_func(
    op_type="MatmulLeakyreluCustom",
    inputs=[input_a, input_b, input_bias], outputs=[output],
    lib_path="liboptiling.so",  # tiling代码编译产物 
)

get_kernel_from_binary¶

功能说明

生成一个可以调用用户Kernel函数的实例。

函数原型

def get_kernel_from_binary(kernel_binary_file: str, kernel_type: str = None, tiling_key: int = None) -> CompiledKernel

参数说明

参数名

输入/输出

是否必选

说明

kernel_binary_file

输入

必选参数。

算子kernel.o路径，可以在工程目录下执行find . -name '*.o'命令进行查找。

数据类型：str。

kernel_type

输入

可选参数。

算子类型。可设置为vec、 cube或mix。

若不配置该参数，msKL工具可能会获取失败。因此，建议手动赋值。

数据类型：str。

tiling_key

输入

可选参数。

调用用户Kernel函数时使用的tiling_key。若不配置该参数，msKL工具将会使用最近一次调用tiling_func的结果。

数据类型：int。

返回值说明

可运行的Kernel对象。

表 1 Kernel入参介绍

参数名	输入/输出	说明
device_id	输入	NPU设备ID，设置运行ST测试用例的昇腾AI处理器的ID。数据类型：int。若未设置此参数，默认为0。
timeout	输入	camodel仿真场景需要默认设置较长超时时间，设置为-1时表示不限制。数据类型：int。单位: ms，默认值为300000。
repeat	输入	重复运行次数，默认值为1。数据类型：int。
stream	输入	预留参数。
kernel_name	输入	预留参数。

[!NOTE]
Kernel对象类型为CompiledKernel，支持如下方式调用Kernel：kernelblockdim，实际调用时，需保证CompiledKernel函数的入参和调用Kernel时的入参一致。

调用示例

示例一：

def run_kernel(input_a, input_b, input_bias, output, workspace, tiling_data):
    kernel_binary_file = "MatmulLeakyreluCustom.o"   #不同的硬件和操作系统展示的.o文件的名称稍有不同
    kernel = get_kernel_from_binary(kernel_binary_file)
    return kernel(input_a, input_b, input_bias, output, workspace, tiling_data)

示例二：

def run_kernel(input_a, input_b, input_bias, output, workspace, tiling_data, tiling_key, blockdim):
    kernel_binary_file = "MatmulLeakyreluCustom.o"    #不同的硬件和操作系统展示的.o文件的名称稍有不同
    kernel = get_kernel_from_binary(kernel_binary_file, kernel_type='mix', tiling_key=tiling_key)
    return kernel[blockdim](input_a, input_b, input_bias, output, workspace, tiling_data, device_id=1, timeout=-1) #运行仿真时，需要手动将timeout参数设置为-1

autotune¶

功能说明

遍历搜索空间，尝试不同参数组合，展示每个组合的运行耗时与最优组合。

函数原型

def autotune(configs: List[Dict], warmup: int = 300, repeat: int = 1, device_ids = [0]):

参数说明

参数名	输入/输出	是否必选	说明
configs	输入	必选参数。	搜索空间定义。数据类型：list[dict]。
warmup	输入	可选参数。	采集性能前的设备预热时间。通常情况下，预热时间越长，采集到的算子性能越稳定。单位：微秒。默认值：1000，取值范围为1~100000之间的整数。
repeat	输入	可选参数。	重放次数，会根据多次重放取运行耗时的平均值作为算子耗时。默认值：1，取值范围为1~10000之间的整数。
device_ids	输入	可选参数。	Device ID列表，目前仅支持单Device模式，如果填写多个Device ID，只有第一个会生效。默认值：[0]。

返回值说明

无。

调用示例

@mskl.autotune(configs=[
    {'L1TileShape': 'MatmulShape<64, 64, 64>', 'L0TileShape': 'MatmulShape<128, 256, 64>'},
    {'L1TileShape': 'MatmulShape<64, 64, 128>', 'L0TileShape': 'MatmulShape<128, 256, 64>'},
    {'L1TileShape': 'MatmulShape<64, 128, 128>', 'L0TileShape': 'MatmulShape<128, 256, 64>'},
    {'L1TileShape': 'MatmulShape<64, 128, 128>', 'L0TileShape': 'MatmulShape<64, 256, 64>'},
    {'L1TileShape': 'MatmulShape<128, 128, 128>', 'L0TileShape': 'MatmulShape<128, 256, 64>'},
], warmup=500, repeat=10, device_ids=[0])
def basic_matmul(problem_shape, a, layout_a, b, layout_b, c, layout_c):
    kernel = get_kernel()
    blockdim = 20
    return kernel[blockdim](problem_shape, a, layout_a, b, layout_b, c, layout_c)

code_gen¶

功能说明

根据输入的模板库Kernel信息，生成Kernel下发代码。

函数原型

gen_file = mskl.Launcher(config).code_gen()

参数说明

参数名

输入/输出

是否必选

说明

gen_file

输入

可选参数。

指定生成Kernel侧下发代码的文件路径。

数据类型：str。

默认值为_gen_launch.cpp。

返回值说明

生成代码的文件路径。

调用示例

config = mskl.KernelInvokeConfig(kernel_file, kernel_name) 
gen_file = mskl.Launcher(config).code_gen()

相关类/结构体定义

class KernelInvokeConfig:
    ...
    A configuration descriptor for a possible kernel developed based on an Act example
    ...
    def __init__(self, kernel_src_file : str, kernel_name : str):
        pass
# 用户仅能传KernelInvokeConfig类型
class Launcher:
    def __init__(self, config: KernelInvokeConfig): 
      ...
        a class that generates launch source code for a kernel

        Args:
            config (KernelInvokeConfig): A configuration descriptor for a kernel
        ...

compile¶

功能说明

编译Kernel下发代码，返回一个可执行的Kernel对象。

函数原型

kernel = compile(build_script, gen_file)

参数说明

参数名	输入/输出	是否必选	说明
build_script	输入	必选参数。	用于模板库Kernel编译的脚本。数据类型：str。
gen_file	输入	必选参数。	由code_gen接口生成的Kernel下发代码文件路径，一般直接使用code_gen接口返回值。数据类型：str。
output_bin_path	输入	可选参数。	指定编译生成的可执行文件路径。数据类型：str。默认值：_gen_module.so。
use_cache	输入	可选参数。	开启后不执行编译，加载output_bin_path所指定的文件。数据类型：bool。默认值：False。

返回值说明

可运行的Kernel对象，类型：CompiledKernel，支持如下方式调用kernel：kernelblockdim，其中arg1、arg2、...是Kernel的入参。

调用示例

kernel = compile(build_script, gen_file)
kernel[blockdim](arg1, arg2, ..., device_id=0)

表 1 CompiledKernel可选入参介绍

参数名	输入/输出	说明
device_id	输入	NPU设备ID，设置运行ST测试用例的昇腾AI处理器的ID。数据类型：int。若未设置此参数，默认为0。
timeout	输入	camodel仿真场景需要默认设置较长超时时间，设置为-1时表示不限制。数据类型：int。单位: ms，默认值为300000。
repeat	输入	重复运行次数，默认值为1。数据类型：int。
stream	输入	预留参数。
kernel_name	输入	预留参数。

autotune_v2¶

功能说明

遍历搜索空间，尝试不同参数组合，展示每个组合的运行耗时与最优组合。

函数原型

def autotune_v2(configs: List[Dict], warmup_times = 5)

参数说明

参数名

输入/输出

是否必选

说明

configs

输入

必选参数。

搜索空间定义。

数据类型：list[dict]。

warmup_times

输入

可选参数。

采集性能前的设备预热次数。

默认值：5，取值范围为1~500之间的整数。

返回值说明

无。

调用示例

@mskl.autotune_v2(configs=[
    {'L1TileShape': 'GemmShape<128, 256, 256>', 'L0TileShape': 'GemmShape<128, 256, 64>'},
    {'L1TileShape': 'GemmShape<256, 128, 256>', 'L0TileShape': 'GemmShape<256, 128, 64>'},
    {'L1TileShape': 'GemmShape<128, 128, 256>', 'L0TileShape': 'GemmShape<128, 128, 64>'},
    {'L1TileShape': 'GemmShape<128, 128, 512>', 'L0TileShape': 'GemmShape<128, 128, 64>'},
    {'L1TileShape': 'GemmShape<64, 256, 128>', 'L0TileShape': 'GemmShape<64, 256, 64>'},
], warmup_times=10)
def run_executable(m, n, k, device_id):
    src_file = "./basic_matmul.cpp"
    build_script = "./jit_build_executable.sh" # executable compile script
    executable = mskl.compile_executable(build_script=build_script, src_file=src_file, use_cache=False)
    return executable(m, n, k, device_id)

compile_executable¶

功能说明

编译代码，返回一个可执行的executable对象。

函数原型

executable = compile_executable(build_script, src_file)

参数说明

参数名	输入/输出	是否必选	说明
build_script	输入	必选参数。	用于编译被调优应用的脚本文件路径。数据类型：str。
src_file	输入	必选参数。	代码文件路径。数据类型：str。
output_bin_path	输入	可选参数。	指定编译生成的可执行文件路径。数据类型：str。默认值：_gen_executable。
use_cache	输入	可选参数。	开启后不执行编译，加载output_bin_path所指定的文件。数据类型：bool。默认值：False。注意：当使用msDebug工具拉起compile接口时，需配置use_cache=True。
profiling_cmd	输入	-	预留参数。

返回值说明

可执行程序对象executable，类型：CompiledExecutable，支持如下方式调用：executable(arg1, arg2, ...)，其中arg1、arg2、...是程序自定义入参。

调用示例

executable = compile_executable(build_script, src_file)
executable(a, b, c)