CANN ops-math 单算子 API 数据类型体系：aclDataType 全量取值与简写规范详解

CANN ops-math 单算子 API 数据类型体系：aclDataType 全量取值与简写规范详解

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math

本文基于 CANN ops-math 仓库官方文档 数据类型说明，系统梳理通过aclCreateTensor接口创建 aclTensor 时支持的全量数据类型，以及两段式接口（如 aclnnCast、aclnnAdd 等）参数说明中使用的数据类型简写规范。读完本文，你将能够准确使用ACL_FLOAT16、ACL_BF16、ACL_FLOAT8_E4M3FN等类型枚举创建张量，并看懂仓库内各算子 API 头文件中对输入/输出类型约束的简写描述。

数据类型的出现位置：aclCreateTensor 与两段式接口

在 ops-math 仓库的单算子（aclnn）API 调用链中，数据类型贯穿始终：

• 张量创建阶段：开发者调用aclCreateTensor接口创建 aclTensor 时，需要传入aclDataType指定张量数据类型。仓库 基础数据结构文档 指出，aclTensor 等基础数据结构可通过 opbase 库中的公共接口创建，开发者无需关注其内部实现，直接使用即可。
• 算子执行阶段：调用两段式接口（第一段aclxxXxxGetWorkspaceSize+ 第二段aclxxXxx）时，两段式接口文档 说明了 workspace 申请与 executor 的传递流程，而各段接口的参数注释里则以"简写形式"描述 aclTensor 支持的数据类型。

因此，理解aclDataType的全量取值及其简写，是使用 ops-math 单算子 API 的前置知识。

全量数据类型简写表（原文档表 1 完整继承）

数据类型文档 明确说明：通过aclCreateTensor接口创建 aclTensor 时，支持的全量数据类型可参见 CANN 官方 acl API（C）文档中"数据类型及其操作接口 > aclDataType"部分。为了在两段式接口参数说明中方便描述，仓库采用如下简写形式（不区分大小写）：

表 1 数据类型简写表

从表中可以看出三个值得注意的点：

1. 多别名规则：部分类型存在两个等价的简写形式，例如ACL_FLOAT既可写作 FLOAT 也可写作 FLOAT32，ACL_DOUBLE既可写作 DOUBLE 也可写作 FLOAT64，ACL_BF16既可写作 BF16 也可写作 BFLOAT16。阅读算子参数说明时，两种写法指向同一枚举值。
2. 低比特量化类型：简写表覆盖了 HIFLOAT8、FLOAT8（E5M2/E4M3FN/E8M0）、FLOAT6（E3M2/E2M3）、FLOAT4（E2M1/E1M2）等低精度类型，体现了该数据类型体系对量化推理场景的覆盖。
3. 复数与稀疏相关类型：COMPLEX32/64/128 复数类型、INT4、UINT1 等也被纳入支持范围。

简写规范在算子 API 头文件中的实际应用

简写规范并非纸面约定，而是被仓库内各算子 API 头文件的 Doxygen 注释直接采用。以 aclnn_cast.h 为例，Cast 算子第一段接口的注释中：

/** * @brief aclnnCast的第一段接口，根据具体的计算流程，计算workspace大小。 * ... * @param [in] self: npu device侧的aclTensor，数据类型支持FLOAT16、FLOAT、DOUBLE、INT8、UINT8、INT16、 * UINT16、INT32、UINT32、INT64、UINT64、BOOL、COMPLEX32、COMPLEX64、COMPLEX128、BFLOAT16、HIFLOAT8、 * FLOAT8_E5M2、FLOAT8_E4M3FN、FLOAT4_E2M1、FLOAT4_E1M2。支持非连续的Tensor，数据格式支持ND。 * @param [in] dtype: host侧的aclDataType，输入tensor要转换的目标dtype。 * ... */ ACLNN_API aclnnStatus aclnnCastGetWorkspaceSize( const aclTensor* self, const aclDataType dtype, aclTensor* out, uint64_t* workspaceSize, aclOpExecutor** executor);

可以看到：参数self的类型说明使用的是简写形式（FLOAT16、BFLOAT16 等），而dtype参数则直接使用aclDataType枚举类型。这正印证了原文档的定位——简写只用于"参数说明"，代码中传参仍以aclDataType枚举为准。

代码中的数据类型传参：以仓库示例为准

仓库的算子调用示例展示了真实的传参方式，与简写表形成呼应：

• Add 算子示例 中，通过CreateAclTensor(..., aclDataType::ACL_FLOAT, &selfX)以ACL_FLOAT枚举创建输入/输出张量；
• Add 算子 PyTorch 算子示例 中则使用aclDataType::ACL_FLOAT16创建张量，并在aclCreateTensor中同时传入 shape、data type、strides 与aclFormat::ACL_FORMAT_ND数据格式。

由此可以看出标准调用模式：先按表 1 选定原始数据类型枚举（如ACL_FLOAT16），再通过aclCreateTensor创建 device 侧张量，最后将其传入两段式接口。

延伸阅读：与数据类型相关的上下文文档

本仓库 docs/zh/context/ 目录下还有一组与数据类型密切相关的上下文文档，建议配合阅读：

• 两段式接口：说明 workspace 申请流程，以及"第二段接口不能重复调用"等关键约束；
• 数据结构：aclTensor、aclScalar、aclIntArray 等基础结构的定义与创建方式；
• 转换关系 与 推导关系：说明多数据类型算子的输入输出类型转换与推导规则，是理解"某个算子支持哪些类型组合"的重要依据；
• 数据格式：与数据类型配合描述张量的 ND/NDHWC 等布局。

小结

本文以 docs/zh/context/data_type.md 为主体，完整继承了其 27 项数据类型简写表，并结合仓库源码补充了三点实战细节：简写仅用于接口参数说明（见 aclnn_cast.h 注释）、代码传参使用aclDataType枚举（见 Add 示例）、多别名类型（FLOAT/FLOAT32、DOUBLE/FLOAT64、BF16/BFLOAT16）在文档中等价互换。掌握这套规范后，即可在 ops-math 中正确创建任意精度张量并读懂全部单算子 API 的类型约束说明。

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math