aclnnQuantMatmulV5

产品支持情况

产品	是否支持
[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]	√
[object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]	√
[object Object]Atlas 200I/500 A2 推理产品[object Object]	×
[object Object]Atlas 推理系列产品 [object Object]	×
[object Object]Atlas 训练系列产品[object Object]	×

功能说明

• 算子功能：完成量化的矩阵乘计算。
  • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：兼容aclnnQuantMatmulV3、aclnnQuantMatmulV4接口功能。完成量化的矩阵乘计算，最小支持输入维度为1维，最大支持输入维度为2维。相似接口有aclnnMm（仅支持2维Tensor作为输入的矩阵乘）。
• 计算公式：
  • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：

    • x1为INT8，x2为INT32，x1Scale为FLOAT32，x2Scale为UINT64，yOffset为FLOAT32：

      $$out = ((x1 @ (x2*x2Scale)) + yOffset) * x1Scale$$

    • 无x1Scale无bias：

      $$out = x1@x2 * x2Scale + x2Offset$$

    • bias INT32：

      $$out = (x1@x2 + bias) * x2Scale + x2Offset$$

    • bias BFLOAT16/FLOAT32（此场景无offset）：

      $$out = x1@x2 * x2Scale + bias$$

    • x1Scale无bias：

      $$out = x1@x2 * x2Scale * x1Scale$$

    • x1Scale， bias INT32（此场景无offset）：

      $$out = (x1@x2 + bias) * x2Scale * x1Scale$$

    • x1Scale， bias BFLOAT16/FLOAT16/FLOAT32（此场景无offset）：

      $$out = x1@x2 * scale * x1Scale + bias$$

函数原型

每个算子分为，必须先调用“aclnnQuantMatmulV5GetWorkspaceSize”接口获取计算所需workspace大小以及包含了算子计算流程的执行器，再调用“aclnnQuantMatmulV5”接口执行计算。

• aclnnStatus aclnnQuantMatmulV5GetWorkspaceSize(const aclTensor *x1, const aclTensor *x2, const aclTensor *x1Scale, const aclTensor *x2Scale, const aclTensor *yScale, const aclTensor *x1Offset, const aclTensor *x2Offset, const aclTensor *yOffset, const aclTensor *bias, bool transposeX1, bool transposeX2, int64_t groupSize, aclTensor *out, uint64_t *workspaceSize, aclOpExecutor **executor)

• aclnnStatus aclnnQuantMatmulV5(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream)

aclnnQuantMatmulV5GetWorkspaceSize

