CANN opbase aclTensor::GetStorageFormat 接口详解获取张量内存排布格式与算子开发实践【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase导读本文以 CANN 算子库基础框架库 opbase 中aclTensor::GetStorageFormat接口为线索完整讲解 StorageFormat 的概念、函数原型、返回值语义与底层实现原理并给出算子开发中的典型调用场景与注意事项。读完本文你将掌握如何通过GetStorageFormat()读取 aclTensor 在内存中的实际排布格式如 NCHW、ND、FRACTAL_NZ 等并能将其与 OriginFormat、ViewFormat 等相邻接口正确区分使用为算子适配与 shape 推导提供可靠依据。一、功能说明什么是 StorageFormatGetStorageFormat是 opbase 公共头文件 common_types.h 中定义的 aclTensor 成员方法用于获取 aclTensor 的 StorageFormat存储格式。在 CANN 算子编程模型中一个张量通常拥有逻辑形态view/origin与物理存储形态storage两层描述StorageFormat表示 aclTensor 的数据在内存中的实际排布格式例如 NCHW、ND、NC1HWC0、FRACTAL_Z 等。它决定了解释底层缓冲区中字节序列的方式是算子侧访问张量数据时必须首先确认的关键信息。与之相对的 OriginFormat原始格式一般表示张量在经历 transdata 节点如果存在该节点之前的原始 Format 信息ViewFormat 则描述视图形态下的格式。三者共同构成张量完整的多层格式描述。在算子开发尤其是 shape 推导与 tiling 计算阶段StorageFormat 直接决定了如何将逻辑 shape 映射到物理存储因此GetStorageFormat是 opbase 中高频使用的读接口之一。二、函数原型与参数说明op::Format GetStorageFormat()项目说明所属对象aclTensor位于 common_types.h参数无返回值op::Format枚举值表示当前张量的存储格式是否为 const 方法是头文件中声明为op::Format GetStorageFormat() const;调用不会修改张量状态该接口无参数、无异常抛出正常使用前提下仅执行一次格式信息的读取成本极低可在算子 host 侧流程中安全、高频调用。三、返回值说明op::Format 与 ge::Format 的关系GetStorageFormat返回op::Format。从 common_types.h 的源码可以看到using Format ge::Format;即op::Format就是ge::Format的类型别名二者完全等价。ge::Format本身是一个枚举包含多种不同的排布格式例如枚举值含义FORMAT_NCHW按 N、C、H、W 顺序排布的标准四维格式FORMAT_NHWC按 N、H、W、C 顺序排布FORMAT_NDN 维通用格式n-dimensional tensorFORMAT_NC1HWC0昇腾 AI 处理器的 5D 分形格式C 维按 C0 对齐切分FORMAT_FRACTAL_Z/FORMAT_FRACTAL_NZ分形格式面向矩阵计算加速FORMAT_NCDHW、FORMAT_NDHWC五维卷积相关格式此外在 AICPU 公共类型定义 cpu_types.h 中可以查看完整的格式枚举范围与取值编号如FORMAT_NCHW 0、FORMAT_HASHTABLE_LOOKUP_LOOKUPS 20、FORMAT_NYUV 45、FORMAT_END与FORMAT_MAX 0xff边界约定可以推断 ge::Format 的枚举集合与之一致或高度兼容。需要特别说明的是FORMAT_MAX仅用于界定枚举取值范围SPEC代码中不应直接使用。四、底层实现GetStorageFormat 的源码级原理在 opbase 的公共实现文件 common_types.cpp 中该接口的实现非常简洁op::Format aclTensor::GetStorageFormat() const { return tensor_-GetFormat().GetStorageFormat(); }其调用链为aclTensor内部持有一个指向底层张量对象的指针tensor_类型为op::Tensor即gert::TensorV2见 common_types.htensor_-GetFormat()取回张量的格式描述对象包含 storage / origin 两套格式信息.GetStorageFormat()从该格式描述对象中提取存储格式字段并返回。也就是说StorageFormat 信息最终由底层gert::StorageFormatusing StorageFormat gert::StorageFormat;见 common_types.h承载。这也解释了为什么该接口无需参数它读取的是 aclTensor 创建或设置时已经固化在张量对象内部的元数据。从源码结构还可以看出aclTensor以对称的三套格式接口对外暴露信息Storage 系列GetStorageFormat()/SetStorageFormat(op::Format)描述内存实际排布Origin 系列GetOriginalFormat()/SetOriginalFormat(op::Format)描述 transdata 前的原始格式View 系列GetViewFormat()/SetViewFormat(op::Format)描述视图形态下的格式。三者的关系是view 是用户逻辑视角origin 是图层面原始语义storage 是真正落盘到物理内存的排布。算子侧判断内存里到底是什么摆法时必须读 Storage 系列。五、调用示例与典型使用场景5.1 基础调用示例文档给出的最小可编译用法如下void Func(const aclTensor *input) { auto format input-GetStorageFormat(); }返回的format变量即可与op::Format/ge::Format枚举值直接比较例如#include nnopbase/opdev/common_types.h void CheckTensorFormat(const aclTensor *input) { auto format input-GetStorageFormat(); if (format op::Format::FORMAT_ND) { // ND 布局按逻辑 shape 顺序连续存储 } else if (format op::Format::FORMAT_FRACTAL_NZ) { // 分形布局面向矩阵计算优化需要按分形规则换算地址 } }5.2 场景一算子格式适配判断算子在执行前需要确认输入张量的存储格式是否符合自身支持范围。opbase 的 shape 推导代码 shape_inference.cpp 中正是同时读取GetOriginalFormat()、GetStorageFormat()、GetDataType()三要素来构造完整的张量描述这说明 StorageFormat 是推导与校验流程的基础输入。5.3 场景二缓存 key 构建与匹配在 individual op 的执行路径中张量格式是算子二进制缓存 key 的重要组成部分。例如 indv_cache_key_builder.cpp 会比较前后两个张量的GetStorageFormat()是否一致并将格式枚举值以单字节形式写入缓存 keyindv_cache_key_builder.cpp。由此可以推断格式不同 → 缓存 key 不同 → 算子需要重新编译因此 StorageFormat 的准确性直接影响算子执行效率。5.4 场景三tiling 与编译描述下发在 indv_tilingcontext_builder.cpp 与 kernel_context_holder.cpp 中GetStorageFormat()的返回值被SetStorageFormat()写入 tiling 数据或编译描述compileDesc中随算子下发到 device 侧。这说明 StorageFormat 不仅影响 host 侧逻辑还会直接传递到编译与运行阶段。5.4 场景五转储与调试信息输出在调试与数据落盘场景中格式信息同样被使用。例如 indv_dump.cpp 将GetStorageFormat()写入 dump 信息common_types.cpp 在aclTensor::ToString()中拼接storage_format ...输出同时 tiling_context_to_json.cpp 还会用ge::GetPrimaryFormat、ge::GetSubFormat、ge::GetC0Format对存储格式做进一步拆分主格式/子格式/C0 信息后写入 JSON方便问题定位。六、测试验证与使用约束6.1 单测覆盖opbase 单元测试对GetStorageFormat有明确覆盖可作为接口行为的事实依据test_common_types.cpp 断言创建出的张量GetStorageFormat()等于op::Format::FORMAT_NDtest_common_types.cpp 验证调用SetStorageFormat(Format::FORMAT_FRACTAL_NZ)后GetStorageFormat()能正确返回FORMAT_FRACTAL_NZ即读写对称test_acl_op_api.cpp 在 aclnn API 测试中同样校验默认张量的存储格式为FORMAT_ND。6.2 约束说明按原文档约定GetStorageFormat本身无额外约束无参数、无前置条件声明。但结合源码使用场景可以给出如下实践提醒与 OriginFormat 的区别GetStorageFormat返回的是内存实际排布而GetOriginalFormat见 GetOriginalFormat.md返回的是 transdata 前的原始格式。在存在格式转换transdata的图结构中两者可能不同切勿混用不要直接对返回值做主/子格式拆分StorageFormat 可能携带子格式信息如需拆分应使用ge::GetPrimaryFormat/ge::GetSubFormat等工具参见 GetPrimaryFormat.md 与 IsPrivateFormat.md私有格式判断对于不透明/私有格式opbase 提供IsPrivateFormat辅助判断相关代码见 tensor_view_utils.cpp在无法解释格式语义时应先做此类判断再决定是否直接解析内存。七、总结aclTensor::GetStorageFormat()是 CANN opbase 中读取张量内存排布格式的核心只读接口无参数、返回op::Format即ge::Format底层直接透传gert::StorageFormat。它广泛参与算子 shape 推导、缓存 key 构建、tiling 编译描述下发、数据 dump 与调试信息输出等环节。理解并正确使用该接口是编写可适配多种排布格式的算子的前提也是排查逻辑 shape 对但数据摆法不对类问题的第一入口。相关文档索引接口列表总览common_types.md关联接口GetOriginalFormat.md、SetStorageFormat.md、SetStorageShape.md格式工具GetPrimaryFormat.md、IsPrivateFormat.md头文件声明common_types.h实现文件common_types.cpp【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考