aclnnGroupedMatmulWeightNz

产品支持情况

产品	是否支持
[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]	√
[object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]	√
[object Object]Atlas 200I/500 A2 推理产品[object Object]	×
[object Object]Atlas 推理系列产品[object Object]	√
[object Object]Atlas 训练系列产品[object Object]	×

功能说明

• 算子功能：实现分组矩阵乘计算，每组矩阵乘的维度大小可以不同。基本功能为矩阵乘，如$y_i[m_i,n_i]=x_i[m_i,k_i] \times weight_i[k_i,n_i], i=1...g$，其中g为分组个数，$m_i/k_i/n_i$为对应shape。输入输出数据类型均为aclTensorList，对应的功能为：

  • k轴分组：$k_i$各不相同，但$m_i/n_i$每组相同，此时$x_i/weight_i$可以在$k_i$上拼接。
  • m轴分组：$k_i$各组相同，$weight_i/y_i$可以在$n_i$上拼接。

  相较于undefined接口，此接口新增：

  • 输入的weight的[数据格式]支持昇腾亲和数据排布格式（FRACTAL_NZ）。
  • 新增参数quantGroupSize，整数型参数，代表分组量化（per-group）的分组大小，不涉及分组量化时，填0。

• 计算公式：

  • 非量化场景：
  $$y_i=x_i\times weight_i + bias_i$$

  • 量化场景（无perTokenScaleOptional）：

    $$y_i=(x_i\times weight_i) * scale_i + offset_i$$
    • x为INT8，bias为INT32$$y_i=(x_i\times weight_i + bias_i) * scale_i + offset_i$$
    • x为INT8，bias为BFLOAT16/FLOAT16/FLOAT32，无offset$$y_i=(x_i\times weight_i) * scale_i + bias_i$$

  • 量化场景（有perTokenScaleOptional）：

    $$y_i=(x_i\times weight_i) * scale_i * per\_token\_scale_i$$
    • x为INT8，bias为INT32$$y_i=(x_i\times weight_i + bias_i) * scale_i * per\_token\_scale_i$$
    • x为INT8，bias为BFLOAT16/FLOAT16/FLOAT32$$y_i=(x_i\times weight_i) * scale_i * per\_token\_scale_i + bias_i$$

  • 量化场景 (mx量化，当前无bias无激活层)：

    $$y_i=(x_i\times per\_token\_scale_i) * (weight_i \times scale_i)$$

  • 反量化场景：

  $$y_i=(x_i\times weight_i + bias_i) * scale_i$$
  • 伪量化场景：
  $$y_i=x_i\times (weight_i + antiquant\_offset_i) * antiquant\_scale_i + bias_i$$

函数原型

每个算子分为undefined，必须先调用“aclnnGroupedMatmulWeightNzGetWorkspaceSize”接口获取入参并根据计算流程计算所需workspace大小，再调用“aclnnGroupedMatmulWeightNz”接口执行计算。

• aclnnStatus aclnnGroupedMatmulWeightNzGetWorkspaceSize(const aclTensorList *x, const aclTensorList *weight, const aclTensorList *biasOptional, const aclTensorList *scaleOptional, const aclTensorList *offsetOptional, const aclTensorList *antiquantScaleOptional, const aclTensorList *antiquantOffsetOptional, const aclTensorList *perTokenScaleOptional, const aclTensor *groupListOptional, const aclTensorList *activationInputOptional, const aclTensorList *activationQuantScaleOptional, const aclTensorList *activationQuantOffsetOptional, int64_t splitItem, int64_t groupType, int64_t groupListType, int64_t actType, aclIntArray *tuningConfigOptional, int64_t quantGroupSize, aclTensorList *out, aclTensorList *activationFeatureOutOptional, aclTensorList *dynQuantScaleOutOptional, uint64_t *workspaceSize, aclOpExecutor **executor)
• aclnnStatus aclnnGroupedMatmulWeightNz(void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, aclrtStream stream)

aclnnGroupedMatmulWeightNzGetWorkspaceSize