• 参数说明：

  • x1（aclTensor*，计算输入）：公式中的输入x1，device侧的aclTensor，支持ND。shape支持2~6维，在transposeX1为false情况下，形状为（batch, m, k）；在transposeX1为true情况下，形状为（batch, k, m），其中batch代表前0~4维，0维表示bacth不存在。仅最后m和k轴转置情况下支持，其他轴方向不支持非连续的Tensor。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持INT8、INT32、INT4。当数据类型为INT32、INT4时，为INT4量化场景，当前仅支持2-6维ND格式，transposeX1为false情况。其中当x1数据类型为INT4时，维度表示：（batch，m，k），要求k为偶数，当x1数据类型为INT32时，每个INT32数据存放8个INT4数据，对应维度表示：（batch，m，k // 8），要求k为8的倍数。
      • 启用A8W8 perblock量化时，目前n需与256对齐, k与128对齐且为4 * 128的倍数。
  • x2（aclTensor*，计算输入）：公式中的输入x2，device侧的aclTensor。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：支持ND格式和昇腾亲和数据排布格式。ND格式下支持最后两根轴转置情况下的非连续tensor，其他场景的不支持。昇腾亲和数据排布格式下，shape支持4~8维。在transposeX2为true情况下各个维度表示：（batch，k1，n1，n0，k0），batch可不存在，其中k0 = 32， n0 = 16， x1 shape中的k和x2 shape中的k1需要满足以下关系：ceil（k / 32） = k1。在transposeX2为false情况下各个维度表示：（batch，n1，k1，k0，n0），batch可不存在，其中k0 = 16，n0 = 32，x1 shape中的k和x2 shape中的k1需要满足以下关系：ceil（k / 16） = k1。可使用aclnnCalculateMatmulWeightSizeV2接口以及aclnnTransMatmulWeight接口完成输入Format从ND到昇腾亲和数据排布格式的转换。数据类型支持INT8、INT32、INT4。当数据类型为INT32、INT4时，为INT4量化场景，当前仅支持2维ND格式。ND格式下，shape支持2~6维，在transposeX2为false情况下各个维度表示：（batch，k，n），在transposeX2为true情况下各个维度表示：（batch，n，k），batch可不存在，其中k与x1的shape中的k一致。
      • 数据类型为INT4时，在transposeX2为true情况下各个维度表示：（n，k），要求k为偶数；在transposeX2为false情况下各个维度表示：（k，n），要求n为偶数。
      • 数据类型为INT32时，每个INT32数据存放8个INT4数据，在transposeX2为true情况下各个维度表示：（n，k // 8），要求k为8的倍数；在transposeX2为false情况下各个维度表示：（k，n // 8），要求n为8的倍数。
      • 可使用aclnnConvertWeightToINT4Pack接口完成x2从INT32（1个int32在0~3bit位存储1个int4）到INT32（1个int32存储8个int4）或INT4（1个int4表示1个int4）的数据格式转换，具体参见。
      • 启用A8W8 perblock量化时，数据类型支持int8, transpose为true, 形状为(n, k), 目前n需与256对齐, k与128对齐且为4 * 128的倍数。
  • x1Scale（aclTensor*，计算输入）：公式中的输入x1Scale，device侧的aclTensor。支持ND。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：shape支持2维，形状为（m，1）。数据类型支持FLOAT32。
      • 启用A8W8 perblock量化时，数据类型为float32, 形状为(m, ceil(k / 128))
  • x2Scale（aclTensor*，计算输入）：表示量化参数，公式中的输入x2Scale，device侧的aclTensor。支持ND。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：shape支持2维，形状为（k / groupSize，n）其中n与x2的n一致。数据类型支持UINT64、INT64、FLOAT32、BFLOAT16。当原始输入类型不满足中类型组合时，由于TransQuantParamV2只支持1维，需要将x2_scale view成一维(k / groupSize * n)，再调用TransQuantParamV2算子的aclnn接口来将x2Scale转成UINT64数据类型，再将输出view成二维（k / groupSize, n）。
      • 启用A8W8 perblock量化时，数据类型为float32, 当x2的transpose为true时，形状为(ceil(n / 128), ceil(k / 128))，当x2的transpose为false时，形状为(ceil(k / 128), ceil(n / 128))
  • yScale（aclTensor*，计算输入）：输出y的反量化scale参数。不支持。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持，需要传入nullptr。
  • x1Offset（aclTensor*，计算输入）：预留参数，当前版本不支持，需要传入nullptr。
  • x2Offset（aclTensor*，计算输入）：公式中的输入offset，device侧的aclTensor。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：可选量化参数，数据类型支持FLOAT32，支持ND，shape是1维（t，），t = 1或n，其中n与x2的n一致。当out数据类型为INT8时，offset可以存在，其他输入类型需要传入nullptr。
  • yOffset（aclTensor*，计算输入）：
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：公式中的输入yOffset，device侧的aclTensor。支持ND。shape支持1维（n）。数据类型支持FLOAT32。值要求为8*x2*x2Scale。
  • bias（aclTensor*，计算输入）：公式中的输入bias，device侧的aclTensor。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持，需要传入nullptr。
      • A8W8 perblock量化时，数据类型支持float32，shape支持一维(n, )。
  • transposeX1（bool，计算输入）：表示x1的输入shape是否包含transpose。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：x1和x2为int32、int4时，transposeX1仅支持false，各个维度表示：（m, k）。
  • transposeX2（bool，计算输入）：表示x2的输入shape是否包含transpose。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：
      • ND格式下，在transposeX2为false情况下各个维度表示：（batch，k，n），在transposeX2为true情况下各个维度表示：（batch，n，k），batch可不存在，其中k与x1的shape中的k一致。
      • 昇腾亲和数据排布格式下，在transposeX2为true情况下各个维度表示：（batch，k1，n1，n0，k0），batch可不存在，其中k0 = 32，n0 = 16，x1 shape中的k和x2 shape中的k1需要满足以下关系：ceil（k / 32） = k1。在transposeX2为false情况下各个维度表示：（batch，n1，k1，k0，n0），batch可不存在，其中k0 = 16，n0 = 32，x1 shape中的k和x2 shape中的k1需要满足以下关系：ceil（k / 16） = k1。
  • groupSize（int64_t，计算输入）：用于输入m、n、k方向上的量化分组大小。groupSize输入由3个方向的groupSizeM，groupSizeN，groupSizeK三个值拼接组成，每个值占16位，共占用int64_t类型groupSize的低48位（groupSize中的高16位的数值无效），计算公式为：groupSize = groupSizeK | groupSizeN << 16 | groupSizeM << 32。
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：[groupSizeM，groupSizeN，groupSizeK]取值组合仅支持仅支持[0，0,256]，即groupSize仅支持256。
      • 在A8W8 perblock量化模式时，[groupSizeM，groupSizeN，groupSizeK]取值组合仅支持[1, 128, 128]。
  • out（aclTensor*，计算输出）：公式中的输出out，device侧的aclTensor。支持ND。支持，
    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：shape支持2维，（m，n）。数据类型支持FLOAT16、INT8、BFLOAT16、INT32。
      • A8W8 perblock量化模式时，目前输出支持bfloat16。
  • workspaceSize（uint64_t*，出参）：返回需要在Device侧申请的workspace大小。
  • executor（aclOpExecutor**，出参）：返回op执行器，包含了算子计算流程。

