MAX 数据类型详解max.dtype 模块的 DType 枚举与 finfo 数值属性查询【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo导读max.dtype是 MAX Python API 中定义张量数据类型的核心模块在 max/python/docs/dtype.rst 中被列为与driver、engine、graph、nn等并列的一级模块见 index.rst。该模块向 Python 层暴露两个公开 API描述所有张量数据类型的DType枚举以及用于查询浮点类型数值精度属性的finfo工具类。阅读本文后你将掌握如何在 MAX Engine 中选用正确的数据类型、在 DType 与 NumPy/MLIR 类型系统之间互转以及如何为 bfloat16、float8、float4 等 NumPy 无法原生表示的格式查询精度边界。max.dtype 模块的组成与定位max.dtype位于 max/python/max/dtype/其公开导出面由init.py 定义from . import dtype_extension from .dtype import DType from .dtype_extension import finfo模块顶层文档字符串dtype.py明确其定位为 Data types for tensors in MAX EngineMAX Engine 张量的数据类型。整个模块由三个文件协作完成文件职责__init__.py公共导出面仅暴露DType与finfo两个名字dtype.py在 nanobind 生成的DType枚举上补充 Python 层扩展NumPy/MLIR 互转、缺失值解析、reprdtype_extension.py实现finfo类为 NumPy 不支持的浮点格式提供硬编码精度参数其中DType枚举本体由 C/nanobind 扩展在max._core.dtype中实现其类型签名与成员文档记录于 stub 文件 max/python/max/_core/dtype.pyi。DTypeMAX 的张量数据类型枚举DType是一个enum.Enum见 max/python/max/_core/dtype.pyi覆盖了 MAX 编译与运行时所需的全部标量张量类型共分三类布尔与整数类型枚举成员说明DType.bool布尔类型存储True/FalseDType.int88 位有符号整数范围 -128 ~ 127DType.int1616 位有符号整数范围 -32,768 ~ 32,767DType.int3232 位有符号整数范围 -2,147,483,648 ~ 2,147,483,647DType.int6464 位有符号整数范围 ±9,223,372,036,854,775,807DType.uint88 位无符号整数范围 0 ~ 255DType.uint1616 位无符号整数范围 0 ~ 65,535DType.uint3232 位无符号整数范围 0 ~ 4,294,967,295DType.uint6464 位无符号整数范围 0 ~ 18,446,744,073,709,551,615标准浮点类型枚举成员说明DType.float1616 位 IEEE 754 半精度1 符号位 5 指数位 10 尾数位DType.float3232 位 IEEE 754 单精度1 符号位 8 指数位 23 尾数位DType.float6464 位 IEEE 754 双精度1 符号位 11 指数位 52 尾数位DType.bfloat1616 位 Brain Float1 符号位 8 指数位 7 尾数位与 float32 同指数范围精度更低低精度浮点类型float4 / float6 / float8MAX 为 AI 推理与量化场景原生支持 OCP MX 与 MLIR 生态中的低精度格式枚举成员位布局说明DType.float4_e2m1fn2 指数位 1 尾数位4 位浮点仅有限值DType.float6_e2m3fn2 指数位 3 尾数位6 位浮点仅有限值DType.float6_e3m2fn3 指数位 2 尾数位6 位浮点仅有限值DType.float8_e8m0fnu8 指数位 0 尾数位8 位浮点仅有限值、无符号位常用于缩放因子DType.float8_e4m3fn4 指数位 3 尾数位8 位浮点仅有限值DType.float8_e4m3fnuz4 指数位 3 尾数位同 e4m3fn但无负零DType.float8_e5m25 指数位 2 尾数位8 位浮点支持 inf/NaNDType.float8_e5m2fnuz5 指数位 2 尾数位仅有限值、无负零DType 的属性与类型判定方法DType除枚举成员外还提供一组用于内存布局与类型分类的成员max/python/max/_core/dtype.pyialignproperty返回该类型的对齐要求字节数用于保证内存访问正确性与性能size_in_bitsproperty存储单个值所需位数size_in_bytesproperty存储单个值所需字节数is_integral()是否为整数类型is_unsigned_integral()/is_signed_integral()是否为无符号/有符号整数is_float()是否为浮点类型is_float8()是否为 8 位浮点类型is_half()是否为半精度浮点类型float16 / bfloat16。这些判定方法在finfo的实现中扮演关键角色——finfo正是通过dtype.is_float()来校验入参是否为浮点类型的见下文。与 NumPy 类型系统的互转max.dtype为DType挂载了双向转换能力实现于 dtype.py通过运行时 monkey-patch 附加到 C 枚举上DType.to_numpy _to_numpy # DType - np.dtype DType.from_numpy _from_numpy # np.dtype / numpy 类型 - DTypeto_numpy()将 DType 转为对应的 NumPy dtype若目标类型不受支持则抛出ValueError: unsupported DType to convert to NumPyfrom_numpy(dtype)同时接受np.dtype对象与 NumPy 类型对象如np.float32不支持的输入抛出ValueError: unsupported NumPy dtype。正向映射表_DTYPE_TO_NUMPYdtype.py值得注意float8 各变体float8_e8m0fnu、float8_e4m3fn、float8_e4m3fnuz、float8_e5m2、float8_e5m2fnuz在 NumPy 中无对应原生类型因此统一映射为np.uint8作为存储容器标准类型则一一对应float16 → np.float16、float32 → np.float32、float64 → np.float64等。反向映射_NUMPY_TO_DTYPE只包含布尔、8/16/32/64 位整数与三种标准浮点——这意味着从np.uint8转换回来得到的是DType.uint8而非某个 float8 类型属于单向不可逆的存储映射。与 MLIR 类型系统的映射MAX 编译器底层基于 MLIR因此DType还暴露了一个_mlirpropertydtype.py返回对应的 MLIR 类型字符串_DTYPE_TO_MLIR { DType.bool: i1, DType.int8: si8, DType.int16: si16, DType.int32: si32, DType.int64: si64, DType.uint8: ui8, DType.uint16: ui16, DType.uint32: ui32, DType.uint64: ui64, DType.float4_e2m1fn: f4e2m1fn, DType.float6_e2m3fn: f6e2m3fn, DType.float6_e3m2fn: f6e3m2fn, DType.float8_e8m0fnu: f8e8m0fnu, DType.float8_e4m3fn: f8e4m3fn, DType.float8_e4m3fnuz: f8e4m3fnuz, DType.float8_e5m2: f8e5m2, DType.float8_e5m2fnuz: f8e5m2fnuz, DType.float16: f16, DType.float32: f32, DType.float64: f64, DType.bfloat16: bf16, }同时通过_missing_钩子dtype.py实现了反向查找当以字符串形式访问不存在的枚举成员时如DType(f32)会尝试从_MLIR_TO_DTYPE反查并返回对应的 DType。此外__repr__被定制为直接返回成员名如DType.float32方便在日志与交互式环境中阅读。finfo浮点类型的数值属性查询finfo是max.dtype公开的第二个 API其定位是仿照torch.finfo设计见 dtype_extension.py 的类文档字符串为 MAX 的每一个浮点 DType 提供数值精度属性。由于 bfloat16、float8、float4、float6 等格式 NumPy 无法原生表示finfo专门为这些类型提供了硬编码精度参数。用法与构造规则import max.dtype as d info d.finfo(d.DType.float32) print(info.bits) # 32 print(info.eps) # 1.1920928955078125e-07 print(info.max) # 3.4028234663852886e38构造规则仅接受浮点类型。若传入非浮点类型如DType.int32构造函数会调用dtype.is_float()校验并抛出TypeError: finfo only supports floating-point types, got int32属性一览属性含义bits类型的位宽eps机器精度machine epsilon即 1 与该类型可表示的最小大于 1 的数之差max该类型可表示的最大有限值min该类型可表示的最小有限值通常为-maxe8m0fnu 无符号位时为最小正数tiny该类型可表示的最小正规格化数smallest_normaltiny的别名兼容torch.finfo的命名dtype被查询的 DType 本身精度参数表对于标准 IEEE 浮点float16/float32/float64finfo直接委托给 NumPy 的np.finfodtype_extension.py对于 NumPy 无法表示的类型则使用依据 IEEE 754 与 OCP MX 规范推导的硬编码值DTypebitsepsmaxmintinybfloat16160.0078125 (2⁻⁷)≈3.3895e38≈-3.3895e38≈1.1755e-38 (2⁻¹²⁶)float8_e4m3fn80.125 (2⁻³)448.0-448.00.015625 (2⁻⁶)float8_e4m3fnuz80.125 (2⁻³)240.0-240.00.0078125 (2⁻⁷)float8_e5m280.25 (2⁻²)57344.0-57344.06.103515625e-05 (2⁻¹⁴)float8_e5m2fnuz80.25 (2⁻²)57344.0-57344.03.0517578125e-05 (2⁻¹⁵)float8_e8m0fnu81.02¹²⁷2⁻¹²⁷2⁻¹²⁷float4_e2m1fn40.56.0-6.01.0float6_e2m3fn60.125 (2⁻³)7.5-7.51.0float6_e3m2fn60.25 (2⁻²)28.0-28.00.25 (2⁻²)数值来源dtype_extension.py 中的_HARDCODED_FINFO表。从表中可以直观看出各类低精度格式的特性例如float8_e8m0fnu没有符号位其min与tiny相同、均为最小正数而float8_e4m3fn的最大值仅 448适合权重/激活量化场景bfloat16则凭借与 float32 相同的 8 位指数位覆盖了几乎相同的数值范围代价是更粗的尾数精度。与 DType 的集成方式finfo不仅作为模块级函数导出还被挂载为DType的类方法DType.finfo finfo # dtype_extension.py因此存在两种等价调用方式d.finfo(d.DType.bfloat16) # 模块级调用 d.DType.bfloat16.finfo() # 枚举成员方法调用一个值得注意的实现细节记录于 max/python/docs/CLAUDE.md由于finfo是 monkey-patch 到DType上的文档构建系统在 conf.py.in 中做了显式跳过处理避免其重复出现在DType的成员列表中它拥有独立的文档页。典型使用场景结合上述 API以下场景最能体现max.dtype的价值1. 创建张量前选择合适的 dtype在 MAX Engine 中构建模型输入或图时用DType.float32通用精度或DType.bfloat16/ 各类 float8内存与带宽受限的推理部署声明张量类型。size_in_bits与align属性可用于估算显存占用与内存布局。2. 与 NumPy 生态互操作import numpy as np import max.dtype as d arr np.zeros((2, 2), dtypenp.float32) dt d.DType.from_numpy(arr.dtype) # DType.float32 back dt.to_numpy() # np.dtype(float32)3. 数值分析时的精度边界查询在实现量化方案或数值稳定性检查时通过finfo获取目标类型的eps决定量化步长的下界参考、max决定缩放因子的上限与tiny判断是否发生下溢。4. 与编译器交互在需要把 Python 侧的 dtype 传入 MLIR 层如自定义算子或图构建时_mlir属性提供类型字符串如f32、bf16、f8e4m3fn可直接拼接生成 MLIR 类型。小结max.dtype是 MAX Python API 中规模虽小但地位基础的类型系统模块DType枚举完整覆盖从bool、各类整数到标准浮点、再到 bfloat16/float4/float6/float8 的 AI 计算类型谱系并通过to_numpy/from_numpy/_mlir实现与 NumPy、MLIR 两大生态的无缝对接finfo则为全部浮点格式包括 NumPy 无法表达的格式提供以 IEEE 754 与 OCP MX 规范为基准的精度参数查询是量化选型与数值分析的有力工具。两个 API 的实现分别位于 dtype.py 与 dtype_extension.py枚举定义与类型签名可在 max/python/max/_core/dtype.pyi 中查阅。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MAX 数据类型详解：max.dtype 模块的 DType 枚举与 finfo 数值属性查询
MAX 数据类型详解max.dtype 模块的 DType 枚举与 finfo 数值属性查询【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo导读max.dtype是 MAX Python API 中定义张量数据类型的核心模块在 max/python/docs/dtype.rst 中被列为与driver、engine、graph、nn等并列的一级模块见 index.rst。该模块向 Python 层暴露两个公开 API描述所有张量数据类型的DType枚举以及用于查询浮点类型数值精度属性的finfo工具类。阅读本文后你将掌握如何在 MAX Engine 中选用正确的数据类型、在 DType 与 NumPy/MLIR 类型系统之间互转以及如何为 bfloat16、float8、float4 等 NumPy 无法原生表示的格式查询精度边界。max.dtype 模块的组成与定位max.dtype位于 max/python/max/dtype/其公开导出面由init.py 定义from . import dtype_extension from .dtype import DType from .dtype_extension import finfo模块顶层文档字符串dtype.py明确其定位为 Data types for tensors in MAX EngineMAX Engine 张量的数据类型。整个模块由三个文件协作完成文件职责__init__.py公共导出面仅暴露DType与finfo两个名字dtype.py在 nanobind 生成的DType枚举上补充 Python 层扩展NumPy/MLIR 互转、缺失值解析、reprdtype_extension.py实现finfo类为 NumPy 不支持的浮点格式提供硬编码精度参数其中DType枚举本体由 C/nanobind 扩展在max._core.dtype中实现其类型签名与成员文档记录于 stub 文件 max/python/max/_core/dtype.pyi。DTypeMAX 的张量数据类型枚举DType是一个enum.Enum见 max/python/max/_core/dtype.pyi覆盖了 MAX 编译与运行时所需的全部标量张量类型共分三类布尔与整数类型枚举成员说明DType.bool布尔类型存储True/FalseDType.int88 位有符号整数范围 -128 ~ 127DType.int1616 位有符号整数范围 -32,768 ~ 32,767DType.int3232 位有符号整数范围 -2,147,483,648 ~ 2,147,483,647DType.int6464 位有符号整数范围 ±9,223,372,036,854,775,807DType.uint88 位无符号整数范围 0 ~ 255DType.uint1616 位无符号整数范围 0 ~ 65,535DType.uint3232 位无符号整数范围 0 ~ 4,294,967,295DType.uint6464 位无符号整数范围 0 ~ 18,446,744,073,709,551,615标准浮点类型枚举成员说明DType.float1616 位 IEEE 754 半精度1 符号位 5 指数位 10 尾数位DType.float3232 位 IEEE 754 单精度1 符号位 8 指数位 23 尾数位DType.float6464 位 IEEE 754 双精度1 符号位 11 指数位 52 尾数位DType.bfloat1616 位 Brain Float1 符号位 8 指数位 7 尾数位与 float32 同指数范围精度更低低精度浮点类型float4 / float6 / float8MAX 为 AI 推理与量化场景原生支持 OCP MX 与 MLIR 生态中的低精度格式枚举成员位布局说明DType.float4_e2m1fn2 指数位 1 尾数位4 位浮点仅有限值DType.float6_e2m3fn2 指数位 3 尾数位6 位浮点仅有限值DType.float6_e3m2fn3 指数位 2 尾数位6 位浮点仅有限值DType.float8_e8m0fnu8 指数位 0 尾数位8 位浮点仅有限值、无符号位常用于缩放因子DType.float8_e4m3fn4 指数位 3 尾数位8 位浮点仅有限值DType.float8_e4m3fnuz4 指数位 3 尾数位同 e4m3fn但无负零DType.float8_e5m25 指数位 2 尾数位8 位浮点支持 inf/NaNDType.float8_e5m2fnuz5 指数位 2 尾数位仅有限值、无负零DType 的属性与类型判定方法DType除枚举成员外还提供一组用于内存布局与类型分类的成员max/python/max/_core/dtype.pyialignproperty返回该类型的对齐要求字节数用于保证内存访问正确性与性能size_in_bitsproperty存储单个值所需位数size_in_bytesproperty存储单个值所需字节数is_integral()是否为整数类型is_unsigned_integral()/is_signed_integral()是否为无符号/有符号整数is_float()是否为浮点类型is_float8()是否为 8 位浮点类型is_half()是否为半精度浮点类型float16 / bfloat16。这些判定方法在finfo的实现中扮演关键角色——finfo正是通过dtype.is_float()来校验入参是否为浮点类型的见下文。与 NumPy 类型系统的互转max.dtype为DType挂载了双向转换能力实现于 dtype.py通过运行时 monkey-patch 附加到 C 枚举上DType.to_numpy _to_numpy # DType - np.dtype DType.from_numpy _from_numpy # np.dtype / numpy 类型 - DTypeto_numpy()将 DType 转为对应的 NumPy dtype若目标类型不受支持则抛出ValueError: unsupported DType to convert to NumPyfrom_numpy(dtype)同时接受np.dtype对象与 NumPy 类型对象如np.float32不支持的输入抛出ValueError: unsupported NumPy dtype。正向映射表_DTYPE_TO_NUMPYdtype.py值得注意float8 各变体float8_e8m0fnu、float8_e4m3fn、float8_e4m3fnuz、float8_e5m2、float8_e5m2fnuz在 NumPy 中无对应原生类型因此统一映射为np.uint8作为存储容器标准类型则一一对应float16 → np.float16、float32 → np.float32、float64 → np.float64等。反向映射_NUMPY_TO_DTYPE只包含布尔、8/16/32/64 位整数与三种标准浮点——这意味着从np.uint8转换回来得到的是DType.uint8而非某个 float8 类型属于单向不可逆的存储映射。与 MLIR 类型系统的映射MAX 编译器底层基于 MLIR因此DType还暴露了一个_mlirpropertydtype.py返回对应的 MLIR 类型字符串_DTYPE_TO_MLIR { DType.bool: i1, DType.int8: si8, DType.int16: si16, DType.int32: si32, DType.int64: si64, DType.uint8: ui8, DType.uint16: ui16, DType.uint32: ui32, DType.uint64: ui64, DType.float4_e2m1fn: f4e2m1fn, DType.float6_e2m3fn: f6e2m3fn, DType.float6_e3m2fn: f6e3m2fn, DType.float8_e8m0fnu: f8e8m0fnu, DType.float8_e4m3fn: f8e4m3fn, DType.float8_e4m3fnuz: f8e4m3fnuz, DType.float8_e5m2: f8e5m2, DType.float8_e5m2fnuz: f8e5m2fnuz, DType.float16: f16, DType.float32: f32, DType.float64: f64, DType.bfloat16: bf16, }同时通过_missing_钩子dtype.py实现了反向查找当以字符串形式访问不存在的枚举成员时如DType(f32)会尝试从_MLIR_TO_DTYPE反查并返回对应的 DType。此外__repr__被定制为直接返回成员名如DType.float32方便在日志与交互式环境中阅读。finfo浮点类型的数值属性查询finfo是max.dtype公开的第二个 API其定位是仿照torch.finfo设计见 dtype_extension.py 的类文档字符串为 MAX 的每一个浮点 DType 提供数值精度属性。由于 bfloat16、float8、float4、float6 等格式 NumPy 无法原生表示finfo专门为这些类型提供了硬编码精度参数。用法与构造规则import max.dtype as d info d.finfo(d.DType.float32) print(info.bits) # 32 print(info.eps) # 1.1920928955078125e-07 print(info.max) # 3.4028234663852886e38构造规则仅接受浮点类型。若传入非浮点类型如DType.int32构造函数会调用dtype.is_float()校验并抛出TypeError: finfo only supports floating-point types, got int32属性一览属性含义bits类型的位宽eps机器精度machine epsilon即 1 与该类型可表示的最小大于 1 的数之差max该类型可表示的最大有限值min该类型可表示的最小有限值通常为-maxe8m0fnu 无符号位时为最小正数tiny该类型可表示的最小正规格化数smallest_normaltiny的别名兼容torch.finfo的命名dtype被查询的 DType 本身精度参数表对于标准 IEEE 浮点float16/float32/float64finfo直接委托给 NumPy 的np.finfodtype_extension.py对于 NumPy 无法表示的类型则使用依据 IEEE 754 与 OCP MX 规范推导的硬编码值DTypebitsepsmaxmintinybfloat16160.0078125 (2⁻⁷)≈3.3895e38≈-3.3895e38≈1.1755e-38 (2⁻¹²⁶)float8_e4m3fn80.125 (2⁻³)448.0-448.00.015625 (2⁻⁶)float8_e4m3fnuz80.125 (2⁻³)240.0-240.00.0078125 (2⁻⁷)float8_e5m280.25 (2⁻²)57344.0-57344.06.103515625e-05 (2⁻¹⁴)float8_e5m2fnuz80.25 (2⁻²)57344.0-57344.03.0517578125e-05 (2⁻¹⁵)float8_e8m0fnu81.02¹²⁷2⁻¹²⁷2⁻¹²⁷float4_e2m1fn40.56.0-6.01.0float6_e2m3fn60.125 (2⁻³)7.5-7.51.0float6_e3m2fn60.25 (2⁻²)28.0-28.00.25 (2⁻²)数值来源dtype_extension.py 中的_HARDCODED_FINFO表。从表中可以直观看出各类低精度格式的特性例如float8_e8m0fnu没有符号位其min与tiny相同、均为最小正数而float8_e4m3fn的最大值仅 448适合权重/激活量化场景bfloat16则凭借与 float32 相同的 8 位指数位覆盖了几乎相同的数值范围代价是更粗的尾数精度。与 DType 的集成方式finfo不仅作为模块级函数导出还被挂载为DType的类方法DType.finfo finfo # dtype_extension.py因此存在两种等价调用方式d.finfo(d.DType.bfloat16) # 模块级调用 d.DType.bfloat16.finfo() # 枚举成员方法调用一个值得注意的实现细节记录于 max/python/docs/CLAUDE.md由于finfo是 monkey-patch 到DType上的文档构建系统在 conf.py.in 中做了显式跳过处理避免其重复出现在DType的成员列表中它拥有独立的文档页。典型使用场景结合上述 API以下场景最能体现max.dtype的价值1. 创建张量前选择合适的 dtype在 MAX Engine 中构建模型输入或图时用DType.float32通用精度或DType.bfloat16/ 各类 float8内存与带宽受限的推理部署声明张量类型。size_in_bits与align属性可用于估算显存占用与内存布局。2. 与 NumPy 生态互操作import numpy as np import max.dtype as d arr np.zeros((2, 2), dtypenp.float32) dt d.DType.from_numpy(arr.dtype) # DType.float32 back dt.to_numpy() # np.dtype(float32)3. 数值分析时的精度边界查询在实现量化方案或数值稳定性检查时通过finfo获取目标类型的eps决定量化步长的下界参考、max决定缩放因子的上限与tiny判断是否发生下溢。4. 与编译器交互在需要把 Python 侧的 dtype 传入 MLIR 层如自定义算子或图构建时_mlir属性提供类型字符串如f32、bf16、f8e4m3fn可直接拼接生成 MLIR 类型。小结max.dtype是 MAX Python API 中规模虽小但地位基础的类型系统模块DType枚举完整覆盖从bool、各类整数到标准浮点、再到 bfloat16/float4/float6/float8 的 AI 计算类型谱系并通过to_numpy/from_numpy/_mlir实现与 NumPy、MLIR 两大生态的无缝对接finfo则为全部浮点格式包括 NumPy 无法表达的格式提供以 IEEE 754 与 OCP MX 规范为基准的精度参数查询是量化选型与数值分析的有力工具。两个 API 的实现分别位于 dtype.py 与 dtype_extension.py枚举定义与类型签名可在 max/python/max/_core/dtype.pyi 中查阅。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
