尧图网页设计 
HIXL Python API 入门指南支持形态、环境约束与核心接口解析【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl本文面向需要在昇腾集群上使用 HIXLHuawei Xfer LibraryPython 接口进行点对点数据传输的开发者系统梳理 HIXL Python API 的产品支持形态、Python 环境要求、内存注册约束并基于 CANN/hixl 开源仓库的 Python 接口参考文档 与源码给出 HIXL Engine 与 LLM-DataDist 两大 Python 模块的接口总览与实用建议。读完本文你将掌握 HIXL Python API 的选型边界哪些硬件形态、哪些 Python 版本可用、初始化与建链/传输的核心流程以及如何从仓库源码与示例中快速上手。一、支持的硬件形态与传输能力约束HIXL Python API 并非在所有昇腾产品上拥有完全一致的能力不同硬件形态的传输协议与内存约束存在差异。在开始编码前请先确认目标设备的形态归属再选择对应的配置方式。Atlas A2 系列Atlas 800I A2 推理服务器 / A200I A2 Box 异构组件Atlas A2 训练系列产品/Atlas A2 推理系列产品中Python API仅支持 Atlas 800I A2 推理服务器、A200I A2 Box 异构组件核心约束如下该场景下 Server 采用 HCCS 传输协议时仅支持 D2DDevice 到 Device传输不支持 D2H/H2D 等涉及 Host 内存的传输形态。该约束同样适用于未配置中转内存池OPTION_BUFFER_POOL未配置时的默认行为参见 HIXL 接口文档 中OPTION_BUFFER_POOL的说明。Atlas A3 系列训练/推理产品Atlas A3 训练系列产品/Atlas A3 推理系列产品场景下采用 HCCS 传输协议时不支持 Host 内存作为远端 Cache即远端缓存必须落在 Device 内存上。Ascend 950PR / Ascend 950DT超节点形态Ascend 950PR/Ascend 950DT 是面向超节点SuperPod的形态其传输能力分层明确超节点内使用 UBUnified Bus协议进行通信超节点间使用 RoCE 协议进行通信。这一UB 打底、RoCE 互联的协议组合意味着在配置本地通信资源OPTION_LOCAL_COMM_RES时endpoint 的 protocol 字段需要按超节点内外分别规划ub_ctp/uboe/ub_rtp用于节点内roce用于节点间详见下文通信资源配置部分与 HIXL 接口文档。以上形态约束的权威出处为 Python API 简介文档更多接口级差异如 Ascend 950PR/950DT 不支持link、unlink、query_register_mem_status等可进一步查阅 LLMDataDist 接口文档 中的逐接口产品支持情况说明。二、Python 版本要求与获取方式HIXL Python API 的可用 Python 版本与安装方式直接相关这是新手最容易踩坑的地方昇腾官网发布包仅支持Python 3.12。如需其他 Python 版本需要通过源码编译方式安装。源码编译支持Python 3.9 – 3.14。也就是说如果你本机 Python 不是 3.12请走源码编译路线参考 源码构建文档 完成环境准备与编译安装。源码编译前需要确保已安装 Toolkit 开发套件包执行 Python 样例前还需确保已安装 ops 算子包。构建时推荐的 CANN 镜像如swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel同样以 Python 3.12 为基线可在 源码构建文档 中查看完整的 Docker 部署与手动安装步骤。从仓库源码结构看Python 侧实现位于 src/python/hixl_pyHIXL 原生 Python 绑定入口为 hixl_py.cc与 src/python/llm_datadistLLM-DataDist Python 层目录setup.py 定义了名为hixl的 Python 包descriptionHIXL Python API说明安装后通过import hixl即可使用。三、内存注册上限与 OS 内存开销约束HIXL 通过register_mem接口注册本地内存以便对端访问。Python API 对注册内存量有明确上限且上限与 HDK 版本强相关内存类别约束上限说明Device 内存最大注册50GB所有支持的形态均适用Host 内存HDK 25.5最大注册20GBHDK 版本低于 25.5 时Host 内存HDK ≥ 25.5最大注册1TBHDK 版本大于等于 25.5 时需要注意注册内存越大占用的 OS 内存越多。因此在大规模 KV Cache 场景下注册内存量与 OS 内存预算需要一并规划。除总量上限外还有几条与注册方式相关的约束详见 HIXL 接口文档建议单个 Hixl 实例注册的内存个数不超过 4K 个注册过多存在 Device OOM 风险且注册个数越多建链耗时越长过多易出现建链超时。Atlas A2/A3 形态下注册 Host 内存需使用aclrtMallocHost申请该接口申请的内存地址自动对齐注册 Device 内存使用aclrtMalloc如通过 HCCS 传输内存分配规则需配置为ACL_MEM_MALLOC_HUGE_ONLY。Ascend 950PR/950DT 场景下使用 host RoCE 网卡时不支持注册aclrtMallocHost申请的内存可使用malloc等方式。对同一内存区域相同 addr 和相同 len重复调用register_mem返回 SUCCESS 并复用首次注册的 mem_handle不会创建新的底层资源。四、Python 接口总览HIXL Engine 与 LLM-DataDistHIXL Python API 由两大模块组成接口索引见 Python 接口参考 READMEHIXL EngineHIXL Engine 模块面向底层点对点传输提供内存注册、建链/断链、同步/异步传输、Notify 通知等能力对应 HIXL 接口、HIXL 数据结构 与 HIXL 错误码。LLM-DataDistLLM-DataDist 模块面向大模型 KV Cache 场景的分布式数据分发能力以 CacheManager 为核心提供跨集群 Cache 的推送/拉取push/pull与角色切换switch_role能力配套 LLMConfig、LLMClusterInfo、CacheKey、CacheDesc 等一系列数据结构。4.1 HIXL Engine核心接口与典型调用链HIXL Engine 的调用生命周期严格遵循初始化 → 注册内存 → 建链 → 传输 → 断链 → 反初始化的顺序import hixl engine hixl.Hixl() engine.initialize(127.0.0.1:16000) # 1. 初始化local_engine 需全局唯一 mem_desc hixl.MemDesc(addrdev_addr, lenbuf_size) ret, handle engine.register_mem(mem_desc, hixl.MemType.MEM_DEVICE) # 2. 注册内存 ret engine.connect(127.0.0.1:16001, timeout_in_millis5000) # 3. 建链 op_descs [hixl.TransferOpDesc(local_addrlocal, remote_addrremote, lensize)] ret engine.transfer_sync(127.0.0.1:16001, hixl.TransferOp.READ, op_descs, timeout_in_millis30000) # 4. 传输 engine.finalize() # 5. 资源清理关键要点与约束如下完整接口语义见 HIXL 接口文档initialize(local_engine, options)local_engine为 HIXL 唯一标识ipv4 格式host_ip:host_port或host_ipipv6 格式[host_ip]:host_port或[host_ip]设置host_port0时本端作为 Server 侦听否则作为 Client。初始化前需先调用aclrtSetDevice重复调用 initialize 返回 SUCCESS 并忽略重复调用。options支持OPTION_ENABLE_USE_FABRIC_MEMFabric Mem 模式仅 Atlas A3、OPTION_BUFFER_POOL中转内存池默认4:8单位 MB0:0关闭、OPTION_RDMA_TRAFFIC_CLASS[0,255] 且为 4 的整数倍默认 132、OPTION_RDMA_SERVICE_LEVEL[0,7]默认 4、OPTION_GLOBAL_RESOURCE_CONFIG全局资源含连接池、链路池、监听端口等、OPTION_AUTO_CONNECT跳过建链直传、OPTION_LOCAL_COMM_RES本地通信资源 JSON等各参数说明与配置示例请参见 HIXL 接口文档。建链方式决定链路上限当OPTION_LOCAL_COMM_RES未配置或 version 为1.0/1.2时走集合通信通信域建链允许最大通信数量为 512建议单卡建链不超过 512当配置 version 为1.3推荐需 HDK ≥ 25.5.0 且 toolkit ≥ 9.1.0时使用 HixlCS 能力建链没有链路上限限制。version 1.3 支持最小配置仅{version: 1.3}其余字段自动生成与完整配置两种写法。传输接口transfer_sync同步批量传输与transfer_async异步传输返回 req_id通过get_transfer_status/get_all_transfer_status查询状态为 COMPLETED/FAILED 后资源释放超时需调用 disconnect 销毁链路。系统默认开启中转内存池op_desc 中本地/远端内存有一个未注册即判定走中转传输未注册的内存按 Host 内存处理中转模式下所有 op_desc 传输类型需相同。异步传输仅支持直传。Notify 机制send_notify/get_notifies用于跨 HIXL 发送轻量消息name与notify_msg长度上限均为 1024 字符每条链路最多存在 4096 条 Notify需远端及时消费适用场景如 Cache 就绪通知。能力探测模块级函数hixl.get_capability(FeatureType)可在 initialize 之前探测库是否支持特定能力如AUTO_CONNECT、CLIENT_SERVER_COMM返回FEATURE_SUPPORTED1/FEATURE_NOT_SUPPORTED0避免硬编码默认值与旧版 .so 不兼容。对应数据结构枚举取值与字段定义参见 HIXL 数据结构文档MemDescaddr/len、MemTypeMEM_DEVICE0/MEM_HOST1、TransferOpREAD0/WRITE1、TransferOpDesclocal_addr/remote_addr/len、TransferArgsuser_data、TransferStatusWAITING/COMPLETED/TIMEOUT/FAILED、AsyncConnectStatusNOT_CONNECT/CONNECT_PENDING/CONNECTING/CONNECTED/CONNECT_FAILED/DISCONNECT_PENDING/DISCONNECTING、NotifyDescname/notify_msg等。4.2 通信资源配置version 1.3HIXL Python API 推荐通过OPTION_LOCAL_COMM_RES或 LLM-DataDist 的local_comm_res配置 version 为1.3的本地通信资源。最小配置只需 version 字段{ version: 1.3 }完整配置可显式指定通信资源信息以 Ascend 950PR/950DT 的 UB 场景为例{ version: 1.3, net_instance_id: superpod1_1, server_id: server_0, endpoint_list: [ { protocol: ub_ctp, comm_id: 00000000007f020000100000df149001, placement: host, dst_eid: 00000000007f030000100000df141c01 } ] }字段含义完整字段表见 HIXL 接口文档version必选1.3需要 HDK ≥ 25.5.0 且 toolkit ≥ 9.1.0net_instance_id必选当前超节点唯一标识server_id可选仅用于 ub_ctp host 场景的同 OS H2rH loopback 判断endpoint_list[].protocolroce/ub_ctp/uboe/ub_rtpendpoint_list[].comm_idub_ctp/ub_rtp 填${eid}roce 填网卡 IPuboe 填 device uboe 网卡 IPendpoint_list[].placementhost/deviceendpoint_list[].plane可选、endpoint_list[].dst_eid可选full-mesh 直连对端的${eid}。重要提醒上述样例中的具体值comm_id、eid 等仅为格式参考实际使用时必须从当前环境查询真实通信资源配置信息进行替换直接拷贝样例值会导致通信失败。Ascend 950PR/950DT 场景下可通过 scripts/tools/lcrgen 工具辅助生成指定 NPU 的 localcommres 信息。4.3 LLM-DataDist面向 KV Cache 的 Python 接口LLM-DataDist 提供面向大模型推理/训练场景的 Cache 分发能力Decode增量与 Prompt全量集群之间可以双向拉取 Cache。核心用法如下from llm_datadist import LLMDataDist, LLMRole, LLMConfig llm_datadist LLMDataDist(LLMRole.PROMPT, 0) # 角色 集群ID建链范围内唯一 llm_config LLMConfig() llm_config.enable_cache_manager True # 必须开启 CacheManager 模式 llm_config.device_id 0 engine_options llm_config.generate_options() # 由 LLMConfig 生成配置字典 llm_datadist.init(engine_options) # ... link_clusters / cache_manager 操作 ... llm_datadist.finalize()接口要点详见 LLMDataDist 接口文档 与 LLMConfig 文档LLMDataDist(role, cluster_id)role取值LLMRole.DECODER增量集群/LLMRole.PROMPT全量集群仅标识角色、对传输无影响cluster_id为集群唯一标识。init(options)options 中必须配置 CacheManager 模式——enable_cache_managerTrue或指定local_comm_res。建链推荐使用单边建链link_clusters(clusters, timeout3000)Client 单侧发起设置listen_ip_info即作为 Server返回(LLMStatusCode, 每集群结果列表)unlink_clusters支持forceTrue强制断链两端都要调用switch_role支持运行时切换角色与 Client/Server 身份切换时存在残留链路会抛出LLM_EXIST_LINK异常。link/unlink/query_register_mem_status为基于通信域的双边建链方式Ascend 950PR/950DT 不支持ranktable 配置示例见 LLMDataDist 文档。LLMConfig 常用配置项device_id必填、enable_cache_manager、enable_remote_cache_accessible开启后本地缓存远端 Cache 元数据加速 Pull更适用于 Cache 仅在初始化阶段分配/注册的 PA 场景Atlas A3 形态不开启时仅支持 RDMA 传输、listen_ip_info如192.168.1.1:26000、sync_kv_timeout默认 1000ms、rdma_traffic_class/rdma_service_level、local_comm_res、link_total_time/link_retry_countHCCL 建链总超时与重试次数、transfer_backend取值为hixl时指定 HIXL 作为传输后端、global_resource_config仅 hixl 后端生效透传至 HIXL 引擎解析以及ge_options如ge.flowGraphMemMaxSize控制 KV cache 最大占用内存等。CacheManager通过llm_datadist.cache_manager获取实例配套 Cache、CacheManager、CacheDesc、CacheKey、BlocksCacheKey、TransferConfig 等数据结构文档使用。五、从仓库源码与示例快速验证仓库为 Python API 提供了可直接运行的示例与测试是验证配置和上手开发的最快路径示例见 examples/python 目录包括 hixl_d2rd_multiproc_sample.pyHIXL Engine 多进程示例与 llm_datadist 下的push_cache_sample.py、pull_cache_sample.py、push_blocks_sample.py、pull_blocks_sample.py、switch_role_sample.py、hixl_transfer_backend_sample.py等覆盖 Cache 推送/拉取、角色切换与 HIXL 传输后端等典型用法。Python 测试见 tests/python如 test_hixl_engine_api.py、test_cache_manager.py、test_parameter_validation.py其中参数校验类测试可作为接口约束的补充参考。C 侧实现佐证Python 绑定通过 hixl_py.cc 对接 C 侧 hixl_impl.cc 与 llm_datadist_v2.cc 等实现OPTION_GLOBAL_RESOURCE_CONFIG的全局资源解析与校验逻辑位于 hixl_options.cc链路池、连接池等机制可进一步查看 channel_manager.cc 等文件。六、总结与选型建议决策点建议硬件形态先对照 brief.md 确认目标设备属于 Atlas A2/A3 还是 Ascend 950PR/950DT再选择协议与配置Python 版本3.12 用官网发布包3.9–3.14 走 源码编译链路上限大规模多链路场景优先配置 version1.3的local_comm_resHixlCS无上限或关闭中转内存池后使用 HixlCS内存规划遵循 50GB Device / 20GB 或 1TB Host 的注册上限并结合 OS 内存开销与 4K 个注册数建议综合规划场景选择底层点对点传输用 HIXL Engine大模型 KV Cache 分发用 LLM-DataDistDecode/Prompt 双向拉取 CacheHIXL Python API 的能力边界清晰、接口分层明确HIXL Engine 负责高效稳定的点对点传输底座LLM-DataDist 在其上构建面向大模型场景的 Cache 分发能力。建议在动手开发前先对照 Python 接口参考文档 逐接口确认产品形态与版本约束再基于 examples/python 示例搭建首个可运行程序。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HIXL Python API 入门指南：支持形态、环境约束与核心接口解析
HIXL Python API 入门指南支持形态、环境约束与核心接口解析【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl本文面向需要在昇腾集群上使用 HIXLHuawei Xfer LibraryPython 接口进行点对点数据传输的开发者系统梳理 HIXL Python API 的产品支持形态、Python 环境要求、内存注册约束并基于 CANN/hixl 开源仓库的 Python 接口参考文档 与源码给出 HIXL Engine 与 LLM-DataDist 两大 Python 模块的接口总览与实用建议。读完本文你将掌握 HIXL Python API 的选型边界哪些硬件形态、哪些 Python 版本可用、初始化与建链/传输的核心流程以及如何从仓库源码与示例中快速上手。一、支持的硬件形态与传输能力约束HIXL Python API 并非在所有昇腾产品上拥有完全一致的能力不同硬件形态的传输协议与内存约束存在差异。在开始编码前请先确认目标设备的形态归属再选择对应的配置方式。Atlas A2 系列Atlas 800I A2 推理服务器 / A200I A2 Box 异构组件Atlas A2 训练系列产品/Atlas A2 推理系列产品中Python API仅支持 Atlas 800I A2 推理服务器、A200I A2 Box 异构组件核心约束如下该场景下 Server 采用 HCCS 传输协议时仅支持 D2DDevice 到 Device传输不支持 D2H/H2D 等涉及 Host 内存的传输形态。该约束同样适用于未配置中转内存池OPTION_BUFFER_POOL未配置时的默认行为参见 HIXL 接口文档 中OPTION_BUFFER_POOL的说明。Atlas A3 系列训练/推理产品Atlas A3 训练系列产品/Atlas A3 推理系列产品场景下采用 HCCS 传输协议时不支持 Host 内存作为远端 Cache即远端缓存必须落在 Device 内存上。Ascend 950PR / Ascend 950DT超节点形态Ascend 950PR/Ascend 950DT 是面向超节点SuperPod的形态其传输能力分层明确超节点内使用 UBUnified Bus协议进行通信超节点间使用 RoCE 协议进行通信。这一UB 打底、RoCE 互联的协议组合意味着在配置本地通信资源OPTION_LOCAL_COMM_RES时endpoint 的 protocol 字段需要按超节点内外分别规划ub_ctp/uboe/ub_rtp用于节点内roce用于节点间详见下文通信资源配置部分与 HIXL 接口文档。以上形态约束的权威出处为 Python API 简介文档更多接口级差异如 Ascend 950PR/950DT 不支持link、unlink、query_register_mem_status等可进一步查阅 LLMDataDist 接口文档 中的逐接口产品支持情况说明。二、Python 版本要求与获取方式HIXL Python API 的可用 Python 版本与安装方式直接相关这是新手最容易踩坑的地方昇腾官网发布包仅支持Python 3.12。如需其他 Python 版本需要通过源码编译方式安装。源码编译支持Python 3.9 – 3.14。也就是说如果你本机 Python 不是 3.12请走源码编译路线参考 源码构建文档 完成环境准备与编译安装。源码编译前需要确保已安装 Toolkit 开发套件包执行 Python 样例前还需确保已安装 ops 算子包。构建时推荐的 CANN 镜像如swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel同样以 Python 3.12 为基线可在 源码构建文档 中查看完整的 Docker 部署与手动安装步骤。从仓库源码结构看Python 侧实现位于 src/python/hixl_pyHIXL 原生 Python 绑定入口为 hixl_py.cc与 src/python/llm_datadistLLM-DataDist Python 层目录setup.py 定义了名为hixl的 Python 包descriptionHIXL Python API说明安装后通过import hixl即可使用。三、内存注册上限与 OS 内存开销约束HIXL 通过register_mem接口注册本地内存以便对端访问。Python API 对注册内存量有明确上限且上限与 HDK 版本强相关内存类别约束上限说明Device 内存最大注册50GB所有支持的形态均适用Host 内存HDK 25.5最大注册20GBHDK 版本低于 25.5 时Host 内存HDK ≥ 25.5最大注册1TBHDK 版本大于等于 25.5 时需要注意注册内存越大占用的 OS 内存越多。因此在大规模 KV Cache 场景下注册内存量与 OS 内存预算需要一并规划。除总量上限外还有几条与注册方式相关的约束详见 HIXL 接口文档建议单个 Hixl 实例注册的内存个数不超过 4K 个注册过多存在 Device OOM 风险且注册个数越多建链耗时越长过多易出现建链超时。Atlas A2/A3 形态下注册 Host 内存需使用aclrtMallocHost申请该接口申请的内存地址自动对齐注册 Device 内存使用aclrtMalloc如通过 HCCS 传输内存分配规则需配置为ACL_MEM_MALLOC_HUGE_ONLY。Ascend 950PR/950DT 场景下使用 host RoCE 网卡时不支持注册aclrtMallocHost申请的内存可使用malloc等方式。对同一内存区域相同 addr 和相同 len重复调用register_mem返回 SUCCESS 并复用首次注册的 mem_handle不会创建新的底层资源。四、Python 接口总览HIXL Engine 与 LLM-DataDistHIXL Python API 由两大模块组成接口索引见 Python 接口参考 READMEHIXL EngineHIXL Engine 模块面向底层点对点传输提供内存注册、建链/断链、同步/异步传输、Notify 通知等能力对应 HIXL 接口、HIXL 数据结构 与 HIXL 错误码。LLM-DataDistLLM-DataDist 模块面向大模型 KV Cache 场景的分布式数据分发能力以 CacheManager 为核心提供跨集群 Cache 的推送/拉取push/pull与角色切换switch_role能力配套 LLMConfig、LLMClusterInfo、CacheKey、CacheDesc 等一系列数据结构。4.1 HIXL Engine核心接口与典型调用链HIXL Engine 的调用生命周期严格遵循初始化 → 注册内存 → 建链 → 传输 → 断链 → 反初始化的顺序import hixl engine hixl.Hixl() engine.initialize(127.0.0.1:16000) # 1. 初始化local_engine 需全局唯一 mem_desc hixl.MemDesc(addrdev_addr, lenbuf_size) ret, handle engine.register_mem(mem_desc, hixl.MemType.MEM_DEVICE) # 2. 注册内存 ret engine.connect(127.0.0.1:16001, timeout_in_millis5000) # 3. 建链 op_descs [hixl.TransferOpDesc(local_addrlocal, remote_addrremote, lensize)] ret engine.transfer_sync(127.0.0.1:16001, hixl.TransferOp.READ, op_descs, timeout_in_millis30000) # 4. 传输 engine.finalize() # 5. 资源清理关键要点与约束如下完整接口语义见 HIXL 接口文档initialize(local_engine, options)local_engine为 HIXL 唯一标识ipv4 格式host_ip:host_port或host_ipipv6 格式[host_ip]:host_port或[host_ip]设置host_port0时本端作为 Server 侦听否则作为 Client。初始化前需先调用aclrtSetDevice重复调用 initialize 返回 SUCCESS 并忽略重复调用。options支持OPTION_ENABLE_USE_FABRIC_MEMFabric Mem 模式仅 Atlas A3、OPTION_BUFFER_POOL中转内存池默认4:8单位 MB0:0关闭、OPTION_RDMA_TRAFFIC_CLASS[0,255] 且为 4 的整数倍默认 132、OPTION_RDMA_SERVICE_LEVEL[0,7]默认 4、OPTION_GLOBAL_RESOURCE_CONFIG全局资源含连接池、链路池、监听端口等、OPTION_AUTO_CONNECT跳过建链直传、OPTION_LOCAL_COMM_RES本地通信资源 JSON等各参数说明与配置示例请参见 HIXL 接口文档。建链方式决定链路上限当OPTION_LOCAL_COMM_RES未配置或 version 为1.0/1.2时走集合通信通信域建链允许最大通信数量为 512建议单卡建链不超过 512当配置 version 为1.3推荐需 HDK ≥ 25.5.0 且 toolkit ≥ 9.1.0时使用 HixlCS 能力建链没有链路上限限制。version 1.3 支持最小配置仅{version: 1.3}其余字段自动生成与完整配置两种写法。传输接口transfer_sync同步批量传输与transfer_async异步传输返回 req_id通过get_transfer_status/get_all_transfer_status查询状态为 COMPLETED/FAILED 后资源释放超时需调用 disconnect 销毁链路。系统默认开启中转内存池op_desc 中本地/远端内存有一个未注册即判定走中转传输未注册的内存按 Host 内存处理中转模式下所有 op_desc 传输类型需相同。异步传输仅支持直传。Notify 机制send_notify/get_notifies用于跨 HIXL 发送轻量消息name与notify_msg长度上限均为 1024 字符每条链路最多存在 4096 条 Notify需远端及时消费适用场景如 Cache 就绪通知。能力探测模块级函数hixl.get_capability(FeatureType)可在 initialize 之前探测库是否支持特定能力如AUTO_CONNECT、CLIENT_SERVER_COMM返回FEATURE_SUPPORTED1/FEATURE_NOT_SUPPORTED0避免硬编码默认值与旧版 .so 不兼容。对应数据结构枚举取值与字段定义参见 HIXL 数据结构文档MemDescaddr/len、MemTypeMEM_DEVICE0/MEM_HOST1、TransferOpREAD0/WRITE1、TransferOpDesclocal_addr/remote_addr/len、TransferArgsuser_data、TransferStatusWAITING/COMPLETED/TIMEOUT/FAILED、AsyncConnectStatusNOT_CONNECT/CONNECT_PENDING/CONNECTING/CONNECTED/CONNECT_FAILED/DISCONNECT_PENDING/DISCONNECTING、NotifyDescname/notify_msg等。4.2 通信资源配置version 1.3HIXL Python API 推荐通过OPTION_LOCAL_COMM_RES或 LLM-DataDist 的local_comm_res配置 version 为1.3的本地通信资源。最小配置只需 version 字段{ version: 1.3 }完整配置可显式指定通信资源信息以 Ascend 950PR/950DT 的 UB 场景为例{ version: 1.3, net_instance_id: superpod1_1, server_id: server_0, endpoint_list: [ { protocol: ub_ctp, comm_id: 00000000007f020000100000df149001, placement: host, dst_eid: 00000000007f030000100000df141c01 } ] }字段含义完整字段表见 HIXL 接口文档version必选1.3需要 HDK ≥ 25.5.0 且 toolkit ≥ 9.1.0net_instance_id必选当前超节点唯一标识server_id可选仅用于 ub_ctp host 场景的同 OS H2rH loopback 判断endpoint_list[].protocolroce/ub_ctp/uboe/ub_rtpendpoint_list[].comm_idub_ctp/ub_rtp 填${eid}roce 填网卡 IPuboe 填 device uboe 网卡 IPendpoint_list[].placementhost/deviceendpoint_list[].plane可选、endpoint_list[].dst_eid可选full-mesh 直连对端的${eid}。重要提醒上述样例中的具体值comm_id、eid 等仅为格式参考实际使用时必须从当前环境查询真实通信资源配置信息进行替换直接拷贝样例值会导致通信失败。Ascend 950PR/950DT 场景下可通过 scripts/tools/lcrgen 工具辅助生成指定 NPU 的 localcommres 信息。4.3 LLM-DataDist面向 KV Cache 的 Python 接口LLM-DataDist 提供面向大模型推理/训练场景的 Cache 分发能力Decode增量与 Prompt全量集群之间可以双向拉取 Cache。核心用法如下from llm_datadist import LLMDataDist, LLMRole, LLMConfig llm_datadist LLMDataDist(LLMRole.PROMPT, 0) # 角色 集群ID建链范围内唯一 llm_config LLMConfig() llm_config.enable_cache_manager True # 必须开启 CacheManager 模式 llm_config.device_id 0 engine_options llm_config.generate_options() # 由 LLMConfig 生成配置字典 llm_datadist.init(engine_options) # ... link_clusters / cache_manager 操作 ... llm_datadist.finalize()接口要点详见 LLMDataDist 接口文档 与 LLMConfig 文档LLMDataDist(role, cluster_id)role取值LLMRole.DECODER增量集群/LLMRole.PROMPT全量集群仅标识角色、对传输无影响cluster_id为集群唯一标识。init(options)options 中必须配置 CacheManager 模式——enable_cache_managerTrue或指定local_comm_res。建链推荐使用单边建链link_clusters(clusters, timeout3000)Client 单侧发起设置listen_ip_info即作为 Server返回(LLMStatusCode, 每集群结果列表)unlink_clusters支持forceTrue强制断链两端都要调用switch_role支持运行时切换角色与 Client/Server 身份切换时存在残留链路会抛出LLM_EXIST_LINK异常。link/unlink/query_register_mem_status为基于通信域的双边建链方式Ascend 950PR/950DT 不支持ranktable 配置示例见 LLMDataDist 文档。LLMConfig 常用配置项device_id必填、enable_cache_manager、enable_remote_cache_accessible开启后本地缓存远端 Cache 元数据加速 Pull更适用于 Cache 仅在初始化阶段分配/注册的 PA 场景Atlas A3 形态不开启时仅支持 RDMA 传输、listen_ip_info如192.168.1.1:26000、sync_kv_timeout默认 1000ms、rdma_traffic_class/rdma_service_level、local_comm_res、link_total_time/link_retry_countHCCL 建链总超时与重试次数、transfer_backend取值为hixl时指定 HIXL 作为传输后端、global_resource_config仅 hixl 后端生效透传至 HIXL 引擎解析以及ge_options如ge.flowGraphMemMaxSize控制 KV cache 最大占用内存等。CacheManager通过llm_datadist.cache_manager获取实例配套 Cache、CacheManager、CacheDesc、CacheKey、BlocksCacheKey、TransferConfig 等数据结构文档使用。五、从仓库源码与示例快速验证仓库为 Python API 提供了可直接运行的示例与测试是验证配置和上手开发的最快路径示例见 examples/python 目录包括 hixl_d2rd_multiproc_sample.pyHIXL Engine 多进程示例与 llm_datadist 下的push_cache_sample.py、pull_cache_sample.py、push_blocks_sample.py、pull_blocks_sample.py、switch_role_sample.py、hixl_transfer_backend_sample.py等覆盖 Cache 推送/拉取、角色切换与 HIXL 传输后端等典型用法。Python 测试见 tests/python如 test_hixl_engine_api.py、test_cache_manager.py、test_parameter_validation.py其中参数校验类测试可作为接口约束的补充参考。C 侧实现佐证Python 绑定通过 hixl_py.cc 对接 C 侧 hixl_impl.cc 与 llm_datadist_v2.cc 等实现OPTION_GLOBAL_RESOURCE_CONFIG的全局资源解析与校验逻辑位于 hixl_options.cc链路池、连接池等机制可进一步查看 channel_manager.cc 等文件。六、总结与选型建议决策点建议硬件形态先对照 brief.md 确认目标设备属于 Atlas A2/A3 还是 Ascend 950PR/950DT再选择协议与配置Python 版本3.12 用官网发布包3.9–3.14 走 源码编译链路上限大规模多链路场景优先配置 version1.3的local_comm_resHixlCS无上限或关闭中转内存池后使用 HixlCS内存规划遵循 50GB Device / 20GB 或 1TB Host 的注册上限并结合 OS 内存开销与 4K 个注册数建议综合规划场景选择底层点对点传输用 HIXL Engine大模型 KV Cache 分发用 LLM-DataDistDecode/Prompt 双向拉取 CacheHIXL Python API 的能力边界清晰、接口分层明确HIXL Engine 负责高效稳定的点对点传输底座LLM-DataDist 在其上构建面向大模型场景的 Cache 分发能力。建议在动手开发前先对照 Python 接口参考文档 逐接口确认产品形态与版本约束再基于 examples/python 示例搭建首个可运行程序。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考