• 返回值：

  aclnnStatus：返回状态码，具体参见。

  [object Object]

aclnnQuantMatmulV5

• 参数说明：

  • workspace(void*, 入参)：在Device侧申请的workspace内存地址。
  • workspaceSize(uint64_t, 入参)：在Device侧申请的workspace大小，由第一段接口aclnnQuantMatmulV5GetWorkspaceSize获取。
  • executor(aclOpExecutor*, 入参)：op执行器，包含了算子计算流程。
  • stream(aclrtStream, 入参)：指定执行任务的Stream。

• 返回值：

  aclnnStatus：返回状态码，具体参见。

约束说明

输入和输出支持以下数据类型组合：

• [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：

  x1	x2	x1Scale	x2Scale	x2Offset	yScale	bias	yOffset	out
  INT8	INT32	FLOAT32	UINT64	null	null	null	FLOAT32	FLOAT16/BFLOAT16
  INT8	INT8	null	UINT64/INT64	null	null	null/INT32	null	FLOAT16
  INT8	INT8	null	UINT64/INT64	null/FLOAT32	null	null/INT32	null	INT8
  INT8	INT8	null/FLOAT32	FLOAT32/BFLOAT16	null	null	null/INT32/BFLOAT16/FLOAT32	null	BFLOAT16
  INT8	INT8	FLOAT32	FLOAT32	null	null	null/INT32/FLOAT16/FLOAT32	null	FLOAT16
  INT4/INT32	INT4/INT32	null	UINT64/INT64	null	null	null/INT32	null	INT32
  INT8	INT8	null	FLOAT32/BFLOAT16	null	null	null/INT32	null	FLOAT16
  INT4/INT32	INT4/INT32	FLOAT32	FLOAT32/BFLOAT16	null	null	null/INT32/BFLOAT16/FLOAT32	null	BFLOAT16
  INT4/INT32	INT4/INT32	FLOAT32	FLOAT32	null	null	null/INT32/FLOAT16/FLOAT32	null	FLOAT16

不同的支持的x1、 x2、x1Scale和x2Scale的输入dtype组合以及支持的平台为：

• [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：

  x1、x2、x1Scale、x2Scale、yOffset和groupSize在不同量化场景下dtype、shape的取值等方面相互影响，关系如下：

  x1数据类型	x2数据类型	x1Scale数据类型	x2Scale数据类型	x1 shape	x2 shape	x1Scale shape	x2Scale shape	yOffset shape	[groupSizeM，groupSizeN，groupSizeK]取值
  INT8	INT32	FLOAT32	UINT64	（m, k）	（k, n // 8）	（m, 1）	（（k // 256），n）	(n)	[0, 0, 256]

调用示例

示例代码如下，仅供参考，具体编译和执行过程请参考。

x1，x2为FLOAT8_E4M3FN，x1Scale为FLOAT32，x2Scale为FLOAT32，无x2Offset，bias为FLOAT32的示例代码如下，仅供参考，具体编译和执行过程请参考。

• [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]： x1为INT8，x2为INT32，x1Scale为FLOAT32，x2Scale为UINT64的示例代码如下，仅供参考，具体编译和执行过程请参考编译与运行样例。

  [object Object]