TBE算子信息库

配置说明

算子开发者需要通过配置算子信息库文件，将算子在昇腾AI处理器上相关实现信息注册到算子信息库中。

算子信息库文件路径：自定义算子工程目录下的tbe/op_info_cfg/ai_core/${soc_version}/xx.ini。

${soc_version}：请配置为用户当前实际使用的昇腾AI处理器的型号。

昇腾AI处理器的型号可通过如下方式查看：

单击如下手册中的链接并进入该手册，《ToolBox 用户指南》。
完成“使用前准备”，然后进入“ascend-dmi工具使用>设备实时状态查询”章节。
使用相关命令查看芯片的详细信息，例如使用ascend-dmi -i -dt命令查看芯片的详细信息，返回信息中“Chip Name”对应取值（将大写字母转换为小写，并去掉中间空格）即为具体使用的${soc_version}。

配置规则请参见表1。需要注意，算子输入参数的顺序与个数、输出参数的顺序与个数，属性的顺序与个数需要与算子原型定义保持一致。

表1 算子信息库配置说明
信息	可选/必选	说明
[OpType]	必选	算子OpType，以英文半角方括号包裹，标识一个算子信息开始，与算子原型定义中REG_OP(OpType)的OpType保持一致。 OpType命名规则请参见算子定义命名规则。
input0.name	必选	第一个输入tensor的名称，需要跟算子原型定义保持一致。对于input0.paramType为dynamic时，只需要配置一个input0.name = x 即可，x 的名称需要与算子原型定义中的名称保持一致。在图运行时，会根据输入的个数自动生成x0、x1、x2……，序号依次递增。
input0.paramType	必选	定义第一个输入tensor的类型。 dynamic：表示该输入是动态个数，可能是1个，也可能是多个。若取值为dynamic，需要配合input0.name使用。 optional：表示该输入为可选，可以有1个，也可以不存在。 required：表示该输入有且仅有1个。默认值为required。
input0.dtype	可选	定义输入tensor支持的数据类型。若支持多种数据类型，请以“,”分隔。有如下取值范围： float16,float,float32,int8,int16,int32,uint8,uint16,uint32,bool等注意：若算子输入支持多种规格，算子输入的dtype与format需要一一对应、按对应顺序进行配置，列出算子支持的所有dtype与format的组合，中间以“,”分隔。请注意数据类型之间请不要输入多余空格。如下所示，input0.dtype与input0.format分别配置了12项。 input0.dtype=float16,float16,float16,float16,float,float,float,float,int32,int32,int32,int32 input0.format=NCHW,NC1HWC0,NHWC,ND,NCHW,NC1HWC0,NHWC,ND,NCHW,NC1HWC0,NHWC,ND 若dynamicFormat.flag配置为true，表示dtype根据算子实现文件中的op_select_format函数进行推导，则此字段不需要配置。须知： input0.dtype的优先级高于dynamicFormat，若既配置了input0.dtype，又设置了dynamicFormat.flag为true，则以input0.dtype为准。建议用户根据dtype的推导方式选择input0.dtype、 dynamicFormat中的一项配置即可。
input0.format	可选	定义第一个输入tensor的数据排布格式。若支持原图中的所有数据排布格式，定义为ND。若支持多种格式，格式之间以“,”分隔，格式的取值范围有以下几种：NCHW,NHWC,NC1HWC0,FRACTAL,ND等。注意：若算子输入支持多种规格，算子输入的dtype与format的需要一一对应、按对应顺序进行配置，列出算子支持的所有dtype与format的组合，中间以“,”分隔。若dynamicFormat.flag配置为true，表示format根据算子实现文件中的op_select_format函数进行推导，input0.format不需要配置。若配置了op.pattern，FE会自动推导出format进行适配，input0.format不需要配置。须知：三个format相关配置项的优先级为： input0.format > dynamicFormat > op.pattern 即若同时配置了input0.format、dynamicFormat.flag为true与op.pattern，以input0.format为准。建议用户根据format的推导方式选择input0.format、 dynamicFormat、 op.pattern中的一项配置即可。
input0.reshapeType	可选	定义第一个输入支持的补维方法。当算子的输入数据format要求为NC1HWC0，但原始网络中此算子的输入不满足4维时，需要配置此参数，将原始网络中不满足4维的shape补齐为4维，配置规则如下：如果原始网络中此算子输入为1维，则可将reshapeType配置为N、C、H、W，表示原图中此层的输入是N、C、H、W中的一维，其余维度补一。例如，原始网络中shape为[20]，原始format为NHWC，如果reshapeType配置为N，则进行补维后shape变为[20,1,1,1]。如果原始网络中此算子输入为2维，如果原始format为NCHW，则可将reshapeType配置为NC、CH、HW、CW、NH、NW，表示原图中维度N、C、H、W中的两维（需保持原format维度的先后顺序），其余维度补一。例如配置为NC，原始shape是[20,30]，则进行补维后shape变为[20,30,1,1]；如果原始format为NHWC，那么可将reshapeType配置为NH、HW、WC、NW、NC、HC，因为补维不能改变维度的排布顺序，所以对于原始format为NHWC且原始维度是两维的情况，配置为CH是不合理的。如果原始网络中的此算子输入为3维，规则同2维，但高维度的reshapeType对于低维度也生效。例如，原始format为NCHW，如果reshapeType配置为NCH，当原始维度是1维的时候，则补齐后shape为[N,1,1,1]；当原始维度是2维的时候，则补齐后shape为[N,C,1,1]；当原始维度是3维的时候，补齐后shape为[N,C,H,1]。若原始网络中此算子输入shape为4维，则reshapeType配置不会生效。若不配置此参数且算子输入format要求为NC1HWC0：当原始format是NCHW时，若原始shape为1维，则使用[1,C,1,1]进行补维；若原始shape为2维，则使用[1,C,H,1]进行补维；若原始shape为3维，则使用[1,C,H,W]进行补维。当原始format是NHWC时，若原始shape为1维，则使用[1,H,1,1]进行补维；若原始shape为2维，则使用[1,H,W,1]进行补维；若原始shape为3维，则使用[1,H,W,C]进行补维。
input1.name	可选	若算子有多个输入tensor，此处请参照input0.xx的参数配置增加对应的input1.xx，input2.xx的配置，序号分别从input1，input2，input3递增。输入tensor的名称需要跟算子原型定义保持一致。
……	可选	input1的其他输入参数配置，参考input0；若算子有其他输入例如input2、input3……，配置也同理参考input0。须知：若配置了算子输入的dtype与format，所有输入的dtype与format个数需要相同，并且需要一一对应、按对应顺序进行配置，中间以“,”分隔。
attr.list	可选	定义算子实现时需要使用到的算子属性列表，多个属性之间用英文半角逗号分割，此处属性的顺序需要与算子声明中属性的顺序保持一致。此列表用于FE从OpDesc中获取对应的属性。例如：stride,padding 注：若算子实现中需要使用相关属性，则此参数需要配置，否则编译失败。
attr_key.type	-	若配置了attr.list，则此参数需要配置，否则编译失败。此参数表示定义其中一个属性的类型，attr是固定前缀，key对应具体参数。此字段需要与attr.list中列出的属性相对应，attr.list中列出了多少属性，需要配置多少条attr_key.type。 type支持的如下取值： int：表示int64类型 float：表示float类型 bool：表示bool类型 str：表示string类型 listInt：表示vector<INT>类型 listFloat：表示vector<FLOAT>类型 listBool：表示vector<BOOL>类型 listStr：表示vector<STR>类型 listListInt：表示 vector<vector<int64_t>>类型 type： ge::DataType表示GE支持所有类型 listType：表示vector<ge::DataType>类型 tensor：std::shared_ptr<GeTensor> list tensor：表示vector<TENSOR>类型
attr_key.value	-	若配置了attr.list，则此参数需要配置，否则编译失败。代表相应属性的取值范围。若支持多种取值，用“,”分隔。例如：1,3,5 若配置为“all”表示支持所有属性值。
attr_key.paramType	可选	定义该参数是否在OpDesc中一定存在。例如：量化和非量化两种不同的场景下，卷积算子的某些参数可能存在，也可能不存在。有以下两种取值： optional：参数可选，从OpDesc中取不到不报错。 required：参数必选，从OpDesc中取不到则报错默认值为required。
attr_key.defaultValue	可选	对于attr_key.paramType为optional时，此参数为必选参数，如果从OpDesc中获取参数值失败，从这里获取默认值。注意：当attr_key.paramType为required时，该参数无效。当attr_key.paramType为optional时，如果OpDesc中获取失败，defaultValue也未定义，则返回失败。
output0.name	必选	定义第一个输出tensor的名称。对于output0.paramType为dynamic时，只需要配置一个output0.name=y 即可，y 的名称需要与算子原型定义中的名称保持一致。在图运行时，会根据输出的个数自动生成y0、y1、y2……，序号依次递增。
output0.paramType	可选	定义第一个输出tensor的类型。 dynamic：表示该输出是动态个数，可能是1个，也可能是多个。多个输出时，需要配合output0.name使用。 optional：表示该输出可选，可以有1个，也可以不存在。 required：表示该输出有且仅有1个。默认值：required。
output0.dtype	可选	定义第一个输出tensor的数据类型。注意：若算子输出支持多种规格，算子输出的dtype与format需要一一对应、按对应顺序进行配置，列出算子支持的所有dtype与format的组合，中间以“,”分隔。如下所示，output0.dtype与output0.format分别配置了12项。 output0.dtype=float16,float16,float16,float16,float,float,float,float,int32,int32,int32,int32 output0.format=NCHW,NC1HWC0,NHWC,ND,NCHW,NC1HWC0,NHWC,ND,NCHW,NC1HWC0,NHWC,ND 若dynamicFormat.flag配置为true，表示dtype根据算子实现文件中的op_select_format函数进行推导，output0.dtype不需要配置。须知： output0.dtype的优先级高于dynamicFormat，若既配置了output0.dtype，又设置了dynamicFormat.flag为true，则以output0.dtype为准。建议用户根据dtype的推导方式选择output0.dtype、 dynamicFormat中的一项配置即可。
output0.format	可选	定义第一个输出tensor的数据排布格式。若支持原图中的所有格式，则format取值为ND。若支持多种格式，格式之间以“,”分隔，格式的取值范围有以下几种：NCHW,NHWC,NC1HWC0,FRACTAL,ND。注意：若算子输出支持多种规格，算子输出的dtype与format需要一一对应、按对应顺序进行配置，列出算子支持的所有dtype与format的组合，中间以“,”分隔。若dynamicFormat.flag配置为true，表示format根据算子实现文件中的op_select_format函数进行推导，output0.format不需要配置。若配置了op.pattern，FE会自动推导出format进行适配，output0.format不需要配置。须知：三个format配置项的优先级为： output0.format > dynamicFormat > op.pattern 即若同时配置了output0.format、dynamicFormat.flag为true、op.pattern，以output0.format为准。建议用户根据format的推导方式选择output0.format、 dynamicFormat、 op.pattern中的一项配置即可。
output1.name	可选	若算子有多个输出tensor，此处请参照output0.xx的参数配置增加对应的output1.xx，output.xx的配置，序号分别从output1，output2递增。
opFile.value	可选	定义算子实现文件名称，FE根据此文件名称查找到算子的实现文件。若不配置此字段，则根据OpType字段，将名称中的大写字母转换为“_”去匹配算子实现文件名称，匹配规则请参见算子定义命名规则。
opInterface.value	可选	定义算子实现接口名称，FE根据此接口名称进行算子的调用。若不配置此字段，则根据OpType字段，将名称中的大写字母转换为“_”去匹配算子接口名称，匹配规则请参见算子定义命名规则。
op.pattern	可选	op.pattern在配置为以下几种值的情况下，算子不需要配置输入输出支持的format。 broadcast：针对具有broadcast能力的算子，FE根据算子当前的shape选出一组支持的format，然后使用这组format来做匹配。 reduce：针对reduce类的算子，FE根据算子的shape、keep_dims、axis信息选出一组支持的format，然后使用这组format来做匹配。 formatAgnostic：针对格式无关算子，例如，当算子为单输入和单输出且支持任意格式时（例如Cast算子），算子开发人员配置op.pattern为formatAgnostic即可，不再需要穷举输入输出的format。须知： op.pattern的优先级低于inputx.format/outputx.format与dynamicFormat，即若配置了输入/输出format配置列表，或者dynamicFormat.flag配置为“true”，则op.pattern配置项不生效，亦无需配置。
dynamicFormat.flag	可选	默认值为“false”。如果配置为“true”，表示通过调用算子实现文件中的op_select_format函数获取算子支持的输入输出的dtype和format。须知：此字段的优先级低于算子本身配置的输入输出支持的dtype与format列表，即： format：对应配置项inputx.format与outputx.format dtype：对应配置项input0.dtype与output0.dtype
precision_reduce.flag	可选	此字段用于进行ATC模型转换或者进行网络调测时，控制算子的精度模式。只有当精度模式("precision_mode")配置为混合精度("allow_mix_precision")前提下生效。若配置为"false"，则认为是黑名单，那么算子必须保持算子本身的原始数据类型。若配置为"true"，则认为是白名单，那么如果算子即支持float32又支持float16数据类型，同时算子的原图格式是float32或者float16的情况下，优先为算子选择float16数据类型。若未配置这个字段，则认为是灰名单，那么算子在有上一个算子的情况下，选择和上一个算子相同的数据类型，否则选择当前算子的原始数据类型。
heavyOp	可选	主要针对Cube类算子，将此标记设置为true后，会对此算子进行重型格式扩散，用于减少格式转换算子的插入，提升网络运行效率。扩散逻辑如下，如果算子的某个输入或者输出的格式选择了如下格式中的一种（称之为重型格式）： NC1HWC0, C1HWNCoC0, FRACTAL_Z, FRACTAL_NZ, NDC1HWC0, FRACTAL_Z_3D, FRACTAL_Z_3D_TRANSPOSE 则沿着该输入或者输出递归地查找相连的算子，把该算子的格式也推导为重型格式，遇到下面三种情况则停止推导：扩散算子不支持当前算子选择的重型格式扩散算子已经选择了当前算子选择的重型格式扩散算子本身的heavyOp字段也为true 默认值为false。
needCheckSupport.flag	可选	标记是否在算子融合阶段调用算子实现文件中的check_supported接口进行data type与shape的校验。若配置为"true"，FE调用算子实现文件中的check_supported接口检查算子是否支持指定输入，此场景下算子实现文件中需要实现check_supported函数。若配置为"false"，表示不需要进行校验。默认值为false。