• 参数说明：

  • x（aclTensorList *，计算输入）：Device侧的aclTensorList，公式中的输入x，undefined支持ND，支持的最大长度为128个。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持FLOAT16、BFLOAT16、INT8。
    • [object Object]Atlas 推理系列产品[object Object]：数据类型支持FLOAT16。
  • weight（aclTensorList *，计算输入）：Device侧的aclTensorList，公式中的weight，undefined支持昇腾亲和数据排布格式(nz)，支持的最大长度为128个。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持FLOAT16、BFLOAT16、INT8、INT4，undefined支持ND和FRACTAL_NZ格式。可使用aclnnCalculateMatmulWeightSizeV2接口以及aclnnTransMatmulWeight接口完成输入Format从ND到昇腾亲和数据排布格式（NZ）的转换，具体使用限制请参考这两个接口的接口说明书。
    • [object Object]Atlas 推理系列产品[object Object]：数据类型支持FLOAT16，undefined仅支持FRACTAL_NZ格式。可使用aclnnCalculateMatmulWeightSizeV2接口以及aclnnTransMatmulWeight接口完成输入Format从ND到昇腾亲和数据排布格式（NZ）的转换，具体使用限制请参考这两个接口的接口说明书。
  • biasOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList，公式中的bias，undefined支持ND，长度与weight相同。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持FLOAT16、FLOAT32、INT32。
    • [object Object]Atlas 推理系列产品[object Object]：数据类型支持FLOAT16。
  • scaleOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList，代表量化参数中的缩放因子，undefined支持ND，一般情况下，长度与weight相同。综合约束请参见undefined。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持UINT64、BFLOAT16、FLOAT32。
    • [object Object]Atlas 推理系列产品[object Object]：功能暂不支持，需传空指针。
  • offsetOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList，代表量化参数中的偏移量，数据类型支持FLOAT32，undefined支持ND，长度与weight相同。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：功能暂不支持，需传空指针。
  • antiquantScaleOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList，代表伪量化参数中的缩放因子，undefined支持ND，长度与weight相同。综合约束请参见undefined。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持FLOAT16、BFLOAT16。
    • [object Object]Atlas 推理系列产品[object Object]：功能暂不支持，需传空指针。
  • antiquantOffsetOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList，代表伪量化参数中的偏移量，undefined支持ND，长度与weight相同。综合约束请参见undefined。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持FLOAT16、BFLOAT16。
    • [object Object]Atlas 推理系列产品[object Object]：功能暂不支持，需传空指针。
  • perTokenScaleOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList，代表量化参数中的由x量化引入的缩放因子，undefined支持ND，一般情况下，只支持1维且长度与x的M相同。仅支持x、weight、out均为单tensor（TensorList长度为1）场景。综合约束请参见undefined。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持FLOAT32。
    • [object Object]Atlas 推理系列产品[object Object]：功能不支持，需传空指针。
  • groupListOptional（aclTensor *，计算输入）：可选参数，Device侧的aclTensor类型，代表输入和输出分组轴方向的matmul大小分布，数据类型支持INT64，undefined支持ND。需注意：当输出中TensorList的长度为1时，groupListOptional中的最后一个值约束了输出数据的有效部分，groupListOptional中未指定的部分将不会参与更新。
  • activationInputOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList类型，代表激活函数的反向输入，当前只支持传入nullptr。
  • activationQuantScaleOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList类型，当前只支持传入nullptr。
  • activationQuantOffsetOptional（aclTensorList *，计算输入）：可选参数，Device侧的aclTensorList类型，当前只支持传入nullptr。
  • splitItem（int64_t，计算输入）：整数型参数，代表输出是否要做tensor切分，0/1代表输出为多tensor；2/3代表输出为单tensor。
  • groupType（int64_t，计算输入）：整数型参数，代表需要分组的轴，如矩阵乘为C[m,n]=A[m,k]xB[k,n]，则groupType取值-1：不分组，0：m轴分组，1：n轴分组，2：k轴分组。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前不支持n、k轴分组。
    • [object Object]Atlas 推理系列产品[object Object]：当前只支持m轴分组。
  • groupListType（int64_t，计算输入）：整数型参数，支持的取值如下：
    • 0: groupListOptional中数值为分组轴大小的cumsum结果（累积和）;
    • 1: groupListOptional中数值为分组轴上每组大小；
    • 2：groupListOptional shape为[e, 2]，e表示Group大小，数据排布为[[groupIdx0, groupSize0], [groupIdx1, groupSize1]...]，其中groupSize为分组轴上每组大小。
    • [object Object]Atlas 推理系列产品[object Object]：不支持取2。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：仅当x和weight参数输入类型为INT8，并且groupType取0（m轴分组）时，支持取2。
  • actType（int64_t，计算输入）：整数型参数，代表激活函数类型。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值范围为0-5，支持的枚举值如下：
      • 0：GMMActType::GMM_ACT_TYPE_NONE；
      • 1：GMMActType::GMM_ACT_TYPE_RELU；
      • 2：GMMActType::GMM_ACT_TYPE_GELU_TANH；
      • 3：GMMActType::GMM_ACT_TYPE_GELU_ERR_FUNC（不支持）；
      • 4：GMMActType::GMM_ACT_TYPE_FAST_GELU；
      • 5：GMMActType::GMM_ACT_TYPE_SILU；
    • [object Object]Atlas 推理系列产品[object Object]：当前只支持传入0，表示GMMActType::GMM_ACT_TYPE_NONE。
  • tuningConfigOptional（aclIntArray*，计算输入）：可选参数，Host侧的aclIntArray，数组里面存储INT64的元素, 要求是非负数且不大于x矩阵的行数。数组中第一个元素表示各个专家处理的token数的预期值，算子tiling时会按照数组中第一个元素进行最优tiling，性能更优。从第二个元素开始预留，用户无须填写，未来会进行扩展。兼容历史版本，用户如不适用该参数，不传(即为nullptr)即可。
    • [object Object]Atlas 推理系列产品[object Object]：不支持此参数。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：适用于量化场景（x和weight为int8类型，输出为int8/fp16/bf16/int32类型），且为单tensor单专家的场景。
  • out（aclTensorList *，计算输出）：Device侧的aclTensorList，公式中的输出y，undefined支持ND，支持的最大长度为128个。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：数据类型支持FLOAT16、BFLOAT16、INT8、FLOAT32、INT32。
    • [object Object]Atlas 推理系列产品[object Object]：数据类型支持FLOAT16。
  • activationFeatureOutOptional（aclTensorList *，计算输出）：Device侧的aclTensorList，激活函数的输入数据，当前只支持传入nullptr。
  • dynQuantScaleOutOptional（aclTensorList *，计算输出）：Device侧的aclTensorList，当前只支持传入nullptr。
  • workspaceSize（uint64_t *，出参）：返回需要在Device侧申请的workspace大小。
  • executor（aclOpExecutor **，出参）：返回op执行器，包含了算子计算流程。

