CANN ops-math aclnnFlatten 算子详解:两段式接口、参数约束与调用示例

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

CANN ops-math aclnnFlatten 算子详解:两段式接口、参数约束与调用示例

本文围绕 CANN ops-math 数学算子库中的 Flatten 转换算子展开,以算子接口文档 conversion/flatten/docs/aclnnFlatten.md 为主体,结合其 op_host 层源码与单元测试,系统讲解 aclnnFlatten 的功能语义、两段式接口用法、参数约束、返回码及底层实现原理。读完本文,你将能够独立完成 aclnnFlatten 的 workspace 申请、执行器创建与算子调用,并理解其内部调用链。

算子功能说明

Flatten 算子的功能是:将输入 Tensor 基于给定的 axis 扁平化为一个 2D 的 Tensor。

  • 若输入 self 的 shape 为 (d₀, d₁, ..., dₙ),则输出 out 的 shape 为 (d₀×d₁×...×d₍ₐₓᵢₛ₋₁₎, dₐₓᵢₛ×dₐₓᵢₛ₊₁×...×dₙ)。即:axis 之前的所有维度相乘作为输出的第 0 维,axis 及之后的所有维度相乘作为输出的第 1 维。
  • 若 axis 取值为 0,则输出 out 的 shape 为 (1, d₀×d₁×...×dₙ)。

例如,输入 shape 为 (2, 3, 4, 5)、axis = 2 时,输出 shape 为 (2×3, 4×5) = (6, 20);axis = 0 时输出 shape 为 (1, 120)。这两个场景分别对应单元测试 test_aclnn_flatten.cpp 中的 flatten_testcase_001_normal_float32(axis=2)与 flatten_testcase_017_axis_boundary(axis=0)。

产品支持情况

根据 aclnnFlatten.md 与 README.md,该算子支持以下产品:

产品 是否支持
Ascend 950PR / Ascend 950DT 支持
Atlas A3 训练系列产品 / Atlas A3 推理系列产品 支持
Atlas A2 训练系列产品 / Atlas A2 推理系列产品 支持
Atlas 200I/500 A2 推理产品 支持
Atlas 推理系列产品 支持
Atlas 训练系列产品 支持

说明:不同芯片(如 Ascend 910 与 Ascend 910B 系列)在部分数据类型的支持上存在差异,BFLOAT16 仅在 910B 及后续平台上支持,详见下文源码解析。

两段式接口与函数原型

aclnnFlatten 属于 aclnn 算子接口,遵循两段式调用范式(详见 docs/zh/context/two_phase_api.md):

  1. 第一段:调用 aclnnFlattenGetWorkspaceSize 完成入参校验,获取计算所需 workspace 大小以及包含了算子计算流程的执行器(executor);
  2. 第二段:调用 aclnnFlatten 执行计算。

函数原型定义于 op_host/op_api/aclnn_flatten.h,如下所示:

aclnnStatus aclnnFlattenGetWorkspaceSize(
    const aclTensor *self,
    int64_t          axis,
    aclTensor       *out,
    uint64_t        *workspaceSize,
    aclOpExecutor  **executor)
aclnnStatus aclnnFlatten(
    void                *workspace,
    uint64_t             workspaceSize,
    aclOpExecutor       *executor,
    const aclrtStream    stream)

aclnnFlattenGetWorkspaceSize 参数说明

参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续 Tensor
self(aclTensor*) 输入 需要进行 flatten 的输入 self 最大维度不能超过 8 INT8、INT16、INT32、INT64、UINT8、UINT16、UINT32、UINT64、BOOL、BFLOAT16、FLOAT、FLOAT16 ND 2-8 √
axis(int64_t) 输入 flatten 计算的基准轴 取值范围为 [-self.dim(), self.dim()-1];若 self 的 dim 为 0 或 1,则 axis 只能取 0,其余情况按文档描述仅支持 axis=1 INT64 - - √
out(aclTensor*) 输出 输出 out shape 为 2D 与 self 保持一致 ND 2 √
workspaceSize(uint64_t*) 输出 返回需要在 Device 侧申请的 workspace 大小 - - - - -
executor(aclOpExecutor**) 输出 返回 op 执行器,包含了算子计算流程 - - - - -

返回值与错误码

两个接口均返回 aclnnStatus 状态码,具体取值参见 docs/zh/context/aclnn_return_code.md。第一段接口会完成入参校验,以下场景会报错:

