CANN PyPTO 数据类型体系完全指南DataType 枚举、转换模式与工具函数详解【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto导读本文基于 CANN PyPTO 仓库 docs/zh/api/tensor_api/datatype/ 下的 15 个数据类型相关 API 文档系统梳理 PyPTOParallel Tensor/Tile Operation 编程范式中面向张量Tensor操作的全部枚举类型与辅助工具函数从核心的DataType数据类型标识到控制数值转换的CastMode/SaturationMode/TransMode再到约束算子行为的PrecisionType/TopKAlgo/OpType等。读完本文你将掌握 PyPTO 中每种枚举的取值语义、产品支持差异、底层舍入规则以及它们在pypto.div、pypto.topk、pypto.bytes_of等真实 API 中的正确用法。一、数据类型索引一览本文主题对应仓库中的 15 个独立页面它们共同构成 PyPTO 的数据类型 API 集合在 datatype/index.md 中以 toctree 形式组织页面主题用途DataType数据类型枚举标识 Tensor 的存储格式与计算精度pypto-bytes_of工具函数查询数据类型占用的字节数CastMode转换舍入模式控制类型转换时的精度处理SaturationMode溢出处理模式控制浮点转整数时的溢出策略TransModeTF32 使能模式控制 matmul 中 FP32 转 TF32PrecisionType高精度算子模式控制 div/log/exp 等算子精度LogBaseType对数底数枚举指定对数运算的底数TileOpFormat瓦片格式枚举区分 ND 与 NZ 内存布局CachePolicy缓存策略枚举控制数据在各级缓存中的行为OpType比较操作枚举指定比较运算类型OutType输出类型枚举指定比较结果输出为布尔或位值ReduceMode归约模式枚举指定多线程安全的归约方式ReLuTypeReLU 使能枚举控制是否使能 ReLU 功能ScatterModescatter 归约模式指定 scatter 时的归约方式TopKAlgoTopK 算法枚举选择 TopK 计算算法从源码结构看这些枚举类在 python/pypto/enum.py 中统一从底层 C 绑定模块pypto_impl导入如DataType pypto_impl.DataType、CastMode pypto_impl.CastMode说明它们是 PTO 框架 Python 前端与 C 内核共享的类型定义枚举值最终会透传到算子实现与代码生成阶段。二、核心类型标识DataType2.1 功能与原型DataType是 PyPTO 中表示 Tensor 数据类型的核心枚举类用于指定 Tensor 的存储格式和计算精度。其原型定义与常量说明如下class DataType(enum.Enum): ... # 枚举类定义包含所有支持的数据类型 # 数据类型常量定义 DT_INT4 ... # 4位有符号整数占用0.5字节内存 DT_INT8 ... # 8位有符号整数占用1字节内存 DT_INT16 ... # 16位有符号整数占用2字节内存 DT_INT32 ... # 32位有符号整数占用4字节内存 DT_INT64 ... # 64位有符号整数占用8字节内存 DT_FP8 ... # 8位浮点数用于低精度计算 DT_FP16 ... # 16位半精度浮点数占用2字节内存 DT_FP32 ... # 32位单精度浮点数占用4字节内存 DT_BF16 ... # 16位Brain Float格式占用2字节内存 DT_HF4 ... # 4位Half Float格式占用0.5字节内存 DT_HF8 ... # 8位Half Float格式占用1字节内存 DT_FP4E2M1 ... # 4位浮点数2位指数1位尾数两个元素占用1字节内存 DT_FP8E4M3 ... # 8位浮点数4位指数3位尾数占用1字节内存 DT_FP8E5M2 ... # 8位浮点数5位指数2位尾数占用1字节内存 DT_FP8E8M0 ... # 8位浮点数8位指数0位尾数占用1字节内存 DT_FP4_E2M1X2 ... # MXFP4格式2位指数1位尾数双元素打包占用1字节内存 DT_FP4_E1M2X2 ... # MXFP4格式1位指数2位尾数双元素打包占用1字节内存 DT_UINT8 ... # 8位无符号整数占用1字节内存 DT_UINT16 ... # 16位无符号整数占用2字节内存 DT_UINT32 ... # 32位无符号整数占用4字节内存 DT_UINT64 ... # 64位无符号整数占用8字节内存 DT_BOOL ... # 布尔类型占用1字节内存 DT_DOUBLE ... # 64位双精度浮点数占用8字节内存可以看出PyPTO 的DataType覆盖了从 4 位低精度DT_INT4、DT_FP4E2M1到 64 位高精度DT_INT64、DT_DOUBLE的完整梯度其中DT_FP4_E2M1X2/DT_FP4_E1M2X2属于 MXFP4Microscaling FP4格式采用双元素打包到 1 字节服务于新一代低比特量化推理场景。2.2 Python 端的常量别名在实际 Python 编程中这些枚举成员可以通过 python/pypto/enum.py 中导出的顶层常量直接引用无需书写DataType.DT_FP32的完整形式DT_INT4 DataType.DT_INT4 DT_FP16 DataType.DT_FP16 DT_FP32 DataType.DT_FP32 DT_BF16 DataType.DT_BF16 ... DT_BOOL DataType.DT_BOOL DT_DOUBLE DataType.DT_DOUBLE因此文档示例中的pypto.tensor([1, 3], pypto.DT_FP16)与pypto.tensor([1, 3], pypto.DataType.DT_FP16)是等价的。此外python/pypto/enum.py 还统一为这些枚举类注入了_enum_repr显示函数打印时输出形如DataType.DT_FP32的可读字符串便于调试。2.3 产品支持约束不同芯片型号支持的DataType成员存在差异以当前仓库文档为准产品型号支持情况Ascend 950PR / Ascend 950DT所有数据类型均支持Atlas A3 训练系列产品 / Atlas A3 推理系列产品不支持 DT_FP8E4M3、DT_FP8E5M2、DT_FP8E8M0Atlas A2 训练系列产品 / Atlas A2 推理系列产品不支持 DT_FP8E4M3、DT_FP8E5M2、DT_FP8E8M0也就是说FP8 系列E4M3/E5M2/E8M0仅在 Ascend 950 系列上可用在 A2/A3 平台使用这些类型前需先做平台能力校验。从文档的通用性看其余 15 个枚举页面CachePolicy、CastMode、PrecisionType等在三类产品上均标注为支持仅TransMode例外——它仅在 Ascend 950 系列上支持详见后文。三、字节大小查询工具pypto.bytes_of3.1 函数原型与参数bytes_of返回某个DataType所占的 Byte 大小是进行内存规划、workspace 估算时最常用的辅助函数bytes_of(dtype: pypto.DataType) - int参数名输入/输出说明dtype输入需要查看 Byte 大小的数据类型返回值该数据类型所占的 Byte 大小。3.2 调用示例import pypto pypto.bytes_of(pypto.DT_FP32)输出示例输出: 43.3 源码实现路径在 Python 前端python/pypto/_utils.py 中bytes_of的实现直接委托给底层 C 绑定接口def bytes_of(dtype: DataType) - int: return the number of bytes of the current datatype ... print(pypto.bytes_of(pypto.DT_FP32)) 4 # implementation return pypto_impl.BytesOf(dtype)从实现看字节数的判定逻辑发生在 C 侧pypto_impl.BytesOf与DataType枚举的位宽定义保持一致。可据此推断DT_INT4/DT_FP4E2M1等 4 位类型返回 0.5 字节的量化语义会通过该接口体现配合双元素打包格式使用时按打包后字节计算实际编码时建议以运行平台的返回值为准。四、数值转换控制枚举这一组枚举直接决定类型转换cast行为是 PyPTO 数据转换 API 中最容易影响数值结果的部分共三个CastMode、SaturationMode、TransMode。4.1 CastMode转换舍入模式CastMode定义了数据类型转换时的舍入模式用于控制浮点数转换时的精度处理方式。class CastMode(enum.Enum): CAST_NONE ... # 不指定舍入模式由框架自动选择默认值 CAST_RINT ... # 舍入到最近整数平局时舍入到偶数IEEE 754默认 CAST_ROUND ... # 舍入到最近整数平局时远离零舍入 CAST_FLOOR ... # 向下舍入向负无穷方向舍入 CAST_CEIL ... # 向上舍入向正无穷方向舍入 CAST_TRUNC ... # 截断舍入向零方向舍入 CAST_ODD ... # 舍入到奇数Von Neumann舍入方式使用注意点CAST_ODD当前仅支持 FP32→FP16 转换。CAST_NONE不是硬件支持的舍入模式而是框架层面的概念表示不指定舍入模式由框架自动选择默认值。默认 CastMode 规则当用户使用CAST_NONE或指定了硬件不支持的CastMode时框架自动采用以下默认规则转换类型默认CastMode浮点数转整数FP→INTCAST_TRUNC向零截断其他转换场景CAST_RINT舍入到最近偶数类型扩展转换类型扩展转换如 FP16→FP32、INT8→FP16、INT16→INT32 等本身是无损转换不需要舍入处理此时用户传入的CastMode参数会被忽略。不支持的 CastMode 处理当用户为某个转换指定了硬件不支持的CastMode时框架不会报错而是自动采用该转换的默认CastMode遵循上述默认规则。4.2 CastMode 二进制舍入规则详解要精确理解各舍入模式的行为差异需要先了解浮点数的二进制表示。PyPTO 文档以三种典型浮点格式为例给出了规范说明。浮点数的表示方式DT_FP16共 16bit包括 1bit 符号位S、5bit 指数位E和 10bit 尾数位M。当 E 不全为 0 或不全为 1 时表示的结果为(-1)^S × 2^(E-15) × (1 M)当 E 全为 0 时表示的结果为(-1)^S × 2^(-14) × M当 E 全为 1 时若 M 全为 0表示 ±inf取决于符号位若 M 不全为 0表示 nan。DT_FP32共 32bit包括 1bit 符号位S、8bit 指数位E和 23bit 尾数位M。当 E 不全为 0 或不全为 1 时表示的结果为(-1)^S × 2^(E-127) × (1 M)当 E 全为 0 时表示的结果为(-1)^S × 2^(-126) × M当 E 全为 1 时若 M 全为 0表示 ±inf取决于符号位若 M 不全为 0表示 nan。DT_BF16共 16bit包括 1bit 符号位S、8bit 指数位E和 7bit 尾数位M。当 E 不全为 0 或不全为 1 时表示的结果为(-1)^S × 2^(E-127) × (1 M)当 E 全为 0 时表示的结果为(-1)^S × 2^(-126) × M当 E 全为 1 时若 M 全为 0表示 ±inf取决于符号位若 M 不全为 0表示 nan。注FP16、FP32 与 BF16 在指数偏移上的差异15 vs 127决定了它们动态范围的不同——BF16 与 FP32 指数位一致因此可表示的范围与 FP32 相同但尾数位更少、精度更低。各舍入模式的具体行为设待舍入部分为超出目标尾数位宽的低位比特CAST_RINT若待舍入部分的第一位为 0则不进位若第一位为 1 且后续位不全为 0则进位若第一位为 1 且后续位全为 0当 M 的最后一位为 0 则不进位当 M 的最后一位为 1 则进位即舍入到最近偶数IEEE 754 默认模式。CAST_FLOOR若 S 为 0则不进位若 S 为 1当待舍入部分全为 0 则不进位否则进位向负无穷方向负数会变得更负。CAST_CEIL若 S 为 1则不进位若 S 为 0当待舍入部分全为 0 则不进位否则进位向正无穷方向。CAST_ROUND若待舍入部分的第一位为 0则不进位否则进位四舍五入中间值远离零。CAST_TRUNC总是不进位直接截断向零方向。CAST_ODD若待舍入部分全为 0则不进位若待舍入部分不全为 0当 M 的最后一位为 1 则不进位当 M 的最后一位为 0 则进位Von Neumann 舍入结果尾数末位总为奇数。4.3 SaturationMode溢出处理模式SaturationMode定义了浮点数转整数时的溢出处理方式用于控制当源数据超出目标整数类型表示范围时的处理策略。class SaturationMode(enum.Enum): OFF ... # 截断模式默认直接截断超出部分可能导致溢出 ON ... # 饱和模式超出范围的值会被截断到目标类型的最大值或最小值OFF默认直接截断超出部分可能产生不可预期的溢出结果适合确认数据一定在目标范围内的场景。ON饱和处理超出上界钳位到目标类型的最大值、低于下界钳位到最小值适合归一化数据或对越界敏感的数值链路。4.4 TransModematmul 的 TF32 转换控制TransMode用于 matmul 输入输出矩阵均为 FP32 数据类型的场景设置是否使能 TF32 计算以及使能 TF32 时的舍入模式。使能后矩阵乘计算时 FP32 数据类型会转换为 TF32 数据类型。TF32 采用 1 个符号位、8 个指数位、10 个尾数位共 19 位进行计算。更少的尾数位减少硬件计算量、加速计算但同时也会带来精度损失。输入数据格式仍然为 FP32通过TransMode参数来确定舍入模式一般情况下采用CAST_ROUND舍入到最近整数中间值远离零模式。class TransMode(enum.Enum): CAST_NONE ... # 不使能float数据类型转换为TF32数据类型 CAST_RINT ... # 舍入到最近整数中间值时舍入到偶数 CAST_ROUND ... # 舍入到最近整数中间值时远离零舍入产品支持差异重要与大多数枚举不同TransMode仅在 Ascend 950PR/Ascend 950DT 上支持Atlas A2、A3 系列产品均不支持。在 A2/A3 上使用 matmul 时无需也无法指定 TF32 舍入模式。五、算子精度与对数底数PrecisionType / LogBaseType5.1 PrecisionType高精度向量算子模式PrecisionType定义了高精度向量算子的精度模式用于控制除法、取模、指数、对数等计算时的精度处理方式。class PrecisionType(enum.Enum): INTRINSIC ... # 指令模式直接使用芯片指令 HIGH_PRECISION ... # 高精度模式参数值说明HIGH_PRECISION高精度模式。在底层实现中使用更高精度的计算方式。INTRINSIC指令模式。直接使用芯片指令进行计算性能更高。使用建议默认行为如果不指定精度模式默认使用HIGH_PRECISION模式以确保计算精度。精度要求高的场景推荐使用HIGH_PRECISION模式可以有效减少精度损失提高计算结果的准确性。对精度要求不高但追求性能的场景可以使用INTRINSIC模式直接使用芯片指令进行计算。HIGH_PRECISION模式的产品支持Ascend 950PR/Ascend 950DT 支持Atlas A3、A2 训练/推理系列产品均不支持。支持的算子算子说明div元素级除法fmod元素级取模remainder元素级余数pow元素级幂运算exp指数运算sqrt开方运算rsqrt开方倒数运算log对数运算log2以2为底的对数运算log10以10为底的对数运算reciprocal倒数运算5.2 源码中的默认值印证在 python/pypto/op/math.py 中div的原型明确将precision_type的默认值设为PrecisionType.HIGH_PRECISION与文档默认使用高精度模式的约定完全一致def div( input: Tensor, other: Union[Tensor, float, int], precision_type: PrecisionType PrecisionType.HIGH_PRECISION ) - Tensor: ... precision_type : PrecisionType, optional The precision type for division. Default is PrecisionType.HIGH_PRECISION. Use PrecisionType.INTRINSIC to directly use chip instructions.5.3 LogBaseType对数底数LogBaseType定义了对数运算的底数类型支持常用的自然对数、以 2 为底和以 10 为底的对数运算。class LogBaseType(enum.Enum): LOG_E ... # 自然对数底数以约2.718为底的对数运算 LOG_2 ... # 以2为底的对数运算常用于信息论和计算机科学 LOG_10 ... # 以10为底的对数运算常用于科学计算和工程应用5.4 使用示例import pypto # 创建张量 a pypto.tensor([1, 3], pypto.DT_FP16) b pypto.tensor([1, 3], pypto.DT_FP16) # 使用高精度模式 out pypto.div(a, b, pypto.PrecisionType.HIGH_PRECISION) # 使用指令模式 out pypto.div(a, b, pypto.PrecisionType.INTRINSIC) # 默认使用高精度模式 out pypto.div(a, b) # 使用运算符自动使用高精度模式 out a / b # 其他算子示例 out pypto.exp(a, pypto.PrecisionType.HIGH_PRECISION) out pypto.sqrt(a, pypto.PrecisionType.INTRINSIC) out pypto.log(a, pypto.LogBaseType.LOG_E, pypto.PrecisionType.HIGH_PRECISION) out pypto.pow(a, b, pypto.PrecisionType.HIGH_PRECISION)六、数据布局与缓存TileOpFormat / CachePolicy6.1 TileOpFormat瓦片操作格式TileOpFormat定义了 Tensor 的瓦片操作格式用于优化不同计算模式下的内存访问和计算效率主要区分密集计算和稀疏计算的瓦片格式。class TileOpFormat(enum.Enum): TILEOP_ND ... # N维Tensor支持标准的多维数组操作 TILEOP_NZ ... # 同FRACTAL_NZ/NZ是对一个Tensor最低两维一个Tensor的所有维度右侧为低维左侧为高维进行填充pad、拆分reshape和转置transpose操作后得到的格式TILEOP_ND标准的多维数组行主序布局直观、易于理解和调试适合逐元素类操作。TILEOP_NZ即 FRACTAL_NZ 分形格式对 Tensor 最低两维进行 pad、reshape 与 transpose 后得到的分块转置布局是昇腾矩阵计算单元Cube友好的数据排布能提升矩阵乘等算子的访存局部性。6.2 CachePolicy缓存策略CachePolicy定义了 Tensor 的缓存策略用于控制数据在各级缓存中的行为优化内存访问性能和减少内存带宽消耗。class CachePolicy(enum.Enum): PREFETCH ... # 预取策略提前将数据加载到缓存中减少访问延迟 NONE_CACHEABLE ... # 不可缓存策略数据不存储在缓存中直接访问主存PREFETCH预取策略适合会被反复访问的热数据提前加载可显著降低访存延迟。NONE_CACHEABLE不可缓存策略适合一次性流式读取或写后不再复用的数据可避免污染缓存、节省带宽。七、比较运算相关OpType / OutType7.1 OpType比较操作类型OpType定义了比较操作的类型用于指定符号标量之间进行比较运算时的操作类型主要用于条件判断和逻辑运算中。class OpType(enum.Enum): EQ ... # 等于操作判断两个值是否相等 NE ... # 不等于操作判断两个值是否不相等 LT ... # 小于操作判断左值是否小于右值 LE ... # 小于等于操作判断左值是否小于或等于右值 GT ... # 大于操作判断左值是否大于右值 GE ... # 大于等于操作判断左值是否大于或等于右值7.2 OutType输出类型OutType定义了输出数据的类型用于指定某些操作如比较操作的输出格式区分布尔值输出和位值输出。class OutType(enum.Enum): BOOL ... # 布尔输出类型输出True或False BIT ... # 位输出类型输出0或1的位值7.3 二者在比较 API 中的联动从 python/pypto/op/comparison.py 可以看到Tensor 与标量的比较如最终会同时携带OpType与OutType调用底层pypto_impl.Compareif isinstance(other, float): # Tensor vs Scalar comparison return pypto_impl.Compare(input, pypto_impl.Element(input.dtype, other), OpType.LE, OutType.BOOL) return pypto_impl.Compare(input, other, OpType.LE, OutType.BOOL)即比较算子的语义由OpType决定是等于、小于还是大于等于结果的呈现格式由OutType决定输出True/False布尔值或0/1位值。BIT模式在需要把比较结果直接作为位掩码参与后续位运算时非常有用可以节省存储并提升流水效率。八、归约、激活与散射ReduceMode / ReLuType / ScatterMode8.1 ReduceMode归约执行模式ReduceMode定义了归约操作的执行模式用于指定多线程或多设备环境下的归约计算方式确保计算结果的正确性和性能。class ReduceMode(enum.Enum): ATOMIC_ADD ... # 原子加法归约使用原子操作确保多线程安全的数据累加目前该枚举仅提供ATOMIC_ADD一种取值在多个并行线程/核心向同一目标地址累加时使用硬件原子加操作保证结果正确性避免数据竞争。8.2 ReLuTypeReLU 使能控制ReLuType定义了 RELU 激活函数的模式用于启用 RELU 功能。它通常作为融合算子的开关参数出现允许在卷积、矩阵乘等算子输出侧就地融合 ReLU减少中间张量的写回与重读。class ReLuType(enum.Enum): NO_RELU ... # 不使能ReLu功能 RELU ... # 使能ReLu功能8.3 ScatterModescatter 归约模式ScatterMode定义了 scatter 函数的 reduce 模式即当多个源元素被 scatter 到同一个目标位置时如何合并class ScatterMode(enum.Enum): NONE ... # 仅做数据搬运 ADD ... # 加法模式 MULTIPLY ... # 乘法模式NONE仅做数据搬运目标位置直接写入最后一个写入者胜出。ADD目标位置累加所有散入的源值。MULTIPLY目标位置累积相乘所有散入的源值。九、TopK 算法选择TopKAlgo9.1 功能与原型TopKAlgo定义了 TopK 的算法用于控制 TopK 计算时的处理方式。class TopKAlgo(enum.Enum): MERGE_SORT ... # 归并排序算法 RADIX_SELECT ... # 基数选择算法9.2 参数说明参数值说明MERGE_SORT归并排序算法。对整个张量排序之后选出前 k 个数。RADIX_SELECT基数选择算法。先找出第 k 个数之后根据第 k 个数找出前 k 个数。9.3 使用建议默认行为如果不指定算法默认使用MERGE_SORT模式。性能要求高的场景推荐使用RADIX_SELECT模式时间复杂度为 O(n)。对性能要求不高的场景可以使用MERGE_SORT模式时间复杂度为 O(nlogn)。9.4 源码中的默认值与调用链python/pypto/op/comparison.py 中topk的原型证实了默认算法为MERGE_SORT并将参数原样透传给底层pypto_impl.TopKop_wrapper def topk( input: Tensor, k: int, dim: Optional[int] None, largest: bool True, algo: TopKAlgo TopKAlgo.MERGE_SORT ) - Tuple[Tensor, Tensor]: Returns the k largest elements of the given input tensor along a given dimension. ... x pypto.tensor([2, 3], pypto.DT_FP32) y pypto.topk(x, 2, -1, True) Input x: [[1.0 2.0 3.0], [1.0 2.0 3.0]] Output y[0]: [[3.0 2.0], [3.0 2.0]] Output y[1]: [[2 1], [2 1]] return pypto_impl.TopK(input, k, (-1 if dim is None else dim), largest, algo)函数返回(values, indices)元组values为沿指定维度最大的 k 个元素largestFalse时返回最小的 k 个indices为对应下标dim缺省时取最后一维。9.5 使用示例import pypto # 创建张量 x pypto.tensor([2, 3], pypto.DT_FP32) # 使用归并排序算法 y pypto.topk(x, 2, -1, True, pypto.TopKAlgo.MERGE_SORT) # 使用基数选择算法 y pypto.topk(x, 2, -1, True, pypto.TopKAlgo.RADIX_SELECT) # 默认使用归并排序算法 y pypto.topk(x, 2, -1, True)十、总结与选型速查PyPTO 的数据类型体系可以按职责划分为四层实际编码时可按需选用类型标识层DataType含DT_*常量别名标识 Tensor 的存储格式与精度是创建张量、规划内存的入口bytes_of用于查询占用字节数。注意 FP8 系列DT_FP8E4M3/DT_FP8E5M2/DT_FP8E8M0仅 Ascend 950 系列支持。数值转换层CastMode控制舍入模式FP→INT 默认CAST_TRUNC其余默认CAST_RINTSaturationMode控制溢出钳位TransMode控制 matmul 的 FP32→TF32 转换仅 Ascend 950 系列支持。算子行为层PrecisionType默认HIGH_PRECISION注意 A2/A3 仅支持INTRINSIC与LogBaseType约束 div/log/exp 等数学算子TopKAlgo选择 TopK 算法默认MERGE_SORTOpType/OutType组合定义比较语义与输出格式。布局与并行层TileOpFormatND/NZ、CachePolicy预取/不可缓存、ReduceMode原子加、ReLuType融合开关、ScatterMode散射归约模式。所有这些枚举在 python/pypto/enum.py 中统一导出底层由 C 绑定模块实现既保证了 Python 前端的易用性又确保了算子下发到硬件时的类型一致性。建议在正式编码前先通过pypto.bytes_of核对目标平台上的类型位宽再结合各枚举的产品支持说明选择合适取值从而在精度、性能与平台兼容性之间取得平衡。【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CANN PyPTO 数据类型体系完全指南：DataType 枚举、转换模式与工具函数详解
CANN PyPTO 数据类型体系完全指南DataType 枚举、转换模式与工具函数详解【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto导读本文基于 CANN PyPTO 仓库 docs/zh/api/tensor_api/datatype/ 下的 15 个数据类型相关 API 文档系统梳理 PyPTOParallel Tensor/Tile Operation 编程范式中面向张量Tensor操作的全部枚举类型与辅助工具函数从核心的DataType数据类型标识到控制数值转换的CastMode/SaturationMode/TransMode再到约束算子行为的PrecisionType/TopKAlgo/OpType等。读完本文你将掌握 PyPTO 中每种枚举的取值语义、产品支持差异、底层舍入规则以及它们在pypto.div、pypto.topk、pypto.bytes_of等真实 API 中的正确用法。一、数据类型索引一览本文主题对应仓库中的 15 个独立页面它们共同构成 PyPTO 的数据类型 API 集合在 datatype/index.md 中以 toctree 形式组织页面主题用途DataType数据类型枚举标识 Tensor 的存储格式与计算精度pypto-bytes_of工具函数查询数据类型占用的字节数CastMode转换舍入模式控制类型转换时的精度处理SaturationMode溢出处理模式控制浮点转整数时的溢出策略TransModeTF32 使能模式控制 matmul 中 FP32 转 TF32PrecisionType高精度算子模式控制 div/log/exp 等算子精度LogBaseType对数底数枚举指定对数运算的底数TileOpFormat瓦片格式枚举区分 ND 与 NZ 内存布局CachePolicy缓存策略枚举控制数据在各级缓存中的行为OpType比较操作枚举指定比较运算类型OutType输出类型枚举指定比较结果输出为布尔或位值ReduceMode归约模式枚举指定多线程安全的归约方式ReLuTypeReLU 使能枚举控制是否使能 ReLU 功能ScatterModescatter 归约模式指定 scatter 时的归约方式TopKAlgoTopK 算法枚举选择 TopK 计算算法从源码结构看这些枚举类在 python/pypto/enum.py 中统一从底层 C 绑定模块pypto_impl导入如DataType pypto_impl.DataType、CastMode pypto_impl.CastMode说明它们是 PTO 框架 Python 前端与 C 内核共享的类型定义枚举值最终会透传到算子实现与代码生成阶段。二、核心类型标识DataType2.1 功能与原型DataType是 PyPTO 中表示 Tensor 数据类型的核心枚举类用于指定 Tensor 的存储格式和计算精度。其原型定义与常量说明如下class DataType(enum.Enum): ... # 枚举类定义包含所有支持的数据类型 # 数据类型常量定义 DT_INT4 ... # 4位有符号整数占用0.5字节内存 DT_INT8 ... # 8位有符号整数占用1字节内存 DT_INT16 ... # 16位有符号整数占用2字节内存 DT_INT32 ... # 32位有符号整数占用4字节内存 DT_INT64 ... # 64位有符号整数占用8字节内存 DT_FP8 ... # 8位浮点数用于低精度计算 DT_FP16 ... # 16位半精度浮点数占用2字节内存 DT_FP32 ... # 32位单精度浮点数占用4字节内存 DT_BF16 ... # 16位Brain Float格式占用2字节内存 DT_HF4 ... # 4位Half Float格式占用0.5字节内存 DT_HF8 ... # 8位Half Float格式占用1字节内存 DT_FP4E2M1 ... # 4位浮点数2位指数1位尾数两个元素占用1字节内存 DT_FP8E4M3 ... # 8位浮点数4位指数3位尾数占用1字节内存 DT_FP8E5M2 ... # 8位浮点数5位指数2位尾数占用1字节内存 DT_FP8E8M0 ... # 8位浮点数8位指数0位尾数占用1字节内存 DT_FP4_E2M1X2 ... # MXFP4格式2位指数1位尾数双元素打包占用1字节内存 DT_FP4_E1M2X2 ... # MXFP4格式1位指数2位尾数双元素打包占用1字节内存 DT_UINT8 ... # 8位无符号整数占用1字节内存 DT_UINT16 ... # 16位无符号整数占用2字节内存 DT_UINT32 ... # 32位无符号整数占用4字节内存 DT_UINT64 ... # 64位无符号整数占用8字节内存 DT_BOOL ... # 布尔类型占用1字节内存 DT_DOUBLE ... # 64位双精度浮点数占用8字节内存可以看出PyPTO 的DataType覆盖了从 4 位低精度DT_INT4、DT_FP4E2M1到 64 位高精度DT_INT64、DT_DOUBLE的完整梯度其中DT_FP4_E2M1X2/DT_FP4_E1M2X2属于 MXFP4Microscaling FP4格式采用双元素打包到 1 字节服务于新一代低比特量化推理场景。2.2 Python 端的常量别名在实际 Python 编程中这些枚举成员可以通过 python/pypto/enum.py 中导出的顶层常量直接引用无需书写DataType.DT_FP32的完整形式DT_INT4 DataType.DT_INT4 DT_FP16 DataType.DT_FP16 DT_FP32 DataType.DT_FP32 DT_BF16 DataType.DT_BF16 ... DT_BOOL DataType.DT_BOOL DT_DOUBLE DataType.DT_DOUBLE因此文档示例中的pypto.tensor([1, 3], pypto.DT_FP16)与pypto.tensor([1, 3], pypto.DataType.DT_FP16)是等价的。此外python/pypto/enum.py 还统一为这些枚举类注入了_enum_repr显示函数打印时输出形如DataType.DT_FP32的可读字符串便于调试。2.3 产品支持约束不同芯片型号支持的DataType成员存在差异以当前仓库文档为准产品型号支持情况Ascend 950PR / Ascend 950DT所有数据类型均支持Atlas A3 训练系列产品 / Atlas A3 推理系列产品不支持 DT_FP8E4M3、DT_FP8E5M2、DT_FP8E8M0Atlas A2 训练系列产品 / Atlas A2 推理系列产品不支持 DT_FP8E4M3、DT_FP8E5M2、DT_FP8E8M0也就是说FP8 系列E4M3/E5M2/E8M0仅在 Ascend 950 系列上可用在 A2/A3 平台使用这些类型前需先做平台能力校验。从文档的通用性看其余 15 个枚举页面CachePolicy、CastMode、PrecisionType等在三类产品上均标注为支持仅TransMode例外——它仅在 Ascend 950 系列上支持详见后文。三、字节大小查询工具pypto.bytes_of3.1 函数原型与参数bytes_of返回某个DataType所占的 Byte 大小是进行内存规划、workspace 估算时最常用的辅助函数bytes_of(dtype: pypto.DataType) - int参数名输入/输出说明dtype输入需要查看 Byte 大小的数据类型返回值该数据类型所占的 Byte 大小。3.2 调用示例import pypto pypto.bytes_of(pypto.DT_FP32)输出示例输出: 43.3 源码实现路径在 Python 前端python/pypto/_utils.py 中bytes_of的实现直接委托给底层 C 绑定接口def bytes_of(dtype: DataType) - int: return the number of bytes of the current datatype ... print(pypto.bytes_of(pypto.DT_FP32)) 4 # implementation return pypto_impl.BytesOf(dtype)从实现看字节数的判定逻辑发生在 C 侧pypto_impl.BytesOf与DataType枚举的位宽定义保持一致。可据此推断DT_INT4/DT_FP4E2M1等 4 位类型返回 0.5 字节的量化语义会通过该接口体现配合双元素打包格式使用时按打包后字节计算实际编码时建议以运行平台的返回值为准。四、数值转换控制枚举这一组枚举直接决定类型转换cast行为是 PyPTO 数据转换 API 中最容易影响数值结果的部分共三个CastMode、SaturationMode、TransMode。4.1 CastMode转换舍入模式CastMode定义了数据类型转换时的舍入模式用于控制浮点数转换时的精度处理方式。class CastMode(enum.Enum): CAST_NONE ... # 不指定舍入模式由框架自动选择默认值 CAST_RINT ... # 舍入到最近整数平局时舍入到偶数IEEE 754默认 CAST_ROUND ... # 舍入到最近整数平局时远离零舍入 CAST_FLOOR ... # 向下舍入向负无穷方向舍入 CAST_CEIL ... # 向上舍入向正无穷方向舍入 CAST_TRUNC ... # 截断舍入向零方向舍入 CAST_ODD ... # 舍入到奇数Von Neumann舍入方式使用注意点CAST_ODD当前仅支持 FP32→FP16 转换。CAST_NONE不是硬件支持的舍入模式而是框架层面的概念表示不指定舍入模式由框架自动选择默认值。默认 CastMode 规则当用户使用CAST_NONE或指定了硬件不支持的CastMode时框架自动采用以下默认规则转换类型默认CastMode浮点数转整数FP→INTCAST_TRUNC向零截断其他转换场景CAST_RINT舍入到最近偶数类型扩展转换类型扩展转换如 FP16→FP32、INT8→FP16、INT16→INT32 等本身是无损转换不需要舍入处理此时用户传入的CastMode参数会被忽略。不支持的 CastMode 处理当用户为某个转换指定了硬件不支持的CastMode时框架不会报错而是自动采用该转换的默认CastMode遵循上述默认规则。4.2 CastMode 二进制舍入规则详解要精确理解各舍入模式的行为差异需要先了解浮点数的二进制表示。PyPTO 文档以三种典型浮点格式为例给出了规范说明。浮点数的表示方式DT_FP16共 16bit包括 1bit 符号位S、5bit 指数位E和 10bit 尾数位M。当 E 不全为 0 或不全为 1 时表示的结果为(-1)^S × 2^(E-15) × (1 M)当 E 全为 0 时表示的结果为(-1)^S × 2^(-14) × M当 E 全为 1 时若 M 全为 0表示 ±inf取决于符号位若 M 不全为 0表示 nan。DT_FP32共 32bit包括 1bit 符号位S、8bit 指数位E和 23bit 尾数位M。当 E 不全为 0 或不全为 1 时表示的结果为(-1)^S × 2^(E-127) × (1 M)当 E 全为 0 时表示的结果为(-1)^S × 2^(-126) × M当 E 全为 1 时若 M 全为 0表示 ±inf取决于符号位若 M 不全为 0表示 nan。DT_BF16共 16bit包括 1bit 符号位S、8bit 指数位E和 7bit 尾数位M。当 E 不全为 0 或不全为 1 时表示的结果为(-1)^S × 2^(E-127) × (1 M)当 E 全为 0 时表示的结果为(-1)^S × 2^(-126) × M当 E 全为 1 时若 M 全为 0表示 ±inf取决于符号位若 M 不全为 0表示 nan。注FP16、FP32 与 BF16 在指数偏移上的差异15 vs 127决定了它们动态范围的不同——BF16 与 FP32 指数位一致因此可表示的范围与 FP32 相同但尾数位更少、精度更低。各舍入模式的具体行为设待舍入部分为超出目标尾数位宽的低位比特CAST_RINT若待舍入部分的第一位为 0则不进位若第一位为 1 且后续位不全为 0则进位若第一位为 1 且后续位全为 0当 M 的最后一位为 0 则不进位当 M 的最后一位为 1 则进位即舍入到最近偶数IEEE 754 默认模式。CAST_FLOOR若 S 为 0则不进位若 S 为 1当待舍入部分全为 0 则不进位否则进位向负无穷方向负数会变得更负。CAST_CEIL若 S 为 1则不进位若 S 为 0当待舍入部分全为 0 则不进位否则进位向正无穷方向。CAST_ROUND若待舍入部分的第一位为 0则不进位否则进位四舍五入中间值远离零。CAST_TRUNC总是不进位直接截断向零方向。CAST_ODD若待舍入部分全为 0则不进位若待舍入部分不全为 0当 M 的最后一位为 1 则不进位当 M 的最后一位为 0 则进位Von Neumann 舍入结果尾数末位总为奇数。4.3 SaturationMode溢出处理模式SaturationMode定义了浮点数转整数时的溢出处理方式用于控制当源数据超出目标整数类型表示范围时的处理策略。class SaturationMode(enum.Enum): OFF ... # 截断模式默认直接截断超出部分可能导致溢出 ON ... # 饱和模式超出范围的值会被截断到目标类型的最大值或最小值OFF默认直接截断超出部分可能产生不可预期的溢出结果适合确认数据一定在目标范围内的场景。ON饱和处理超出上界钳位到目标类型的最大值、低于下界钳位到最小值适合归一化数据或对越界敏感的数值链路。4.4 TransModematmul 的 TF32 转换控制TransMode用于 matmul 输入输出矩阵均为 FP32 数据类型的场景设置是否使能 TF32 计算以及使能 TF32 时的舍入模式。使能后矩阵乘计算时 FP32 数据类型会转换为 TF32 数据类型。TF32 采用 1 个符号位、8 个指数位、10 个尾数位共 19 位进行计算。更少的尾数位减少硬件计算量、加速计算但同时也会带来精度损失。输入数据格式仍然为 FP32通过TransMode参数来确定舍入模式一般情况下采用CAST_ROUND舍入到最近整数中间值远离零模式。class TransMode(enum.Enum): CAST_NONE ... # 不使能float数据类型转换为TF32数据类型 CAST_RINT ... # 舍入到最近整数中间值时舍入到偶数 CAST_ROUND ... # 舍入到最近整数中间值时远离零舍入产品支持差异重要与大多数枚举不同TransMode仅在 Ascend 950PR/Ascend 950DT 上支持Atlas A2、A3 系列产品均不支持。在 A2/A3 上使用 matmul 时无需也无法指定 TF32 舍入模式。五、算子精度与对数底数PrecisionType / LogBaseType5.1 PrecisionType高精度向量算子模式PrecisionType定义了高精度向量算子的精度模式用于控制除法、取模、指数、对数等计算时的精度处理方式。class PrecisionType(enum.Enum): INTRINSIC ... # 指令模式直接使用芯片指令 HIGH_PRECISION ... # 高精度模式参数值说明HIGH_PRECISION高精度模式。在底层实现中使用更高精度的计算方式。INTRINSIC指令模式。直接使用芯片指令进行计算性能更高。使用建议默认行为如果不指定精度模式默认使用HIGH_PRECISION模式以确保计算精度。精度要求高的场景推荐使用HIGH_PRECISION模式可以有效减少精度损失提高计算结果的准确性。对精度要求不高但追求性能的场景可以使用INTRINSIC模式直接使用芯片指令进行计算。HIGH_PRECISION模式的产品支持Ascend 950PR/Ascend 950DT 支持Atlas A3、A2 训练/推理系列产品均不支持。支持的算子算子说明div元素级除法fmod元素级取模remainder元素级余数pow元素级幂运算exp指数运算sqrt开方运算rsqrt开方倒数运算log对数运算log2以2为底的对数运算log10以10为底的对数运算reciprocal倒数运算5.2 源码中的默认值印证在 python/pypto/op/math.py 中div的原型明确将precision_type的默认值设为PrecisionType.HIGH_PRECISION与文档默认使用高精度模式的约定完全一致def div( input: Tensor, other: Union[Tensor, float, int], precision_type: PrecisionType PrecisionType.HIGH_PRECISION ) - Tensor: ... precision_type : PrecisionType, optional The precision type for division. Default is PrecisionType.HIGH_PRECISION. Use PrecisionType.INTRINSIC to directly use chip instructions.5.3 LogBaseType对数底数LogBaseType定义了对数运算的底数类型支持常用的自然对数、以 2 为底和以 10 为底的对数运算。class LogBaseType(enum.Enum): LOG_E ... # 自然对数底数以约2.718为底的对数运算 LOG_2 ... # 以2为底的对数运算常用于信息论和计算机科学 LOG_10 ... # 以10为底的对数运算常用于科学计算和工程应用5.4 使用示例import pypto # 创建张量 a pypto.tensor([1, 3], pypto.DT_FP16) b pypto.tensor([1, 3], pypto.DT_FP16) # 使用高精度模式 out pypto.div(a, b, pypto.PrecisionType.HIGH_PRECISION) # 使用指令模式 out pypto.div(a, b, pypto.PrecisionType.INTRINSIC) # 默认使用高精度模式 out pypto.div(a, b) # 使用运算符自动使用高精度模式 out a / b # 其他算子示例 out pypto.exp(a, pypto.PrecisionType.HIGH_PRECISION) out pypto.sqrt(a, pypto.PrecisionType.INTRINSIC) out pypto.log(a, pypto.LogBaseType.LOG_E, pypto.PrecisionType.HIGH_PRECISION) out pypto.pow(a, b, pypto.PrecisionType.HIGH_PRECISION)六、数据布局与缓存TileOpFormat / CachePolicy6.1 TileOpFormat瓦片操作格式TileOpFormat定义了 Tensor 的瓦片操作格式用于优化不同计算模式下的内存访问和计算效率主要区分密集计算和稀疏计算的瓦片格式。class TileOpFormat(enum.Enum): TILEOP_ND ... # N维Tensor支持标准的多维数组操作 TILEOP_NZ ... # 同FRACTAL_NZ/NZ是对一个Tensor最低两维一个Tensor的所有维度右侧为低维左侧为高维进行填充pad、拆分reshape和转置transpose操作后得到的格式TILEOP_ND标准的多维数组行主序布局直观、易于理解和调试适合逐元素类操作。TILEOP_NZ即 FRACTAL_NZ 分形格式对 Tensor 最低两维进行 pad、reshape 与 transpose 后得到的分块转置布局是昇腾矩阵计算单元Cube友好的数据排布能提升矩阵乘等算子的访存局部性。6.2 CachePolicy缓存策略CachePolicy定义了 Tensor 的缓存策略用于控制数据在各级缓存中的行为优化内存访问性能和减少内存带宽消耗。class CachePolicy(enum.Enum): PREFETCH ... # 预取策略提前将数据加载到缓存中减少访问延迟 NONE_CACHEABLE ... # 不可缓存策略数据不存储在缓存中直接访问主存PREFETCH预取策略适合会被反复访问的热数据提前加载可显著降低访存延迟。NONE_CACHEABLE不可缓存策略适合一次性流式读取或写后不再复用的数据可避免污染缓存、节省带宽。七、比较运算相关OpType / OutType7.1 OpType比较操作类型OpType定义了比较操作的类型用于指定符号标量之间进行比较运算时的操作类型主要用于条件判断和逻辑运算中。class OpType(enum.Enum): EQ ... # 等于操作判断两个值是否相等 NE ... # 不等于操作判断两个值是否不相等 LT ... # 小于操作判断左值是否小于右值 LE ... # 小于等于操作判断左值是否小于或等于右值 GT ... # 大于操作判断左值是否大于右值 GE ... # 大于等于操作判断左值是否大于或等于右值7.2 OutType输出类型OutType定义了输出数据的类型用于指定某些操作如比较操作的输出格式区分布尔值输出和位值输出。class OutType(enum.Enum): BOOL ... # 布尔输出类型输出True或False BIT ... # 位输出类型输出0或1的位值7.3 二者在比较 API 中的联动从 python/pypto/op/comparison.py 可以看到Tensor 与标量的比较如最终会同时携带OpType与OutType调用底层pypto_impl.Compareif isinstance(other, float): # Tensor vs Scalar comparison return pypto_impl.Compare(input, pypto_impl.Element(input.dtype, other), OpType.LE, OutType.BOOL) return pypto_impl.Compare(input, other, OpType.LE, OutType.BOOL)即比较算子的语义由OpType决定是等于、小于还是大于等于结果的呈现格式由OutType决定输出True/False布尔值或0/1位值。BIT模式在需要把比较结果直接作为位掩码参与后续位运算时非常有用可以节省存储并提升流水效率。八、归约、激活与散射ReduceMode / ReLuType / ScatterMode8.1 ReduceMode归约执行模式ReduceMode定义了归约操作的执行模式用于指定多线程或多设备环境下的归约计算方式确保计算结果的正确性和性能。class ReduceMode(enum.Enum): ATOMIC_ADD ... # 原子加法归约使用原子操作确保多线程安全的数据累加目前该枚举仅提供ATOMIC_ADD一种取值在多个并行线程/核心向同一目标地址累加时使用硬件原子加操作保证结果正确性避免数据竞争。8.2 ReLuTypeReLU 使能控制ReLuType定义了 RELU 激活函数的模式用于启用 RELU 功能。它通常作为融合算子的开关参数出现允许在卷积、矩阵乘等算子输出侧就地融合 ReLU减少中间张量的写回与重读。class ReLuType(enum.Enum): NO_RELU ... # 不使能ReLu功能 RELU ... # 使能ReLu功能8.3 ScatterModescatter 归约模式ScatterMode定义了 scatter 函数的 reduce 模式即当多个源元素被 scatter 到同一个目标位置时如何合并class ScatterMode(enum.Enum): NONE ... # 仅做数据搬运 ADD ... # 加法模式 MULTIPLY ... # 乘法模式NONE仅做数据搬运目标位置直接写入最后一个写入者胜出。ADD目标位置累加所有散入的源值。MULTIPLY目标位置累积相乘所有散入的源值。九、TopK 算法选择TopKAlgo9.1 功能与原型TopKAlgo定义了 TopK 的算法用于控制 TopK 计算时的处理方式。class TopKAlgo(enum.Enum): MERGE_SORT ... # 归并排序算法 RADIX_SELECT ... # 基数选择算法9.2 参数说明参数值说明MERGE_SORT归并排序算法。对整个张量排序之后选出前 k 个数。RADIX_SELECT基数选择算法。先找出第 k 个数之后根据第 k 个数找出前 k 个数。9.3 使用建议默认行为如果不指定算法默认使用MERGE_SORT模式。性能要求高的场景推荐使用RADIX_SELECT模式时间复杂度为 O(n)。对性能要求不高的场景可以使用MERGE_SORT模式时间复杂度为 O(nlogn)。9.4 源码中的默认值与调用链python/pypto/op/comparison.py 中topk的原型证实了默认算法为MERGE_SORT并将参数原样透传给底层pypto_impl.TopKop_wrapper def topk( input: Tensor, k: int, dim: Optional[int] None, largest: bool True, algo: TopKAlgo TopKAlgo.MERGE_SORT ) - Tuple[Tensor, Tensor]: Returns the k largest elements of the given input tensor along a given dimension. ... x pypto.tensor([2, 3], pypto.DT_FP32) y pypto.topk(x, 2, -1, True) Input x: [[1.0 2.0 3.0], [1.0 2.0 3.0]] Output y[0]: [[3.0 2.0], [3.0 2.0]] Output y[1]: [[2 1], [2 1]] return pypto_impl.TopK(input, k, (-1 if dim is None else dim), largest, algo)函数返回(values, indices)元组values为沿指定维度最大的 k 个元素largestFalse时返回最小的 k 个indices为对应下标dim缺省时取最后一维。9.5 使用示例import pypto # 创建张量 x pypto.tensor([2, 3], pypto.DT_FP32) # 使用归并排序算法 y pypto.topk(x, 2, -1, True, pypto.TopKAlgo.MERGE_SORT) # 使用基数选择算法 y pypto.topk(x, 2, -1, True, pypto.TopKAlgo.RADIX_SELECT) # 默认使用归并排序算法 y pypto.topk(x, 2, -1, True)十、总结与选型速查PyPTO 的数据类型体系可以按职责划分为四层实际编码时可按需选用类型标识层DataType含DT_*常量别名标识 Tensor 的存储格式与精度是创建张量、规划内存的入口bytes_of用于查询占用字节数。注意 FP8 系列DT_FP8E4M3/DT_FP8E5M2/DT_FP8E8M0仅 Ascend 950 系列支持。数值转换层CastMode控制舍入模式FP→INT 默认CAST_TRUNC其余默认CAST_RINTSaturationMode控制溢出钳位TransMode控制 matmul 的 FP32→TF32 转换仅 Ascend 950 系列支持。算子行为层PrecisionType默认HIGH_PRECISION注意 A2/A3 仅支持INTRINSIC与LogBaseType约束 div/log/exp 等数学算子TopKAlgo选择 TopK 算法默认MERGE_SORTOpType/OutType组合定义比较语义与输出格式。布局与并行层TileOpFormatND/NZ、CachePolicy预取/不可缓存、ReduceMode原子加、ReLuType融合开关、ScatterMode散射归约模式。所有这些枚举在 python/pypto/enum.py 中统一导出底层由 C 绑定模块实现既保证了 Python 前端的易用性又确保了算子下发到硬件时的类型一致性。建议在正式编码前先通过pypto.bytes_of核对目标平台上的类型位宽再结合各枚举的产品支持说明选择合适取值从而在精度、性能与平台兼容性之间取得平衡。【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
