HIXL C 样例实战指南KvCache 分离部署传输与 D2D/D2H 单边通信【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读本文围绕 CANN HIXL 开源仓库 examples/cpp 下的 C 样例展开系统讲解两类典型场景的落地方法一类是基于 LLM-DataDist 接口实现的KvCache 分离部署disaggregated serving传输pull / push cache 与 blocks、角色切换另一类是基于 HIXL 原生接口实现的Device-to-DeviceD2D、Device-to-HostD2H单边通信含单进程、多进程与 FabricMem 模式。阅读本文后你将掌握每个样例的源码结构、命令行参数、编译方式、运行前提与协议选择策略并理解其背后的Initialize / RegisterKvCache / TransferSync / RegisterMem等核心调用链可直接在昇腾 A2 / A3 / A5Ascend 950PR/950DT集群环境中复现与二次开发。样例整体介绍与目录结构本目录的样例通过 LLM-DataDist、HIXL 接口实现分离部署场景下 KvCache 传输功能。其中 LLM-DataDist 系列用于 Prompt/Decoder 分离部署时缓存与 KV block 的传输HIXL 系列用于展示单边通信的多种协议与运行形态。examples/cpp/ ├── prompt_pull_cache_and_blocks.cpp // pull cache 和 pull blocks 的 prompt 侧实现 ├── decoder_pull_cache_and_blocks.cpp // pull cache 和 pull blocks 的 decoder 侧实现 ├── prompt_push_cache_and_blocks.cpp // push cache 和 push blocks 的 prompt 侧实现 ├── decoder_push_cache_and_blocks.cpp // push cache 和 push blocks 的 decoder 侧实现 ├── prompt_switch_roles.cpp // switch_roles 的 prompt 侧实现 ├── decoder_switch_roles.cpp // switch_roles 的 decoder 侧实现 ├── hixl_example_d2rd.cpp // HIXL D2rD 单进程场景样例 ├── hixl_example_d2rh.cpp // HIXL D2rH 单进程场景样例 ├── hixl_example_d2rd_multiproc.cpp // HIXL D2rD 多进程场景样例 ├── fabric_mem_d2d.cpp // HIXL fabric-mem 模式下的 d2d 场景样例 └── CMakeLists.txt // 编译脚本从编译脚本 examples/cpp/CMakeLists.txt 可以看到目标名称与源文件同名其中前 6 个 LLM-DataDist 样例链接llm_datadist库而hixl_example_d2rd、hixl_example_d2rh、hixl_example_d2rd_multiproc、fabric_mem_d2d以及仓库另附的hixl_example_quickstart链接cann_hixl库二者均依赖acl_rt与ascend_hal。环境与配置前提A5 环境的 RDMA 链路说明下面个别用例支持在 A5 环境使用 RDMA 链路执行且需要在双机上执行会在对应用例中特别说明。在 A5 环境中未手动配置local_comm_res时默认使用 UB 协议如果需要使用 RDMA 链路需要手动配置local_comm_res配置方法参考 HIXL-interface.md 中 Initialize 的 optionsAscend 950PR/Ascend 950DT说明。可通过以下操作获取 host 网卡的 IP 信息# 查询 RoCE 设备和网口的对应关系查看状态为 Up 的网口名 ibdev2netdev # 根据网口名找出对应的 IP 信息 ifconfig从接口文档对OPTION_LOCAL_COMM_RES的描述可以确认A5950PR/950DT上配置local_comm_res的version为1.3时使用 HixlCS 能力建链推荐需要 HDK 大于等于 25.5.0 且 toolkit 大于等于 9.1.0无链路上限限制而version为1.0/1.2的 ranktable 格式则走集合通信通信域方式建链建议单卡建链数量不超过 512。生产环境建议通过 scripts/tools/hixl_tool 工具辅助生成真实环境的 localcommres 信息切勿直接拷贝样例值。软件包与驱动执行所有样例前需要确保已经安装驱动和固件执行 Python 样例前还需要安装 ops 包。构建编译需要 Toolkit 开发套件包安装方式可参考 源码构建包括 Docker 部署与手动安装两种场景A5 容器还需要额外挂载/dev/ummu、/dev/uburma设备与driver/topo目录。程序编译参考 源码构建 中的编译执行章节利用bash build.sh --examples进行编译# 若源码未改动或修改不涉及 src/ops 下的代码建议添加 --host 参数 bash build.sh --examples bash build.sh --host --examples编译结束后在build/examples/cpp目录下生成多个可执行文件其名称与上表源文件名一一对应。编译依赖的第三方开源软件googletest、json、makeself、pybind11、cann-cmake会在编译时自动下载离线环境可通过--cann_3rd_lib_path{your_3rd_party_path}指定已上传的依赖包目录。LLM-DataDist 样例分离部署 KvCache 传输通用运行说明所有样例需要成对运行prompt 侧和 decoder 侧执行间隔时间不要过长。样例中 decoder 侧设置WAIT_PROMPT_TIME为 5sprompt 侧设置WAIT_TIME为 10s用户可根据实际情况自行修改这两个变量的值以保证用例成功运行。下面所有样例以 prompt 和 decoder 运行在相同机器上为前提编写将local_ip和remote_ip设为相同。以 prompt_pull_cache_and_blocks.cpp 为例源码中定义kPromptListenPort 26000、kPromptControlPort 26002、kPromptClusterId 0、kNumTensors 4、tensor shape 为{8, 16}DT_INT32类型并接受device_id、local_ip、可选transfer_backend、可选local_comm_res共 2~4 个参数。配置环境变量若运行环境上安装的是 “Ascend-cann-toolkit” 包环境变量设置如下${HOME}/Ascend请替换为相关软件包的实际安装路径source ${HOME}/Ascend/cann/set_env.sh若运行环境上安装的是 “CANN-XXX.run” 包环境变量设置如下source ${HOME}/Ascend/latest/bin/setenv.bash1pull_cache_and_blocksdecoder 向 prompt 拉取此样例介绍 decoder 向 prompt 进行 pull cache 和 pull blocks 的流程其中 link 和 pull 的方向与角色无关可以根据需求更改。默认走 adxl 传输后端可选参数transfer_backend传hixl可切换为 hixl cs 后端。A5 环境上只支持使用 hixl cs 后端默认走 UB 协议可手动配置local_comm_res走 RDMA 链路。执行 prompt 侧参数为device_id、local_ip、可选transfer_backend与local_comm_res其中device_id为 prompt 要使用的 device_idlocal_ip为 prompt 所在 host 的 IP./prompt_pull_cache_and_blocks 0 10.10.170.1 hixl执行 decoder 侧参数为device_id、local_ip、remote_ip、可选transfer_backend与local_comm_res其中device_id为 decoder 要使用的 device_idlocal_ip为 decoder 所在 host 的 IPremote_ip为 prompt 所在 host 的 IP./decoder_pull_cache_and_blocks 2 10.170.10.1 10.170.10.1 hixl从源码看prompt 侧流程为Initialize写入OPTION_DEVICE_ID、OPTION_LISTEN_IP_INFO与可选的OPTION_TRANSFER_BACKEND/OPTION_LOCAL_COMM_RES→aclrtMalloc分配 4 个 tensor buffer 并初始化 →RegisterKvCache(cache_desc, tensor_addrs, {}, cache_id)注册 KvCache → 通过 26002 端口等待 decoder 完成 unlink 的通知WaitUnlinkDone超时 60s→UnregisterKvCache释放。decoder 侧则解析remote_ip建链、执行 pull再通知 prompt 侧可以释放。2push_cache_and_blocksprompt 向 decoder 推送此样例介绍 prompt 向 decoder 进行 push cache 和 push blocks 的流程其中 link 和 push 的方向与角色无关可以根据需求更改。默认走 HCCL 传输后端可选参数transfer_backend传hixl可切换为 hixl 后端。在 A5 环境上使用 hixl 时默认走 UB 协议可手动配置local_comm_res走 RDMA 链路。执行 prompt 侧参数为device_id、local_ip、remote_ip、可选transfer_backend与local_comm_res其中device_id为 prompt 要使用的 device_idlocal_ip为 prompt 所在 host 的 IPremote_ip为 decoder 所在 host 的 IP./prompt_push_cache_and_blocks 0 10.10.10.1 10.10.10.1 hixl执行 decoder 侧参数为device_id、local_ip、可选transfer_backend与local_comm_res其中device_id为 decoder 要使用的 device_idlocal_ip为 decoder 所在 host 的 IP./decoder_push_cache_and_blocks 4 10.10.10.1 hixl3switch_rolesprompt 与 decoder 角色切换此样例介绍 prompt 和 decoder 进行角色切换并结合 pull 以及 push 使用流程。两端的参数均为device_id、local_ip、remote_ip三个必选参数。执行 prompt 侧device_id为 prompt 要使用的 device_idlocal_ip为 prompt 所在 host 的 IPremote_ip为 decoder 所在 host 的 IP./prompt_switch_roles 0 10.10.170.1 10.170.10.1执行 decoder 侧device_id为 decoder 要使用的 device_idlocal_ip为 decoder 所在 host 的 IPremote_ip为 prompt 所在 host 的 IP./decoder_switch_roles 2 10.170.10.1 10.170.10.1参数与后端选型小结样例默认传输后端可选后端参数按顺序pull_cache_and_blocksadxlhixlA5 仅支持 hixl cs 后端promptdevice_id local_ip [transfer_backend] [local_comm_res]decoderdevice_id local_ip remote_ip [transfer_backend] [local_comm_res]push_cache_and_blocksHCCLhixlpromptdevice_id local_ip remote_ip [transfer_backend] [local_comm_res]decoderdevice_id local_ip [transfer_backend] [local_comm_res]switch_roles--两侧均为device_id local_ip remote_iptransfer_backend仅支持hixl取值传其他值会在 Initialize 中直接报错并退出。local_comm_res为可选的本地通信资源 JSON 字符串在 A5 上用于切换 RDMA 链路。HIXL 样例D2rD / D2rH 单边通信运行形态说明单进程用例hixl_example_d2rd、hixl_example_d2rh在一个进程内启动两个 engine无需分开终端在大于等于 CANN-9.1.0 版本支持。多进程用例hixl_example_d2rd_multiproc需要分别在两个终端启动 server 和 clientserver 先启动无 CANN 版本要求。fabric_mem_d2d需要成对运行两个终端分别启动。HIXL 样例进程参数说明参数适用样例必选/可选默认值说明--protocoltype[,...]hixl_example_d2rd、hixl_example_d2rh、hixl_example_d2rd_multiproc必选-通信协议支持逗号分隔多协议。hixl_example_d2rd 支持roce:device、uboe:device、ub_rtp:device、ub_ctp:devicehixl_example_d2rh 支持roce:device、uboe:device、ub_rtp:device、ub_ctp、ub_ctp:device、ub_ctp:hosthixl_example_d2rd_multiproc 支持hccs:device、roce:device、uboe:device、ub_rtp:device、ub_ctp:device。协议硬件依赖如下hccs:device、roce:device仅支持 Atlas A2 训练系列产品/Atlas A2 推理系列产品、Atlas A3 训练系列产品/Atlas A3 推理系列产品uboe:device、ub_rtp:device、ub_ctp、ub_ctp:device、ub_ctp:host仅支持 Ascend 950PR/Ascend 950DT。协议定义详见 HIXL 接口 中comm_resource_config.protocol_desc的 option 说明。--deviceid或--deviceid1,id2hixl_example_d2rd、hixl_example_d2rh、hixl_example_d2rd_multiproc可选hixl_example_d2rd、hixl_example_d2rh 默认 0,2hixl_example_d2rd_multiproc 默认 client0、server2hixl_example_d2rd、hixl_example_d2rh 使用--deviceid1,id2指定两个 engine 分别绑定的 devicehixl_example_d2rd_multiproc 使用--deviceid指定当前进程绑定的 device。--version0\|1hixl_example_d2rd、hixl_example_d2rh、hixl_example_d2rd_multiproc可选1配置为 0 时表示使用 HCCL 集合通信通信域方式构筑的单边通信能力仅支持 Atlas A2 训练系列产品/Atlas A2 推理系列产品、Atlas A3 训练系列产品/Atlas A3 推理系列产品配置为 1 时表示 HIXL 调用 HIXL CS 接口实现的单边通信能力解耦通信域推荐使用支持 Atlas A2 训练系列产品/Atlas A2 推理系列产品、Atlas A3 训练系列产品/Atlas A3 推理系列产品、Ascend 950PR/Ascend 950DT。--roleclient\|serverhixl_example_d2rd_multiproc必选-指定当前进程为 client 或 server。--local-engineip:porthixl_example_d2rd_multiproc可选client127.0.0.1:16000、server127.0.0.1:16001指定当前进程的 engine 地址。--remote-engineip:porthixl_example_d2rd_multiproc可选client127.0.0.1:16001、server127.0.0.1:16000指定对端进程的 engine 地址。几点源码级补充说明在 hixl_example_d2rd.cpp 的ParseArgs中--protocol缺失会被判定为错误version0模式仅接受roce:device单一协议。version0 的 legacy 流程ConfigLegacyOptions会写入OPTION_LOCAL_COMM_RES{version: 1.2}、OPTION_GLOBAL_RESOURCE_CONFIG{comm_resource_config.listen_port: port}与OPTION_BUFFER_POOL0:0并针对 roce 设置HCCL_INTRA_ROCE_ENABLE1而 version1 的 v2 流程ConfigV2Options则写入OPTION_GLOBAL_RESOURCE_CONFIG{comm_resource_config.protocol_desc: [...]}通过comm_resource_config.protocol_desc配置协议数组。关于protocol_desc接口文档说明支持ub_ctp/roce:device/hccs:device/ub_ctp:device/ub_ctp:host/uboe:device/ub_rtp:device/roce:host。A5 上未配置该字段或仅配置ub_ctp:device时自动生成 Device UB 资源Host 内存通过 UBMEM 映射到 Device 地址后使用 Device UB 链路传输同时配置ub_ctp:device与ub_ctp:host时生成 DeviceHost UB 资源并使用纯 URMA 路径与单独配置ub_ctp等价。环境变量配置与 LLM-DataDist 样例相同按 Toolkit 包或 run 包二选一执行source命令即可。1hixl_example_d2rdD2RD 单进程场景单进程一个线程内启动两个 engine分别绑定不同 device由 engine A 发起 WRITE 传输到 engine B 的 device buffer。传输缓冲区 8 MiB被切分为 512 个 16 KiB 的 block逐个构造TransferOpDesc后通过TransferSync一次提交最后将 engine B 的 device buffer 拷回 Host 校验是否为填充值0xAA对应 Transfer/Verify。运行示例# 使用 roce:device 协议 ./hixl_example_d2rd --protocolroce:device # 指定 device ./hixl_example_d2rd --protocolroce:device --device0,2 # 使用 version 0 模式仅支持 roce:device ./hixl_example_d2rd --protocolroce:device --version02hixl_example_d2rhD2RH 单进程场景单进程一个线程内启动两个 engine分别绑定不同 device双方各自发起 WRITE 传输到对方的 host buffer。该样例支持纯 URMA 的ub_ctp协议及其等价写法ub_ctp:device,ub_ctp:host。运行示例# 使用 roce:device 协议 ./hixl_example_d2rh --protocolroce:device # 使用 UB CTP 纯 URMA 协议 ./hixl_example_d2rh --protocolub_ctp # 原有 DeviceHost 写法同样使用纯 URMA 协议 ./hixl_example_d2rh --protocolub_ctp:device,ub_ctp:host # 使用 version 0 模式 ./hixl_example_d2rh --protocolroce:device --version03hixl_example_d2rd_multiprocD2RD 多进程场景两个独立进程分别启动 engine通过 socket 交换 buffer 地址后由 client 发起 READ 传输并本地校验。从 hixl_example_d2rd_multiproc.cpp 可以看到server 在local_engine端口号 1000 的偏移端口上监听接受 client 连接后将本地 device buffer 地址发送出去client 通过 socket 获取远端地址后执行TransferSync(READ)再校验数据是否为填充值0xAA。该样例支持hccs:device是唯一覆盖 HCCS 协议的多进程样例且 version0 模式支持roce:device与hccs:device。运行示例注意 server 先启动# 使用 roce 协议 ./hixl_example_d2rd_multiproc --roleserver --protocolroce:device ./hixl_example_d2rd_multiproc --roleclient --protocolroce:device # 使用 hccs 协议 ./hixl_example_d2rd_multiproc --roleserver --protocolhccs:device ./hixl_example_d2rd_multiproc --roleclient --protocolhccs:device # 使用 version 0 模式 ./hixl_example_d2rd_multiproc --roleserver --protocolroce:device --version0 ./hixl_example_d2rd_multiproc --roleclient --protocolroce:device --version0fabric_mem_d2dFabricMem 模式 D2D 场景版本与硬件前提FabricMem 仅支持 Atlas A3 训练系列产品/Atlas A3 推理系列产品最低支持 HDK 25.5。HDK 25.5 不支持aclrtMemRetainAllocationHandle。在该版本上FabricMem 场景的 Host 内存必须使用 ADXL 提供的MallocMem/FreeMem进行申请和释放。HDK 26.0 及以上版本可以直接使用 ACL 接口管理 FabricMem 场景的 Host 内存。当前fabric_mem_d2d样例在AllocateBuffer中直接使用 ACL VMM 接口aclrtReserveMemAddress、aclrtMallocPhysical和aclrtMapMem分配内存随后以MEM_DEVICE注册未通过 ADXL 的AdxlEngine::MallocMem分配。该注册路径需要aclrtMemRetainAllocationHandle因此样例要求 HDK 26.0 及以上版本不兼容 HDK 25.5。样例中的aclrtMallocHost/aclrtFreeHost仅用于初始化和校验 buffer并非 FabricMem Host 内存注册。从 fabric_mem_d2d.cpp 源码可以看到Initialize阶段向 options 写入OPTION_ENABLE_USE_FABRIC_MEM 1以开启 FabricMem 能力随后通过Connect、TransferSync(WRITE)完成跨 engine 的显存到显存写入两端以文件ip:port命名的本地文件方式交换对方 buffer 地址具备 60s 等待超时。传输大小为 2 MiB写 1 MiB。运行方法两个终端成对运行参数为device_id、local engine 和 remote engine其中device_id为当前 engine 要使用的 device_id终端一server1./fabric_mem_d2d 0 127.0.0.1:16000 127.0.0.1:16001终端二server2./fabric_mem_d2d 1 127.0.0.1:16001 127.0.0.1:16000常见问题与排查建议成对运行与超时LLM-DataDist 样例的 prompt/decoder 必须成对启动且间隔不宜过长若超时可增大源码中的WAIT_PROMPT_TIMEdecoder 侧默认 5s与WAIT_TIMEprompt 侧默认 10s。A5 默认协议与 RDMA 切换A5 上未手动配置local_comm_res时默认走 UB 协议需要 RDMA 时须手动配置local_comm_res推荐version: 1.3并先用ibdev2netdev、ifconfig确认 RoCE 网口与 IP。可参考 scripts/tools/hixl_tool/readme.md 使用工具生成 localcommres 信息。协议与硬件不匹配hccs:device、roce:device仅支持 A2/A3 系列产品uboe:device、ub_rtp:device、ub_ctp*仅支持 Ascend 950PR/950DT选型时务必与protocol_desc的硬件依赖对齐。version 模式限制version0HCCL 通信域方式仅支持roce:deviced2rd/d2rh或roce:device/hccs:devicemultiproc且仅支持 A2/A3 系列产品新项目建议使用默认的 version1HIXL CS 方式。FabricMem 版本兼容当前fabric_mem_d2d样例基于aclrtMemRetainAllocationHandle的注册路径要求 HDK 26.0 及以上HDK 25.5 上应改用 ADXLMallocMem/FreeMem管理 Host 内存。如需继续深入学习可结合 HIXL C 接口文档重点看 Initialize 的 options 与comm_resource_config.protocol_desc字段说明以及 LLM-DataDist 接口文档 理解各 option 的完整语义也可参考 examples/README.md 了解 Python 侧样例与其余示例。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
