aclnnScale
产品支持情况
- Ascend 950PR&950DT系列产品:支持
- Atlas A3系列产品:支持
- Atlas A2系列产品:支持
- Atlas 200I/500 A2推理产品:不支持
- Atlas推理系列产品:支持
- Atlas训练系列产品:不支持
功能说明
-
接口功能:计算输入的scale和bias的结果。
-
计算公式:
若不输入bias,则
y=x∗scaley=x*scale
若输入bias,则
y=x∗scale+biasy=x*scale + bias
说明:scale/bias支持跟X的broadcast,scale/bias的shape规则如下
-
当scaleFromBlob为True时(axis转换为正数,numAxes为-1时表示到最后轴):
numAxes=0时,scale必须包含且仅包含一个元素,rank为0~8,允许
()、[1]、[1,1]等单元素形状按标量广播;x的rank为1~8,axis等通用约束仍须满足。numAxes=-1时,scaleShape为xShape[axis:];numAxes>0时,须满足axis + numAxes ≤ rank(xShape),scaleShape为xShape[axis:axis + numAxes]。
bias存在时,其shape和dtype必须与scale一致。
-
当scaleFromBlob为False时(axis转换为正数,numAxes不参与shape推导,但仍须满足numAxes>=-1):
scaleShape为xShape[axis:axis + rank(scaleShape)]
biasShape为xShape[axis:axis + rank(scaleShape)]
此分支须满足axis + rank(scaleShape) ≤ rank(xShape)。scale为
()或[1]时按标量广播;其余scaleShape必须逐维等于上述x窗口,不能用size-1维替代窗口中的非1维。bias存在时shape必须与scale相同。例如xShape=[2,4]、scaleShape=[4]、axis=1合法;scaleShape=[1,4]、axis=0会在第一阶段返回ACLNN_ERR_PARAM_INVALID(161002)。 -
示例:
-
scaleFromBlob = True:
xShape = [a, b, c, d, e, f] axis = 3 numAxes = 2 --> scaleShape = [d, e]
xShape = [a, b, c, d, e, f] axis = 3 numAxes = 3 --> scaleShape = [d, e, f]
xShape = [a, b, c, d, e, f] axis = 3 numAxes = -1 --> scaleShape = [d, e, f]
-
scaleFromBlob = False:
xShape = [a, b, c, d, e, f] axis = 3 rank(scaleShape) = 2 --> scaleShape = [d, e]
xShape = [a, b, c, d, e, f] axis = 3 rank(scaleShape) = 3 --> scaleShape = [d, e, f]
xShape = [a, b, c, d, e, f] axis = 3 rank(scaleShape) = 1 --> scaleShape = [d]
-
-
函数原型
每个算子分为两段式接口,必须先调用“aclnnScaleGetWorkspaceSize”接口获取计算所需workspace大小以及包含了算子计算流程的执行器,再调用“aclnnScale”接口执行计算。
aclnnStatus aclnnScaleGetWorkspaceSize(
const aclTensor* x,
const aclTensor* scale,
const aclTensor* bias,
int64_t axis,
int64_t numAxes,
bool scaleFromBlob,
aclTensor* y,
uint64_t* workspaceSize,
aclOpExecutor** executor)
aclnnStatus aclnnScale(
void* workspace,
uint64_t workspaceSize,
aclOpExecutor* executor,
aclrtStream stream)
aclnnScaleGetWorkspaceSize
-
参数说明:
参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor x(const aclTensor*) 输入 算子输入的Tensor。 不得为空指针。shape各维度的长度必须为非负数;支持零元素Tensor(shape中至少一维为0),但仍须满足shape、dtype、axis等参数约束;参数校验通过后返回同shape的空输出。秩为0的x没有合法axis,属于非法输入。 FLOAT、FLOAT16、BFLOAT16 ND 1-8 √ scale(const aclTensor*) 输入 算子输入的Tensor。 不得为空指针。数据类型需要与x的数据类型相同,shape各维度的长度必须为非负数且须满足broadcast要求(参见功能说明);仅当合法shape本身包含0维长时支持零元素Tensor,x非空时不能传入零元素scale。 FLOAT、FLOAT16、BFLOAT16 ND 0-8 √ bias(const aclTensor*) 可选输入 算子输入的Tensor。 可传nullptr表示不提供偏置。指针非空时,数据类型和shape必须与scale一致,即使bias为零元素Tensor也须满足此要求;零元素bias不等同于nullptr。 FLOAT、FLOAT16、BFLOAT16 ND 0-8 √ axis(int64_t) 输入 指定进行scale的起始轴。 取值范围[-x_rank, x_rank)(x_rank表示x的shape维度)。 - - - - numAxes(int64_t) 输入 指定进行scale的轴长度。 True/False分支均要求取值>=-1。仅当scaleFromBlob为True时,numAxes=-1表示从axis轴开始scale到最后一轴;False时不参与shape推导。 - - - - scaleFromBlob(bool) 输入 指定要scaleFromBlob类型。 - True:scale from blob,使用numAxes + axis进行scale;
- False:scale from input scale,从axis开始按scale的rank推导shape;numAxes不参与shape推导,但仍须>=-1。
- - - - y(aclTensor*) 输出 输出Tensor。 不得为空指针。支持空Tensor。数据类型必须与x相同,shape必须与x完全一致(维数以及每一维的长度均相同)。 FLOAT、FLOAT16、BFLOAT16 ND 1-8 √ workspaceSize(uint64_t*) 输出 返回需要在Device侧申请的workspace大小。 必须为有效的非空输出地址。实际workspace大小以本接口返回值为准,可能包含非连续输入转换、中间结果和输出回拷所需的临时空间。 - - - - executor(aclOpExecutor**) 输出 返回op执行器,包含了算子计算流程。 必须为有效的非空输出地址。 - - - - - Atlas推理系列产品:不支持BFLOAT16。
-
返回值:
aclnnStatus:返回状态码,具体参见aclnn返回码。
第一段接口完成入参校验,出现以下场景时报错:
返回码 码值 描述 ACLNN_ERR_PARAM_NULLPTR 161001 传入的x、scale、y、workspaceSize或executor是空指针。 ACLNN_ERR_PARAM_INVALID 161002 x的数据类型不在支持的范围之内。 bias指针非空时,bias与scale的数据类型不一致。 scale与x的数据类型不一致。 y与x的数据类型不一致。 x和y的shape不一致。 bias指针非空时,bias与scale的shape不一致。 x的秩不在1~8范围内,scale或bias的秩大于8,或者x、scale、bias、y的shape包含负维度长度。 axis的取值不在[-x_rank, x_rank)范围内。 numAxes的取值小于-1。 scaleFromBlob为True,numAxes等于0且scale的元素总数不等于1。 scaleFromBlob为True且numAxes>0时,axis转换为正数之后与numAxes相加,大于x_rank。 scale的shape与预期不符(预期shape推导参考功能说明)。
aclnnScale
-
参数说明:
参数名 输入/输出 描述 workspace 输入 在Device侧申请的workspace内存地址。 workspaceSize 输入 在Device侧申请的workspace大小,由第一段接口aclnnScaleGetWorkspaceSize获取。 executor 输入 op执行器,包含了算子计算流程。 stream 输入 指定执行任务的Stream。 -
返回值:
aclnnStatus:返回状态码,具体参见aclnn返回码。
约束说明
- aclnnScale默认确定性实现。
- x、scale、bias、y的数据类型必须一致;bias为nullptr时不参与校验。
- y的shape必须与x完全一致,包含维数及每一维的长度。
- bias不为nullptr时,其shape必须与scale完全一致。
- scale的shape必须满足功能说明中的广播窗口规则。
- 支持非连续的Tensor,维数不超过8。
- 参数表中的ND为公开保证的数据格式。接口不对所有非ND格式统一报错;非ND描述可能由框架转换后执行,不代表任意非ND格式组合均受支持。
- 可执行的Tensor规模受设备可用内存及框架资源限制;本接口未规定统一的2³¹元素或4GiB字节上限。
- Ascend 950PR&950DT系列产品:FLOAT16、BFLOAT16输入使用FLOAT计算,结果转换回输入的数据类型;FLOAT输入直接计算。
调用示例
示例代码如下,仅供参考,具体编译和执行过程请参考编译与运行样例。
#include <iostream>
#include <memory>
#include <type_traits>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_scale.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;
}
using StreamPtr = std::unique_ptr<std::remove_pointer<aclrtStream>::type, decltype(&aclrtDestroyStream)>;
using DeviceMemPtr = std::unique_ptr<void, decltype(&aclrtFree)>;
using TensorPtr = std::unique_ptr<aclTensor, decltype(&aclDestroyTensor)>;
int Init(int32_t deviceId, StreamPtr& stream, bool& initialized, bool& deviceSet) {
// 固定写法,资源初始化
auto ret = aclInit(nullptr);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret);
initialized = true;
ret = aclrtSetDevice(deviceId);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret);
deviceSet = true;
aclrtStream rawStream = nullptr;
ret = aclrtCreateStream(&rawStream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret);
stream.reset(rawStream);
return 0;
}
template <typename T>
int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, aclDataType dataType,
DeviceMemPtr& deviceAddr, TensorPtr& tensor) {
auto size = GetShapeSize(shape) * sizeof(T);
// 调用aclrtMalloc申请device侧内存
void* rawDeviceAddr = nullptr;
auto ret = aclrtMalloc(&rawDeviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret);
deviceAddr.reset(rawDeviceAddr);
// 调用aclrtMemcpy将host侧数据拷贝到device侧内存上
ret = aclrtMemcpy(deviceAddr.get(), 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
aclTensor* rawTensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0,
aclFormat::ACL_FORMAT_ND, shape.data(), shape.size(), deviceAddr.get());
CHECK_RET(rawTensor != nullptr, LOG_PRINT("aclCreateTensor failed.\n"); return ACL_ERROR_FAILURE);
tensor.reset(rawTensor);
return 0;
}
int main() {
// 1.(固定写法)device/stream初始化,参考acl API手册
// 根据自己的实际device填写deviceId
int32_t deviceId = 0;
bool initialized = false;
bool deviceSet = false;
std::shared_ptr<void> aclGuard(nullptr, [&](void*) {
if (deviceSet) {
aclrtResetDevice(deviceId);
}
if (initialized) {
aclFinalize();
}
});
StreamPtr stream(nullptr, &aclrtDestroyStream);
auto ret = Init(deviceId, stream, initialized, deviceSet);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);
// 2.构造输入与输出,需要根据API的接口自定义构造
std::vector<int64_t> selfShape = {4, 2};
std::vector<int64_t> tensor1Shape = {4};
std::vector<int64_t> tensor2Shape = {4};
std::vector<int64_t> outShape = {4, 2};
DeviceMemPtr selfDeviceAddr(nullptr, &aclrtFree);
DeviceMemPtr tensor1DeviceAddr(nullptr, &aclrtFree);
DeviceMemPtr tensor2DeviceAddr(nullptr, &aclrtFree);
DeviceMemPtr outDeviceAddr(nullptr, &aclrtFree);
TensorPtr self(nullptr, &aclDestroyTensor);
TensorPtr tensor1(nullptr, &aclDestroyTensor);
TensorPtr tensor2(nullptr, &aclDestroyTensor);
TensorPtr out(nullptr, &aclDestroyTensor);
std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7};
std::vector<float> tensor1HostData = {2, 2, 2, 2};
std::vector<float> tensor2HostData = {2, 2, 2, 2};
std::vector<float> outHostData = {0, 0, 0, 0, 0, 0, 0, 0};
int64_t axis = 0;
int64_t numAxes = 1;
bool fromBlob = true;
// 创建self aclTensor
ret = CreateAclTensor(selfHostData, selfShape, aclDataType::ACL_FLOAT, selfDeviceAddr, self);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建tensor1 aclTensor
ret = CreateAclTensor(tensor1HostData, tensor1Shape, aclDataType::ACL_FLOAT, tensor1DeviceAddr, tensor1);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建tensor2 aclTensor
ret = CreateAclTensor(tensor2HostData, tensor2Shape, aclDataType::ACL_FLOAT, tensor2DeviceAddr, tensor2);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建out aclTensor
ret = CreateAclTensor(outHostData, outShape, aclDataType::ACL_FLOAT, outDeviceAddr, out);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 3.调用CANN算子库API,需要修改为具体的API名称
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnScale第一段接口
ret = aclnnScaleGetWorkspaceSize(self.get(), tensor1.get(), tensor2.get(), axis, numAxes, fromBlob, out.get(),
&workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnScaleGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
// 根据第一段接口计算出的workspaceSize申请device内存
DeviceMemPtr workspaceAddr(nullptr, &aclrtFree);
if (workspaceSize > 0) {
void* rawWorkspaceAddr = nullptr;
ret = aclrtMalloc(&rawWorkspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
workspaceAddr.reset(rawWorkspaceAddr);
}
// 调用aclnnScale第二段接口
ret = aclnnScale(workspaceAddr.get(), workspaceSize, executor, stream.get());
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnScale failed. ERROR: %d\n", ret); return ret);
// 4.(固定写法)同步等待任务执行结束
ret = aclrtSynchronizeStream(stream.get());
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);
// 5.获取输出的值,将device侧内存上的结果拷贝至host侧,需要根据具体API的接口定义修改
auto size = GetShapeSize(outShape);
std::vector<float> resultData(size, 0);
ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]),
outDeviceAddr.get(), size * sizeof(resultData[0]), ACL_MEMCPY_DEVICE_TO_HOST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy resultData from device to host failed. ERROR: %d\n", ret);
return ret);
for (int64_t i = 0; i < size; i++) {
LOG_PRINT("resultData[%ld] is: %f\n", i, resultData[i]);
}
return 0;
}