CANN opbase 算子开发指南：L0 基础张量操作接口 Reshape 详解

CANN opbase 算子开发指南L0 基础张量操作接口 Reshape 详解【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase导读本文档详细讲解 CANN 算子库基础框架opbase中 Level0L0层基础张量操作接口l0op::Reshape的完整使用方式涵盖其功能语义、函数原型、参数与返回值约定、约束条件及调用示例。本文面向使用 aclnn API 进行算子开发的开发者帮助读者理解 Reshape 这类仅修改 shape 元信息、不搬运数据的视图View类操作在 CANN 算子框架中的定位与底层实现机制并掌握在 L0 接口中正确调用 Reshape 的工程方法。接口定位基础张量操作接口L0 层在 opbase 接口列表 中nnopbase 对外提供的接口被划分为两大类框架能力接口提供实现 aclnn API 的基础能力例如算子执行器 aclOpExecutor 处理、数据类型/格式/shape 操作、常用类与宏等基础张量操作接口提供实现 aclnn API 的基础张量操作例如 Tensor 数据类型转换、shape 重构等Reshape即属于此类接口与 Cast、Contiguous、Slice、Transpose、TransData 等并列完整列表参见 基础张量操作接口。从接口层级上看Level0 层接口简称 L0 接口表示调用单 Kernel 的 Host 侧 API提供了细颗粒 API单 Kernel 下发和算子 API 开发的基础结构体如 Tensor 定义等与公共基础能力如 workspace 复用、引擎调度等上层应用或 L2 层接口可以通过 L0 接口的快速组装实现高性能计算。L0 接口具有如下固定约定返回值类型是 Tensor 类型的结构例如aclTensor*、std::tupleaclTensor*, aclTensor*、aclTensorList*最后一个参数固定为aclOpExecutor *executor类型与名称均不可变命名空间为namespace l0op接口名为${op_type}${format}${dtype}的组合形式。Reshape接口正是遵循上述 L0 约定设计的返回值是const aclTensor*最后一个参数是aclOpExecutor *executor。所属头文件为aclnn_kernels/reshape.h。产品支持情况Reshape接口在如下产品形态上支持情况不同开发与部署前请先确认目标硬件平台产品支持情况Ascend 950PR / Ascend 950DT不支持Atlas A3 训练系列产品 / Atlas A3 推理系列产品支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品支持Atlas 200I/500 A2 推理产品支持Atlas 推理系列产品支持Atlas 训练系列产品支持功能说明Reshape函数不改变算子的 tensor 数据只是将用户传入的输入 tensorx的 shape 转换成该函数的第二个参数shape。换言之Reshape 属于典型的元信息重构操作数据在内存中的存放位置与字节内容保持不变变化的只是张量的维度描述。这一语义决定了 Reshape 与 Cast转换数据类型、Transpose按 perm 维度转置、TransData转换 format等基础张量操作在本质上不同——后几者通常涉及实际的数据重排或类型转换而 Reshape 在满足连续内存与元素总数一致的条件下可以仅通过修改 shape 描述完成。从源码结构看这一零拷贝特性也体现在框架的图建模设计中在 common_types.h 中aclStorage的extend_指针注释明确写道ViewCopy 和 Reshape 是特殊 op不会调用 ADD_TO_AICORE_KERNEL_LAUNCH_LIST因此没有对应的 kernel nodes。唯一的关系是 Op1 输出 aclTensor 的 storage 指针与 Op2 输入 aclTensor 的 storage 指针相同我们使用这个 extend 指针在 KernelGraph 中链接它们。可以推断在 KernelGraph 层面Reshape 并不会产生实际的 kernel 任务节点而是通过共享 storage 指针将上游算子的输出张量与下游算子的输入张量在图中关联起来从而避免无谓的数据搬运。函数原型Reshape提供两个重载版本区别仅在于目标 shape 的传入方式const aclTensor *Reshape(const aclTensor *x, const op::Shape shape, aclOpExecutor *executor)const aclTensor *Reshape(const aclTensor *x, const aclIntArray *shape, aclOpExecutor *executor)两个版本均在命名空间l0op下调用即l0op::Reshape(x, shape, executor)。其中op::Shape版本适合在 L0/L2 接口内部已有op::Shape对象的场景类型与算子开发中惯用的 shape 表示一致无需额外转换aclIntArray*版本适合 shape 以int64_t数组形式存在、或来自外部 API 入参的场景。在 opbase 的类型体系中op::Shape本质上是gert::Shape的别名而 shape 底层数据由op::ShapeVector承载其定义为存储容量长度为 25 的FVectorint64_t, ...MAX_DIM_NUM 25详见 common_types.hnamespace op { constexpr uint64_t MAX_DIM_NUM 25; using ShapeVector FVectorint64_t, MAX_DIM_NUM; using Shape gert::Shape; }因此通过op::Shape传入的维度数量理论上限为 25 维而aclIntArray则是int64_t类型的数组对象由ACL_ARRAY(Int, int64_t)宏生成见 common_types.h数据一般存放在 host 侧。参数说明参数输入/输出说明x输入待转换的输入 tensor。数据类型和数据格式不限制。输入必须保证是连续内存数据。shape输入转换后的目标 shape支持 aclIntArray*、op::Shape即 gert::Shape类型。数据类型和数据格式不限制。executor输入op 执行器包含了算子计算流程。对参数的进一步说明x输入 tensor由于 Reshape 不搬运数据仅重写 shape 描述因此要求输入数据在内存中是连续的。若输入是非连续张量例如经过切片或转置得到的 View其内存布局与目标 shape 无法一一对应此时应先用Contiguous接口将其转换为连续 tensor再执行 Reshape。连续性的判断可以通过 tensor_view_utils 等工具完成参见 tensor_view_utils)。shape目标 shape两种重载版本分别接收op::Shape与aclIntArray*。该参数只描述维度信息与数据类型、数据格式无关。executor执行器aclOpExecutor是记录整个 host 侧 API 运行信息的上下文结构如 L2 接口执行过程中的计算图、L0 算子 launch 子任务、workspace 地址和大小等信息。L0 接口的最后一个参数固定为它类型与名称均不可变。返回值说明若 Reshape 转换成功则返回带有目标 shape 信息的aclTensor给调用者若失败则返回nullptr。因此调用方需要检查返回值是否为空指针。在返回的aclTensor上可以继续读取其 shape 相关信息——aclTensor在 opbase 中维护了 storage存储、original原始、view视图三套维度描述相关接口包括GetStorageShape()、GetOriginalShape()、GetViewShape()以及GetStorageFormat()/GetViewFormat()等见 common_types.hReshape 本质上是更新了这些 shape 描述中的目标维度信息而底层存储地址GetStorageAddr()保持不变。约束说明使用Reshape必须满足以下约束元素总数一致Reshape 转换成功的前提是x的 ShapeSize 需要和第二个参数shape的 ShapeSize 相等。所谓 ShapeSize 举例如下A 的 shape(1, 3, 256, 256)则 A 的 ShapeSize1*3*256*256。不支持转换为空 tensor当前不支持转换成空 tensor所谓空 tensor 即 shape 中包含 0例如(0, 3, 256, 256)。约束 1 是 Reshape 可行的数学基础——只有元素总数相等才能在不改变数据、不搬运内存的前提下仅调整维度划分约束 2 则与aclTensor::IsEmpty()的空张量语义相关空张量没有合法的元素布局可供重写因此直接拒绝转换。调用示例以下示例展示了在 L0 接口开发中调用l0op::Reshape的基本方式void Func(const aclTensor *x, const op::Shape shape, aclOpExecutor *executor) { auto ret l0op::Reshape(x, shape, executor); return; }将该示例扩展为包含空指针检查与 shape 校验的完整写法更贴近实际工程void Func(const aclTensor *x, const op::Shape shape, aclOpExecutor *executor) { // 调用 Reshape将 x 的 shape 重写为 shape const aclTensor *ret l0op::Reshape(x, shape, executor); if (ret nullptr) { // 转换失败可能原因是 x 的 ShapeSize 与 shape 的 ShapeSize 不相等 // 或目标 shape 中包含 0空 tensor 不支持 return; } // 转换成功ret 携带目标 shape 信息后续可作为下游算子的输入继续组装 return; }若目标 shape 来自外部数组而非op::Shape对象可使用aclIntArray*重载版本void FuncWithIntArray(const aclTensor *x, const aclIntArray *shape, aclOpExecutor *executor) { auto ret l0op::Reshape(x, shape, executor); return; }总结l0op::Reshape是 CANN opbase 中一类极具代表性的零拷贝基础张量操作它不触碰 tensor 数据仅将输入张量的 shape 重写为目标 shape并以携带新 shape 信息的aclTensor*返回。使用时需牢记两大约束ShapeSize 相等、不支持空 tensor并保证输入为连续内存数据。在 KernelGraph 层面Reshape 与 ViewCopy 一样属于不生成 kernel 节点的特殊 op通过共享 storage 指针在图中建立上下游张量的关联这也是其高性能特性的底层来源。相关接口与实现可继续查阅 Reshape 文档、基础张量操作接口列表 与 common_types.h。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考