返回值 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的 self、out 是空指针
ACLNN_ERR_PARAM_INVALID 161002 self 和 out 的数据类型不在支持的范围之内
ACLNN_ERR_PARAM_INVALID 161002 self 和 out 的数据类型不一致
ACLNN_ERR_PARAM_INVALID 161002 axis 不在输入 self 的合理维度范围之内
ACLNN_ERR_PARAM_INVALID 161002 self 的维度大于 8

aclnnFlatten 参数说明

参数名 输入/输出 描述
workspace 输入 在 Device 侧申请的 workspace 内存地址
workspaceSize 输入 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnFlattenGetWorkspaceSize 获取
executor 输入 op 执行器,包含了算子计算流程
stream 输入 指定执行任务的 Stream

约束说明

  • 输入张量 self 的维度不能大于 8,输出 out 为 2D Tensor。
  • axis 必须在有效的维度范围内。
  • 输入与输出的数据类型必须一致。
  • 非连续 Tensor:self 与 out 均支持非连续(view)Tensor,底层会通过 l0op::Contiguous 与 l0op::ViewCopy 自动处理(详见下文源码解析)。
  • 确定性计算:aclnnFlatten 默认采用确定性实现,保证相同输入得到确定输出。

源码实现与底层调用链

两段式接口的固定骨架

第一段接口的实现位于 op_host/op_api/aclnn_flatten.cpp 的 aclnnFlattenGetWorkspaceSize,整体遵循固定的四步骨架:

  1. 创建执行器:通过 CREATE_EXECUTOR() 宏创建 aclOpExecutor;
  2. 参数校验:调用 CheckParams(self, axis, out) 依次完成空指针检查、数据类型检查、shape 检查与 format 检查;
  3. 图编排:将算子计算流程以 l0op 算子(Contiguous / Flatten / ViewCopy)注册进执行器;
  4. 获取 workspace:通过 uniqueExecutor->GetWorkspaceSize() 汇总计算流程所需的临时内存大小,并将执行器通过 ReleaseTo(executor) 交还用户。

第二段接口 aclnnFlatten 则直接调用框架统一的 CommonOpExecutorRun(workspace, workspaceSize, executor, stream) 完成计算,自身不包含业务逻辑。

参数校验的源码级拆解

CheckParams 的校验逻辑对应文档中的错误码表格:

  • CheckNotNull:OP_CHECK_NULL 检查 self、out 是否为空指针,失败返回 ACLNN_ERR_PARAM_NULLPTR(161001);

  • CheckDtypeValid:先校验 self 与 out 数据类型一致(OP_CHECK_DTYPE_NOT_SAME),再根据当前 Soc 版本选择 dtype 支持列表。源码中维护了两份列表:

    • Ascend910_DTYPE_SUPPORT_LIST:FLOAT、FLOAT16、INT32、INT8、UINT8、INT64、INT16、UINT16、UINT32、UINT64、BOOL(共 11 种);
    • Ascend910B_DTYPE_SUPPORT_LIST:在上述基础上额外支持 BF16(共 12 种)。

    也就是说,BFLOAT16 仅在 Ascend 910B(含 910_93)及寄存器级(IsRegBase)平台上受支持,这与文档中 BFLOAT16 的数据类型标注是一致的;

  • CheckShape:OP_CHECK_MAX_DIM 限制 self 维度不超过 8;再对 axis 做合法性检查:当 self 的 dim 为 0 或 1 时,axis 只能为 0;其他情况下 axis 必须落在 [0, selfDim-1](负轴会被 MakeWrapDim 先转换为正索引)。最后调用 GetOutShape 推导出期望输出 shape,并与用户传入的 out 的 shape 比对,不一致即返回 ACLNN_ERR_PARAM_INVALID;

  • CheckFormat:若 self 的存储格式为 FORMAT_FRACTAL_NZ,仅打印一条可能影响精度的警告日志,不阻断执行。

GetOutShape 在逐维累乘时还会做 INT64_MAX 溢出保护,若乘积超出 int64 数据范围,同样返回 ACLNN_ERR_PARAM_INVALID。

负轴(negative axis)的处理

文档中 axis 的取值范围为 [-self.dim(), self.dim()-1],允许负索引。源码中的 MakeWrapDim 负责将负轴转换为等效的正索引:

