CANN ops-math 算子开发指南:aclnnTransConvolutionWeight 卷积权重格式转换接口详解

原创2026-09-21 20:45:141,332 阅读
文章标签:算子库人工智能深度学习高性能计算CANNAscend

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)串联的转换流水线:

  1. Contiguous:l0op::Contiguous(weightIn, ...) 将非连续的输入 Tensor 转为连续 Tensor(因此文档允许 weightIn 为非连续 Tensor,见参数表中"非连续Tensor √"标记);
  2. Cast:l0op::Cast(weightInContiguous, weightOut->GetDataType(), ...) 将数据类型统一转为输出要求的 Float16;
  3. TransData:l0op::TransData(weightInCast, Format::FORMAT_FRACTAL_Z, groups, ...) 将 NCHW 权重按 groups 变换为对 Cube 计算亲和的 FRACTAL_Z 私有格式(对应 transdata 算子实现 与 transdata tiling 逻辑);
  4. 元信息同步:把 weightFz 的 storage format / storage shape 同步到 weightOut 上,并将 weightOut 的 view shape 临时设置为存储 shape、view format 设置为 FRACTAL_Z;
  5. ViewCopy:l0op::ViewCopy(weighttemp, weightOut, ...) 执行视图拷贝,将转换结果写入用户提供的输出 Tensor;
  6. 复位视图:计算完成后,再将 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;
}

示例的关键步骤拆解:

  1. 环境初始化:Init 中依次调用 aclInit、aclrtSetDevice、aclrtCreateStream,这是 aclnn 单算子调用的固定前置流程;
  2. 创建 Tensor:通过 aclrtMalloc + aclrtMemcpy 把 Host 数据搬入 Device,再用 aclCreateTensor 以 NCHW 格式创建 aclTensor;其中权重 Tensor 的创建走 CreateWeightAclTensor,会先调用 aclnnCalculateConvolutionWeightSize 计算转换后元素数,再为转换结果申请内存;
  3. 权重预处理:调用第一段接口 aclnnTransConvolutionWeightGetWorkspaceSize 获得 workspaceSize 与 executor,按需申请 workspace,再调用第二段接口 aclnnTransConvolutionWeight 执行转换;
  4. 结果验证:用转换后的 transWeight 作为权重,调用 aclnnConvolutionGetWorkspaceSize / aclnnConvolution 执行正向卷积,最后通过 aclrtSynchronizeStream 等待任务结束,并把结果从 Device 拷贝回 Host 打印;
  5. 资源释放: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 一致性等参数约束,是正确、高效使用该接口的关键。建议读者结合 接口头文件、实现源码 和 配套文档 深入研读,并将本文示例代码落地验证。

登录后查看全文
ops-math