HIXL 内存信息结构体 MemInfoPython 接口解析、Memtype 枚举与 remap_registered_memory 故障修复实践【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读MemInfo 是 CANN HIXL 项目中 LLM-DataDist Python 接口中用于描述一块待处理内存的轻量数据结构它由内存类型Memtype、起始地址addr与长度size三元组构成。它的主要应用场景有两个一是作为CacheManager.remap_registered_memory()的参数用于在 KV Cache 内存发生 UCE 故障后向网卡重新注册修复后的内存二是作为 LLM-DataDist 内部把内存描述跨语言Python → C传递的载体。读完本文你将掌握 MemInfo 的完整构造规则、Memtype枚举语义、各型号产品的支持范围以及如何配合CacheManager.remap_registered_memory()写出可用的故障修复调用链。说明本文以 MemInfo.md 为核心主体结合仓库中的 Python 绑定与 C 封装源码进行验证与扩充。MemInfo 文档在仓库中的原始位置为 docs/zh/api/python/MemInfo.md与之配套的枚举定义见 MemType.md。函数功能与定位MemInfo 在 LLM-DataDist 中的角色MemInfo用于构造一段内存描述信息通常作为CacheManager.remap_registered_memory接口的参数类型使用该接口的完整说明见 CacheManager.md 的 remap_registered_memory 章节。也就是说MemInfo 本身并不触发任何数据传输它只是把内存类型 地址 大小封装成一个可校验、可传递的对象供上层框架在内存故障修复等场景中描述待处理的内存区域。从源码实现看MemInfo 是 LLM-DataDist v2 Python 包中公开的数据结构之一定义在 src/python/llm_datadist/llm_datadist/v2/llm_types.pyclass MemInfo(object): def __init__(self, mem_type: Memtype, addr: int, size: int): ... check_isinstance(mem_type, mem_type, Memtype) check_isinstance(addr, addr, int) check_isinstance(size, size, int) self._mem_type mem_type self._addr addr self._size size可以看到构造函数内部会对三个参数逐一做类型校验check_isinstancemem_type必须是Memtype枚举类型addr与size必须是 Python 内置int类型。校验不通过时即抛出TypeError或ValueError异常这与文档传入数据类型错误情况下会抛出 TypeError 或 ValueError 异常的返回值说明完全一致。MemInfo 同时暴露了三个只读属性mem_type、addr、size并实现了__str__/__repr__方便打印调试。整个类体非常精简是一个典型的纯数据载体DTO结构不依赖任何运行时上下文因此也可以脱离 CacheManager 单独构造使用。产品支持情况MemInfo 的构造与使用受设备型号支持范围的约束。根据文档说明其支持情况如下Ascend 950PR / Ascend 950DT支持注意该系列产品不支持remap_registered_memory接口本身详见后文约束说明Atlas A3 训练系列产品 / Atlas A3 推理系列产品支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品支持但仅支持 Atlas 800I A2 推理服务器、A200I A2 Box 异构组件。由于 MemInfo 最核心的用途是配合remap_registered_memory使用在实际规划部署时应同时核对目标型号对remap_registered_memory的支持情况在 Ascend 950PR/Ascend 950DT 上该接口不支持此时 MemInfo 仅可用于其他场景例如作为内存描述信息传递。函数原型与参数说明函数原型__init__(mem_type: Memtype, addr: int, size: int)参数说明参数名称数据类型取值说明mem_typeMemtype内存地址类型。addrint内存地址。sizeint内存地址对应大小单位字节。对参数细节的补充addr是内存的虚拟地址如故障场景下通过torch_npu.npu.restart_device等机制获取的错误虚拟地址以整数形式传入。从 C 封装层看该值最终被解析为 64 位整数见下文源码级实现链路一节因此从 Python 侧传入的int值会在包装时被转换为uint64/int64语义使用。size以字节为单位必须大于 0。在remap_registered_memory的调用路径中Python 层会强制校验mem_info.size 0见 cache_manager.py非法取值会抛出LLMException。mem_type的合法取值由Memtype枚举给出详见下一节。Memtype 枚举内存地址类型Memtype用于表示地址所在位置是MemInfo.mem_type参数的类型。其定义位于 src/python/llm_datadist/llm_datadist/v2/llm_types.pyclass Memtype(Enum): MEM_TYPE_DEVICE 0 MEM_TYPE_HOST 1枚举值含义MEM_TYPE_DEVICE表示设备是 Device即昇腾设备侧显存。MEM_TYPE_HOST表示设备是 Host即主机侧内存。在 MemType.md 中对该枚举的语义说明与上述源码定义一一对应。需要特别注意的一点是在remap_registered_memory的调用路径上目前只支持Memtype.MEM_TYPE_DEVICE类型的内存修复文档约束说明章节亦写明当前仅支持 Device 类型的内存修复。Python 侧会逐个校验列表中的 MemInfo遇到非 DEVICE 类型会直接报错raise_if_false( mem_info.mem_type Memtype.MEM_TYPE_DEVICE, fcheck mem_info.mem_type failed, only support Memtype.MEM_TYPE_DEVICE, index{i}., )因此在故障修复场景中构造 MemInfo 时请务必使用Memtype.MEM_TYPE_DEVICE。调用示例基础构造示例文档给出的最简构造示例from llm_datadist import MemInfo mem_info MemInfo(Memtype.MEM_TYPE_DEVICE, 1234, 10)该示例构造了一个 Device 类型、起始地址为 1234、长度为 10 字节的内存描述对象。构造成功后可通过只读属性读取各字段print(mem_info.mem_type) # Memtype.MEM_TYPE_DEVICE print(mem_info.addr) # 1234 print(mem_info.size) # 10 print(mem_info) # MemInfo(mem_typeMemtype.MEM_TYPE_DEVICE, addr1234, size10)完整故障修复场景示例配合 CacheManagerMemInfo 的典型实战用法是配合CacheManager.remap_registered_memory()完成 KV Cache 内存 UCE 故障修复。CacheManager实例通过LLMDataDist.cache_manager获取生命周期与 LLMDataDist 初始化周期一致见 CacheManager.md。完整示例from llm_datadist import * role LLMRole.PROMPT # 发生故障的角色 cluster_id 1 # 发生故障的LLMDataDist id datadist LLMDataDist(role, cluster_id) cache_manager datadist.cache_manager addr 12345678 # 发生故障的地址 size 1024 # 发生故障的地址大小 mem_info MemInfo(Memtype.MEM_TYPE_DEVICE, addr, size) cache_manager.remap_registered_memory(mem_info)remap_registered_memory的原型为remap_registered_memory(mem_infos: Union[MemInfo, list[MemInfo]]) - None即既可以传入单个MemInfo也可以传入MemInfo的列表例如一次修复多段故障内存时mem_infos [ MemInfo(Memtype.MEM_TYPE_DEVICE, addr_1, size_1), MemInfo(Memtype.MEM_TYPE_DEVICE, addr_2, size_2), ] cache_manager.remap_registered_memory(mem_infos)使用前提源自 CacheManager.md 的 remap_registered_memory 章节该接口当前为预留接口暂不支持大模型推理过程中发生内存 UCE 故障时运行时返回错误码ACL_ERROR_RT_DEVICE_MEM_ERROR上层框架需先判断故障内存是否为 KV Cache 内存如果不是 KV Cache 内存请参考 PyTorchtorch_npu.npu.restart_device接口的说明获取并修复内存 UCE 的错误虚拟地址如果是 KV Cache 内存则需要再调用本接口remap_registered_memory修复注册给网卡的 KV Cache 内存当前仅支持 Device 类型的内存修复且 Ascend 950PR/Ascend 950DT 不支持该接口。返回值与异常正常情况返回MemInfo的实例即构造成功。传入数据类型错误抛出TypeError或ValueError异常。这一行为源自构造函数内部的check_isinstance强类型校验——例如把mem_type传成字符串、把addr传成浮点数都会在构造阶段立即失败。补充说明当 MemInfo 被传给remap_registered_memory时非法取值如size 0、mem_type非 DEVICE、mem_infos不是 MemInfo 或 MemInfo 列表还会抛出LLMException详见 cache_manager.py 中的raise_if_false校验逻辑与handle_llm_status错误处理。源码级实现链路MemInfo 如何跨越 Python 与 C 边界为了理解 MemInfo 的实际作用有必要梳理它从 Python 对象到 C 层的完整传递链路对应 CacheManager.md 中remap_registered_memory接口的实现第 1 步Python 侧打包。cache_manager.remap_registered_memory()校验完 MemInfo 列表后调用pack_mem_info把每个 MemInfo 展开为元组(mem_type.value, addr, size)见 src/python/llm_datadist/llm_datadist/v2/llm_utils.pydef pack_mem_info(mem_info: MemInfo) - Tuple[int, int, int]: return (mem_info.mem_type.value, mem_info.addr, mem_info.size)第 2 步Wrapper 拆包。元组列表通过 pybind 绑定进入 C 封装层LLMDataDistV2Wrapper::RemapRegisteredMemory把std::vectorMemInfoTuple拆包为内部结构LLMMemInfo见 src/python/llm_wrapper/llm_datadist_v2_wrapper.cc 与 src/python/llm_wrapper/llm_datadist_v2_wrapper.ccge::Status LLMDataDistV2Wrapper::RemapRegisteredMemory(const std::vectorMemInfoTuple mem_infos) { auto unpacked LLMDataDistV2Wrapper::UnpackMemInfos(mem_infos); std::shared_lockstd::shared_mutex lock(mutex_); LLM_CHECK_NOTNULL(llm_data_dist); return llm_data_dist-RemapRegisteredMemory(unpacked); }第 3 步进入引擎核心。拆包后的LLMMemInfo最终交给llm_data_dist-RemapRegisteredMemory()执行实际的网卡内存重映射操作。从这条链路可以看出MemInfo 的设计意图非常清晰用最小的字段集类型/地址/大小承载内存描述信息在 Python 侧做严格类型校验在 C 侧做拆包与语义转换。这也是为什么文档强调它通常在 remap_registered_memory 中作为参数类型使用——它是 LLM-DataDist 内存故障修复能力与上层框架之间的标准内存描述协议。约束说明MemInfo 构造本身无额外约束文档约束说明章节为无。但将其用于remap_registered_memory时需遵循以下由接口带来的约束详见 CacheManager.md 的 remap_registered_memory 章节当前仅支持 Device 类型的内存修复即mem_type必须为Memtype.MEM_TYPE_DEVICEAscend 950PR/Ascend 950DT 不支持remap_registered_memory接口该接口为预留接口暂不支持传入数据类型错误时抛出TypeError或ValueError。延伸阅读MemType.mdMemtype枚举的完整语义MEM_TYPE_DEVICE / MEM_TYPE_HOST。CacheManager.mdremap_registered_memory接口的完整说明、使用前提与约束以及 CacheManager 生命周期管理LLMDataDist.init()/finalize()后旧实例失效规则。MemInfo 源码定义Python 侧类实现与类型校验逻辑。remap_registered_memory 实现Python 侧参数校验与调用封装。pack_mem_info 打包函数Python → C 边界处的元组化转换。C 封装层 RemapRegisteredMemory跨语言调用链的 C 入口。完整的可运行示例请参考 examples/python/README.mdLLM-DataDist 相关示例位于 examples/python/llm_datadist 目录。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HIXL 内存信息结构体 MemInfo：Python 接口解析、Memtype 枚举与 remap_registered_memory 故障修复实践
HIXL 内存信息结构体 MemInfoPython 接口解析、Memtype 枚举与 remap_registered_memory 故障修复实践【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读MemInfo 是 CANN HIXL 项目中 LLM-DataDist Python 接口中用于描述一块待处理内存的轻量数据结构它由内存类型Memtype、起始地址addr与长度size三元组构成。它的主要应用场景有两个一是作为CacheManager.remap_registered_memory()的参数用于在 KV Cache 内存发生 UCE 故障后向网卡重新注册修复后的内存二是作为 LLM-DataDist 内部把内存描述跨语言Python → C传递的载体。读完本文你将掌握 MemInfo 的完整构造规则、Memtype枚举语义、各型号产品的支持范围以及如何配合CacheManager.remap_registered_memory()写出可用的故障修复调用链。说明本文以 MemInfo.md 为核心主体结合仓库中的 Python 绑定与 C 封装源码进行验证与扩充。MemInfo 文档在仓库中的原始位置为 docs/zh/api/python/MemInfo.md与之配套的枚举定义见 MemType.md。函数功能与定位MemInfo 在 LLM-DataDist 中的角色MemInfo用于构造一段内存描述信息通常作为CacheManager.remap_registered_memory接口的参数类型使用该接口的完整说明见 CacheManager.md 的 remap_registered_memory 章节。也就是说MemInfo 本身并不触发任何数据传输它只是把内存类型 地址 大小封装成一个可校验、可传递的对象供上层框架在内存故障修复等场景中描述待处理的内存区域。从源码实现看MemInfo 是 LLM-DataDist v2 Python 包中公开的数据结构之一定义在 src/python/llm_datadist/llm_datadist/v2/llm_types.pyclass MemInfo(object): def __init__(self, mem_type: Memtype, addr: int, size: int): ... check_isinstance(mem_type, mem_type, Memtype) check_isinstance(addr, addr, int) check_isinstance(size, size, int) self._mem_type mem_type self._addr addr self._size size可以看到构造函数内部会对三个参数逐一做类型校验check_isinstancemem_type必须是Memtype枚举类型addr与size必须是 Python 内置int类型。校验不通过时即抛出TypeError或ValueError异常这与文档传入数据类型错误情况下会抛出 TypeError 或 ValueError 异常的返回值说明完全一致。MemInfo 同时暴露了三个只读属性mem_type、addr、size并实现了__str__/__repr__方便打印调试。整个类体非常精简是一个典型的纯数据载体DTO结构不依赖任何运行时上下文因此也可以脱离 CacheManager 单独构造使用。产品支持情况MemInfo 的构造与使用受设备型号支持范围的约束。根据文档说明其支持情况如下Ascend 950PR / Ascend 950DT支持注意该系列产品不支持remap_registered_memory接口本身详见后文约束说明Atlas A3 训练系列产品 / Atlas A3 推理系列产品支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品支持但仅支持 Atlas 800I A2 推理服务器、A200I A2 Box 异构组件。由于 MemInfo 最核心的用途是配合remap_registered_memory使用在实际规划部署时应同时核对目标型号对remap_registered_memory的支持情况在 Ascend 950PR/Ascend 950DT 上该接口不支持此时 MemInfo 仅可用于其他场景例如作为内存描述信息传递。函数原型与参数说明函数原型__init__(mem_type: Memtype, addr: int, size: int)参数说明参数名称数据类型取值说明mem_typeMemtype内存地址类型。addrint内存地址。sizeint内存地址对应大小单位字节。对参数细节的补充addr是内存的虚拟地址如故障场景下通过torch_npu.npu.restart_device等机制获取的错误虚拟地址以整数形式传入。从 C 封装层看该值最终被解析为 64 位整数见下文源码级实现链路一节因此从 Python 侧传入的int值会在包装时被转换为uint64/int64语义使用。size以字节为单位必须大于 0。在remap_registered_memory的调用路径中Python 层会强制校验mem_info.size 0见 cache_manager.py非法取值会抛出LLMException。mem_type的合法取值由Memtype枚举给出详见下一节。Memtype 枚举内存地址类型Memtype用于表示地址所在位置是MemInfo.mem_type参数的类型。其定义位于 src/python/llm_datadist/llm_datadist/v2/llm_types.pyclass Memtype(Enum): MEM_TYPE_DEVICE 0 MEM_TYPE_HOST 1枚举值含义MEM_TYPE_DEVICE表示设备是 Device即昇腾设备侧显存。MEM_TYPE_HOST表示设备是 Host即主机侧内存。在 MemType.md 中对该枚举的语义说明与上述源码定义一一对应。需要特别注意的一点是在remap_registered_memory的调用路径上目前只支持Memtype.MEM_TYPE_DEVICE类型的内存修复文档约束说明章节亦写明当前仅支持 Device 类型的内存修复。Python 侧会逐个校验列表中的 MemInfo遇到非 DEVICE 类型会直接报错raise_if_false( mem_info.mem_type Memtype.MEM_TYPE_DEVICE, fcheck mem_info.mem_type failed, only support Memtype.MEM_TYPE_DEVICE, index{i}., )因此在故障修复场景中构造 MemInfo 时请务必使用Memtype.MEM_TYPE_DEVICE。调用示例基础构造示例文档给出的最简构造示例from llm_datadist import MemInfo mem_info MemInfo(Memtype.MEM_TYPE_DEVICE, 1234, 10)该示例构造了一个 Device 类型、起始地址为 1234、长度为 10 字节的内存描述对象。构造成功后可通过只读属性读取各字段print(mem_info.mem_type) # Memtype.MEM_TYPE_DEVICE print(mem_info.addr) # 1234 print(mem_info.size) # 10 print(mem_info) # MemInfo(mem_typeMemtype.MEM_TYPE_DEVICE, addr1234, size10)完整故障修复场景示例配合 CacheManagerMemInfo 的典型实战用法是配合CacheManager.remap_registered_memory()完成 KV Cache 内存 UCE 故障修复。CacheManager实例通过LLMDataDist.cache_manager获取生命周期与 LLMDataDist 初始化周期一致见 CacheManager.md。完整示例from llm_datadist import * role LLMRole.PROMPT # 发生故障的角色 cluster_id 1 # 发生故障的LLMDataDist id datadist LLMDataDist(role, cluster_id) cache_manager datadist.cache_manager addr 12345678 # 发生故障的地址 size 1024 # 发生故障的地址大小 mem_info MemInfo(Memtype.MEM_TYPE_DEVICE, addr, size) cache_manager.remap_registered_memory(mem_info)remap_registered_memory的原型为remap_registered_memory(mem_infos: Union[MemInfo, list[MemInfo]]) - None即既可以传入单个MemInfo也可以传入MemInfo的列表例如一次修复多段故障内存时mem_infos [ MemInfo(Memtype.MEM_TYPE_DEVICE, addr_1, size_1), MemInfo(Memtype.MEM_TYPE_DEVICE, addr_2, size_2), ] cache_manager.remap_registered_memory(mem_infos)使用前提源自 CacheManager.md 的 remap_registered_memory 章节该接口当前为预留接口暂不支持大模型推理过程中发生内存 UCE 故障时运行时返回错误码ACL_ERROR_RT_DEVICE_MEM_ERROR上层框架需先判断故障内存是否为 KV Cache 内存如果不是 KV Cache 内存请参考 PyTorchtorch_npu.npu.restart_device接口的说明获取并修复内存 UCE 的错误虚拟地址如果是 KV Cache 内存则需要再调用本接口remap_registered_memory修复注册给网卡的 KV Cache 内存当前仅支持 Device 类型的内存修复且 Ascend 950PR/Ascend 950DT 不支持该接口。返回值与异常正常情况返回MemInfo的实例即构造成功。传入数据类型错误抛出TypeError或ValueError异常。这一行为源自构造函数内部的check_isinstance强类型校验——例如把mem_type传成字符串、把addr传成浮点数都会在构造阶段立即失败。补充说明当 MemInfo 被传给remap_registered_memory时非法取值如size 0、mem_type非 DEVICE、mem_infos不是 MemInfo 或 MemInfo 列表还会抛出LLMException详见 cache_manager.py 中的raise_if_false校验逻辑与handle_llm_status错误处理。源码级实现链路MemInfo 如何跨越 Python 与 C 边界为了理解 MemInfo 的实际作用有必要梳理它从 Python 对象到 C 层的完整传递链路对应 CacheManager.md 中remap_registered_memory接口的实现第 1 步Python 侧打包。cache_manager.remap_registered_memory()校验完 MemInfo 列表后调用pack_mem_info把每个 MemInfo 展开为元组(mem_type.value, addr, size)见 src/python/llm_datadist/llm_datadist/v2/llm_utils.pydef pack_mem_info(mem_info: MemInfo) - Tuple[int, int, int]: return (mem_info.mem_type.value, mem_info.addr, mem_info.size)第 2 步Wrapper 拆包。元组列表通过 pybind 绑定进入 C 封装层LLMDataDistV2Wrapper::RemapRegisteredMemory把std::vectorMemInfoTuple拆包为内部结构LLMMemInfo见 src/python/llm_wrapper/llm_datadist_v2_wrapper.cc 与 src/python/llm_wrapper/llm_datadist_v2_wrapper.ccge::Status LLMDataDistV2Wrapper::RemapRegisteredMemory(const std::vectorMemInfoTuple mem_infos) { auto unpacked LLMDataDistV2Wrapper::UnpackMemInfos(mem_infos); std::shared_lockstd::shared_mutex lock(mutex_); LLM_CHECK_NOTNULL(llm_data_dist); return llm_data_dist-RemapRegisteredMemory(unpacked); }第 3 步进入引擎核心。拆包后的LLMMemInfo最终交给llm_data_dist-RemapRegisteredMemory()执行实际的网卡内存重映射操作。从这条链路可以看出MemInfo 的设计意图非常清晰用最小的字段集类型/地址/大小承载内存描述信息在 Python 侧做严格类型校验在 C 侧做拆包与语义转换。这也是为什么文档强调它通常在 remap_registered_memory 中作为参数类型使用——它是 LLM-DataDist 内存故障修复能力与上层框架之间的标准内存描述协议。约束说明MemInfo 构造本身无额外约束文档约束说明章节为无。但将其用于remap_registered_memory时需遵循以下由接口带来的约束详见 CacheManager.md 的 remap_registered_memory 章节当前仅支持 Device 类型的内存修复即mem_type必须为Memtype.MEM_TYPE_DEVICEAscend 950PR/Ascend 950DT 不支持remap_registered_memory接口该接口为预留接口暂不支持传入数据类型错误时抛出TypeError或ValueError。延伸阅读MemType.mdMemtype枚举的完整语义MEM_TYPE_DEVICE / MEM_TYPE_HOST。CacheManager.mdremap_registered_memory接口的完整说明、使用前提与约束以及 CacheManager 生命周期管理LLMDataDist.init()/finalize()后旧实例失效规则。MemInfo 源码定义Python 侧类实现与类型校验逻辑。remap_registered_memory 实现Python 侧参数校验与调用封装。pack_mem_info 打包函数Python → C 边界处的元组化转换。C 封装层 RemapRegisteredMemory跨语言调用链的 C 入口。完整的可运行示例请参考 examples/python/README.mdLLM-DataDist 相关示例位于 examples/python/llm_datadist 目录。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考