static inline int64_t MakeWrapDim(int64_t dim, int64_t dimPostExpr) {
  // 支持0维tensor
  if (dimPostExpr <= 0) {
    dimPostExpr = 1;
  }
  if (dim < 0) {
    dim += dimPostExpr;
  }
  return dim;
}

单元测试 flatten_testcase_011_negative_axis 使用 4 维输入 (2, 3, 4, 5)、axis = -2(等效于 axis = 2)验证了该路径,期望输出 shape 为 (6, 20),返回 ACLNN_SUCCESS。

底层执行图:Contiguous → Flatten → ViewCopy

从源码看,aclnnFlatten 的计算流程并非简单的单算子下发,而是由多个 l0op 基础算子组合而成(aclnn_flatten.h 中的 mermaid 计算图给出了直观描述):

  1. l0op::Contiguous(self):若 self 是非连续(view)Tensor,先转为连续 Tensor 再进行扁平化,保证后续 Flatten 语义正确;
  2. l0op::Flatten(selfContiguous, executor, axisWrap):核心扁平化算子。实现位于 op_host/op_api/flatten.cpp,内部先通过 IsAiCoreSupport 按芯片类型与 dtype 判断是否支持走 AiCore 路径(910 平台使用 ASCEND910_AICORE_DTYPE_SUPPORT_LIST,其余平台使用含 BF16 的 ASCEND910B_AICORE_DTYPE_SUPPORT_LIST),随后用 executor->AllocTensor 构造 shape 为 (dim0, dim1) 的临时输出,并通过宏 ADD_TO_LAUNCHER_LIST_AICORE(Flatten, OP_INPUT(self), OP_OUTPUT(out), OP_ATTR(axis)) 将 Flatten kernel 加入任务队列。注意该算子仅有 AiCore 实现、无 AiCPU 兜底,dtype 不在支持列表内时 Flatten 会直接返回空指针;l0op::Flatten 的声明在 op_host/op_api/flatten.h,其默认 axis 取值为 1;
  3. l0op::ViewCopy(flattenResult, out):将计算得到的连续结果拷贝到用户提供的 out 上,因此 out 同样支持非连续 Tensor。

此外,在寄存器级(IsRegBase())平台上,源码使用 l0op::Reshape 取代 l0op::Flatten 来完成扁平化,再同样以 ViewCopy 落地到 out,属于平台相关的实现分叉。

空 Tensor 的特殊处理

在 aclnnFlattenGetWorkspaceSize 中,若 self 或 out 为空 Tensor,会提前返回:*workspaceSize = 0 并直接释放执行器给用户,不再编排任何计算图。不过单元测试 flatten_testcase_003_normal_empty_tensor 与 flatten_testcase_014_exception_out_empty_tensor 显示,输入/输出 shape 为 (0,) 这类空 tensor 场景在校验阶段会返回 ACLNN_ERR_PARAM_INVALID,说明空 Tensor 需要满足 shape 一致性等约束才能走通提前返回分支。

调用示例

以下完整示例摘自仓库 conversion/flatten/examples/test_aclnn_flatten.cpp(文档 aclnnFlatten.md 中亦包含等价版本)。该示例将 shape 为 (4, 2) 的 FLOAT 输入以 axis = 0 扁平化为 shape (1, 8) 的输出,并校验计算结果。具体编译与执行过程请参考 docs/zh/context/compile_and_run_sample.md。

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_flatten.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 shape_size = 1;
    for (auto i : shape) {
        shape_size *= i;
    }
    return shape_size;
}

int Init(int32_t deviceId, aclrtStream* 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_ND,
                              shape.data(), shape.size(), *deviceAddr);
    return 0;
}

