HIXL 数据类型枚举 DataType 详解Python API 的 14 种张量类型及底层实现【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读DataType是 HIXLHuawei Xfer LibraryPython API 中用于描述张量数据类型的枚举类在 LLM DataDist 的 KV Cache 注册、Cache 描述CacheDesc等场景中扮演类型声明的核心角色。本文以官方 API 文档 DataType.md 为主体结合仓库内 Python 绑定与 C 实现源码完整梳理 14 个枚举值的含义、Python 层与 C 层的绑定链路、与 NumPy dtype 的转换方法以及在实际示例中的典型用法帮助你正确声明数据类型并避免精度不匹配导致的传输错误。DataType 枚举类概览DataType是定义在llm_datadist包中的标准enum.Enum子类源码见 data_type.py它枚举了 HIXL 传输链路支持的全部张量数据类型覆盖浮点、有符号/无符号整数、布尔、双精度浮点与字符串类型共 14 个枚举值枚举值含义DT_FLOAT32位浮点数DT_FLOAT1616位浮点数DT_BF1616位brain floatDT_INT88位有符号整数DT_INT1616位有符号整数DT_UINT1616位无符号整数DT_UINT88位无符号整数DT_INT3232位有符号整数DT_INT6464位有符号整数DT_UINT3232位无符号整数DT_UINT6464位无符号整数DT_BOOL布尔值DT_DOUBLE双精度浮点数DT_STRING字符串类型该枚举覆盖了常见的深度学习数值类型训练与推理中最常用的DT_FLOATFP32、混合精度场景的DT_FLOAT16FP16与DT_BF16Brain Float 16以及 KV Cache 索引、计数等场景所需的整型家族INT8/16/32/64、UINT8/16/32/64。底层实现Python 枚举到 C 枚举的绑定链路从源码结构看DataType的每个成员值并非在 Python 层凭空定义而是直接取自 C 层ge::DataType枚举的整型值。这条绑定链路共分两层C → Python 绑定层metadef_wrapper是一个 pybind11 模块源码见 metadef_wrapper.cc它在模块初始化时把 GE 图引擎的ge::DataType枚举逐一映射为 Pythonint常量例如m.attr(DT_FLOAT) py::int_(static_castint32_t(ge::DataType::DT_FLOAT)); m.attr(DT_FLOAT16) py::int_(static_castint32_t(ge::DataType::DT_FLOAT16)); m.attr(DT_BF16) py::int_(static_castint32_t(ge::DataType::DT_BF16)); m.attr(DT_STRING) py::int_(static_castint32_t(ge::DataType::DT_STRING));Python 枚举层data_type.py中的DataType枚举成员值即metadef_wrapper中同名常量经int()转换后的结果data_type.py例如DT_FLOAT int(metadef_wrapper.DT_FLOAT)。这意味着 Python 层使用的类型标识与底层图引擎、传输框架的类型系统完全一致不存在两层类型编号错位的风险。同时data_type.py中还维护了两张双向映射表_dwrapper_dtype_to_python_dtype与python_dtype_2_dwrapper_dtype用于 Python 枚举与包装层整型常量之间的快速互转。典型使用场景CacheDesc 中的类型声明DataType最典型的应用场景是构造CacheDescCache 描述符用它声明 KV Cache 中每个张量的数据类型。CacheDesc的构造函数签名要求data_type参数必须是DataType类型类型校验见 llm_types.pyCacheDesc(num_tensors, shape, data_type, placementPlacement.DEVICE, batch_dim_index0, seq_len_dim_index-1, kv_tensor_formatNone)仓库示例 push_cache_sample.py 给出了完整的注册流程from llm_datadist import CacheDesc, DataType, Placement cache_manager datadist.cache_manager cache_desc CacheDesc( num_tensorsNUM_TENSORS, shape[BLOCKS_NUM, KV_SHAPE], data_typeDataType.DT_FLOAT, placementPlacement.DEVICE, ) tensor torch.full((BLOCKS_NUM, KV_SHAPE), 0, dtypetorch.float).npu() addr int(tensor.data_ptr()) cache cache_manager.register_cache(cache_desc, [addr, addr2])这里有一个关键的一致性要求CacheDesc中声明的data_type必须与实际 tensor 的内存 dtype 一致上例中DataType.DT_FLOAT对应torch.float。如果声明类型与实际数据精度不一致可能导致传输过程中按错误的字节宽度解析数据。混合精度训练中常用的对应关系包括DataTypePyTorch dtype说明DT_FLOAT16torch.float16半精度训练主力类型DT_BF16torch.bfloat16Brain Float与 FP16 同为 16 位但精度分布不同DT_FLOATtorch.float32默认单精度DT_DOUBLEtorch.float64双精度常用于数值敏感计算DT_INT8 / DT_INT32 / DT_INT64torch.int8 / torch.int32 / torch.int64索引、计数等整型数据DT_BOOLtorch.bool布尔标志值得注意的是CacheDesc的size属性会通过包装层函数calc_tensor_size(shape, data_type.value)依据 shape 与类型计算张量字节大小llm_types.py其 C 侧实现CalcTensorSize将数据类型强转为ge::DataType后调用LLMUtils::CalcTensorMemSize完成字节数计算llm_wrapper_v2.cc。这说明DataType的枚举值不仅是语义标签还直接参与底层的内存大小计算。与 NumPy dtype 的双向转换data_type.py提供了一套 DataType 与 NumPy dtype 之间的转换工具便于与 numpy 数组无缝衔接。出于懒加载设计这些工具仅在首次访问时才导入 numpy源码注释明确说明这是为版本兼容性保留的机制预计在 10.0.x 版本删除见 data_type.pydtype_to_np_dtypeDataType → numpy dtype的映射字典np_dtype_to_dtypenumpy dtype → DataType的反向映射字典valid_np_dtypes所有受支持的 numpy dtype 列表可用于合法性校验。映射关系如下摘自源码实现DataTypeNumPy dtypeDT_FLOATnp.float32DT_FLOAT16np.float16DT_BF16np.float16DT_INT8np.int8DT_INT16np.int16DT_UINT16np.uint16DT_UINT8np.uint8DT_INT32np.int32DT_INT64np.int64DT_UINT32np.uint32DT_UINT64np.uint64DT_BOOLnp.bool_DT_DOUBLEnp.doubleDT_STRINGnp.bytes_使用示例from llm_datadist import DataType # DataType 转 numpy dtype np_float DataType.dtype_to_np_dtype[DataType.DT_FLOAT] # numpy.float32 np_fp16 DataType.dtype_to_np_dtype[DataType.DT_FLOAT16] # numpy.float16 # numpy dtype 转 DataType dt DataType.np_dtype_to_dtype[np.dtype(np.float32)] # DataType.DT_FLOAT需要特别注意两点映射语义DT_BF16与DT_FLOAT16在 numpy 侧都映射为np.float16。这是因为 NumPy 本身没有原生的 bfloat16 类型两者在 numpy 中无法区分实际声明类型时仍需根据张量真实布局选择DT_BF16或DT_FLOAT16不要依赖 numpy 侧的反向映射做精确判别。DT_STRING映射为np.bytes_字节串而非 Python 的str类型这是字节级传输语义的体现。类型转换的容错机制除了映射字典data_type.py还暴露了函数get_python_dtype_from_wrapper_dtype(wrapper_dtype)data_type.py当传入的包装层类型不在支持范围内时会抛出ValueError并提示The data type xxx is not supported.避免未知类型在传输链路中静默传播。最佳实践与注意事项声明一致性在CacheDesc、Cache等对象中声明的DataType必须与注册内存的实际张量 dtype 完全一致传输两端如 Prompt 侧与 Decoder 侧应使用相同的类型声明否则字节宽度解析不一致会导致数据错乱。优先使用混合精度主流类型KV Cache 场景通常使用DT_FLOAT16或DT_BF16以节省显存需要精确数值计算时使用DT_FLOAT或DT_DOUBLE。选择时注意 bf16 与 fp16 的精度范围差异bf16 动态范围更大、尾数精度更低应结合模型实际精度需求决定。勿混用 numpy 映射做类型判等由于DT_BF16与DT_FLOAT16在 numpy 侧同为np.float16涉及两者的判别逻辑应在DataType枚举层面完成而不是通过 numpy dtype 反查。类型即字节大小DataType会参与CalcTensorSize的底层计算llm_wrapper_v2.cc错误声明类型将直接导致内存大小与真实分配不符进而影响传输与校验。相关文档与代码索引官方 API 参考DataType.md、CacheDesc.md、Cache.mdPython 枚举实现data_type.pyC 绑定层metadef_wrapper.cc类型参与大小计算的实现llm_wrapper_v2.cc使用 DataType 的示例push_cache_sample.py、pull_cache_sample.py、hixl_transfer_backend_sample.py相关测试llm_datadist_v2_api_unittest.cc、data_cache_engine_unittest.cc【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HIXL 数据类型枚举 DataType 详解Python API 的 14 种张量类型及底层实现【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读DataType是 HIXLHuawei Xfer LibraryPython API 中用于描述张量数据类型的枚举类在 LLM DataDist 的 KV Cache 注册、Cache 描述CacheDesc等场景中扮演类型声明的核心角色。本文以官方 API 文档 DataType.md 为主体结合仓库内 Python 绑定与 C 实现源码完整梳理 14 个枚举值的含义、Python 层与 C 层的绑定链路、与 NumPy dtype 的转换方法以及在实际示例中的典型用法帮助你正确声明数据类型并避免精度不匹配导致的传输错误。DataType 枚举类概览DataType是定义在llm_datadist包中的标准enum.Enum子类源码见 data_type.py它枚举了 HIXL 传输链路支持的全部张量数据类型覆盖浮点、有符号/无符号整数、布尔、双精度浮点与字符串类型共 14 个枚举值枚举值含义DT_FLOAT32位浮点数DT_FLOAT1616位浮点数DT_BF1616位brain floatDT_INT88位有符号整数DT_INT1616位有符号整数DT_UINT1616位无符号整数DT_UINT88位无符号整数DT_INT3232位有符号整数DT_INT6464位有符号整数DT_UINT3232位无符号整数DT_UINT6464位无符号整数DT_BOOL布尔值DT_DOUBLE双精度浮点数DT_STRING字符串类型该枚举覆盖了常见的深度学习数值类型训练与推理中最常用的DT_FLOATFP32、混合精度场景的DT_FLOAT16FP16与DT_BF16Brain Float 16以及 KV Cache 索引、计数等场景所需的整型家族INT8/16/32/64、UINT8/16/32/64。底层实现Python 枚举到 C 枚举的绑定链路从源码结构看DataType的每个成员值并非在 Python 层凭空定义而是直接取自 C 层ge::DataType枚举的整型值。这条绑定链路共分两层C → Python 绑定层metadef_wrapper是一个 pybind11 模块源码见 metadef_wrapper.cc它在模块初始化时把 GE 图引擎的ge::DataType枚举逐一映射为 Pythonint常量例如m.attr(DT_FLOAT) py::int_(static_castint32_t(ge::DataType::DT_FLOAT)); m.attr(DT_FLOAT16) py::int_(static_castint32_t(ge::DataType::DT_FLOAT16)); m.attr(DT_BF16) py::int_(static_castint32_t(ge::DataType::DT_BF16)); m.attr(DT_STRING) py::int_(static_castint32_t(ge::DataType::DT_STRING));Python 枚举层data_type.py中的DataType枚举成员值即metadef_wrapper中同名常量经int()转换后的结果data_type.py例如DT_FLOAT int(metadef_wrapper.DT_FLOAT)。这意味着 Python 层使用的类型标识与底层图引擎、传输框架的类型系统完全一致不存在两层类型编号错位的风险。同时data_type.py中还维护了两张双向映射表_dwrapper_dtype_to_python_dtype与python_dtype_2_dwrapper_dtype用于 Python 枚举与包装层整型常量之间的快速互转。典型使用场景CacheDesc 中的类型声明DataType最典型的应用场景是构造CacheDescCache 描述符用它声明 KV Cache 中每个张量的数据类型。CacheDesc的构造函数签名要求data_type参数必须是DataType类型类型校验见 llm_types.pyCacheDesc(num_tensors, shape, data_type, placementPlacement.DEVICE, batch_dim_index0, seq_len_dim_index-1, kv_tensor_formatNone)仓库示例 push_cache_sample.py 给出了完整的注册流程from llm_datadist import CacheDesc, DataType, Placement cache_manager datadist.cache_manager cache_desc CacheDesc( num_tensorsNUM_TENSORS, shape[BLOCKS_NUM, KV_SHAPE], data_typeDataType.DT_FLOAT, placementPlacement.DEVICE, ) tensor torch.full((BLOCKS_NUM, KV_SHAPE), 0, dtypetorch.float).npu() addr int(tensor.data_ptr()) cache cache_manager.register_cache(cache_desc, [addr, addr2])这里有一个关键的一致性要求CacheDesc中声明的data_type必须与实际 tensor 的内存 dtype 一致上例中DataType.DT_FLOAT对应torch.float。如果声明类型与实际数据精度不一致可能导致传输过程中按错误的字节宽度解析数据。混合精度训练中常用的对应关系包括DataTypePyTorch dtype说明DT_FLOAT16torch.float16半精度训练主力类型DT_BF16torch.bfloat16Brain Float与 FP16 同为 16 位但精度分布不同DT_FLOATtorch.float32默认单精度DT_DOUBLEtorch.float64双精度常用于数值敏感计算DT_INT8 / DT_INT32 / DT_INT64torch.int8 / torch.int32 / torch.int64索引、计数等整型数据DT_BOOLtorch.bool布尔标志值得注意的是CacheDesc的size属性会通过包装层函数calc_tensor_size(shape, data_type.value)依据 shape 与类型计算张量字节大小llm_types.py其 C 侧实现CalcTensorSize将数据类型强转为ge::DataType后调用LLMUtils::CalcTensorMemSize完成字节数计算llm_wrapper_v2.cc。这说明DataType的枚举值不仅是语义标签还直接参与底层的内存大小计算。与 NumPy dtype 的双向转换data_type.py提供了一套 DataType 与 NumPy dtype 之间的转换工具便于与 numpy 数组无缝衔接。出于懒加载设计这些工具仅在首次访问时才导入 numpy源码注释明确说明这是为版本兼容性保留的机制预计在 10.0.x 版本删除见 data_type.pydtype_to_np_dtypeDataType → numpy dtype的映射字典np_dtype_to_dtypenumpy dtype → DataType的反向映射字典valid_np_dtypes所有受支持的 numpy dtype 列表可用于合法性校验。映射关系如下摘自源码实现DataTypeNumPy dtypeDT_FLOATnp.float32DT_FLOAT16np.float16DT_BF16np.float16DT_INT8np.int8DT_INT16np.int16DT_UINT16np.uint16DT_UINT8np.uint8DT_INT32np.int32DT_INT64np.int64DT_UINT32np.uint32DT_UINT64np.uint64DT_BOOLnp.bool_DT_DOUBLEnp.doubleDT_STRINGnp.bytes_使用示例from llm_datadist import DataType # DataType 转 numpy dtype np_float DataType.dtype_to_np_dtype[DataType.DT_FLOAT] # numpy.float32 np_fp16 DataType.dtype_to_np_dtype[DataType.DT_FLOAT16] # numpy.float16 # numpy dtype 转 DataType dt DataType.np_dtype_to_dtype[np.dtype(np.float32)] # DataType.DT_FLOAT需要特别注意两点映射语义DT_BF16与DT_FLOAT16在 numpy 侧都映射为np.float16。这是因为 NumPy 本身没有原生的 bfloat16 类型两者在 numpy 中无法区分实际声明类型时仍需根据张量真实布局选择DT_BF16或DT_FLOAT16不要依赖 numpy 侧的反向映射做精确判别。DT_STRING映射为np.bytes_字节串而非 Python 的str类型这是字节级传输语义的体现。类型转换的容错机制除了映射字典data_type.py还暴露了函数get_python_dtype_from_wrapper_dtype(wrapper_dtype)data_type.py当传入的包装层类型不在支持范围内时会抛出ValueError并提示The data type xxx is not supported.避免未知类型在传输链路中静默传播。最佳实践与注意事项声明一致性在CacheDesc、Cache等对象中声明的DataType必须与注册内存的实际张量 dtype 完全一致传输两端如 Prompt 侧与 Decoder 侧应使用相同的类型声明否则字节宽度解析不一致会导致数据错乱。优先使用混合精度主流类型KV Cache 场景通常使用DT_FLOAT16或DT_BF16以节省显存需要精确数值计算时使用DT_FLOAT或DT_DOUBLE。选择时注意 bf16 与 fp16 的精度范围差异bf16 动态范围更大、尾数精度更低应结合模型实际精度需求决定。勿混用 numpy 映射做类型判等由于DT_BF16与DT_FLOAT16在 numpy 侧同为np.float16涉及两者的判别逻辑应在DataType枚举层面完成而不是通过 numpy dtype 反查。类型即字节大小DataType会参与CalcTensorSize的底层计算llm_wrapper_v2.cc错误声明类型将直接导致内存大小与真实分配不符进而影响传输与校验。相关文档与代码索引官方 API 参考DataType.md、CacheDesc.md、Cache.mdPython 枚举实现data_type.pyC 绑定层metadef_wrapper.cc类型参与大小计算的实现llm_wrapper_v2.cc使用 DataType 的示例push_cache_sample.py、pull_cache_sample.py、hixl_transfer_backend_sample.py相关测试llm_datadist_v2_api_unittest.cc、data_cache_engine_unittest.cc【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