配置示例如下：

[Upsample]
input0.name=x
input0.paramType=required
input0.dtype=float16,float
input0.format=NC1HWC0,NC1HWC0
attr.list=scale,stride_h,stride_w
attr_scale.type=float
attr_scale.value=all
attr_scale.defaultValue=1
attr_scale.paramType=optional
attr_stride_h.type=int
attr_stride_h.value=all
attr_stride_h.defaultValue=2
attr_stride_h.paramType=optional
attr_stride_w.type=int
attr_stride_w.value=all
attr_stride_w.defaultValue=2
attr_stride_w.paramType=optional
output0.name=y
output0.paramType=required
output0.dtype=float16,float
output0.format=NC1HWC0,NC1HWC0

自定义算子信息库文件编译部署完成后，会将算子相关定义信息存入对应昇腾AI处理器版本的算子信息库中，存储路径为：<path>/<vendor_name>/op_impl/ai_core/tbe/config/${soc_version}/aic-${soc_version}-ops-info.json，其中<path>为算子包的安装目录，详细可参见算子包部署，其中<vendor_name>为提供自定义算子的厂商名字，关于此名字的定义，详细可参见算子工程编译。

算子定义命名规则

算子类型需要采用大驼峰的命名方式，即采用大写字符区分不同的语义。
算子实现文件名称和算子定义函数名称，可选用以下任意一种命名规则：
- 用户自定义，此时需要在TBE算子信息库中配置opFile.value与opInterface.value。
- 不配置TBE算子信息库中的opFile.value与opInterface.value，FE会将OpType按照如下方式进行转换后进行算子文件名和算子函数名的匹配。
  转换规则如下：
  - 首字符的大写字符转换为小写字符。
    例如：Abc -> abc
  - 小写字符后的大写字符转换为下划线+小写字符。
    例如：AbcDef -> abc_def
  - 紧跟数字以及大写字符后的大写字符，作为同一语义字符串，查找此字符串后的第一个小写字符，并将此小写字符的前一个大写字符转换为下划线+小写字符，其余大写字符转换为小写字符。若此字符串后不存在小写字符，则直接将此字符串中的大写字符转换为小写字符。
    例如：ABCDef -> abc_def；Abc2DEf -> abc2d_ef；Abc2DEF -> abc2def；ABC2dEF -> abc2d_ef。