int main()
{
    int32_t deviceId = 0;
    aclrtStream stream;
    auto ret = Init(deviceId, &stream);
    CHECK_RET(ret == 0, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);
    std::vector<int64_t> selfShape = {4, 2};
    std::vector<int64_t> outShape = {1, 8};
    void* selfDeviceAddr = nullptr;
    void* outDeviceAddr = nullptr;
    aclTensor* self = nullptr;
    aclTensor* out = nullptr;
    std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7};
    // outHostData 仅为占位初值;aclnnFlatten 执行后 out 应等于 self 的扁平化结果 {0, 1, 2, 3, 4, 5, 6, 7}
    std::vector<float> outHostData = {1, 1, 1, 1, 0, 0, 0, 0};

    ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
    CHECK_RET(ret == ACL_SUCCESS, return ret);
    ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
    CHECK_RET(ret == ACL_SUCCESS, return ret);

    // 创建attr
    int64_t axis = 0;

    uint64_t workspaceSize = 0;
    aclOpExecutor* executor;
    ret = aclnnFlattenGetWorkspaceSize(self, axis, out, &workspaceSize, &executor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnFlattenGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);

    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);
    }

    ret = aclnnFlatten(workspaceAddr, workspaceSize, executor, stream);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnFlatten failed. ERROR: %d\n", ret); return ret);

    ret = aclrtSynchronizeStream(stream);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);

    auto 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_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]);
    }
    std::vector<float> expectedData = {0, 1, 2, 3, 4, 5, 6, 7};
    for (int64_t i = 0; i < size; i++) {
        if (resultData[i] != expectedData[i]) {
            LOG_PRINT("result mismatch at [%ld], expected %f got %f\n", i, expectedData[i], resultData[i]);
            return -1;
        }
    }

    aclDestroyTensor(self);
    aclDestroyTensor(out);

    // 释放device资源
    aclrtFree(selfDeviceAddr);
    aclrtFree(outDeviceAddr);
    if (workspaceSize > 0) {
        aclrtFree(workspaceAddr);
    }
    aclrtDestroyStream(stream);
    aclrtResetDevice(deviceId);
    aclFinalize();
    return 0;
}

示例的调用要点归纳:

  1. 初始化:aclInit → aclrtSetDevice → aclrtCreateStream 完成环境与 Stream 初始化;
  2. 构造 Tensor:通过 aclrtMalloc 申请 Device 内存、aclrtMemcpy 拷入数据,计算连续 strides 后调用 aclCreateTensor 创建输入/输出 aclTensor(ND 格式);
  3. 两段式调用:先调用 aclnnFlattenGetWorkspaceSize 拿到 workspaceSize 与 executor,再按需 aclrtMalloc 申请 workspace,最后调用 aclnnFlatten 执行,并用 aclrtSynchronizeStream 等待任务完成;
  4. 结果校验与资源回收:将结果从 Device 拷回 Host 后与期望数据比对,随后依次销毁 Tensor、释放 Device 内存、销毁 Stream、Reset 设备并 aclFinalize。

单元测试与框架适配

仓库为 aclnnFlatten 提供了覆盖正常与异常场景的单元测试 tests/ut/op_host/op_api/test_aclnn_flatten.cpp,关键用例包括:

  • 正常路径:FLOAT 4 维输入 axis=2(flatten_testcase_001_normal_float32)、INT64(flatten_testcase_015_normal_int64)、BOOL(flatten_testcase_016_normal_bool)、axis 边界 0(flatten_testcase_017_axis_boundary)、负轴 -2(flatten_testcase_011_negative_axis)、1 维输入 axis=0(flatten_testcase_018_normal_float32_self_dim1)等,均返回 ACLNN_SUCCESS;
  • 异常路径:空指针 out/self(ACLNN_ERR_PARAM_NULLPTR)、输入输出 dtype 不一致(ACLNN_ERR_PARAM_INVALID)、错误 out shape、COMPLEX64/COMPLEX128 不支持、维度超过 8、1 维输入 axis=1 越界等,均按文档错误码表返回对应状态码。

此外,仓库还提供了 framework/flatten_onnx_plugin.cpp 作为 ONNX 框架适配插件:将 ONNX 的 ai.onnx::8 ~ ai.onnx::18 各版本 Flatten 算子解析为内部 Flatten 算子,解析时读取 ONNX 节点的 axis 属性(默认值为 1)并写入算子属性。这说明 aclnnFlatten 不仅可被应用直接调用,也可作为 ONNX 模型中 Flatten 节点在 NPU 上执行的底层承载算子。

总结

aclnnFlatten 是 ops-math 中实现张量扁平化转换的基础算子:语义上它把任意不超过 8 维的 ND 输入按 axis 合并为 2D 输出;接口上遵循"GetWorkspaceSize + 执行"的两段式范式;实现上由 l0op::Contiguous、l0op::Flatten(寄存器级平台为 l0op::Reshape)与 l0op::ViewCopy 组合而成,天然支持非连续 Tensor,且默认确定性计算。阅读本文后,你可以结合 docs/zh/context/two_phase_api.md、docs/zh/context/aclnn_return_code.md 与 docs/zh/context/compile_and_run_sample.md 进一步了解通用接口规范,并在实际工程中复用上文示例完成算子接入与验证。

登录后查看全文
ops-math