• 返回值：

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

  [object Object]

aclnnGroupedMatmulWeightNz

• 参数说明：

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

• 返回值：

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

约束说明

• 如果传入groupListOptional，当groupListType为0时，groupListOptional必须为非负单调非递减数列，当groupListType为1时，groupListOptional必须为非负数列，且长度不能为1，groupListType为2时，groupListOptional的第二列数据必须为非负数列，且长度不能为1。

• x和weight中每一组tensor的每一维大小在32字节对齐后都应小于int32的最大值2147483647。

• [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：

  • 非量化场景支持的输入类型为：

    • x为FLOAT16、weight为FLOAT16、biasOptional为FLOAT16、scaleOptional为空、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为空、activationInputOptional为空、out为FLOAT16。
    • x为BFLOAT16、weight为BFLOAT16、biasOptional为FLOAT32、scaleOptional为空、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为空、activationInputOptional为空、out为BFLOAT16。

  • 量化场景支持的输入类型为：

    • x为INT8、weight为INT8、biasOptional为INT32、scaleOptional为BFLOAT16、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为空或FLOAT32、activationInputOptional为空、out为BFLOAT16。
    • x为INT8、weight为INT8、biasOptional为INT32、scaleOptional为FLOAT32、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为空或为FLOAT32、activationInputOptional为空、out为FLOAT16。

  • 伪量化场景支持的输入类型为：

    • 伪量化参数antiquantScaleOptional和antiquantOffsetOptional的shape要满足下表（其中g为matmul组数，G为pergroup数，$G_i$为第i个tensor的pergroup数）：

      使用场景	子场景	shape限制
      伪量化perchannel	weight单	$[g, n]$
      伪量化perchannel	weight多	$[n_i]$
      伪量化pergroup	weight单	$[g, G, n]$
      伪量化pergroup	weight多	$[G_i, n_i]$

    • x为INT8、weight为INT4、biasOptional为FLOAT32、scaleOptional为UINT64、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为FLOAT32、activationInputOptional为空。此场景支持对称量化和非对称量化：
      • 对称量化场景：
        • 该场景下输出out的dtype为BFLOAT16或FLOAT16
        • 该场景下offsetOptional为空
        • 该场景下仅支持count模式（算子不会检查groupListType的值），k要求为quantGroupSize的整数倍，且要求k <= 18432。其中quantGroupSize为k方向上pergroup量化长度，当前支持quantGroupSize=256。
        • 该场景下scale为pergroup与perchannel离线融合后的结果，shape要求为$[e, quantGroupNum, n]$，其中$quantGroupNum=k \div quantGroupSize$。
        • Bias为计算过程中离线计算的辅助结果，值要求为$8\times weight \times scale$，并在第1维累加，shape要求为$[e, n]$。
        • 该场景下要求n为8的整数倍。
      • 非对称量化场景：
        • 该场景下输出out的dtype为为FLOAT16
        • 该场景下仅支持count模式（算子不会检查groupListType的值）。
        • 该场景下{k, n}要求为{7168, 4096}或者{2048, 7168}。
        • scale为pergroup与perchannel离线融合后的结果，shape要求为$[e, 1, n]$。
        • 该场景下offsetOptional不为空。非对称量化offsetOptional为计算过程中离线计算辅助结果，即$antiquantOffset \times scale$，shape要求为$[e, 1, n]$，dtype为FLOAT32。
        • Bias为计算过程中离线计算的辅助结果，值要求为$8\times weight \times scale$，并在第1维累加，shape要求为$[e, n]$。
        • 该场景下要求n为8的整数倍。

  • 伪量化场景下，若weight的类型为INT8，仅支持perchannel模式；若weight的类型为INT4，对称量化支持perchannel和pergroup两种模式。若为pergroup，pergroup数G或$G_i$必须要能整除对应的$k_i$。若weight为多tensor，定义pergroup长度$s_i = k_i / G_i$，要求所有$s_i(i=1,2,...g)$都相等。非对称量化支持perchannel模式。

  • 伪量化场景下若weight的类型为INT4，则weight中每一组tensor的最后一维大小都应是偶数。$weight_i$的最后一维指weight不转置时$weight_i$的N轴或当weight转置时$weight_i$的K轴。并且在pergroup场景下，当weight转置时，要求pergroup长度$s_i$是偶数。

  • 不同groupType支持场景:

    • 量化、伪量化仅支持groupType为-1和0场景。
    • 支持场景中单表示单tensor，多表示多tensor，表示顺序为x，weight，y，例如单多单表示支持x为单tensor，weight多tensor，y单tensor的场景。

      groupType	支持场景	场景限制
      -1	多多多	1）仅支持splitItem为0/1[object Object]2）x中tensor要求维度一致，支持2-6维，weight中tensor需为2维，y中tensor维度和x保持一致[object Object]3）groupListOptional必须传空[object Object]4）支持weight转置，但weight的tensorList中每个tensor是否转置需保持统一[object Object]5）x不支持转置
      0	单单单	1）仅支持splitItem为2/3[object Object]2）weight中tensor需为3维，x，y中tensor需为2维[object Object]3）必须传groupListOptional，且当groupListType为0时，最后一个值与x中tensor的第一维相等，当groupListType为1时，数值的总和与x中tensor的第一维相等，当groupListType为2时，第二列数值的总和与x中tensor的第一维相等[object Object]4）groupListOptional第1维最大支持1024，即最多支持1024个group[object Object]5）支持weight转置[object Object]6）x不支持转置
      0	单多单	1）仅支持splitItem为2/3[object Object]2）必须传groupListOptional，且当groupListType为0时，最后一个值与x中tensor的第一维相等，当groupListType为1时，数值的总和与x中tensor的第一维相等且长度最大为128，当groupListType为2时，第二列数值的总和与x中tensor的第一维相等且长度最大为128[object Object]3）x,weight,y中tensor需为2维[object Object]4）weight中每个tensor的N轴必须相等[object Object]5）支持weight转置，但weight的tensorList中每个tensor是否转置需保持统一[object Object]6）x不支持转置
      0	多多单	1）仅支持splitItem为2/3[object Object]2）x,weight,y中tensor需为2维[object Object]3）weight中每个tensor的N轴必须相等[object Object]4）若传入groupListOptional，当groupListType为0时，groupListOptional的差值需与x中tensor的第一维一一对应，当groupListType为1时，groupListOptional的数值需与x中tensor的第一维一一对应，且长度最大为128，当groupListType为2时，groupListOptional第二列的数值需与x中tensor的第一维一一对应，且长度最大为128[object Object]5）支持weight转置，但weight的tensorList中每个tensor是否转置需保持统一[object Object]6）x不支持转置

  • x和weight中每一组tensor的最后一维大小都应小于65536。$x_i$的最后一维指当x不转置时$x_i$的K轴或当x转置时$x_i$的M轴。$weight_i$的最后一维指当weight不转置时$weight_i$的N轴或当weight转置时$weight_i$的K轴。

  • 仅量化场景 (per-token)、反量化场景支持激活函数计算。

• [object Object]Atlas 推理系列产品[object Object]：

  • 输入输出只支持float16的数据类型，输出y的n轴大小需要是16的倍数。

    groupType	支持场景	场景限制
    0	单单单	1）仅支持splitItem为2/3[object Object]2）weight中tensor需为3维，x，y中tensor需为2维[object Object]3）必须传groupListOptional，且当groupListType为0时，最后一个值与x中tensor的第一维相等，当groupListType为1时，数值的总和与x中tensor的第一维相等[object Object]4）groupListOptional第1维最大支持1024，即最多支持1024个group[object Object]5）支持weight转置，不支持x转置

调用示例

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