CANN ops-math aclnnFlatten 算子详解:两段式接口、参数约束与调用示例
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):
- 第一段:调用
aclnnFlattenGetWorkspaceSize完成入参校验,获取计算所需 workspace 大小以及包含了算子计算流程的执行器(executor); - 第二段:调用
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,整体遵循固定的四步骨架:
- 创建执行器:通过
CREATE_EXECUTOR()宏创建aclOpExecutor; - 参数校验:调用
CheckParams(self, axis, out)依次完成空指针检查、数据类型检查、shape 检查与 format 检查; - 图编排:将算子计算流程以
l0op算子(Contiguous / Flatten / ViewCopy)注册进执行器; - 获取 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 计算图给出了直观描述):
l0op::Contiguous(self):若 self 是非连续(view)Tensor,先转为连续 Tensor 再进行扁平化,保证后续 Flatten 语义正确;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;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;
}
示例的调用要点归纳:
- 初始化:
aclInit→aclrtSetDevice→aclrtCreateStream完成环境与 Stream 初始化; - 构造 Tensor:通过
aclrtMalloc申请 Device 内存、aclrtMemcpy拷入数据,计算连续 strides 后调用aclCreateTensor创建输入/输出aclTensor(ND 格式); - 两段式调用:先调用
aclnnFlattenGetWorkspaceSize拿到 workspaceSize 与 executor,再按需aclrtMalloc申请 workspace,最后调用aclnnFlatten执行,并用aclrtSynchronizeStream等待任务完成; - 结果校验与资源回收:将结果从 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 进一步了解通用接口规范,并在实际工程中复用上文示例完成算子接入与验证。