aclnnGroupedMatmulV4
支持的产品型号
- Atlas A2训练系列产品/Atlas 800I A2推理产品
- Atlas 推理系列产品(Ascend 310P处理器)
接口原型
每个算子分为两段式接口,必须先调用“aclnnGroupedMatmulV4GetWorkspaceSize”接口获取入参并根据计算流程计算所需workspace大小,再调用“aclnnGroupedMatmulV4”接口执行计算。
aclnnStatus aclnnGroupedMatmulV4GetWorkspaceSize(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, aclTensorList *out, aclTensorList *activationFeatureOutOptional, aclTensorList *dynQuantScaleOutOptional, uint64_t *workspaceSize, aclOpExecutor **executor)
aclnnStatus aclnnGroupedMatmulV4(void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, aclrtStream stream)
功能描述
算子功能:实现分组矩阵乘计算,每组矩阵乘的维度大小可以不同。基本功能为矩阵乘,如,其中g为分组个数,为应对shape。输入输出数据类型均为aclTensorList,支持aclTensorList长度为1,对应的功能为:
- k轴分组:各不相同,但每组相同,此时可以在上拼接,对应aclTensorList长度为1。
- m轴分组:各组相同,可以在上拼接。
- n轴分组:各组相同,分别可以在上拼接。
相较于aclnnGroupedMatmulV3接口,此接口新增: - 支持静态量化(pertensor+perchannel)bfloat16输出,带激活及不带激活场景 - 支持动态量化(pertoken+perchannel)bfloat16和float16输出,带激活及不带激活场景。 - 支持groupListOptional中数值为分组轴上每组大小。
**说明:** 单tensor指一个tensor list中所有分组的tensor在groupType指定的分组轴上合并为1个;否则为多tensor。
- 计算公式:
- 非量化场景:
- 量化场景 (per-channel):
- 量化场景 (per-token):
- 反量化场景:
- 伪量化场景:
aclnnGroupedMatmulV4GetWorkspaceSize
参数说明:
- x(aclTensorList*,计算输入):必选参数,Device侧的aclTensorList,公式中的输入x,数据类型支持FLOAT16、BFLOAT16、INT8、FLOAT32,数据格式支持ND,支持的最大长度为128个。
- weight(aclTensorList*,计算输入):必选参数,Device侧的aclTensorList,公式中的weight,数据类型支持FLOAT16、BFLOAT16、INT8、FLOAT32,数据格式支持ND,支持的最大长度为128个。
- biasOptional(aclTensorList*,计算输入)可选参数,Device侧的aclTensorList,公式中的bias,数据类型支持FLOAT16、FLOAT32、INT32,数据格式支持ND,长度与weight相同。
- scaleOptional(aclTensorList*,计算输入)可选参数,Device侧的aclTensorList,代表量化参数中的缩放因子,数据类型支持UINT64、BFLOAT16,数据格式支持ND,长度与weight相同。
- offsetOptional(aclTensorList*,计算输入)可选参数,Device侧的aclTensorList,代表量化参数中的偏移量,数据类型支持FLOAT32,数据格式支持ND,长度与weight相同。
- antiquantScaleOptional(aclTensorList*,计算输入)可选参数,Device侧的aclTensorList,代表伪量化参数中的缩放因子,数据类型支持FLOAT16、BFLOAT16,数据格式支持ND,长度与weight相同。
- antiquantOffsetOptional(aclTensorList*,计算输入)可选参数,Device侧的aclTensorList,代表伪量化参数中的偏移量,数据类型支持FLOAT16、BFLOAT16,数据格式支持ND,长度与weight相同。
- perTokenScaleOptional(aclTensorList*,计算输入)可选参数,Device侧的aclTensorList,代表量化参数中的由x量化引入的缩放因子,数据类型支持FLOAT32,数据格式支持ND,只支持1维且长度与x相同。
- groupListOptional(aclTensor*,计算输入):可选参数,Host侧的aclTensor类型,代表输入和输出分组轴方向的matmul大小分布,数据类型支持INT64,数据格式支持ND。
- activationInputOptional(aclTensorList*,计算输入):可选参数,Host侧的aclTensorList类型,代表激活函数的反向输入,当前只支持传入nullptr。
- activationQuantScaleOptional*,计算输入):可选参数,Host侧的aclTensorList类型,当前只支持传入nullptr。
- activationQuantOffsetOptional*,计算输入):可选参数,Host侧的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轴分组,当前不支持n轴分组。
- groupListType(int64_t,计算输入):整数型参数,可取值0或1,0代表groupListOptional中数值为分组轴大小的cumsum结果(累积和),1代表groupListOptional中数值为分组轴上每组大小。
- actType(int64_t,计算输入):整数型参数,代表激活函数类型,取值范围为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;
- out(aclTensorList*,计算输出):Device侧的aclTensorList,公式中的输出y,数据类型支持FLOAT16、BFLOAT16、INT8、FLOAT32,数据格式支持ND,支持的最大长度为128个。
- activationFeatureOutOptional(aclTensorList*,计算输出):Device侧的aclTensorList,激活函数的输入数据,当前只支持传入nullptr。
- dynQuantScaleOutOptional*,计算输出):Device侧的aclTensorList,当前只支持传入nullptr。
- workspaceSize(uint64_t*,出参):返回需要在Device侧申请的workspace大小。
- executor(aclOpExecutor**,出参):返回op执行器,包含了算子计算流程。
返回值:
返回aclnnStatus状态码,具体参见aclnn返回码。
第一段接口完成入参校验,若出现以下错误码,则对应原因为: - 返回161001(ACLNN_ERR_PARAM_NULLPTR): 1.如果传入参数是必选输入、输出或者必选属性,且是空指针。 2.传入参数weight的元素存在空指针。 3.传入参数x的元素为空指针,且传出参数y的元素不为空指针。 4.传入参数x的元素不为空指针,且传出参数y的元素为空指针。 - 返回161002(ACLNN_ERR_PARAM_INVALID): 1.x、weight、biasOptional、scaleOptional、offsetOptional、antiquantScaleOptional、antiquantOffsetOptional、groupListOptional、splitItem、groupType、actType、y的数据类型和数据格式不在支持的范围内。 2.weight的长度大于128;若bias不为空,bias的长度不等于weight的长度。 3.groupListOptional维度为1。 4.splitItem为2、3的场景,y长度不等于1。 5.splitItem为0、1的场景,y长度不等于weight的长度,groupListOptional长度不等于weight的长度。
aclnnGroupedMatmulV4
参数说明:
- workspace(void*,入参):在Device侧申请的workspace内存地址。
- workspaceSize(uint64_t,入参):在Device侧申请的workspace大小,由第一段接口aclnnGroupedMatmulV4GetWorkspaceSize获取。
- executor(aclOpExecutor*,入参):op执行器,包含了算子计算流程。
- stream(aclrtStream,入参):指定执行任务的AscendCL stream流。
返回值:
返回aclnnStatus状态码,具体参见aclnn返回码。
约束与限制
非量化场景支持的输入类型为:
- x为FLOAT16、weight为FLOAT16、biasOptional为FLOAT16、scaleOptional为空、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为空、activationInputOptional为空、y为FLOAT16;
- x为BFLOAT16、weight为BFLOAT16、biasOptional为FLOAT32、scaleOptional为空、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为空、activationInputOptional为空、y为BFLOAT16;
- x为FLOAT32、weight为FLOAT32、biasOptional为FLOAT32、scaleOptional为空、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为空、activationInputOptional为空、y为FLOAT32(仅x、weight、y都为单tensor场景支持);
per-channel量化场景支持的输入类型为:
- x为INT8、weight为INT8、biasOptional为INT32、scaleOptional为UINT64、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为空、activationInputOptional为空、y为INT8;
per-token量化场景支持的输入类型为:
- x为INT8、weight为INT8、biasOptional为INT32、scaleOptional为BFLOAT16、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为FLOAT32、activationInputOptional为空、y为BFLOAT16;
- x为INT8、weight为INT8、biasOptional为INT32、scaleOptional为FLOAT32、offsetOptional为空、antiquantScaleOptional为空、antiquantOffsetOptional为空、perTokenScaleOptional为FLOAT32、activationInputOptional为空、y为FLOAT16;
伪量化场景支持的输入类型为:
- x为FLOAT16、weight为INT8、biasOptional为FLOAT16、scaleOptional为空,offsetOptional为空,antiquantScaleOptional为FLOAT16、antiquantOffsetOptional为FLOAT16、perTokenScaleOptional为空、activationInputOptional为空、y为FLOAT16;
- x为BFLOAT16、weight为INT8、biasOptional为FLOAT32、scaleOptional为空,offsetOptional为空,antiquantScaleOptional为BFLOAT16、antiquantOffsetOptional为BFLOAT16、perTokenScaleOptional为空、activationInputOptional为空、y为BFLOAT16;
在Atlas 推理系列产品(Ascend 310P处理器)上运行时,输入输出只支持float16的数据类型,输出y的n轴大小需要是16的倍数。
如果传入groupListOptional,当groupListType为0时,groupListOptional必须为非负单调非递减数列,当groupListType为1时,groupListOptional必须为非负数列,且长度不能为1。
不同groupType支持场景:
- 量化、伪量化仅支持groupType为-1和0场景。
- 支持场景中单表示单tensor,多表示多tensor,表示顺序为x,weight,y,例如单多单表示支持x为单tensor,weight多tensor,y单tensor的场景。
groupType 支持场景 场景限制 -1 多多多 1)仅支持splitItem为0/1
2)x中tensor支持2-6维,weight中tensor需为2维,y中tensor维度和x保持一致
3)groupListOptional必须传空0 单单单 1)仅支持splitItem为2/3
2)weight中tensor需为3维,x,y中tensor需为2维
3)必须传groupListOptional,且当groupListType为0时,最后一个值与x中tensor的第一维相等,当groupListType为1时,数值的总和与x中tensor的第一维相等
4)groupListOptional最大长度为10240 单多单 1)仅支持splitItem为2/3
2)必须传groupListOptional,且当groupListType为0时,最后一个值与x中tensor的第一维相等,当groupListType为1时,数值的总和与x中tensor的第一维相等,长度最大为128
3)x,weight,y中tensor需为2维
4)weight中每个tensor的N轴必须相等0 多多单 1)仅支持splitItem为2/3
2)x,weight,y中tensor需为2维
3)weight中每个tensor的N轴必须相等
4)若传入groupListOptional,当groupListType为0时,groupListOptional的差值需与x中tensor的第一维一一对应,当groupListType为1时,groupListOptional的数值需与x中tensor的第一维一一对应,且长度最大为1282 单单单 1)仅支持splitItem为2/3
2)x,weight中tensor需为2维,y中tensor需为3维
3)必须传groupListOptional,且当groupListType为0时,最后一个值与x中tensor的第二维相等,当groupListType为1时,数值的总和与x中tensor的第二维相等
4)groupListOptional最大长度为1024其中Atlas 推理系列产品(Ascend 310P处理器)仅支持x为单tensor,weight为单tensor,y为单tensor,且groupType为0的转置与非转置场景。
x和weight中每一组tensor的最后一维大小都应小于65536。的最后一维指当属性transpose_x为false时的K轴或当transpose_x为true时的M轴。的最后一维指当属性transpose_weight为false时的N轴或当transpose_weight为true时的K轴。
x和weight中每一组tensor的每一维大小在32字节对齐后都应小于int32的最大值2147483647。
仅量化场景 (per-token)、反量化场景支持激活函数计算。
调用示例
示例代码如下,仅供参考,具体编译和执行过程请参考编译与运行样例。
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_grouped_matmul_v4.h"
#define CHECK_RET(cond, return_expr) \
do { \
if (!(cond)) { \
return_expr; \
} \
} while (0)
#define LOG_PRINT(message, ...) \
do { \
printf(message, ##__VA_ARGS__); \
} while (0)
int64_t GetShapeSize(const std::vector<int64_t>& shape) {
int64_t shapeSize = 1;
for (auto i : shape) {
shapeSize *= i;
}
return shapeSize;
}
int Init(int32_t deviceId, aclrtStream* stream) {
// 固定写法,AscendCL初始化
auto ret = aclInit(nullptr);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret);
ret = aclrtSetDevice(deviceId);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret);
ret = aclrtCreateStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret);
return 0;
}
template <typename T>
int CreateAclTensor(const std::vector<int64_t>& shape, void** deviceAddr,
aclDataType dataType, aclTensor** tensor) {
auto size = GetShapeSize(shape) * sizeof(T);
// 调用aclrtMalloc申请Device侧内存
auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret);
// 调用aclrtMemcpy将Host侧数据拷贝到Device侧内存上
std::vector<T> hostData(size, 0);
ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret);
// 计算连续tensor的strides
std::vector<int64_t> strides(shape.size(), 1);
for (int64_t i = shape.size() - 2; i >= 0; i--) {
strides[i] = shape[i + 1] * strides[i + 1];
}
// 调用aclCreateTensor接口创建aclTensor
*tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND,
shape.data(), shape.size(), *deviceAddr);
return 0;
}
int CreateAclTensorList(const std::vector<std::vector<int64_t>>& shapes, void** deviceAddr,
aclDataType dataType, aclTensorList** tensor) {
int size = shapes.size();
aclTensor* tensors[size];
for (int i = 0; i < size; i++) {
int ret = CreateAclTensor<uint16_t>(shapes[i], deviceAddr + i, dataType, tensors + i);
CHECK_RET(ret == ACL_SUCCESS, return ret);
}
*tensor = aclCreateTensorList(tensors, size);
return ACL_SUCCESS;
}
int main() {
// 1. (固定写法)device/stream初始化,参考AscendCL对外接口列表
// 根据自己的实际device填写deviceId
int32_t deviceId = 0;
aclrtStream stream;
auto ret = Init(deviceId, &stream);
// check根据自己的需要处理
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);
// 2. 构造输入与输出,需要根据API的接口自定义构造
std::vector<std::vector<int64_t>> xShape = {{1, 16}, {4, 32}};
std::vector<std::vector<int64_t>> weightShape= {{16, 24}, {32, 16}};
std::vector<std::vector<int64_t>> biasShape = {{24}, {16}};
std::vector<std::vector<int64_t>> yShape = {{1, 24}, {4, 16}};
void* xDeviceAddr[2];
void* weightDeviceAddr[2];
void* biasDeviceAddr[2];
void* yDeviceAddr[2];
aclTensorList* x = nullptr;
aclTensorList* weight = nullptr;
aclTensorList* bias = nullptr;
aclTensor* groupedList = nullptr;
aclTensorList* scale = nullptr;
aclTensorList* offset = nullptr;
aclTensorList* antiquantScale = nullptr;
aclTensorList* antiquantOffset = nullptr;
aclTensorList* perTokenScale = nullptr;
aclTensorList* activationInput = nullptr;
aclTensorList* activationQuantScale = nullptr;
aclTensorList* activationQuantOffset = nullptr;
aclTensorList* y = nullptr;
aclTensorList* activationFeatureOut = nullptr;
aclTensorList* dynQuantScaleOut = nullptr;
int64_t splitItem = 0;
int64_t groupType = -1;
int64_t groupListType = 0;
int64_t actType = 0;
// 创建x aclTensorList
ret = CreateAclTensorList(xShape, xDeviceAddr, aclDataType::ACL_FLOAT16, &x);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建weight aclTensorList
ret = CreateAclTensorList(weightShape, weightDeviceAddr, aclDataType::ACL_FLOAT16, &weight);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建bias aclTensorList
ret = CreateAclTensorList(biasShape, biasDeviceAddr, aclDataType::ACL_FLOAT16, &bias);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建y aclTensorList
ret = CreateAclTensorList(yShape, yDeviceAddr, aclDataType::ACL_FLOAT16, &y);
CHECK_RET(ret == ACL_SUCCESS, return ret);
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 3. 调用CANN算子库API
// 调用aclnnGroupedMatmulV4第一段接口
ret = aclnnGroupedMatmulV4GetWorkspaceSize(x, weight, bias, scale, offset, antiquantScale, antiquantOffset, perTokenScale, groupedList, activationInput, activationQuantScale, activationQuantOffset, splitItem, groupType, groupListType, actType, y, activationFeatureOut, dynQuantScaleOut, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnGroupedMatmulGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
// 根据第一段接口计算出的workspaceSize申请device内存
void* workspaceAddr = nullptr;
if (workspaceSize > 0) {
ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
}
// 调用aclnnGroupedMatmulV4第二段接口
ret = aclnnGroupedMatmulV4(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnGroupedMatmul failed. ERROR: %d\n", ret); return ret);
// 4. (固定写法)同步等待任务执行结束
ret = aclrtSynchronizeStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);
// 5. 获取输出的值,将Device侧内存上的结果拷贝至Host侧,需要根据具体API的接口定义修改
for (int i = 0; i < 2; i++) {
auto size = GetShapeSize(yShape[i]);
std::vector<uint16_t> resultData(size, 0);
ret = aclrtMemcpy(resultData.data(), size * sizeof(resultData[0]), yDeviceAddr[i],
size * sizeof(resultData[0]), ACL_MEMCPY_DEVICE_TO_HOST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret);
for (int64_t j = 0; j < size; j++) {
LOG_PRINT("result[%ld] is: %d\n", j, resultData[j]);
}
}
// 6. 释放aclTensor和aclScalar,需要根据具体API的接口定义修改
aclDestroyTensorList(x);
aclDestroyTensorList(weight);
aclDestroyTensorList(bias);
aclDestroyTensorList(y);
// 7. 释放device资源,需要根据具体API的接口定义修改
for (int i = 0; i < 2; i++) {
aclrtFree(xDeviceAddr[i]);
aclrtFree(weightDeviceAddr[i]);
aclrtFree(biasDeviceAddr[i]);
aclrtFree(yDeviceAddr[i]);
}
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}