尧图网站建设 
CANN HIXL Python 示例实战指南LLM-DataDist 解耦部署下的 KV Cache 管理与 HIXL D2D 传输【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl本指南以 CANN HIXL 开源仓库 examples/python/README_en.md 为主体系统讲解仓库内置的 10 个 Python 示例如何使用 LLM-DataDist API 在解耦部署Disaggregated Deployment场景下实现 KV Cache 管理拉取、推送、角色切换、按层异步传输以及如何使用 HIXL API 完成 Device-to-DeviceD2D多进程数据传输。读完本文你将掌握每个示例的适用场景、运行命令、关键参数含义并能结合源码理解其底层建链、内存注册与传输后端选择机制直接在自己的昇腾集群上复现运行。一、示例总览两大 API 家族与核心能力仓库examples/python目录下的示例分为两个 API 家族对应两类能力LLM-DataDist APIllm_datadist目录面向大模型 KV Cache 解耦部署提供缓存管理cache_manager、集群建链link/link_clusters、块/缓存传输push_blocks/pull_blocks/push_cache/pull_cache/transfer_cache_async以及角色切换switch_role能力HIXL APIhixl目录面向单边通信One-Side Communication的 D2D 数据传输示例hixl_d2rd_multiproc_sample.py直接调用hixl.Hixl引擎完成内存注册、连接建立与同步传输transfer_sync。其中hixl_transfer_backend_sample.py是两者的桥梁——它通过LLMConfig.transfer_backend hixl将 HIXL 作为 LLM-DataDist 的传输后端展示上层管理缓存、底层走 HIXL 通信的组合用法这与 docs/design/llm-datadist_supporting_the_hixl_transfer_backend.md 描述的设计方向一致。二、目录结构原文给出的示例目录结构如下与仓库实际布局一致├── python │ ├── llm_datadist │ │ ├── pull_blocks_sample.py │ │ ├── pull_blocks_xpyd_sample.py │ │ ├── pull_cache_sample.py │ │ ├── pull_from_cache_to_blocks.py │ │ ├── push_blocks_sample.py │ │ ├── push_cache_sample.py │ │ ├── switch_role_sample.py │ │ ├── transfer_cache_async_sample.py │ │ └── hixl_transfer_backend_sample.py │ └── hixl │ └── hixl_d2rd_multiproc_sample.py三、环境准备3.1 安装 Python 依赖仓库根目录的 requirements.txt 列出了示例运行所需的 Python 依赖numpy、pyyaml、decorator、sympy、scipy、attrs、protobuf、psutil、setuptools、wheel、coverage 等执行pip3 install -r requirements.txt若环境已安装可跳过。3.2 PyTorch 与 torch_npu 版本搭配示例大量使用torch.npu.set_device()、tensor.npu()等 NPU 张量操作因此必须安装与 CANN 版本匹配的pytorch与torch_npu插件。原文档给出了 Python 3.13 环境下的兼容组合可直接参照PyTorch 版本torch_npu 插件版本Python 版本系统架构CANN 版本安装方式2.7.126.0.0Python 3.13AArch649.0.0离线 Whl2.7.126.0.0Python 3.13X86_649.0.0离线 Whl安装思路为先安装与 Python 版本匹配的 PyTorch CPU/基础 whl 包再安装对应版本的 torch_npu 插件 whl 包例如pip3 install torch_npu-2.7.1.post4-cp313-...whl。其他 Python 版本请依据 Ascend 官方版本兼容矩阵选择对应组合安装完成后建议通过import torch_npu验证插件可正常加载。3.3 昇腾环境变量所有示例运行前都需要先加载 CANN 环境变量source ${HOME}/Ascend/cann/set_env.sh其中${HOME}/Ascend需替换为实际 CANN 软件安装路径。对于双机示例建议在两台主机上同步执行上述操作并保证两台主机上的脚本内容完全一致。四、样本配置网络与设备信息4.1 修改设备与主机 IP双机示例以10.10.10.x作为主机 IP、192.168.x.x作为设备DeviceIP 的占位符运行前需按实际组网修改脚本顶部的常量以 pull_cache_sample.py 为例PROMPT_HOST_IPPrompt 主机的 Host IPPROMPT_IP_LISTPrompt 主机各 NPU 的device_ip列表DECODER_HOST_IPDecoder 主机的 Host IPDECODER_IP_LISTDecoder 主机各 NPU 的device_ip列表。同时要确保两台主机上的脚本保持完全一致。4.2 A5 环境 RDMA 链路与 local_comm_res 配置原文档特别说明部分示例支持 A5 环境Ascend 950PR / Ascend 950DT下的 RDMA 链路且必须在双机上执行。在 A5 环境中若未手动配置local_comm_res默认使用UB 协议若要使用RDMA 链路需手动配置local_comm_res配置项细节参见 docs/zh/api/cpp/HIXL-interface.md 中Initialize一节表 2 中 Ascend 950PR/Ascend 950DT 相关 option。local_comm_res的底层行为可以在 docs/zh/api/cpp/HIXL-interface.md 的OPTION_LOCAL_COMM_RES说明中印证不配置或配置为空串自动生成相关信息使用集合通信的通信域方式建链Device 侧 Stream 资源有限建议单卡建链数不超过 512配置 version 为1.0/1.2的 ranktable 格式同样走通信域方式建链仅需配置当前 LLM-DataDist 使用的 Device 信息配置 version 为1.3推荐需 HDK 25.5.0 且 toolkit 9.1.0使用 HixlCS 能力建链没有链路上限限制只需配置 version 字段其他字段自动生成。UB 场景支持自动生成net_instance_id与endpoint_list如需自行生成指定 NPU 的 localcommres 信息可使用仓库提供的工具用法见 scripts/tools/hixl_tool/readme.md。查询本机 RoCE 网卡与 IP 的参考命令# 查询 RoCE 设备与网口的映射关系并定位 Up 状态的端口 ibdev2netdev # 根据网口查找对应 IP 地址 ifconfig五、样本运行详解下面按原文档顺序逐个给出运行方法与源码要点。通用约定device_id指定使用的 NPU 卡号源码校验范围为 0–7见各脚本argparse后的校验分支cluster_id指定集群 ID所有参与建链的节点上必须保持唯一。5.1 pull_cache内存池分配 双向建链拉取缓存该示例演示在配置内存池的场景下分配缓存内存、建立双向连接并从远端节点拉取缓存。双机执行# Prompt 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_cache_sample.py --device_id 0 --cluster_id 1 # Decoder 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_cache_sample.py --device_id 0 --cluster_id 2单机执行Prompt 与 Decoder 两个进程并发于同一主机host_ip为本地主机 IP# Prompt 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_cache_sample.py --device_id 0 --cluster_id 1 --is_single true --host_ip 10.10.10.1 # Decoder 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_cache_sample.py --device_id 1 --cluster_id 2 --is_single true --host_ip 10.10.10.1源码要点pull_cache_sample.py通过LLMConfig.enable_cache_manager True打开缓存管理器并配置内存池mem_pool_cfg {memory_size: 67108864}64 MiB见 L83-L94缓存描述CacheDesc(num_tensors4, shape[2, 16*1024], data_typeDT_FLOAT16, placementDEVICE)Prompt 端用CacheKey(prompt_cluster_id1, req_id0/1, model_id0)关联缓存L206-L212Prompt 端allocate_cache后Decoder 端通过cache_manager.pull_cache(cache_key, cache, batch_index...)拉取流程通过dist.barrier()同步L215-L227链路生命周期为datadist.link(link, cluster_rank_info, rank_table)→ 轮询query_register_mem_status直到RegisterMemStatus.OK→datadist.unlink(comm_id)L185-L198。5.2 pull_blocksTorch 分配内存 双向建链拉取块该示例使用Torch 分配内存、建立双向连接并从远端节点拉取块Blocks。双机执行# Prompt 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_sample.py --device_id 0 --cluster_id 1 # Decoder 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_sample.py --device_id 0 --cluster_id 2单机执行# Prompt 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_sample.py --device_id 0 --cluster_id 1 --is_single true --host_ip 10.10.10.1 # Decoder 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_sample.py --device_id 1 --cluster_id 2 --is_single true --host_ip 10.10.10.1源码要点pull_blocks_sample.pyDecoder 端torch.ones(...).npu()分配设备内存后register_blocks_cache通过pull_blocks(BlocksCacheKey(1, 0), cache, src_blocks[0,1], dst_blocks[0,1])拉取随后示例还演示了块换出/换入swap_blocks(cache, cpu_cache, {0:0, 1:1})swap out与swap_blocks(cpu_cache, cache, {0:0, 1:1})swap in将设备块暂存到 CPU 端 CacheL220-L250。5.3 pull_from_cache_to_blocks从缓存拉取到块该示例演示将远端 Prompt 侧的 Cache 数据拉取到本地 Decoder 侧注册的 Blocks 中。双机执行# Prompt 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_from_cache_to_blocks.py --device_id 0 --cluster_id 1 # Decoder 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_from_cache_to_blocks.py --device_id 0 --cluster_id 2单机执行# Prompt 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_from_cache_to_blocks.py --device_id 0 --cluster_id 1 --is_single true --host_ip 10.10.10.1 # Decoder 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_from_cache_to_blocks.py --device_id 1 --cluster_id 2 --is_single true --host_ip 10.10.10.1源码要点pull_from_cache_to_blocks.pyPrompt 端allocate_cache(cache_desc, [cache_key])分配 KV CacheDecoder 端register_blocks_cache注册本地块随后以CacheKey为索引执行pull_blocks(cache_key, cache, src_blocks[], dst_blocks[0])L201-L228Prompt 端在结束后调用remove_cache_key与deallocate_cache释放缓存源码注释说明若pull_cache失败或对端未调用remove_cache_key可确保缓存被释放若成功则为空操作。5.4 push_blocks / push_cache单边建链推送这两个示例均采用单边建链方式分配内存、注册块/缓存后由Decoder 主动发起连接并推送。push_blocks 双机执行默认走通信域后端传--transfer_backend hixl可切换 HIXL CS 后端# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/push_blocks_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/push_blocks_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0A5 环境传--transfer_backend hixl未手动配置local_comm_res时默认走 UB 链路也可手动配置以启用 RDMA# Prompt 主机 python llm_datadist/push_blocks_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 --transfer_backend hixl # Decoder 主机 python llm_datadist/push_blocks_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0 --transfer_backend hixlpush_cache 双机执行# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/push_cache_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/push_cache_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0A5 环境传--transfer_backend hixl# Prompt 主机 python llm_datadist/push_cache_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 --transfer_backend hixl # Decoder 主机 python llm_datadist/push_cache_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0 --transfer_backend hixl参数说明role取pPrompt/dDecoderlocal_host_ip为本机 Host IPremote_host_ip为对端 Host IP--transfer_backend支持hixl其余值会触发unsupported transfer_backend报错见 push_blocks_sample.py。源码要点push_blocks_sample.py建链使用LLMClusterInfolink_clusters([cluster], 5000)5 秒超时Decoder 端append_local_ip_info(local_host_ip, 26001)、append_remote_ip_info(remote_host_ip, 26000)L136-L143并监听在listen_ip_info local_host_ip:26001推送通过cache_manager.push_blocks(BlocksCacheKey(PROMPT_CLUSTER_ID, 0), cache, src_blocks[0,1], dst_blocks[0,2])完成L146-L151push_cache 对应使用CacheKeyByIdAndIndex与push_cache(...)push_cache_sample.py解链统一走unlink_clusters([cluster], 5000, forceTrue)。5.5 switch_role运行中切换 Prompt / Decoder 角色该示例演示单边建链下的角色切换流程先用 Torch 分配内存并注册块Decoder 发起建链拉取块随后双方切换角色改由 Prompt 发起建链、Decoder 推送块。双机执行# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/switch_role_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/switch_role_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0源码要点switch_role_sample.pyPrompt 侧完成第一轮pull_blocks后调用datadist.switch_role(LLMRole.DECODER)L96Decoder 侧解链后携带新的listen_ip_info调用datadist.switch_role(LLMRole.PROMPT, llm_options)L176-L179第二轮由切换后的 Prompt 发起建链、Decoder 通过push_blocks回推其中还展示了带层范围的传输参数src_layer_rangerange(0,2)、dst_layer_rangerange(0,2)、tensor_num_per_layer1L187-L195。5.6 pull_blocks_xpydxPyD 多对多场景该示例支持xPyD 测试场景x 个 Prompt、y 个 Decoder采用单边建链每个进程分配内存并注册块每个 Decoder 向所有 Prompt 发起建链并拉取块。local_ip_port指定本机 IP 与端口。# Prompt 侧可启动任意多个进程 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 0 --role p --local_ip_port ${local_ip_0:port_0} GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 1 --role p --local_ip_port ${local_ip_1:port_1} ... # Decoder 侧remote_ip_port 由 Prompt 侧全部 ip:port 以 ; 分隔组成 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id n1 --role d --local_ip_port ${local_ip_n1:port_n1} --remote_ip_port ${prompt_ip_list}其中${prompt_ip_list}为 Prompt 侧所有${local_ip:port}条目以分号;分隔。一个双 Prompt 双 Decoder 的具体示例# Prompt 侧任意数量主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 0 --role p --local_ip_port 10.10.10.0:26000 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 1 --role p --local_ip_port 10.10.10.0:26001 # Decoder 侧任意数量主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 2 --role d --local_ip_port 10.10.10.0:26002 --remote_ip_port 10.10.10.0:26000;10.10.10.0:26001 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 3 --role d --local_ip_port 10.10.10.0:26003 --remote_ip_port 10.10.10.0:26000;10.10.10.0:26001源码要点pull_blocks_xpyd_sample.py该示例不依赖 gloo 进程组而是通过ip_port_to_int把ip:port编码为 48 位整数32 位 IP 16 位端口作为cluster_idL38-L51Decoder 遍历remote_ip_port.split(;)为每个 Prompt 构造LLMClusterInfo并一次link_clusters(cluster_list, 5000)批量建链再逐个pull_blocksL116-L137。5.7 transfer_cache_async按层异步传输缓存该示例使用单边建链方式分配内存、注册缓存并由Prompt 侧发起连接将缓存按层layer异步传输到 Decoder。双机执行默认走通信域后端传--transfer_backend hixl可切换 HIXL CS 后端# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/transfer_cache_async_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/transfer_cache_async_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0A5 环境传--transfer_backend hixl# Prompt 主机 python llm_datadist/transfer_cache_async_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 --transfer_backend hixl # Decoder 主机 python llm_datadist/transfer_cache_async_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0 --transfer_backend hixl源码要点transfer_cache_async_sample.py配置上需要同时开启enable_cache_manager与enable_remote_cache_accessible远端 Cache 可直接访问见 L72-L73核心调用为cache_manager.transfer_cache_async(cache, layer_synchronizer, [transfer_config])其中transfer_config用TransferWithCacheKeyConfig(BlocksCacheKey(...), range(0,1), range(0,1))描述目标缓存键与源/目的层范围LayerSynchronizer通过实现synchronize_layer(layer_index, timeout_in_millis)接口控制逐层推进任务完成后cache_task.get_results()获取结果L83-L130。5.8 hixl_transfer_backend显式指定 HIXL 传输后端该示例将 HIXL 作为 LLM-DataDist 的传输后端演示完整流程内存注册 → 连接建立 → 数据传输。具体为分配内存并注册块Decoder 发起连接并推送块Prompt 发起连接并拉取块。双机执行# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/hixl_transfer_backend_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/hixl_transfer_backend_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0源码要点hixl_transfer_backend_sample.py初始化时llm_config.transfer_backend hixlL64Prompt 监听26000、Decoder 监听26001流程为 Prompt/Decoder 各自register_blocks_cache→ 双方link_clusters→ Decoderpush_blocks(src_blocks[0,1], dst_blocks[0,1])→ Promptpull_blocks(src_blocks[2], dst_blocks[2])→ 数据校验Prompt 端用torch.equal比对全 0 期望张量见 L122-L136→unlink_clusters收尾。5.9 hixl_d2rd_multiprocHIXL 原生 D2D 多进程传输该示例直接使用 HIXL API 进行 Device-to-Device 多进程传输在 Server 与 Client 主机上分别执行。device指定设备号protocol指定传输协议如roce:device、hccs:device# Server python hixl/hixl_d2rd_multiproc_sample.py --role server --device 2 --local-engine 10.10.10.1:16101 --protocol roce:device # Client python hixl/hixl_d2rd_multiproc_sample.py --role client --device 0 --local-engine 10.10.10.0:16100 --remote-engine 10.10.10.1:16101 --protocol roce:device源码要点hixl_d2rd_multiproc_sample.py默认常量缓冲区BUF_SIZE 8 MiB块大小BLOCK_SIZE 16 KiB共BLOCK_COUNT 512个块默认 Client 设备 0、Server 设备 2默认引擎地址127.0.0.1:16000/16001L28-L34引擎初始化通过hixl.OPTION_AUTO_CONNECT与hixl.OPTION_GLOBAL_RESOURCE_CONFIG内含comm_resource_config.protocol_desc即--protocol参数构造 optionsL70-L78流程engine.initialize(local_engine, options)→register_mem(MemDesc(addr, size), MemType.MEM_DEVICE)注册设备内存 → Client 通过辅助 socket 获取 Server 的远端地址端口偏移SOCKET_PORT_OFFSET 1000带重试机制见 L37-L41→engine.connect(remote_engine, timeout_in_millis5000)→ 构造 512 个TransferOpDesc后transfer_sync(remote_engine, TransferOp.READ, op_descs, timeout_in_millis30000)一次性读回全部数据L204-L216数据校验Client 端将 NPU 缓冲区拷回 CPU与全0xAA填充值逐字节比对任何不匹配即抛异常L219-L225。六、源码级要点解读6.1 两种建链模式仓库示例体现了 LLM-DataDist 的两种建链方式双向建链pull_cache / pull_blocks / pull_from_cache_to_blocks通过datadist.link(link, cluster_rank_info, rank_table)建立双向连接cluster_rank_info映射如{1: 0, 2: 1}将cluster_id映射为 rank随后轮询query_register_mem_status等待双方内存注册就绪单边建链push_*/switch_role/pull_blocks_xpyd/transfer_cache_async 等通过LLMClusterInfo描述对端remote_cluster_id与append_local_ip_info/append_remote_ip_info指定的监听/目标地址调用link_clusters或解链时unlink_clusters。谁调用link_clusters谁发起连接因此 push 场景由 Decoder 发起、transfer_cache_async 场景由 Prompt 发起。6.2 核心数据结构CacheDesc(num_tensors, shape, data_type, placement)描述一个 Cache/块集合的张量个数、形状、数据类型与放置位置Placement.DEVICE/Placement.HOSTCacheKey(prompt_cluster_id, req_id, model_id)按请求粒度索引缓存cache 语义BlocksCacheKey(cluster_id, ...)按集群索引块blocks 语义CacheKeyByIdAndIndex(cluster_id, cache_id, batch_index)push_cache 场景按 cache_id batch_index 索引LLMClusterInfoTransferWithCacheKeyConfig/LayerSynchronizer分别用于描述对端集群信息与按层异步传输参数。6.3 单机single-host模式与 rank tablepull_cache、pull_blocks、pull_from_cache_to_blocks三个示例支持--is_single true单机运行。此时脚本不再使用写死的PROMPT_IP_LIST/DECODER_IP_LIST而是扫描/dev/davinci*获取物理设备列表并通过hccn_tool -i device_id -ip -g查询每张卡的device_ip动态构建单机 rank tablepull_cache_sample.py。双机模式则使用 version1.2格式的分布式 rank table将 Prompt/Decoder 各作为一个 server 写入server_list。6.4 传输后端与 A5 链路push_blocks、push_cache、transfer_cache_async三个示例暴露了--transfer_backend参数默认空串使用通信域后端传hixl时通过LLMConfig.transfer_backend hixl切换为 HIXL CS 后端。A5 环境下未手动配置local_comm_res时默认走 UB 链路配置后可走 RDMA其详细 option 语义见 docs/zh/api/cpp/HIXL-interface.md 中OPTION_LOCAL_COMM_RES的说明version 1.3 走 HixlCS 建链、无链路上限。6.5 环境变量语义GLOO_SOCKET_IFNAME指定本机用于 gloo 进程组通信的网卡名通过ifconfig查询保证 Prompt/Decoder 之间控制面可达HCCL_INTRA_ROCE_ENABLE1指示使用 RoCE 网卡进行集合通信域的数据面通信。七、运行注意事项与排查建议脚本一致性双机示例务必保证两台主机脚本尤其是 IP 常量完全一致cluster_id在所有建链节点上必须唯一端口规划单边建链示例固定监听端口26000/26001xPyD 场景各进程需分配互不冲突的ip:portD2D 示例端口自动加 1000 偏移避免与引擎端口冲突版本约束local_comm_resversion 1.3HixlCS 建链要求 HDK 25.5.0、toolkit 9.1.0自动生成 localcommres 对 LCNE/HDK 版本也有要求详见 docs/zh/api/cpp/HIXL-interface.md 中的注意事项参数校验各脚本对device_id0–7与rolep/d做了硬校验越界会直接抛RuntimeError结果校验hixl_transfer_backend_sample与hixl_d2rd_multiproc_sample内置数据一致性校验torch.equal与逐字节比对跑通即代表端到端传输正确是验证组网与驱动配置是否正常的快速手段。以上示例的运行目录、命令与参数均可直接从仓库 examples/python 目录获取并复现相关接口的详细语义可进一步查阅 docs/zh/api/python 下的 LLMDataDist、CacheManager 等接口文档。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN HIXL Python 示例实战指南：LLM-DataDist 解耦部署下的 KV Cache 管理与 HIXL D2D 传输
CANN HIXL Python 示例实战指南LLM-DataDist 解耦部署下的 KV Cache 管理与 HIXL D2D 传输【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl本指南以 CANN HIXL 开源仓库 examples/python/README_en.md 为主体系统讲解仓库内置的 10 个 Python 示例如何使用 LLM-DataDist API 在解耦部署Disaggregated Deployment场景下实现 KV Cache 管理拉取、推送、角色切换、按层异步传输以及如何使用 HIXL API 完成 Device-to-DeviceD2D多进程数据传输。读完本文你将掌握每个示例的适用场景、运行命令、关键参数含义并能结合源码理解其底层建链、内存注册与传输后端选择机制直接在自己的昇腾集群上复现运行。一、示例总览两大 API 家族与核心能力仓库examples/python目录下的示例分为两个 API 家族对应两类能力LLM-DataDist APIllm_datadist目录面向大模型 KV Cache 解耦部署提供缓存管理cache_manager、集群建链link/link_clusters、块/缓存传输push_blocks/pull_blocks/push_cache/pull_cache/transfer_cache_async以及角色切换switch_role能力HIXL APIhixl目录面向单边通信One-Side Communication的 D2D 数据传输示例hixl_d2rd_multiproc_sample.py直接调用hixl.Hixl引擎完成内存注册、连接建立与同步传输transfer_sync。其中hixl_transfer_backend_sample.py是两者的桥梁——它通过LLMConfig.transfer_backend hixl将 HIXL 作为 LLM-DataDist 的传输后端展示上层管理缓存、底层走 HIXL 通信的组合用法这与 docs/design/llm-datadist_supporting_the_hixl_transfer_backend.md 描述的设计方向一致。二、目录结构原文给出的示例目录结构如下与仓库实际布局一致├── python │ ├── llm_datadist │ │ ├── pull_blocks_sample.py │ │ ├── pull_blocks_xpyd_sample.py │ │ ├── pull_cache_sample.py │ │ ├── pull_from_cache_to_blocks.py │ │ ├── push_blocks_sample.py │ │ ├── push_cache_sample.py │ │ ├── switch_role_sample.py │ │ ├── transfer_cache_async_sample.py │ │ └── hixl_transfer_backend_sample.py │ └── hixl │ └── hixl_d2rd_multiproc_sample.py三、环境准备3.1 安装 Python 依赖仓库根目录的 requirements.txt 列出了示例运行所需的 Python 依赖numpy、pyyaml、decorator、sympy、scipy、attrs、protobuf、psutil、setuptools、wheel、coverage 等执行pip3 install -r requirements.txt若环境已安装可跳过。3.2 PyTorch 与 torch_npu 版本搭配示例大量使用torch.npu.set_device()、tensor.npu()等 NPU 张量操作因此必须安装与 CANN 版本匹配的pytorch与torch_npu插件。原文档给出了 Python 3.13 环境下的兼容组合可直接参照PyTorch 版本torch_npu 插件版本Python 版本系统架构CANN 版本安装方式2.7.126.0.0Python 3.13AArch649.0.0离线 Whl2.7.126.0.0Python 3.13X86_649.0.0离线 Whl安装思路为先安装与 Python 版本匹配的 PyTorch CPU/基础 whl 包再安装对应版本的 torch_npu 插件 whl 包例如pip3 install torch_npu-2.7.1.post4-cp313-...whl。其他 Python 版本请依据 Ascend 官方版本兼容矩阵选择对应组合安装完成后建议通过import torch_npu验证插件可正常加载。3.3 昇腾环境变量所有示例运行前都需要先加载 CANN 环境变量source ${HOME}/Ascend/cann/set_env.sh其中${HOME}/Ascend需替换为实际 CANN 软件安装路径。对于双机示例建议在两台主机上同步执行上述操作并保证两台主机上的脚本内容完全一致。四、样本配置网络与设备信息4.1 修改设备与主机 IP双机示例以10.10.10.x作为主机 IP、192.168.x.x作为设备DeviceIP 的占位符运行前需按实际组网修改脚本顶部的常量以 pull_cache_sample.py 为例PROMPT_HOST_IPPrompt 主机的 Host IPPROMPT_IP_LISTPrompt 主机各 NPU 的device_ip列表DECODER_HOST_IPDecoder 主机的 Host IPDECODER_IP_LISTDecoder 主机各 NPU 的device_ip列表。同时要确保两台主机上的脚本保持完全一致。4.2 A5 环境 RDMA 链路与 local_comm_res 配置原文档特别说明部分示例支持 A5 环境Ascend 950PR / Ascend 950DT下的 RDMA 链路且必须在双机上执行。在 A5 环境中若未手动配置local_comm_res默认使用UB 协议若要使用RDMA 链路需手动配置local_comm_res配置项细节参见 docs/zh/api/cpp/HIXL-interface.md 中Initialize一节表 2 中 Ascend 950PR/Ascend 950DT 相关 option。local_comm_res的底层行为可以在 docs/zh/api/cpp/HIXL-interface.md 的OPTION_LOCAL_COMM_RES说明中印证不配置或配置为空串自动生成相关信息使用集合通信的通信域方式建链Device 侧 Stream 资源有限建议单卡建链数不超过 512配置 version 为1.0/1.2的 ranktable 格式同样走通信域方式建链仅需配置当前 LLM-DataDist 使用的 Device 信息配置 version 为1.3推荐需 HDK 25.5.0 且 toolkit 9.1.0使用 HixlCS 能力建链没有链路上限限制只需配置 version 字段其他字段自动生成。UB 场景支持自动生成net_instance_id与endpoint_list如需自行生成指定 NPU 的 localcommres 信息可使用仓库提供的工具用法见 scripts/tools/hixl_tool/readme.md。查询本机 RoCE 网卡与 IP 的参考命令# 查询 RoCE 设备与网口的映射关系并定位 Up 状态的端口 ibdev2netdev # 根据网口查找对应 IP 地址 ifconfig五、样本运行详解下面按原文档顺序逐个给出运行方法与源码要点。通用约定device_id指定使用的 NPU 卡号源码校验范围为 0–7见各脚本argparse后的校验分支cluster_id指定集群 ID所有参与建链的节点上必须保持唯一。5.1 pull_cache内存池分配 双向建链拉取缓存该示例演示在配置内存池的场景下分配缓存内存、建立双向连接并从远端节点拉取缓存。双机执行# Prompt 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_cache_sample.py --device_id 0 --cluster_id 1 # Decoder 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_cache_sample.py --device_id 0 --cluster_id 2单机执行Prompt 与 Decoder 两个进程并发于同一主机host_ip为本地主机 IP# Prompt 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_cache_sample.py --device_id 0 --cluster_id 1 --is_single true --host_ip 10.10.10.1 # Decoder 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_cache_sample.py --device_id 1 --cluster_id 2 --is_single true --host_ip 10.10.10.1源码要点pull_cache_sample.py通过LLMConfig.enable_cache_manager True打开缓存管理器并配置内存池mem_pool_cfg {memory_size: 67108864}64 MiB见 L83-L94缓存描述CacheDesc(num_tensors4, shape[2, 16*1024], data_typeDT_FLOAT16, placementDEVICE)Prompt 端用CacheKey(prompt_cluster_id1, req_id0/1, model_id0)关联缓存L206-L212Prompt 端allocate_cache后Decoder 端通过cache_manager.pull_cache(cache_key, cache, batch_index...)拉取流程通过dist.barrier()同步L215-L227链路生命周期为datadist.link(link, cluster_rank_info, rank_table)→ 轮询query_register_mem_status直到RegisterMemStatus.OK→datadist.unlink(comm_id)L185-L198。5.2 pull_blocksTorch 分配内存 双向建链拉取块该示例使用Torch 分配内存、建立双向连接并从远端节点拉取块Blocks。双机执行# Prompt 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_sample.py --device_id 0 --cluster_id 1 # Decoder 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_sample.py --device_id 0 --cluster_id 2单机执行# Prompt 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_sample.py --device_id 0 --cluster_id 1 --is_single true --host_ip 10.10.10.1 # Decoder 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_sample.py --device_id 1 --cluster_id 2 --is_single true --host_ip 10.10.10.1源码要点pull_blocks_sample.pyDecoder 端torch.ones(...).npu()分配设备内存后register_blocks_cache通过pull_blocks(BlocksCacheKey(1, 0), cache, src_blocks[0,1], dst_blocks[0,1])拉取随后示例还演示了块换出/换入swap_blocks(cache, cpu_cache, {0:0, 1:1})swap out与swap_blocks(cpu_cache, cache, {0:0, 1:1})swap in将设备块暂存到 CPU 端 CacheL220-L250。5.3 pull_from_cache_to_blocks从缓存拉取到块该示例演示将远端 Prompt 侧的 Cache 数据拉取到本地 Decoder 侧注册的 Blocks 中。双机执行# Prompt 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_from_cache_to_blocks.py --device_id 0 --cluster_id 1 # Decoder 主机 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_from_cache_to_blocks.py --device_id 0 --cluster_id 2单机执行# Prompt 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_from_cache_to_blocks.py --device_id 0 --cluster_id 1 --is_single true --host_ip 10.10.10.1 # Decoder 进程 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_from_cache_to_blocks.py --device_id 1 --cluster_id 2 --is_single true --host_ip 10.10.10.1源码要点pull_from_cache_to_blocks.pyPrompt 端allocate_cache(cache_desc, [cache_key])分配 KV CacheDecoder 端register_blocks_cache注册本地块随后以CacheKey为索引执行pull_blocks(cache_key, cache, src_blocks[], dst_blocks[0])L201-L228Prompt 端在结束后调用remove_cache_key与deallocate_cache释放缓存源码注释说明若pull_cache失败或对端未调用remove_cache_key可确保缓存被释放若成功则为空操作。5.4 push_blocks / push_cache单边建链推送这两个示例均采用单边建链方式分配内存、注册块/缓存后由Decoder 主动发起连接并推送。push_blocks 双机执行默认走通信域后端传--transfer_backend hixl可切换 HIXL CS 后端# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/push_blocks_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/push_blocks_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0A5 环境传--transfer_backend hixl未手动配置local_comm_res时默认走 UB 链路也可手动配置以启用 RDMA# Prompt 主机 python llm_datadist/push_blocks_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 --transfer_backend hixl # Decoder 主机 python llm_datadist/push_blocks_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0 --transfer_backend hixlpush_cache 双机执行# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/push_cache_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/push_cache_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0A5 环境传--transfer_backend hixl# Prompt 主机 python llm_datadist/push_cache_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 --transfer_backend hixl # Decoder 主机 python llm_datadist/push_cache_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0 --transfer_backend hixl参数说明role取pPrompt/dDecoderlocal_host_ip为本机 Host IPremote_host_ip为对端 Host IP--transfer_backend支持hixl其余值会触发unsupported transfer_backend报错见 push_blocks_sample.py。源码要点push_blocks_sample.py建链使用LLMClusterInfolink_clusters([cluster], 5000)5 秒超时Decoder 端append_local_ip_info(local_host_ip, 26001)、append_remote_ip_info(remote_host_ip, 26000)L136-L143并监听在listen_ip_info local_host_ip:26001推送通过cache_manager.push_blocks(BlocksCacheKey(PROMPT_CLUSTER_ID, 0), cache, src_blocks[0,1], dst_blocks[0,2])完成L146-L151push_cache 对应使用CacheKeyByIdAndIndex与push_cache(...)push_cache_sample.py解链统一走unlink_clusters([cluster], 5000, forceTrue)。5.5 switch_role运行中切换 Prompt / Decoder 角色该示例演示单边建链下的角色切换流程先用 Torch 分配内存并注册块Decoder 发起建链拉取块随后双方切换角色改由 Prompt 发起建链、Decoder 推送块。双机执行# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/switch_role_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/switch_role_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0源码要点switch_role_sample.pyPrompt 侧完成第一轮pull_blocks后调用datadist.switch_role(LLMRole.DECODER)L96Decoder 侧解链后携带新的listen_ip_info调用datadist.switch_role(LLMRole.PROMPT, llm_options)L176-L179第二轮由切换后的 Prompt 发起建链、Decoder 通过push_blocks回推其中还展示了带层范围的传输参数src_layer_rangerange(0,2)、dst_layer_rangerange(0,2)、tensor_num_per_layer1L187-L195。5.6 pull_blocks_xpydxPyD 多对多场景该示例支持xPyD 测试场景x 个 Prompt、y 个 Decoder采用单边建链每个进程分配内存并注册块每个 Decoder 向所有 Prompt 发起建链并拉取块。local_ip_port指定本机 IP 与端口。# Prompt 侧可启动任意多个进程 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 0 --role p --local_ip_port ${local_ip_0:port_0} GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 1 --role p --local_ip_port ${local_ip_1:port_1} ... # Decoder 侧remote_ip_port 由 Prompt 侧全部 ip:port 以 ; 分隔组成 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id n1 --role d --local_ip_port ${local_ip_n1:port_n1} --remote_ip_port ${prompt_ip_list}其中${prompt_ip_list}为 Prompt 侧所有${local_ip:port}条目以分号;分隔。一个双 Prompt 双 Decoder 的具体示例# Prompt 侧任意数量主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 0 --role p --local_ip_port 10.10.10.0:26000 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 1 --role p --local_ip_port 10.10.10.0:26001 # Decoder 侧任意数量主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 2 --role d --local_ip_port 10.10.10.0:26002 --remote_ip_port 10.10.10.0:26000;10.10.10.0:26001 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/pull_blocks_xpyd_sample.py --device_id 3 --role d --local_ip_port 10.10.10.0:26003 --remote_ip_port 10.10.10.0:26000;10.10.10.0:26001源码要点pull_blocks_xpyd_sample.py该示例不依赖 gloo 进程组而是通过ip_port_to_int把ip:port编码为 48 位整数32 位 IP 16 位端口作为cluster_idL38-L51Decoder 遍历remote_ip_port.split(;)为每个 Prompt 构造LLMClusterInfo并一次link_clusters(cluster_list, 5000)批量建链再逐个pull_blocksL116-L137。5.7 transfer_cache_async按层异步传输缓存该示例使用单边建链方式分配内存、注册缓存并由Prompt 侧发起连接将缓存按层layer异步传输到 Decoder。双机执行默认走通信域后端传--transfer_backend hixl可切换 HIXL CS 后端# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/transfer_cache_async_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/transfer_cache_async_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0A5 环境传--transfer_backend hixl# Prompt 主机 python llm_datadist/transfer_cache_async_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 --transfer_backend hixl # Decoder 主机 python llm_datadist/transfer_cache_async_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0 --transfer_backend hixl源码要点transfer_cache_async_sample.py配置上需要同时开启enable_cache_manager与enable_remote_cache_accessible远端 Cache 可直接访问见 L72-L73核心调用为cache_manager.transfer_cache_async(cache, layer_synchronizer, [transfer_config])其中transfer_config用TransferWithCacheKeyConfig(BlocksCacheKey(...), range(0,1), range(0,1))描述目标缓存键与源/目的层范围LayerSynchronizer通过实现synchronize_layer(layer_index, timeout_in_millis)接口控制逐层推进任务完成后cache_task.get_results()获取结果L83-L130。5.8 hixl_transfer_backend显式指定 HIXL 传输后端该示例将 HIXL 作为 LLM-DataDist 的传输后端演示完整流程内存注册 → 连接建立 → 数据传输。具体为分配内存并注册块Decoder 发起连接并推送块Prompt 发起连接并拉取块。双机执行# Prompt 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/hixl_transfer_backend_sample.py --device_id 0 --role p --local_host_ip 10.10.10.0 --remote_host_ip 10.10.10.1 # Decoder 主机 GLOO_SOCKET_IFNAMEenp67s0f5 HCCL_INTRA_ROCE_ENABLE1 python llm_datadist/hixl_transfer_backend_sample.py --device_id 1 --role d --local_host_ip 10.10.10.1 --remote_host_ip 10.10.10.0源码要点hixl_transfer_backend_sample.py初始化时llm_config.transfer_backend hixlL64Prompt 监听26000、Decoder 监听26001流程为 Prompt/Decoder 各自register_blocks_cache→ 双方link_clusters→ Decoderpush_blocks(src_blocks[0,1], dst_blocks[0,1])→ Promptpull_blocks(src_blocks[2], dst_blocks[2])→ 数据校验Prompt 端用torch.equal比对全 0 期望张量见 L122-L136→unlink_clusters收尾。5.9 hixl_d2rd_multiprocHIXL 原生 D2D 多进程传输该示例直接使用 HIXL API 进行 Device-to-Device 多进程传输在 Server 与 Client 主机上分别执行。device指定设备号protocol指定传输协议如roce:device、hccs:device# Server python hixl/hixl_d2rd_multiproc_sample.py --role server --device 2 --local-engine 10.10.10.1:16101 --protocol roce:device # Client python hixl/hixl_d2rd_multiproc_sample.py --role client --device 0 --local-engine 10.10.10.0:16100 --remote-engine 10.10.10.1:16101 --protocol roce:device源码要点hixl_d2rd_multiproc_sample.py默认常量缓冲区BUF_SIZE 8 MiB块大小BLOCK_SIZE 16 KiB共BLOCK_COUNT 512个块默认 Client 设备 0、Server 设备 2默认引擎地址127.0.0.1:16000/16001L28-L34引擎初始化通过hixl.OPTION_AUTO_CONNECT与hixl.OPTION_GLOBAL_RESOURCE_CONFIG内含comm_resource_config.protocol_desc即--protocol参数构造 optionsL70-L78流程engine.initialize(local_engine, options)→register_mem(MemDesc(addr, size), MemType.MEM_DEVICE)注册设备内存 → Client 通过辅助 socket 获取 Server 的远端地址端口偏移SOCKET_PORT_OFFSET 1000带重试机制见 L37-L41→engine.connect(remote_engine, timeout_in_millis5000)→ 构造 512 个TransferOpDesc后transfer_sync(remote_engine, TransferOp.READ, op_descs, timeout_in_millis30000)一次性读回全部数据L204-L216数据校验Client 端将 NPU 缓冲区拷回 CPU与全0xAA填充值逐字节比对任何不匹配即抛异常L219-L225。六、源码级要点解读6.1 两种建链模式仓库示例体现了 LLM-DataDist 的两种建链方式双向建链pull_cache / pull_blocks / pull_from_cache_to_blocks通过datadist.link(link, cluster_rank_info, rank_table)建立双向连接cluster_rank_info映射如{1: 0, 2: 1}将cluster_id映射为 rank随后轮询query_register_mem_status等待双方内存注册就绪单边建链push_*/switch_role/pull_blocks_xpyd/transfer_cache_async 等通过LLMClusterInfo描述对端remote_cluster_id与append_local_ip_info/append_remote_ip_info指定的监听/目标地址调用link_clusters或解链时unlink_clusters。谁调用link_clusters谁发起连接因此 push 场景由 Decoder 发起、transfer_cache_async 场景由 Prompt 发起。6.2 核心数据结构CacheDesc(num_tensors, shape, data_type, placement)描述一个 Cache/块集合的张量个数、形状、数据类型与放置位置Placement.DEVICE/Placement.HOSTCacheKey(prompt_cluster_id, req_id, model_id)按请求粒度索引缓存cache 语义BlocksCacheKey(cluster_id, ...)按集群索引块blocks 语义CacheKeyByIdAndIndex(cluster_id, cache_id, batch_index)push_cache 场景按 cache_id batch_index 索引LLMClusterInfoTransferWithCacheKeyConfig/LayerSynchronizer分别用于描述对端集群信息与按层异步传输参数。6.3 单机single-host模式与 rank tablepull_cache、pull_blocks、pull_from_cache_to_blocks三个示例支持--is_single true单机运行。此时脚本不再使用写死的PROMPT_IP_LIST/DECODER_IP_LIST而是扫描/dev/davinci*获取物理设备列表并通过hccn_tool -i device_id -ip -g查询每张卡的device_ip动态构建单机 rank tablepull_cache_sample.py。双机模式则使用 version1.2格式的分布式 rank table将 Prompt/Decoder 各作为一个 server 写入server_list。6.4 传输后端与 A5 链路push_blocks、push_cache、transfer_cache_async三个示例暴露了--transfer_backend参数默认空串使用通信域后端传hixl时通过LLMConfig.transfer_backend hixl切换为 HIXL CS 后端。A5 环境下未手动配置local_comm_res时默认走 UB 链路配置后可走 RDMA其详细 option 语义见 docs/zh/api/cpp/HIXL-interface.md 中OPTION_LOCAL_COMM_RES的说明version 1.3 走 HixlCS 建链、无链路上限。6.5 环境变量语义GLOO_SOCKET_IFNAME指定本机用于 gloo 进程组通信的网卡名通过ifconfig查询保证 Prompt/Decoder 之间控制面可达HCCL_INTRA_ROCE_ENABLE1指示使用 RoCE 网卡进行集合通信域的数据面通信。七、运行注意事项与排查建议脚本一致性双机示例务必保证两台主机脚本尤其是 IP 常量完全一致cluster_id在所有建链节点上必须唯一端口规划单边建链示例固定监听端口26000/26001xPyD 场景各进程需分配互不冲突的ip:portD2D 示例端口自动加 1000 偏移避免与引擎端口冲突版本约束local_comm_resversion 1.3HixlCS 建链要求 HDK 25.5.0、toolkit 9.1.0自动生成 localcommres 对 LCNE/HDK 版本也有要求详见 docs/zh/api/cpp/HIXL-interface.md 中的注意事项参数校验各脚本对device_id0–7与rolep/d做了硬校验越界会直接抛RuntimeError结果校验hixl_transfer_backend_sample与hixl_d2rd_multiproc_sample内置数据一致性校验torch.equal与逐字节比对跑通即代表端到端传输正确是验证组网与驱动配置是否正常的快速手段。以上示例的运行目录、命令与参数均可直接从仓库 examples/python 目录获取并复现相关接口的详细语义可进一步查阅 docs/zh/api/python 下的 LLMDataDist、CacheManager 等接口文档。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考