op_select_format函数

若dynamicFormat.flag配置为true，算子信息库文件中无需配置算子输入输出支持的dtype与format，但需要在算子实现文件（*.py）中实现op_select_format函数，推导算子的输入输出支持的dtype和format。

op_select_format的定义如下所示：

def op_select_format(input, output, attr, kernel_name="xx"):

op_select_format函数的入参和算子接口保持一致(即算子的输入、输出、属性及kernel_name)，出参为包含了当前算子输入输出支持的format和dtype列表的字符串，字符串的格式如下：

{
"input0": {
"name": "x",
"dtype": "float16,float16,int8,int8",
"format": "NC1HWC0_C04,NC1HWC0,NC1HWC0_C04,NC1HWC0"
},
"input1": {
"name": "y",
"dtype": "float16,float16,int8,int8",
"format": "FRACTAL_Z_C04,FRACTAL_Z,FRACTAL_Z_C04,FRACTAL_Z"
},
"output0": {
"name": "z",
"dtype": "float16,float16,int32,int32",
"format": "NC1HWC0,NC1HWC0,NC1HWC0,NC1HWC0"
}
}

实现样例可参见（可选）Format推导及参数校验。

check_supported函数

若needCheckSupport.flag配置为true，则算子融合阶段会调用算子实现文件中的check_supported接口进行相关信息的校验。

check_supported函数的声明如下所示：

def check_supported(input_x1, input_x2, output_y, attribute1=None, attribute2=None,..., kernel_name="xx"):

check_supported函数的入参和算子接口函数保持一致(即算子的输入、输出、属性及kernel_name)。

若校验成功，则返回True；若校验失败，则返回False。

实现样例可参见check_supported函数实现。

父主题： 算子信息库定义