CANN ops-math 算子开发指南:aclnnTransConvolutionWeight 卷积权重格式转换接口详解
CANN ops-math 算子开发指南:aclnnTransConvolutionWeight 卷积权重格式转换接口详解
导读
aclnnTransConvolutionWeight 是 CANN ops-math 开源仓库(数学类基础计算算子库)中 conversion/trans_data 目录下提供的一个 L2 级 aclnn 接口,用于将 Convolution 算子的 NCHW 权重 Tensor 预转换为对计算性能更亲和的私有格式(FRACTAL_Z),并同步完成 Float32 到 Float16 的数据类型转换。本文以该接口的官方文档为主体,结合仓库中的 接口头文件、接口实现源码 与 L2 单元测试,完整讲解其两段式调用方式、参数约束、返回码语义、源码级实现原理与可编译运行的完整示例,帮助开发者在 Atlas 推理系列产品上正确使用该接口做 Convolution 权重预处理,从而提升算子执行性能。
产品支持情况
与仓库中所有算子文档一致,该接口按 NPU 型号声明支持范围。根据 aclnnTransConvolutionWeight 官方文档,各产品的支持情况如下:
| 产品类型 | 支持情况 |
|---|---|
| Ascend 950PR / Ascend 950DT | 不支持 |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | 不支持 |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | 不支持 |
| Atlas 200I/500 A2 推理产品 | 不支持 |
| Atlas 推理系列产品 | 支持 |
| Atlas 训练系列产品 | 不支持 |
从源码中也可以印证这一点:aclnn_trans_convolution_weight.cpp 中的 CheckParams 会读取当前平台信息,通过 GetCurNpuArch() 判断架构是否为 NpuArch::DAV_2002(即 Atlas 推理系列产品对应的架构),否则直接返回 ACLNN_ERR_PARAM_INVALID 并打印 "only support ascend310P" 日志。在编写调用代码前,务必先确认目标设备属于 Atlas 推理系列产品。
功能说明:与 aclnnCalculateConvolutionWeightSize 配套使用
aclnnTransConvolutionWeight 的功能是创建一个对于 Convolution 算子计算性能亲和的 weight Tensor。它需要与 aclnnCalculateConvolutionWeightSize 接口配套使用:
- aclnnCalculateConvolutionWeightSize:Host 侧纯计算接口,在 Convolution 算子 NCHW 格式输入下,根据 shape 计算出权重经过格式转换后实际需要多少个元素(elements)的数据量,用于确定转换后权重 Tensor 的内存大小,仅支持 Float16 数据类型。例如输入 shape 为
[2, 4, 8, 8]时,该函数出于性能角度考虑,会将 shape 变换为[64, 1, 16, 16],因此返回的元素数为 16384。 - aclnnTransConvolutionWeight:真正执行转换的 Device 侧算子接口,将输入权重转换为私有格式(FRACTAL_Z)并 cast 为 Float16。
两者构成典型的"先算尺寸、再申请内存、后执行转换"的使用链路,示例代码中的 CreateWeightAclTensor 辅助函数正是先调用 aclnnCalculateConvolutionWeightSize 拿到 transWeightSize,再据此为转换结果 Tensor 申请 Device 内存。
两段式接口与函数原型
每个 aclnn 算子通常采用两段式接口(详见 两段式接口说明):必须先调用 GetWorkspaceSize 第一段接口,完成入参校验、计算流程编排并获取计算所需 workspace 大小以及包含算子计算流程的执行器(executor);再按照 workspaceSize 在 Device 侧申请内存,最后调用第二段接口执行计算。
aclnnTransConvolutionWeight 的两段函数原型如下:
aclnnStatus aclnnTransConvolutionWeightGetWorkspaceSize(
const aclTensor* weightIn,
bool transposed,
const int64_t groups,
aclTensor* weightOut,
uint64_t* workspaceSize,
aclOpExecutor** executor)
aclnnStatus aclnnTransConvolutionWeight(
void* workspace,
uint64_t workspaceSize,
aclOpExecutor* executor,
aclrtStream stream)
注意:第二段接口
aclnnTransConvolutionWeight(...)不能重复调用,同一个 executor 只能执行一次,重复调用会出现异常。
aclnnTransConvolutionWeightGetWorkspaceSize 参数详解
第一段接口完成入参校验与计算流程构建,各参数说明如下:
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| weightIn | 输入 | 表示一个待处理的 Convolution 的 weight Tensor | 支持空 Tensor 输入;当 weightIn 为空 Tensor 时,weightOut 也必须为空 Tensor | FLOAT16、FLOAT32 | NCHW | 4 | √ |
| transposed | 输入 | 表明是否为转置卷积 | 目前仅支持设为 false | BOOL | - | - | - |
| groups | 输入 | 表示从输入通道到输出通道的块连接个数 | 取值范围为 [1, 65535] | INT64 | - | - | - |
| weightOut | 输出 | 表示返回输入 weight 转换为私有格式后的 tensor | 支持空 Tensor 输出;当 weightOut 为空 Tensor 时,weightIn 也必须为空 Tensor | FLOAT16 | NCHW | 4 | - |
| workspaceSize | 输出 | 返回需要在 Device 侧申请的 workspace 大小 | 不能为空指针;空 Tensor 场景下返回 0 | - | - | - | - |
| executor | 输出 | 返回 op 执行器,包含了算子计算流程 | 不能为空指针 | - | - | - | - |
关键约束要点:
- weightIn 数据类型支持 Float16 与 Float32 两种;weightOut 数据类型固定为 Float16。这一点在源码 CheckTensor 中有明确校验:
weightIn必须是DT_FLOAT16或DT_FLOAT,weightOut必须是DT_FLOAT16,且两者GetViewFormat()都必须为FORMAT_NCHW,同时要求weightOut是连续(contiguous)Tensor。 - 维度约束:仅支持 4 维 Tensor。源码 CheckParams 中通过
g_dimNum = 4静态常量校验维度数,非 4 维直接报ACLNN_ERR_PARAM_INVALID。 - transposed:仅支持
false(正向卷积),源码中transposed == true时直接报参数非法。 - groups:表示分组卷积中从输入通道到输出通道的块连接个数,取值范围 [1, 65535];源码中仅显式校验
groups == 0时报错,配合文档约束共同约束取值范围。 - 空 Tensor 一致性:weightIn 与 weightOut 必须同时为空或同时非空。源码 aclnnTransConvolutionWeightGetWorkspaceSize 中对两者
IsEmpty()状态做了交叉校验,状态不一致时报ACLNN_ERR_PARAM_INVALID;两者均为空时直接返回workspaceSize = 0并跳过实际转换。
返回值与错误码
两段接口均返回 aclnnStatus 状态码,完整说明参见 aclnn返回码。第一段接口在入参校验阶段可能出现如下错误:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 输入是空指针。例如 weightIn、weightOut、workspaceSize 或 executor 传入 nullptr。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | 输入输出 Tensor 的数据类型、数据格式以及其他参数不符合预期。例如输入 weightIn 为非 FLOAT16、FLOAT32 数据类型或者非 NCHW 数据格式;或 weightIn/weightOut 空 Tensor 状态不一致;或 transposed 为 true;或 groups 为 0;或 Tensor 维度不为 4。 |
对应地,在 L2 单元测试 中对这些异常场景逐一做了验证,例如 ascend310P3_test_wrong_format(NHWC 格式输入返回 161002)、ascend310P3_test_wrong_dtype_input_int8(int8 输入返回 161002)、ascend310P3_dim_larger_than_4(5 维输入返回 161002)、ascend310P3_group_0(groups=0 返回 161002)、ascend310P3_transpose_true(transposed=true 返回 161002),以及 ascend310P3_in_nullptr / ascend310P3_out_nullptr(空指针返回 161001)。
aclnnTransConvolutionWeight(第二段接口)参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址。 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnTransConvolutionWeightGetWorkspaceSize 获取。 |
| executor | 输入 | op 执行器,包含了算子计算流程。 |
| stream | 输入 | 指定执行任务的 Stream。 |
第二段接口在 源码 中的实现非常精简:它通过 L2_DFX_PHASE_2 宏记录执行阶段信息后,直接调用框架能力 CommonOpExecutorRun(workspace, workspaceSize, executor, stream) 完成实际计算,可见真正的算子逻辑编排(contiguous → cast → transdata → viewcopy)全部封装在第一段接口构建的 executor 中。
约束说明
- 确定性计算:aclnnTransConvolutionWeight 默认确定性实现。
- 仅支持正向 Conv2D 场景,不支持转置卷积(transposed 必须为 false)。
- 不支持 cache 缓存能力。这一点在源码中有明确体现:aclnnTransConvolutionWeightGetWorkspaceSize 在创建 executor 后立即调用了
uniqueExecutor.get()->AbandonCache()主动放弃缓存能力。 - 支持空 Tensor:当 weightIn 与 weightOut 均为空 Tensor 时,不执行实际转换,workspaceSize 返回 0。
源码实现原理:从 NCHW 到 FRACTAL_Z 的转换流水线
从 aclnn_trans_convolution_weight.cpp 的实现可以看出,第一段接口内部构建了一条由基础算子(l0op)串联的转换流水线:
- Contiguous:
l0op::Contiguous(weightIn, ...)将非连续的输入 Tensor 转为连续 Tensor(因此文档允许 weightIn 为非连续 Tensor,见参数表中"非连续Tensor √"标记); - Cast:
l0op::Cast(weightInContiguous, weightOut->GetDataType(), ...)将数据类型统一转为输出要求的 Float16; - TransData:
l0op::TransData(weightInCast, Format::FORMAT_FRACTAL_Z, groups, ...)将 NCHW 权重按 groups 变换为对 Cube 计算亲和的 FRACTAL_Z 私有格式(对应 transdata 算子实现 与 transdata tiling 逻辑); - 元信息同步:把
weightFz的 storage format / storage shape 同步到weightOut上,并将weightOut的 view shape 临时设置为存储 shape、view format 设置为 FRACTAL_Z; - ViewCopy:
l0op::ViewCopy(weighttemp, weightOut, ...)执行视图拷贝,将转换结果写入用户提供的输出 Tensor; - 复位视图:计算完成后,再将
weightOut的 view shape 恢复为weightFz->GetOriginalShape()、view format 恢复为 NCHW——这样用户从逻辑视角看到的是一个 shape 不变、但存储层已是私有格式的权重 Tensor,可以直接交给aclnnConvolution使用。
aclnnCalculateConvolutionWeightSize 的计算逻辑则更为轻量:它在 Host 侧用一个 shape 信息创建占位 aclTensor,调用 l0op::TransData 推导出 FRACTAL_Z 转换后的存储 shape,再通过 CalculateConvWeightSize 将存储 shape 各维度相乘得到转换后所需的元素个数——这就是文档示例中 [2, 4, 8, 8] 变为 [64, 1, 16, 16]、元素数变为 16384 的由来。从源码结构看,元素数一般会大于原始元素数(原始为 512),因为 FRACTAL_Z 分形格式存在 pad 对齐开销。
完整调用示例
以下示例代码与 官方文档 保持一致,完整演示了"权重预处理 + 用转换结果调用 aclnnConvolution 验证"的全流程。示例在完成权重转换后,继续调用 aclnnConvolutionGetWorkspaceSize 和 aclnnConvolution 验证转换结果;这两个接口的参数约束和使用方式请参考 CANN 算子库的 aclnnConvolution 接口文档。具体编译和执行过程请参考 编译与运行样例。
#include <iostream>
#include <memory>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_convolution.h"
#include "aclnnop/aclnn_trans_convolution_weight.h"
using namespace std;
#define CHECK_RET(cond, return_expr) \
do { \
if (!(cond)) { \
return_expr; \
} \
} while (0)
#define CHECK_FREE_RET(cond, return_expr) \
do { \
if (!(cond)) { \
Finalize(deviceId, stream); \
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) {
// 固定写法,Stream初始化
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<T>& hostData, 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侧内存上
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_NCHW,
shape.data(), shape.size(), *deviceAddr);
return 0;
}
template <typename T>
int CreateWeightAclTensor(const std::vector<T> &hostData, const std::vector<int64_t> &shape, void **deviceAddr,
aclDataType dataType, aclTensor **tensor, uint64_t &TransWeightSize)
{
auto size = GetShapeSize(shape) * sizeof(T);
// 调用transweight host接口 计算实际elements数量
aclIntArray* weightSize = aclCreateIntArray(shape.data(), shape.size());
std::unique_ptr<aclIntArray, aclnnStatus (*)(const aclIntArray *)> weightSizePtr(weightSize, aclDestroyIntArray);
auto ret = aclnnCalculateConvolutionWeightSize(weightSize, false, 1, aclDataType::ACL_FLOAT16, &TransWeightSize);
// 调用aclrtMalloc申请device侧内存
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侧内存上
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_NCHW,
shape.data(), shape.size(), *deviceAddr);
return 0;
}
void Finalize(int32_t deviceId, aclrtStream& stream)
{
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
}
int aclnnTransConvolutionWeightTest(int32_t deviceId, aclrtStream& stream) {
auto ret = Init(deviceId, &stream);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);
// 2.构造输入与输出,需要根据API的接口自定义构造
std::vector<int64_t> inputShape = {1, 4, 16, 16};
std::vector<int64_t> weightShape = {2, 4, 8, 8};
std::vector<int64_t> biasShape = {2};
std::vector<int64_t> outShape = {1, 2, 9, 9};
void* inputDeviceAddr = nullptr;
void* weightDeviceAddr = nullptr;
void* biasDeviceAddr = nullptr;
void* outDeviceAddr = nullptr;
aclTensor* input = nullptr;
aclTensor* weight = nullptr;
aclTensor* bias = nullptr;
aclTensor* out = nullptr;
std::vector<float> inputHostData(1024, 1);
std::vector<float> weightHostData(512, 1);
std::vector<float> biasHostData(2, 1);
std::vector<float> outHostData(162, 0);
uint64_t transWeightSize = 0;
// 创建input aclTensor
ret = CreateAclTensor(inputHostData, inputShape, &inputDeviceAddr, aclDataType::ACL_FLOAT, &input);
std::unique_ptr<aclTensor, aclnnStatus (*)(const aclTensor *)> selfTensorPtr(input, aclDestroyTensor);
std::unique_ptr<void, aclError (*)(void *)> inputDeviceAddrPtr(inputDeviceAddr, aclrtFree);
CHECK_FREE_RET(ret == ACL_SUCCESS, return ret);
// 创建weight aclTensor
ret = CreateWeightAclTensor(weightHostData, weightShape, &weightDeviceAddr, aclDataType::ACL_FLOAT,
&weight, transWeightSize);
std::unique_ptr<aclTensor, aclnnStatus (*)(const aclTensor *)> weightTensorPtr(weight, aclDestroyTensor);
std::unique_ptr<void, aclError (*)(void *)> weightDeviceAddrPtr(weightDeviceAddr, aclrtFree);
CHECK_FREE_RET(ret == ACL_SUCCESS, return ret);
// 创建bias aclTensor
ret = CreateAclTensor(biasHostData, biasShape, &biasDeviceAddr, aclDataType::ACL_FLOAT, &bias);
std::unique_ptr<aclTensor, aclnnStatus (*)(const aclTensor *)> biasTensorPtr(bias, aclDestroyTensor);
std::unique_ptr<void, aclError (*)(void *)> biasDeviceAddrPtr(biasDeviceAddr, aclrtFree);
CHECK_FREE_RET(ret == ACL_SUCCESS, return ret);
// 创建out aclTensor
ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
std::unique_ptr<aclTensor, aclnnStatus (*)(const aclTensor *)> outTensorPtr(out, aclDestroyTensor);
std::unique_ptr<void, aclError (*)(void *)> outDeviceAddrPtr(outDeviceAddr, aclrtFree);
CHECK_FREE_RET(ret == ACL_SUCCESS, return ret);
// 创建Transweight acltensor
void* transWeightDeviceAddr = nullptr;
uint64_t size = transWeightSize * sizeof(float) / 2;
ret = aclrtMalloc(&transWeightDeviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret);return ret);
std::vector<float> transData;
transData.resize(transWeightSize * 2);
// 调用aclrtMemcpy将Host侧数据拷贝到device侧内存上transData.data()
ret = aclrtMemcpy(transWeightDeviceAddr, size, transData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret);
return ret);
// 计算连续tensor的strides
vector<int64_t> shape = weightShape;
std::vector<int64_t> s(shape.size(), 1);
for (int64_t i = shape.size() - 2; i >= 0; i--) {
s[i] = shape[i + 1] * s[i + 1];
}
aclTensor* transWeight = aclCreateTensor(shape.data(), shape.size(), aclDataType::ACL_FLOAT16, s.data(), 0, aclFormat::ACL_FORMAT_NCHW,
shape.data(), shape.size(), transWeightDeviceAddr);
std::unique_ptr<aclTensor, aclnnStatus (*)(const aclTensor *)> transWeightTensorPtr(transWeight, aclDestroyTensor);
std::unique_ptr<void, aclError (*)(void *)> transWeightDeviceAddrAddrPtr(transWeightDeviceAddr, aclrtFree);
// 3.调用aclnnTransConvolutionWeight
int8_t cubeMathType = 2; // USE_FP16
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
bool transposed = 0;
uint64_t groups = 1;
// 调用TransWeight
ret = aclnnTransConvolutionWeightGetWorkspaceSize(weight, transposed, groups, transWeight,
&workspaceSize, &executor);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnTransConvolutionWeightGetWorkspaceSize failed. ERROR: %d\n", ret);
return ret);
// 根据第一段接口计算出的workspaceSize申请device内存
void* workspaceAddr = nullptr;
std::unique_ptr<void, aclError (*)(void *)> workspaceAddrPtr(nullptr, aclrtFree);
if (workspaceSize > 0) {
ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
workspaceAddrPtr.reset(workspaceAddr);
}
// 调用aclnnTransConvolutionWeight第二段接口
ret = aclnnTransConvolutionWeight(workspaceAddr, workspaceSize, executor, stream);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnTransConvolutionWeight failed. ERROR: %d\n", ret); return ret);
std::vector<int64_t> convStrides = {1, 1};
std::vector<int64_t> convPads = {0, 0};
std::vector<int64_t> convOutPads = {1, 1};
std::vector<int64_t> convDilations = {1, 1};
aclIntArray *strides = aclCreateIntArray(convStrides.data(), convStrides.size());
std::unique_ptr<aclIntArray, aclnnStatus (*)(const aclIntArray *)> stridesPtr(strides, aclDestroyIntArray);
CHECK_FREE_RET(strides != nullptr, return ACL_ERROR_INTERNAL_ERROR);
aclIntArray *pads = aclCreateIntArray(convPads.data(), convPads.size());
std::unique_ptr<aclIntArray, aclnnStatus (*)(const aclIntArray *)> padsPtr(pads, aclDestroyIntArray);
CHECK_FREE_RET(pads != nullptr, return ACL_ERROR_INTERNAL_ERROR);
aclIntArray *outPads = aclCreateIntArray(convOutPads.data(), convOutPads.size());
std::unique_ptr<aclIntArray, aclnnStatus (*)(const aclIntArray *)> outPadsPtr(outPads, aclDestroyIntArray);
CHECK_FREE_RET(outPads != nullptr, return ACL_ERROR_INTERNAL_ERROR);
aclIntArray *dilations = aclCreateIntArray(convDilations.data(), convDilations.size());
std::unique_ptr<aclIntArray, aclnnStatus (*)(const aclIntArray *)> dilationsPtr(dilations, aclDestroyIntArray);
CHECK_FREE_RET(dilations != nullptr, return ACL_ERROR_INTERNAL_ERROR);
// 4.调用aclnnConvolution
workspaceSize = 0;
// 调用aclnnConvolution第一段接口
ret = aclnnConvolutionGetWorkspaceSize(input, transWeight, bias, strides, pads, dilations, false, outPads, groups,
out, cubeMathType, &workspaceSize, &executor);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnConvolutionGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
// 根据第一段接口计算出的workspaceSize申请device内存
workspaceAddr = nullptr;
if (workspaceSize > 0) {
ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
}
// 调用aclnnConvolution第二段接口
ret = aclnnConvolution(workspaceAddr, workspaceSize, executor, stream);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnConvolution failed. ERROR: %d\n", ret); return ret);
// 4.(固定写法)同步等待任务执行结束
ret = aclrtSynchronizeStream(stream);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);
// 5.获取输出的值,将device侧内存上的结果拷贝至host侧,需要根据具体API的接口定义修改
size = GetShapeSize(outShape);
std::vector<float> resultData(size, 0);
ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr,
size * sizeof(float), ACL_MEMCPY_DEVICE_TO_HOST);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret);
for (int64_t i = 0; i < size; i++) {
LOG_PRINT("result[%ld] is: %f\n", i, resultData[i]);
}
return ACL_SUCCESS;
}
int main() {
// 1.(固定写法)device/stream初始化,参考acl API手册
// 根据自己的实际device填写deviceId
int32_t deviceId = 0;
aclrtStream stream;
auto ret = aclnnTransConvolutionWeightTest(deviceId, stream);
CHECK_FREE_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnTransConvolutionWeightTest failed. ERROR: %d\n", ret); return ret);
Finalize(deviceId, stream);
return 0;
}
示例的关键步骤拆解:
- 环境初始化:
Init中依次调用aclInit、aclrtSetDevice、aclrtCreateStream,这是 aclnn 单算子调用的固定前置流程; - 创建 Tensor:通过
aclrtMalloc+aclrtMemcpy把 Host 数据搬入 Device,再用aclCreateTensor以 NCHW 格式创建aclTensor;其中权重 Tensor 的创建走CreateWeightAclTensor,会先调用aclnnCalculateConvolutionWeightSize计算转换后元素数,再为转换结果申请内存; - 权重预处理:调用第一段接口
aclnnTransConvolutionWeightGetWorkspaceSize获得 workspaceSize 与 executor,按需申请 workspace,再调用第二段接口aclnnTransConvolutionWeight执行转换; - 结果验证:用转换后的
transWeight作为权重,调用aclnnConvolutionGetWorkspaceSize/aclnnConvolution执行正向卷积,最后通过aclrtSynchronizeStream等待任务结束,并把结果从 Device 拷贝回 Host 打印; - 资源释放:
Finalize中销毁 stream、reset 设备并aclFinalize,代码中同时使用 RAII 智能指针(std::unique_ptr+ 对应销毁函数)保证异常路径下的资源回收。
测试覆盖与质量保证
仓库在 tests/ut/op_api/test_aclnn_trans_convolution_weight_l2.cpp 中为这两个接口提供了完整的 L2 级单元测试,可归纳为以下几类:
- 正常路径:
ascend310P3_test_normal_input_FP16(Float16 输入)、ascend310P3_test_normal_input_FP32(Float32 输入转 Float16 输出)均断言返回ACLNN_SUCCESS; - 格式非法:输入为 NHWC 格式(
ascend310P3_test_wrong_format)、输出为 Float32(ascend310P3_test_wrong_format_out)均返回ACLNN_ERR_PARAM_INVALID; - 数据类型非法:int8 输入(
ascend310P3_test_wrong_dtype_input_int8、ascend310P3_test_wrong_dtype_input_int8_out)返回 161002; - 维度非法:5 维输入(
ascend310P3_dim_larger_than_4)返回 161002; - 参数非法:groups 为 0(
ascend310P3_group_0)、transposed 为 true(ascend310P3_transpose_true)均返回 161002; - 空指针:weightIn 或 weightOut 为 nullptr(
ascend310P3_in_nullptr、ascend310P3_out_nullptr)返回ACLNN_ERR_PARAM_NULLPTR; - Calculate 接口专项:覆盖正常 shape(
ascend310P_normal_shape)、shape 空指针(ascend310P_shape_nullptr)、size 空指针(ascend310P_size_nullptr)、Float32 数据类型(ascend310P_datatype_fp32)、groups=0、错误维度、transposed=true 等场景。
这些测试用例与文档中的参数约束一一对应,可作为开发者在迁移或二次开发该接口时的行为参考基准。
总结
aclnnTransConvolutionWeight 与配套的 aclnnCalculateConvolutionWeightSize 共同构成了 Atlas 推理系列产品上 Convolution 权重预处理的标准方案:先用 Host 侧纯计算接口确定转换后所需的元素数量并申请内存,再通过两段式 aclnn 接口把 NCHW 权重转换为 FRACTAL_Z 私有格式并统一 cast 为 Float16。理解其源码中的 Contiguous → Cast → TransData → ViewCopy 流水线,以及维度、格式、数据类型、groups、空 Tensor 一致性等参数约束,是正确、高效使用该接口的关键。建议读者结合 接口头文件、实现源码 和 配套文档 深入研读,并将本文示例代码落地验证。