Qualcomm® AI Engine Direct 使用手册(12)
5.1.2 XML OpDef 架构参考
本页概述了用于在 QNN 中定义操作定义 (Op Defs) 的架构。操作定义指定构成操作的输入、输出、参数和描述性元数据。
该模式使用可扩展标记语言 (XML) 和 XML 模式定义 (XSD) 进行形式化。定义 Op Defs 以及用于定义与 一起使用的多个操作的构造的 XSD 文件qnn-op-package-generator位于:
${QNN_SDK_ROOT}/lib/python/qti/aisw/op_package_generator/translator/OpDef.xsd
操作定义架构
将详细探讨以下要素:
-
操作定义
-
补充操作定义
-
操作定义列表
-
补充OpDef列表
-
OpDef集合
这里给出了描述这些实体之间关系的简单 UML 图:
笔记
以@为前缀的成员是XML属性,没有前缀的成员是XML元素。
操作定义
OpDef 是一个描述最高级别操作的 XML 元素。即,它包含以下内容。有内容的元素是必需的,空的元素是可选的。
<OpDef>
<Name>OpName</Name>
<Description>
<Content></Content>
<Code></Code>
</Description>
<Reference Source="" Url=""></Reference>
<!--Requires at least one input-->
<Input>
<Name>in[0]</Name>
<Mandatory>true</Mandatory>
<Constraint id="" Type=""></Constraint>
<Datatype>QNN_DATATYPE_FLOAT_32</Datatype>
<Shape>
<Rank>1D</Rank>
<Layout></Layout>
<Text></Text>
</Shape>
<Default></Default>
<Repeated></Repeated>
<IsStaticTensor></IsStaticTensor>
</Input>
<!--Requires at least one output-->
<Output>
<Name>out[0]</Name>
<Mandatory>true</Mandatory>
<Constraint id="" Type=""></Constraint>
<Datatype>QNN_DATATYPE_FLOAT_32</Datatype>
<Shape>
<Rank>1D</Rank>
<Layout></Layout>
<Text></Text>
</Shape>
<Repeated></Repeated>
</Output>
<!--Parameters are optional-->
<Parameter>
<Name>param</Name>
<Mandatory>false</Mandatory>
<Constraint id="" Type=""></Constraint>
<Datatype>QNN_DATATYPE_INT_32</Datatype>
<Shape>
<Rank>1D</Rank>
<Layout></Layout>
<Text></Text>
</Shape>
<Default></Default>
<Enumeration>
<Enum></Enum>
</Enumeration>
</Parameter>
<UseDefaultTranslation></UseDefaultTranslation>
<SupportedBackend>HTP</SupportedBackend>
</OpDef>
-
名称:操作的名称。
-
描述:可选字段,通过内容和代码序列描述操作:
-
内容:描述操作的字符串。
-
Code:表示描述操作的代码的字符串。例如,输出高度=输入高度-作物顶部-作物底部
-
-
参考:可选字段,定义操作的一个或多个参考。
- Source:操作来源的属性。例如Tensorflow、ONNX等。
Url:源 URL 的属性。
-
输入:定义操作的一个或多个输入。输入是 具有以下附加字段的张量的扩展:
-
IsStaticTensor:可选的布尔标志,如果设置为 True,则表示输入张量是包含或引用静态数据的参数。如果未设置,张量将被视为动态输入。
-
Repeated:可选布尔值,指定此输入是否重复。用于具有可变输入的操作,例如 Concat 1。
-
-
输出:定义操作的一个或多个输出。输出是 具有以下附加字段的张量的扩展:
- Repeated:可选布尔值,指定此输出是否重复。用于具有可变输出的操作,例如 MultiClassNms 1。
-
参数:可选地,为操作定义一个或多个参数。参数是张量的扩展 ,另外定义
- 枚举:枚举参数的可选字段。枚举由称为Enum 的子字段组成 ,其内容给出了表示给定值的枚举的名称。值按照指定 Enum 的顺序分配。
-
SupportedBackend:指定支持此操作的一个或多个后端的字段。当后端共享操作的通用定义时使用。如果同一操作的字段在不同后端有所不同,请使用SupplementalOpDef并使用 BACKEND_SPECIFIC 标记该字段。
-
UseDefaultTranslation:布尔字段,如果设置为 true,则表示自定义操作将覆盖 QNN 本机操作。自定义操作类型必须与 QNN 本机操作类型匹配才能准确转换。当设置为 false 时,自定义操作将转换为通用用户定义操作。在 false 模式下,自定义操作类型必须与源框架类型匹配。
创建 OpDef 的关键组件是输入、输出和参数,所有这些都是张量的扩展。张量元素定义如下:
-
名称:张量的名称。
-
描述:可选字段,通过内容和代码序列描述张量:
-
内容:描述张量的字符串。
-
Code:表示描述张量的代码的字符串。例如,输出高度=输入高度-作物顶部-作物底部
-
-
Constraint:可选字段,定义给定张量的一个或多个约束。约束以元素2主体中的字符串形式给出。
-
id:指定约束 id 的数字。用于覆盖补充操作定义的约束。
-
类型:约束的类型。有效类型有:
-
Number:以基数为特征的约束。例如输入数量 >= 1
-
形状:以张量维度限制为特征的约束。例如排名 >= 1
-
值:以张量值为特征的约束。例如张量只有正数
-
数据类型:以数据类型限制为特征的约束。通常用于可以具有多种数据类型但必须与另一个张量具有相同数据类型的张量。
-
描述:不符合任何其他类别的约束的约束。
-
-
-
强制:指示是否必须提供/定义张量的布尔值3。
-
数据类型:定义张量允许的数据类型。必须是以下之一:
-
QNN_DATATYPE_INT_8
-
QNN_DATATYPE_INT_16
-
QNN_DATATYPE_INT_32
-
QNN_DATATYPE_INT_64
-
QNN_DATATYPE_UINT_8
-
QNN_DATATYPE_UINT_16
-
QNN_DATATYPE_UINT_32
-
QNN_DATATYPE_UINT_64
-
QNN_DATATYPE_SFIXED_POINT_4
-
QNN_DATATYPE_SFIXED_POINT_8
-
QNN_DATATYPE_SFIXED_POINT_16
-
QNN_DATATYPE_SFIXED_POINT_32
-
QNN_DATATYPE_UFIXED_POINT_4
-
QNN_DATATYPE_UFIXED_POINT_8
-
QNN_DATATYPE_UFIXED_POINT_16
-
QNN_DATATYPE_UFIXED_POINT_32
-
QNN_DATATYPE_BOOL_8
-
QNN_DATATYPE_FLOAT_16
-
QNN_DATATYPE_FLOAT_32
-
QNN_DATATYPE_FLOAT_64
-
BACKEND_SPECIFIC 用于指示数据类型依赖于后端。必须与SupplementalOpDef结合使用以指定具体的数据类型。
-
-
形状:指定张量的形状。
-
Rank:张量的排名作为具有以下值的枚举:
-
标量:标量
-
一维:矢量
-
2D:矩阵
-
3D:3D 张量或图像
-
4D:4D 张量或批处理图像
-
ND:通用 ND 张量 N >= 0
-
-
布局:可选字段,指定张量的布局。必须是以下之一:
-
NHWC
-
NHCW
-
UNDEFINED 用于标识布局既不是 NHCW 也不是 NHWC
-
BACKEND_SPECIFIC 用于指示布局依赖于后端。必须与SupplementalOpDef结合使用以指定具体布局。
-
-
文本:可以选择提供张量形状的文本描述。
-
-
默认值:可以选择提供表示张量默认值的文本。可以是其中之一
-
张量:使用大括号或方括号创建列表,例如 [[1, 2], [3, 4]]
-
标量:提供标量值,例如 1、1.1、-1
-
布尔值:提供 0(假)或 1(真)
-
字符串:任何其他字符串。如果文本无法解析为上述类别之一,它将被存储为字符串。
-
笔记
自定义操作的输入和输出的等级必须 >= 1。
自定义操作必须至少有一个输入和输出。
IsDefaultTranslation 和 IsStaticTensor 均仅与自定义操作转换用例相关。
补充操作定义
SupplementalOpDef 是定义跨后端可变内容的 XML 元素。SupplementalOpDef 扩展了 OpDef 中定义的内容,但限制了可以覆盖的字段。SupplementalOpDef 的结构如下。有内容的元素是必需的,空的元素是可选的。
<SupplementalOpDef>
<Name>OpName</Name>
<!--Only supplemented Inputs are required-->
<Input>
<Name>in[0]</Name>
<Constraint id="" Type=""></Constraint>
<Datatype></Datatype>
<Shape>
<Layout></Layout>
<Text></Text>
</Shape>
<OnlyDefaultSupported></OnlyDefaultSupported>
</Input>
<!--Only supplemented Outputs are required-->
<Output>
<Name>out[0]</Name>
<Constraint id="" Type=""></Constraint>
<Datatype></Datatype>
<Shape>
<Layout></Layout>
<Text></Text>
</Shape>
<OnlyDefaultSupported></OnlyDefaultSupported>
</Output>
<!--Only supplemented Params are required-->
<Parameter>
<Name>param</Name>
<Constraint id="" Type=""></Constraint>
<Datatype></Datatype>
<Shape>
<Layout></Layout>
<Text></Text>
</Shape>
<OnlyDefaultSupported></OnlyDefaultSupported>
</Parameter>
</SupplementalOpDef>
-
名称:操作的名称。必须对应于同一配置中定义的 OpDef。
-
输入:(可选)将一个或多个输入扩展到操作。补充输入是 补充张量。
-
输出:(可选)将一个或多个输出扩展到操作。补充输出是 补充张量。
-
参数:可选地,为操作扩展一个或多个参数。补充参数是 补充张量。
输入、输出和参数都是补充张量,只能指定某些字段。补充张量中除名称外的所有字段都是可选的。
-
名称:张量的名称。必须对应于正在扩展的原始 OpDef 中的张量名称。
-
Constraint:可选字段,定义给定张量的一个或多个约束。约束以元素2主体中的字符串形式给出。
-
id:指定约束 id 的数字。用于覆盖补充操作定义的约束。
-
类型:约束的类型。有效类型有:
-
Number:以基数为特征的约束。例如输入数量 >= 1
-
形状:以张量维度限制为特征的约束。例如排名 >= 1
-
值:以张量值为特征的约束。例如张量只有正数
-
数据类型:以数据类型限制为特征的约束。通常用于可以具有多种数据类型但必须与另一个张量具有相同数据类型的张量。
-
描述:不符合任何其他类别的约束的约束。
-
-
-
数据类型:定义张量允许的数据类型。必须是其中之一
-
QNN_DATATYPE_INT_8
-
QNN_DATATYPE_INT_16
-
QNN_DATATYPE_INT_32
-
QNN_DATATYPE_INT_64
-
QNN_DATATYPE_UINT_8
-
QNN_DATATYPE_UINT_16
-
QNN_DATATYPE_UINT_32
-
QNN_DATATYPE_UINT_64
-
QNN_DATATYPE_SFIXED_POINT_4
-
QNN_DATATYPE_SFIXED_POINT_8
-
QNN_DATATYPE_SFIXED_POINT_16
-
QNN_DATATYPE_SFIXED_POINT_32
-
QNN_DATATYPE_UFIXED_POINT_4
-
QNN_DATATYPE_UFIXED_POINT_8
-
QNN_DATATYPE_UFIXED_POINT_16
-
QNN_DATATYPE_UFIXED_POINT_32
-
QNN_DATATYPE_BOOL_8
-
QNN_DATATYPE_FLOAT_16
-
QNN_DATATYPE_FLOAT_32
-
QNN_DATATYPE_FLOAT_64
-
-
形状:指定张量的形状。
-
布局:可选字段,指定张量的布局。必须是以下之一:
-
NHWC
-
NHCW
-
UNDEFINED 用于标识布局既不是 NHCW 也不是 NHWC
-
BACKEND_SPECIFIC 用于指示布局依赖于后端。与 SupplementalOpDef 结合使用来指定具体布局。
-
-
文本:可以选择提供张量形状的文本描述。
-
-
OnlyDefaultSupported:可选布尔值,指示后端仅支持该张量的相应 OpDef 中定义的默认值。
操作定义列表
OpDefList 是由OpDef元素序列组成的 XML 元素。OpDefList 与后端无关,仅用作多个 OpDef 的包装器。
<OpDefList>
<!--One or more OpDef-->
<OpDef>
<!--OpDef defined above -->
</OpDef>
</OpDefList>
补充OpDef列表
SupplementalOpDefList 是由SupplementalOpDef元素序列组成的 XML 元素。此外,SupplementalOpDefLists 包含以下字段。
<SupplementalOpDefList Backend="HTP">
<SupportedOps>
<OpName></OpName>
</SupportedOps>
<SupplementalOpDef>
<!--SupplementalOpDef defined above-->
</SupplementalOpDef>
</SupplementalOpDefList>
Backend:指定 SupplementalOpDef 所补充的后端的属性。
SupportedOps :包含OpName元素序列的元素。每个OpName对应对应OpDefList中定义的一个操作,表示后端支持该Op。该信息可能与OpDef 元素的SupportedBackend字段是冗余的。
OpDef集合
OpDefCollection 是配置文件的根 XML 元素,旨在与qnn-op-package-generator. 它包含指定所有用户包所需的所有信息。OpDefCollection 包含以下内容
<OpDefCollection
xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
xs:noNamespaceSchemaLocation="OpDef.xsd"
PackageName="ExamplePackage"
Domain="example"
Version="1.0"
>
<!--One OpDefList-->
<OpDefList>
<!--OpDefList defined above-->
</OpDefList>
<!--SupplementalOpDefLists are not required-->
<SupplementalOpDefList Backend="HTP">
<!--SupplementalOpDefList defined above-->
</SupplementalOpDefList>
</OpDefCollection>
-
PackageName:指定用户 OpPackage 名称的属性。因为包是每个后端的,所以实际的包名称将是此处指定的值附加 例如 MyPackageNameHtp
-
Domain:指定包的域的属性。
-
Version:指定包版本的属性。
-
OpDefList:一个OpDefList指定包的所有操作。
-
SupplementalOpDefList:可以选择指定一个或多个SupplementalOpDefList以指定每个后端信息。
一个 OpDefCollection 元素可用于生成多个每个后端包。
笔记
1 ( 1 , 2 )
HTP 后端当前不支持未知数量输入/输出的操作。
2 ( 1 , 2 )
约束纯粹是一个描述性字段,不需要数学表达。目前尚未强制执行限制。
3
输出不是强制性的,但不能有默认值,如果未提供,则假定为 NULL。