CANN opbase aclTensor::SetStorageFormat 详解为张量设置存储格式StorageFormat【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbaseSetStorageFormat是 CANN opbase 框架库中aclTensor类的核心属性设置接口用于指定张量在设备内存中的实际排布格式如 NCHW、ND 等。本文以 docs/en/api/nnopbase/opdev/common_types/SetStorageFormat.md 为骨架结合仓库内头文件声明、实现源码与算子执行链路中的真实调用完整讲解该接口的原型、参数语义、可用格式取值、底层实现机制与在算子开发中的典型用法帮助算子开发者正确读写张量的存储格式元数据。1. 功能概述什么是 StorageFormat在 CANN opbase 中aclTensor是算子开发过程中传递张量数据的核心对象。一个aclTensor在内存中的实际排布方式由StorageFormat存储格式描述常见的取值包括NCHW、ND等。从仓库源码结构看aclTensor对张量格式的管理分为三个相互独立的维度对应三组 Get/Set 接口维度语义对应接口StorageFormat张量在物理内存中的实际排布格式GetStorageFormat、SetStorageFormatOriginalFormat张量的原始逻辑格式数据来源时携带的格式GetOriginalFormat、SetOriginalFormatViewFormat当前视图view视角下张量的格式GetViewFormat、SetViewFormatSetStorageFormat专门负责设置其中的StorageFormat维度即声明该aclTensor在内存中实际是怎么排的。2. 接口原型与参数说明2.1 原型SetStorageFormat是aclTensor的公有成员函数原型如下void SetStorageFormat(op::Format format)该声明位于 include/nnopbase/opdev/common_types.h#L162-L163op::Format GetStorageFormat() const; void SetStorageFormat(op::Format format);2.2 参数参数Input/Output说明formatInput数据类型为op::Format即ge::Format是定义不同格式的枚举类型例如 NCHW、ND 等关于op::Format的类型来源include/nnopbase/opdev/common_types.h#L44-L55 中给出了明确的类型别名定义namespace op { using Format ge::Format; using StorageFormat gert::StorageFormat; // ... } // namespace op也就是说op::Format与ge::Format是同一枚举类型二者可以互换使用文档示例中也直接以ge::FORMAT_ND作为参数传入。2.3 返回值该接口无返回值void调用失败时也不会抛出异常——它只是纯元数据写入操作详见第 5 节的源码实现分析。2.4 限制无。3. 支持的格式取值op::Format / ge::Format 枚举SetStorageFormat的入参是ge::Format枚举。结合 src/nnopbase/common/utils/format_utils.cpp 中ToString(Format)支持的格式映射表仓库实际识别并支持的格式包括但不限于格式枚举字符串典型用途FORMAT_NCHWNCHW4 维图像数据默认逻辑排布FORMAT_NHWCNHWC通道在最后的图像数据排布FORMAT_NDND通用 N 维数据排布未指定特殊排布时使用FORMAT_NC1HWC0NC1HWC0昇腾 5D 格式私有格式FORMAT_FRACTAL_ZFRACTAL_Z分形 Z 格式私有格式FORMAT_FRACTAL_NZFRACTAL_NZ分形 NZ 格式私有格式FORMAT_NCNC2 维矩阵数据排布FORMAT_NCLNCL3 维数据排布FORMAT_NDHWC/FORMAT_NCDHWNDHWC / NCDHW5 维数据排布FORMAT_NDC1HWC0NDC1HWC05D 变体格式FORMAT_FRACTAL_Z_3DFRACTAL_Z_3D3 维分形格式FORMAT_FRACTAL_NZ_C0_16等系列FRACTAL_NZ_C0_16/32/2/4/8面向不同 C0 对齐宽度的分形格式说明上表仅摘录了常用格式完整的枚举映射可查看 src/nnopbase/common/utils/format_utils.cpp#L103-L171 中的kFormatToStringMap它覆盖了 50 余种格式。3.1 私有格式的注意事项仓库将部分格式标记为私有格式private format。src/nnopbase/common/utils/format_utils.cpp#L21-L31 中的op::IsPrivateFormat()会判定FORMAT_NC1HWC0、FORMAT_FRACTAL_Z、FORMAT_NDC1HWC0、FORMAT_FRACTAL_Z_3D、FORMAT_FRACTAL_NZ及FORMAT_FRACTAL_NZ_C0_*等为私有格式。在使用特定构造路径创建aclTensor时若视图格式为私有格式框架会打印告警日志见 src/nnopbase/common/utils/common_types.cpp#L212-L214提示此类格式不应通过某些普通构造接口创建。因此在调用SetStorageFormat之前建议结合算子实际支持的格式合理取值。4. 使用示例文档给出的最简示例是将输入张量的存储格式设置为 ND// Set the storage format of the input to ND. void Func(const aclTensor *input) { input-SetStorageFormat(ge::FORMAT_ND); }在实际算子开发中SetStorageFormat常与读取接口配合使用例如将算子输出张量的存储格式与输入保持一致void SetOutputSameAsInput(const aclTensor *input, aclTensor *output) { // 先读取输入张量当前的存储格式 op::Format inputFormat input-GetStorageFormat(); // 将输出张量的存储格式设置为与输入一致 output-SetStorageFormat(inputFormat); // 同时可配合设置原始格式 output-SetOriginalFormat(input-GetOriginalFormat()); }读取侧对应的实现是 src/nnopbase/common/utils/common_types.cpp#L404 的GetStorageFormat()它返回底层op::Tensorgert::TensorV2中保存的存储格式op::Format aclTensor::GetStorageFormat() const { return tensor_-GetFormat().GetStorageFormat(); }5. 源码级实现SetStorageFormat 做了什么5.1 实现位置SetStorageFormat的实现位于 src/nnopbase/common/utils/common_types.cpp#L475void aclTensor::SetStorageFormat(op::Format format) { tensor_-SetStorageFormat(format); }5.2 工作原理从实现看aclTensor::SetStorageFormat是一个纯元数据写入操作aclTensor内部维护一个op::Tensor* tensor_指针即gert::TensorV2所有格式、形状、数据类型信息都保存在该底层张量对象中见 include/nnopbase/opdev/common_types.h#L258-L267 的成员声明SetStorageFormat将入参透传给底层tensor_-SetStorageFormat(format)更新TensorV2内部Format描述中的 storage 部分该操作不会对张量数据做任何搬运、转置或重排也不重新分配内存——它只改变这段内存该如何被解释的描述信息。如果存储格式与实际内存排布不一致可能引发算子侧对数据解释错误因此调用前需要确保值与真实排布相符。这一点与aclTensor的多种构造函数的行为一致构造函数内部通过op::StorageFormat format; format.SetStorageFormat(storageFormat);完成初始存储格式的写入见 src/nnopbase/common/utils/common_types.cpp#L130-L136SetStorageFormat只是把这一写入能力开放为运行时可调用的公有接口。6. 在算子执行链路中的实际应用SetStorageFormat不仅用于算子开发侧的显式调用也被框架内部多个执行模块使用6.1 复合算子composite op编译描述构建在 src/nnopbase/composite_op/aclnn_engine/kernel_context_holder.cpp#L240 与 第 298 行 中框架在构建算子编译描述时会把输入/输出张量的存储格式直接透传到compileDesccompileDesc_[inputNum_].storage_format_.SetStorageFormat(tensor-GetStorageFormat()); // ... compileDesc_[inputNum_ outputNum_].storage_format_.SetStorageFormat(tensor-GetStorageFormat());可见aclTensor上设置的 StorageFormat 会作为算子编译tiling/编译描述阶段的输入信息直接影响算子的编译与调度决策。6.2 独立算子individual op运行时张量同步在 src/nnopbase/individual_op/executor/indv_executor_tensor.cpp#L305-L308 中框架在构造运行时runtime张量时也会调用SetStorageFormatrt2Tensor-SetStorageFormat(ge::FORMAT_ND); // ... rt2Tensor-SetStorageFormat(format);这说明在执行器把算子输入转换为 runtime 张量时会通过SetStorageFormat显式声明张量的存储格式默认场景使用FORMAT_ND特殊场景透传原格式保证下游 kernel 拿到正确的排布信息。6.3 调试与序列化输出此外aclTensor::ToString()见 src/nnopbase/common/utils/common_types.cpp#L744-L759在打印张量信息时会同时输出storage_format、ori_format等字段方便开发者在 dump 调试时核对SetStorageFormat是否生效。7. 相关辅助工具与配套接口7.1 格式工具函数include/nnopbase/opdev/format_utils.h 提供了与op::Format配套的工具函数在设置存储格式前后可用于格式校验与转换函数作用op::IsPrivateFormat(Format)判断是否为私有格式NC1HWC0、FRACTAL_Z 等op::ToFormat(const std::string)将字符串如ND转换为Format枚举op::ToString(Format)将Format枚举转换为可读字符串op::GetPrimaryFormat(Format)提取主格式低 8 位op::GetSubFormat(Format)提取子格式信息op::HasSubFormat(Format)判断是否携带子格式op::ToOpFormat(aclFormat)将aclFormat转换为op::Formatop::ToAclFormat(Format)将op::Format转换回aclFormat不支持时返回ACL_FORMAT_UNDEFINED其中op::ToFormat与op::ToString的完整字符串-枚举映射见 src/nnopbase/common/utils/format_utils.cpp可作为设置存储格式时取值范围的权威参考。7.2 配套接口SetStorageFormat属于 common_types 接口族 的一员常用配套接口包括GetStorageFormat读取存储格式与SetStorageFormat互为读写对SetOriginalFormat / GetOriginalFormat设置/读取原始格式SetViewFormat / GetViewFormat设置/读取视图格式SetStorageShape / GetStorageShape设置/读取存储形状存储格式与存储形状共同决定内存布局的完整描述。8. 总结aclTensor::SetStorageFormat(op::Format format)用于设置张量的存储格式元数据参数类型为op::Format即ge::Format无返回值、无限制实现上仅为对底层gert::TensorV2的元数据写入src/nnopbase/common/utils/common_types.cpp#L475不会触发数据搬运或内存重排调用前需确保与实际排布一致存储格式会沿算子执行链路向下透传复合算子的编译描述构建kernel_context_holder.cpp与独立算子的 runtime 张量构造indv_executor_tensor.cpp都会消费该信息是算子正确编译与执行的关键属性之一。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN opbase aclTensor::SetStorageFormat 详解：为张量设置存储格式（StorageFormat）
CANN opbase aclTensor::SetStorageFormat 详解为张量设置存储格式StorageFormat【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbaseSetStorageFormat是 CANN opbase 框架库中aclTensor类的核心属性设置接口用于指定张量在设备内存中的实际排布格式如 NCHW、ND 等。本文以 docs/en/api/nnopbase/opdev/common_types/SetStorageFormat.md 为骨架结合仓库内头文件声明、实现源码与算子执行链路中的真实调用完整讲解该接口的原型、参数语义、可用格式取值、底层实现机制与在算子开发中的典型用法帮助算子开发者正确读写张量的存储格式元数据。1. 功能概述什么是 StorageFormat在 CANN opbase 中aclTensor是算子开发过程中传递张量数据的核心对象。一个aclTensor在内存中的实际排布方式由StorageFormat存储格式描述常见的取值包括NCHW、ND等。从仓库源码结构看aclTensor对张量格式的管理分为三个相互独立的维度对应三组 Get/Set 接口维度语义对应接口StorageFormat张量在物理内存中的实际排布格式GetStorageFormat、SetStorageFormatOriginalFormat张量的原始逻辑格式数据来源时携带的格式GetOriginalFormat、SetOriginalFormatViewFormat当前视图view视角下张量的格式GetViewFormat、SetViewFormatSetStorageFormat专门负责设置其中的StorageFormat维度即声明该aclTensor在内存中实际是怎么排的。2. 接口原型与参数说明2.1 原型SetStorageFormat是aclTensor的公有成员函数原型如下void SetStorageFormat(op::Format format)该声明位于 include/nnopbase/opdev/common_types.h#L162-L163op::Format GetStorageFormat() const; void SetStorageFormat(op::Format format);2.2 参数参数Input/Output说明formatInput数据类型为op::Format即ge::Format是定义不同格式的枚举类型例如 NCHW、ND 等关于op::Format的类型来源include/nnopbase/opdev/common_types.h#L44-L55 中给出了明确的类型别名定义namespace op { using Format ge::Format; using StorageFormat gert::StorageFormat; // ... } // namespace op也就是说op::Format与ge::Format是同一枚举类型二者可以互换使用文档示例中也直接以ge::FORMAT_ND作为参数传入。2.3 返回值该接口无返回值void调用失败时也不会抛出异常——它只是纯元数据写入操作详见第 5 节的源码实现分析。2.4 限制无。3. 支持的格式取值op::Format / ge::Format 枚举SetStorageFormat的入参是ge::Format枚举。结合 src/nnopbase/common/utils/format_utils.cpp 中ToString(Format)支持的格式映射表仓库实际识别并支持的格式包括但不限于格式枚举字符串典型用途FORMAT_NCHWNCHW4 维图像数据默认逻辑排布FORMAT_NHWCNHWC通道在最后的图像数据排布FORMAT_NDND通用 N 维数据排布未指定特殊排布时使用FORMAT_NC1HWC0NC1HWC0昇腾 5D 格式私有格式FORMAT_FRACTAL_ZFRACTAL_Z分形 Z 格式私有格式FORMAT_FRACTAL_NZFRACTAL_NZ分形 NZ 格式私有格式FORMAT_NCNC2 维矩阵数据排布FORMAT_NCLNCL3 维数据排布FORMAT_NDHWC/FORMAT_NCDHWNDHWC / NCDHW5 维数据排布FORMAT_NDC1HWC0NDC1HWC05D 变体格式FORMAT_FRACTAL_Z_3DFRACTAL_Z_3D3 维分形格式FORMAT_FRACTAL_NZ_C0_16等系列FRACTAL_NZ_C0_16/32/2/4/8面向不同 C0 对齐宽度的分形格式说明上表仅摘录了常用格式完整的枚举映射可查看 src/nnopbase/common/utils/format_utils.cpp#L103-L171 中的kFormatToStringMap它覆盖了 50 余种格式。3.1 私有格式的注意事项仓库将部分格式标记为私有格式private format。src/nnopbase/common/utils/format_utils.cpp#L21-L31 中的op::IsPrivateFormat()会判定FORMAT_NC1HWC0、FORMAT_FRACTAL_Z、FORMAT_NDC1HWC0、FORMAT_FRACTAL_Z_3D、FORMAT_FRACTAL_NZ及FORMAT_FRACTAL_NZ_C0_*等为私有格式。在使用特定构造路径创建aclTensor时若视图格式为私有格式框架会打印告警日志见 src/nnopbase/common/utils/common_types.cpp#L212-L214提示此类格式不应通过某些普通构造接口创建。因此在调用SetStorageFormat之前建议结合算子实际支持的格式合理取值。4. 使用示例文档给出的最简示例是将输入张量的存储格式设置为 ND// Set the storage format of the input to ND. void Func(const aclTensor *input) { input-SetStorageFormat(ge::FORMAT_ND); }在实际算子开发中SetStorageFormat常与读取接口配合使用例如将算子输出张量的存储格式与输入保持一致void SetOutputSameAsInput(const aclTensor *input, aclTensor *output) { // 先读取输入张量当前的存储格式 op::Format inputFormat input-GetStorageFormat(); // 将输出张量的存储格式设置为与输入一致 output-SetStorageFormat(inputFormat); // 同时可配合设置原始格式 output-SetOriginalFormat(input-GetOriginalFormat()); }读取侧对应的实现是 src/nnopbase/common/utils/common_types.cpp#L404 的GetStorageFormat()它返回底层op::Tensorgert::TensorV2中保存的存储格式op::Format aclTensor::GetStorageFormat() const { return tensor_-GetFormat().GetStorageFormat(); }5. 源码级实现SetStorageFormat 做了什么5.1 实现位置SetStorageFormat的实现位于 src/nnopbase/common/utils/common_types.cpp#L475void aclTensor::SetStorageFormat(op::Format format) { tensor_-SetStorageFormat(format); }5.2 工作原理从实现看aclTensor::SetStorageFormat是一个纯元数据写入操作aclTensor内部维护一个op::Tensor* tensor_指针即gert::TensorV2所有格式、形状、数据类型信息都保存在该底层张量对象中见 include/nnopbase/opdev/common_types.h#L258-L267 的成员声明SetStorageFormat将入参透传给底层tensor_-SetStorageFormat(format)更新TensorV2内部Format描述中的 storage 部分该操作不会对张量数据做任何搬运、转置或重排也不重新分配内存——它只改变这段内存该如何被解释的描述信息。如果存储格式与实际内存排布不一致可能引发算子侧对数据解释错误因此调用前需要确保值与真实排布相符。这一点与aclTensor的多种构造函数的行为一致构造函数内部通过op::StorageFormat format; format.SetStorageFormat(storageFormat);完成初始存储格式的写入见 src/nnopbase/common/utils/common_types.cpp#L130-L136SetStorageFormat只是把这一写入能力开放为运行时可调用的公有接口。6. 在算子执行链路中的实际应用SetStorageFormat不仅用于算子开发侧的显式调用也被框架内部多个执行模块使用6.1 复合算子composite op编译描述构建在 src/nnopbase/composite_op/aclnn_engine/kernel_context_holder.cpp#L240 与 第 298 行 中框架在构建算子编译描述时会把输入/输出张量的存储格式直接透传到compileDesccompileDesc_[inputNum_].storage_format_.SetStorageFormat(tensor-GetStorageFormat()); // ... compileDesc_[inputNum_ outputNum_].storage_format_.SetStorageFormat(tensor-GetStorageFormat());可见aclTensor上设置的 StorageFormat 会作为算子编译tiling/编译描述阶段的输入信息直接影响算子的编译与调度决策。6.2 独立算子individual op运行时张量同步在 src/nnopbase/individual_op/executor/indv_executor_tensor.cpp#L305-L308 中框架在构造运行时runtime张量时也会调用SetStorageFormatrt2Tensor-SetStorageFormat(ge::FORMAT_ND); // ... rt2Tensor-SetStorageFormat(format);这说明在执行器把算子输入转换为 runtime 张量时会通过SetStorageFormat显式声明张量的存储格式默认场景使用FORMAT_ND特殊场景透传原格式保证下游 kernel 拿到正确的排布信息。6.3 调试与序列化输出此外aclTensor::ToString()见 src/nnopbase/common/utils/common_types.cpp#L744-L759在打印张量信息时会同时输出storage_format、ori_format等字段方便开发者在 dump 调试时核对SetStorageFormat是否生效。7. 相关辅助工具与配套接口7.1 格式工具函数include/nnopbase/opdev/format_utils.h 提供了与op::Format配套的工具函数在设置存储格式前后可用于格式校验与转换函数作用op::IsPrivateFormat(Format)判断是否为私有格式NC1HWC0、FRACTAL_Z 等op::ToFormat(const std::string)将字符串如ND转换为Format枚举op::ToString(Format)将Format枚举转换为可读字符串op::GetPrimaryFormat(Format)提取主格式低 8 位op::GetSubFormat(Format)提取子格式信息op::HasSubFormat(Format)判断是否携带子格式op::ToOpFormat(aclFormat)将aclFormat转换为op::Formatop::ToAclFormat(Format)将op::Format转换回aclFormat不支持时返回ACL_FORMAT_UNDEFINED其中op::ToFormat与op::ToString的完整字符串-枚举映射见 src/nnopbase/common/utils/format_utils.cpp可作为设置存储格式时取值范围的权威参考。7.2 配套接口SetStorageFormat属于 common_types 接口族 的一员常用配套接口包括GetStorageFormat读取存储格式与SetStorageFormat互为读写对SetOriginalFormat / GetOriginalFormat设置/读取原始格式SetViewFormat / GetViewFormat设置/读取视图格式SetStorageShape / GetStorageShape设置/读取存储形状存储格式与存储形状共同决定内存布局的完整描述。8. 总结aclTensor::SetStorageFormat(op::Format format)用于设置张量的存储格式元数据参数类型为op::Format即ge::Format无返回值、无限制实现上仅为对底层gert::TensorV2的元数据写入src/nnopbase/common/utils/common_types.cpp#L475不会触发数据搬运或内存重排调用前需确保与实际排布一致存储格式会沿算子执行链路向下透传复合算子的编译描述构建kernel_context_holder.cpp与独立算子的 runtime 张量构造indv_executor_tensor.cpp都会消费该信息是算子正确编译与执行的关键属性之一。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考