已合并
docs: 新增BatchMatMulV3/MatMulV3算子Ascend IR接口文档 #10433
林泽辉创建于 9月15日
docs: 新增BatchMatMulV3/MatMulV3算子Ascend IR接口文档 #10433
已合并
共 2 个文件变更+187-0
| @@ -0,0 +1,92 @@ | |||
| 1 | +# BatchMatMulV3 | ||
| 2 | + | ||
| 3 | +## 产品支持情况 | ||
| 4 | + | ||
| 5 | +<!-- npu="950" id1 --> | ||
| 6 | +- <term>Ascend 950PR/Ascend 950DT</term>：支持 | ||
| 7 | +<!-- end id1 --> | ||
| 8 | +<!-- npu="A3" id2 --> | ||
| 9 | +- <term>Atlas A3 训练系列产品/Atlas A3 推理系列产品</term>：支持 | ||
| 10 | +<!-- end id2 --> | ||
| 11 | +<!-- npu="910b" id3 --> | ||
| 12 | +- <term>Atlas A2 训练系列产品/Atlas A2 推理系列产品</term>：支持 | ||
| 13 | +<!-- end id3 --> | ||
| 14 | +<!-- npu="310b" id4 --> | ||
| 15 | +- <term>Atlas 200I/500 A2 推理产品</term>：不支持 | ||
| 16 | +<!-- end id4 --> | ||
| 17 | +<!-- npu="310p" id5 --> | ||
| 18 | +- <term>Atlas 推理系列产品</term>：支持 | ||
| 19 | +<!-- end id5 --> | ||
| 20 | +<!-- npu="910" id6 --> | ||
| 21 | +- <term>Atlas 训练系列产品</term>：支持 | ||
| 22 | +<!-- end id6 --> | ||
| 23 | + | ||
| 24 | +## 功能说明 | ||
| 25 | + | ||
| 26 | +- 算子功能：完成带batch维度的矩阵乘计算，输入支持2~6维，前若干维为batch维度（支持batch维广播），最后两维做矩阵乘计算，并支持在乘法结果上累加偏置向量（bias）。 | ||
| 27 | +- 计算公式： | ||
| 28 | + | ||
| 29 | + $$ | ||
| 30 | + y = x1 @ x2 + bias | ||
| 31 | + $$ | ||
| 32 | + | ||
| 33 | + 其中： | ||
| 34 | + - $x1$：左矩阵，最后两维为$(M, K)$；当adj_x1=true时，$x1$传入的最后两维为$(K, M)$，计算时逻辑转置为$(M, K)$。 | ||
| 35 | + - $x2$：右矩阵，最后两维为$(K, N)$；当adj_x2=true时，$x2$传入的最后两维为$(N, K)$，计算时逻辑转置为$(K, N)$。 | ||
| 36 | + - $bias$：维度为$(N)$、$(1, N)$或$(B, 1, N)$的偏置向量，逐元素累加到乘法结果对应列上。 | ||
| 37 | + - $y$：输出矩阵，最后两维为$(M, N)$，batch维度为$x1$与$x2$广播后的结果。例如$x1$、$x2$输入维度分别为$(B, M, K)$、$(B, K, N)$时，$y$维度为$(B, M, N)$。B为矩阵乘法的batch数，M为$x1$的行数和$y$的行数，N为$x2$的列数和$y$的列数，K为$x1$的列数和$x2$的行数。 | ||
| 38 | + | ||
| 39 | +## Ascend IR定义 | ||
| 40 | + | ||
| 41 | +Ascend IR定义所在头文件路径：[batch_mat_mul_v3_proto.h](../op_graph/batch_mat_mul_v3_proto.h) | ||
| 42 | + | ||
| 43 | +```cpp | ||
| 44 | +REG_OP(BatchMatMulV3) | ||
| 45 | + .INPUT(x1, TensorType({DT_FLOAT16, DT_BF16, DT_FLOAT})) | ||
| 46 | + .INPUT(x2, TensorType({DT_FLOAT16, DT_BF16, DT_FLOAT})) | ||
| 47 | + .OPTIONAL_INPUT(bias, TensorType({DT_FLOAT16, DT_FLOAT, DT_BF16})) | ||
| 48 | + .OUTPUT(y, TensorType({DT_FLOAT16, DT_BF16, DT_FLOAT})) | ||
| 49 | + .OPTIONAL_INPUT(offset_w, TensorType({DT_INT8, DT_INT4})) | ||
| 50 | + .ATTR(adj_x1, Bool, false) | ||
| 51 | + .ATTR(adj_x2, Bool, false) | ||
| 52 | + .ATTR(offset_x, Int, 0) | ||
| 53 | + .ATTR(enable_hf32, Bool, false) | ||
| 54 | + .OP_END_FACTORY_REG(BatchMatMulV3) | ||
| 55 | +``` | ||
| 56 | + | ||
| 57 | +## 参数说明 | ||
| 58 | + | ||
| 59 | +| 参数名 | 输入/属性/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度（shape） | | ||
| 60 | +| ------ | -------------- | ---- | -------- | -------- | -------- | ------------- | | ||
| 61 | +| x1 | 必选输入 | 矩阵乘运算的左矩阵，公式中的$x1$。 | adj_x1=false时，最后两维为(M, K)；adj_x1=true时，最后两维为(K, M)，计算时逻辑转置为(M, K)参与计算。 | FLOAT16、BFLOAT16、FLOAT32 | ND、FRACTAL_NZ | 2~6 | | ||
| 62 | +| x2 | 必选输入 | 矩阵乘运算的右矩阵，公式中的$x2$。 | adj_x2=false时，最后两维为(K, N)；adj_x2=true时，最后两维为(N, K)，计算时逻辑转置为(K, N)参与计算。Reduce维度K需与x1一致。 | FLOAT16、BFLOAT16、FLOAT32 | ND、FRACTAL_NZ | 2~6 | | ||
| 63 | +| bias | 可选输入 | 矩阵乘运算结果上累加的偏置向量，公式中的$bias$。 | N需与x2的N维一致。 | FLOAT16、BFLOAT16、FLOAT32 | ND | 1~3 | | ||
| 64 | +| offset_w | 可选输入 | 权重量化偏移矩阵。 | 预留参数，当前暂不支持。 | INT8、INT4 | ND | 2 | | ||
| 65 | +| y | 必选输出 | 矩阵乘运算的计算结果，公式中的$y$。 | batch维度为x1与x2广播后的结果。 | FLOAT16、BFLOAT16、FLOAT32 | ND、FRACTAL_NZ | 2~6 | | ||
| 66 | +| adj_x1 | 必选属性 | 指示左矩阵x1参与矩阵乘前是否转置。 | 默认值false；取值true时x1最后两维逻辑转置后参与计算。 | Bool | - | - | | ||
| 67 | +| adj_x2 | 必选属性 | 指示右矩阵x2参与矩阵乘前是否转置。 | 默认值false；取值true时x2最后两维逻辑转置后参与计算。 | Bool | - | - | | ||
| 68 | +| offset_x | 必选属性 | 左矩阵x1的量化偏移。 | 预留参数，当前暂不支持。默认值0。 | Int | - | - | | ||
| 69 | +| enable_hf32 | 必选属性 | 指示是否以HFLOAT32（高精度浮点32位）模式执行计算。 | 默认值false。 | Bool | - | - | | ||
| 70 | + | ||
| 71 | +<!-- npu="950" id7 --> | ||
| 72 | +- <term>Ascend 950PR/Ascend 950DT</term>：仅x2支持FRACTAL_NZ格式。 | ||
| 73 | +<!-- end id7 --> | ||
| 74 | +<!-- npu="A3,910b" id8 --> | ||
| 75 | +- <term>Atlas A3 训练系列产品/Atlas A3 推理系列产品</term>、<term>Atlas A2 训练系列产品/Atlas A2 推理系列产品</term>：bias不支持BFLOAT16数据类型。 | ||
| 76 | +<!-- end id8 --> | ||
| 77 | +<!-- npu="310p" id9 --> | ||
| 78 | +- <term>Atlas 推理系列产品</term>：仅支持FLOAT16数据类型，且x2仅支持FRACTAL_NZ格式。 | ||
| 79 | +<!-- end id9 --> | ||
| 80 | + | ||
| 81 | +## 约束说明 | ||
| 82 | + | ||
| 83 | +- 确定性计算：默认确定性实现。 | ||
| 84 | +- 支持空tensor，空tensor场景下不支持bias。 | ||
| 85 | +- 支持连续tensor，[非连续tensor](../../../docs/zh/context/non_contiguous_tensor.md)仅支持转置场景。 | ||
| 86 | +- x1与x2的batch维度需满足[broadcast关系](../../../docs/zh/context/broadcast_relationship.md)，Reduce维度K需大小相等。 | ||
| 87 | + | ||
| 88 | +## 调用示例 | ||
| 89 | + | ||
| 90 | +| 调用方式 | 样例代码 | 说明 | | ||
| 91 | +| ---------------- | --------------------------- | --------------------------------------------------- | | ||
| 92 | +| aclnn接口 | [test_aclnn_batchmatmul](../examples/test_aclnn_batchmatmul.cpp) | 通过<br>[aclnnAddbmm&aclnnInplaceAddbmm](aclnnAddbmm&aclnnInplaceAddbmm.md)<br>[aclnnBaddbmm&aclnnInplaceBaddbmm](aclnnBaddbmm&aclnnInplaceBaddbmm.md)<br>[aclnnBatchMatMul](aclnnBatchMatMul.md)<br>[aclnnBatchMatMulWeightNz](aclnnBatchMatMulWeightNz.md)<br>等方式调用BatchMatMulV3算子。 | | ||
| @@ -0,0 +1,95 @@ | |||
| 1 | +# MatMulV3 | ||
| 2 | + | ||
| 3 | +## 产品支持情况 | ||
| 4 | + | ||
| 5 | +<!-- npu="950" id1 --> | ||
| 6 | +- <term>Ascend 950PR/Ascend 950DT</term>：支持 | ||
| 7 | +<!-- end id1 --> | ||
| 8 | +<!-- npu="A3" id2 --> | ||
| 9 | +- <term>Atlas A3 训练系列产品/Atlas A3 推理系列产品</term>：支持 | ||
| 10 | +<!-- end id2 --> | ||
| 11 | +<!-- npu="910b" id3 --> | ||
| 12 | +- <term>Atlas A2 训练系列产品/Atlas A2 推理系列产品</term>：支持 | ||
| 13 | +<!-- end id3 --> | ||
| 14 | +<!-- npu="310b" id4 --> | ||
| 15 | +- <term>Atlas 200I/500 A2 推理产品</term>：不支持 | ||
| 16 | +<!-- end id4 --> | ||
| 17 | +<!-- npu="310p" id5 --> | ||
| 18 | +- <term>Atlas 推理系列产品</term>：支持 | ||
| 19 | +<!-- end id5 --> | ||
| 20 | +<!-- npu="910" id6 --> | ||
| 21 | +- <term>Atlas 训练系列产品</term>：不支持 | ||
| 22 | +<!-- end id6 --> | ||
| 23 | + | ||
| 24 | +## 功能说明 | ||
| 25 | + | ||
| 26 | +- 算子功能：完成两个二维矩阵的通用矩阵乘（GEMM）计算，支持通过属性分别控制左矩阵、右矩阵在参与计算前是否转置，并支持在乘法结果上按列累加偏置向量（bias），即"乘、加"一步完成。 | ||
| 27 | +- 计算公式： | ||
| 28 | + | ||
| 29 | + $$ | ||
| 30 | + y = op(x1) @ op(x2) + bias | ||
| 31 | + $$ | ||
| 32 | + | ||
| 33 | + 其中： | ||
| 34 | + - $op(x1)$：参与矩阵乘的左矩阵，维度为$(M, K)$。当transpose_x1=false时，$op(x1)=x1$；当transpose_x1=true时，$op(x1)=x1^T$（x1传入为$(K, M)$，计算时逻辑转置为$(M, K)$）。 | ||
| 35 | + - $op(x2)$：参与矩阵乘的右矩阵，维度为$(K, N)$。当transpose_x2=false时，$op(x2)=x2$；当transpose_x2=true时，$op(x2)=x2^T$（x2传入为$(N, K)$，计算时逻辑转置为$(K, N)$）。 | ||
| 36 | + - $bias$：维度为$(N)$或$(1, N)$的偏置向量，逐元素累加到乘法结果对应列上。 | ||
| 37 | + - $y$：输出矩阵，维度为$(M, N)$。 | ||
| 38 | + | ||
| 39 | +## Ascend IR定义 | ||
| 40 | + | ||
| 41 | +Ascend IR定义所在头文件路径：[mat_mul_v3_proto.h](../op_graph/mat_mul_v3_proto.h) | ||
| 42 | + | ||
| 43 | +```cpp | ||
| 44 | +REG_OP(MatMulV3) | ||
| 45 | + .INPUT(x1, TensorType({DT_FLOAT16, DT_BF16, DT_FLOAT})) | ||
| 46 | + .INPUT(x2, TensorType({DT_FLOAT16, DT_BF16, DT_FLOAT})) | ||
| 47 | + .OPTIONAL_INPUT(bias, TensorType({DT_FLOAT, DT_FLOAT16, DT_BF16})) | ||
| 48 | + .OUTPUT(y, TensorType({DT_FLOAT16, DT_BF16, DT_FLOAT})) | ||
| 49 | + .OPTIONAL_INPUT(offset_w, TensorType({DT_INT8, DT_INT4})) | ||
| 50 | + .ATTR(transpose_x1, Bool, false) | ||
| 51 | + .ATTR(transpose_x2, Bool, false) | ||
| 52 | + .ATTR(offset_x, Int, 0) | ||
| 53 | + .ATTR(opImplMode, Int, 0x1) | ||
| 54 | + .OP_END_FACTORY_REG(MatMulV3) | ||
| 55 | +``` | ||
| 56 | + | ||
| 57 | +## 参数说明 | ||
| 58 | + | ||
| 59 | +| 参数名 | 输入/属性/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度（shape） | | ||
| 60 | +| ------ | -------------- | ---- | -------- | -------- | -------- | ------------- | | ||
| 61 | +| x1 | 必选输入 | 矩阵乘运算的左矩阵，公式中的$op(x1)$。 | transpose_x1=false时，shape为(M, K)；transpose_x1=true时，shape为(K, M)，计算时逻辑转置为(M, K)参与计算。 | FLOAT16、BFLOAT16、FLOAT32 | ND、FRACTAL_NZ | 2 | | ||
| 62 | +| x2 | 必选输入 | 矩阵乘运算的右矩阵，公式中的$op(x2)$。 | transpose_x2=false时，shape为(K, N)；transpose_x2=true时，shape为(N, K)，计算时逻辑转置为(K, N)参与计算。FRACTAL_NZ格式下为4维：不转置时排布为(n1, k1, k0, n0)，转置时排布为(k1, n1, n0, k0)，其中k0=16、n0=16。 | FLOAT16、BFLOAT16、FLOAT32 | ND、FRACTAL_NZ | 2（ND）或4（NZ） | | ||
| 63 | +| bias | 可选输入 | 矩阵乘运算结果上累加的偏置向量，公式中的$bias$。 | 长度需与x2的N维一致。 | FLOAT16、BFLOAT16、FLOAT32 | ND | 1~2 | | ||
| 64 | +| offset_w | 可选输入 | 权重量化偏移矩阵。 | 预留参数，当前暂不支持。 | INT8、INT4 | ND | 2 | | ||
| 65 | +| y | 必选输出 | 矩阵乘运算的计算结果，公式中的$y$。 | - | FLOAT16、BFLOAT16、FLOAT32 | ND、FRACTAL_NZ | 2 | | ||
| 66 | +| transpose_x1 | 必选属性 | 指示左矩阵x1参与矩阵乘前是否转置。 | 默认值false；取值true时x1逻辑转置后参与计算。 | Bool | - | - | | ||
| 67 | +| transpose_x2 | 必选属性 | 指示右矩阵x2参与矩阵乘前是否转置。 | 默认值false；取值true时x2逻辑转置后参与计算。 | Bool | - | - | | ||
| 68 | +| offset_x | 必选属性 | 左矩阵x1的量化偏移。 | 预留参数，当前暂不支持。默认值0。 | Int | - | - | | ||
| 69 | +| opImplMode | 必选属性 | 算子实现模式。 | 默认值0x1（default）。支持的取值：0x1（default，默认模式）、0x2（high_performance，高性能模式）、0x4（high_precision，高精度模式）、0x8（super_performance，超高性能模式）、0x10（support_of_bound_index）、0x20（enable_float_32_execution，FLOAT32执行）、0x40（enable_hi_float_32_execution，HF32执行）。 | Int | - | - | | ||
| 70 | + | ||
| 71 | +<!-- npu="950" id7 --> | ||
| 72 | +- <term>Ascend 950PR/Ascend 950DT</term>：仅x2支持FRACTAL_NZ格式。 | ||
| 73 | +<!-- end id7 --> | ||
| 74 | +<!-- npu="A3,910b" id8 --> | ||
| 75 | +- <term>Atlas A3 训练系列产品/Atlas A3 推理系列产品</term>、<term>Atlas A2 训练系列产品/Atlas A2 推理系列产品</term>：不支持FRACTAL_NZ格式，bias不支持BFLOAT16数据类型。 | ||
| 76 | +<!-- end id8 --> | ||
| 77 | +<!-- npu="310p" id9 --> | ||
| 78 | +- <term>Atlas 推理系列产品</term>：仅支持FLOAT16数据类型，且x2仅支持FRACTAL_NZ格式。 | ||
| 79 | +<!-- end id9 --> | ||
| 80 | + | ||
| 81 | +## 约束说明 | ||
| 82 | + | ||
| 83 | +- 确定性计算：默认确定性实现。 | ||
| 84 | +- 支持空tensor，空tensor场景下不支持bias。 | ||
| 85 | +- 支持连续tensor，[非连续tensor](../../../docs/zh/context/non_contiguous_tensor.md)仅支持转置场景。 | ||
| 86 | +- x1与x2需满足数据类型[互推导关系](../../../docs/zh/context/deduction_relationship.md)。 | ||
| 87 | +<!-- npu="A3,910b" id10 --> | ||
| 88 | +- <term>Atlas A2 训练系列产品/Atlas A2 推理系列产品</term>、<term>Atlas A3 训练系列产品/Atlas A3 推理系列产品</term>：不支持两个输入分别为BFLOAT16和FLOAT16、BFLOAT16和FLOAT32的类型推导。 | ||
| 89 | +<!-- end id10 --> | ||
| 90 | + | ||
| 91 | +## 调用示例 | ||
| 92 | + | ||
| 93 | +| 调用方式 | 样例代码 | 说明 | | ||
| 94 | +| ---------------- | --------------------------- | --------------------------------------------------- | | ||
| 95 | +| aclnn接口 | [test_aclnn_addmm](../examples/test_aclnn_addmm_aclnninplace_addmm.cpp) | 通过<br> - [aclnnAddmm&aclnnInplaceAddmm](aclnnAddmm&aclnnInplaceAddmm.md)<br> - [aclnnMatmul](aclnnMatmul.md)<br> - [aclnnMatmulWeightNz](aclnnMatmulWeightNz.md)<br> - [aclnnMm](aclnnMm.md)<br>- [aclnnAddmmWeightNz](aclnnAddmmWeightNz.md)<br>等方式调用MatMulV3算子。 | | ||