CANN HIXL LLM-DataDist Python 快速入门从零构建大模型推理 PD 分离框架【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixlLLM-DataDist 是 CANN HIXL 单边通信库中的大模型分布式集群与数据管理组件面向昇腾集群提供高性能、零拷贝的点对点 KV Cache 传输能力。本文基于 docs/zh/guide/python/quick_start.md 展开讲解如何将 LLM-DataDist 使能到大模型推理框架中完成 PDPrefill/Decode分离式部署并配套介绍环境准备、关键环境变量、完整样例参考与底层源码佐证。读完本文你将掌握 PD 分离框架的整体开发流程、LLM-DataDist 初始化/建链/注册/传输/释放的完整接口调用链以及如何在本地运行官方样例验证整套流程。整体开发流程推理框架中的四个抽象模块为了统一描述不同推理框架的改造点LLM-DataDist 将推理框架抽象为四个模块资源初始化模块负责框架底层资源Device、通信等的初始化。KV Cache 管理模块负责 KV Cache 内存的创建、分配PA/PagedAttention 场景与销毁。模型推理模块负责实际的 Prefill / Decode 推理执行。资源释放模块负责框架退出时的资源清理。LLM-DataDist 的核心目标就是在这四个模块中以最小侵入方式使能 PD 之间高性能的 KV Cache 传输能力。整体开发流程分为五步资源初始化阶段使能 LLM-DataDist找到推理框架的资源初始化模块在该阶段调用 LLM-DataDist 的初始化接口LLMDataDist()构造 init()和建链接口link_clusters/link。KV Cache 管理阶段注册内存在 KV Cache 管理模块调用 LLM-DataDist 的 KV Cache 注册接口register_cache/register_blocks_cache将推理框架自行申请的内存注册到 LLM-DataDist 中供后续远端访问。拆分解耦 Prefill 与 Decode将推理脚本拆分为 Prefill全量脚本与 Decode增量脚本分离部署到不同的集群节点上。Decode 阶段执行前需要接收 Prefill 阶段的输出作为输入并调用 LLM-DataDist 的 KV Cache 传输接口pull_cache/pull_blocks/push_cache/push_blocks等拉取或推送 Prefill 侧缓存的 KV Cache。分别执行推理脚本在各自集群上运行 Prefill 推理脚本和 Decode 推理脚本。释放 LLM-DataDist 资源在框架的资源释放模块调用unlink_clusters或unlink断链并调用finalize()释放 LLM-DataDist 相关资源。从源码结构看这五步与 src/llm_datadist/llm_datadist_v2.cc 及 src/llm_datadist/api/llm_datadist_impl.cc 中的接口实现一一对应init/finalize/link_clusters/unlink_clusters等能力均由底层引擎调度完成。环境准备硬件形态、网络检测与环境变量支持的硬件形态LLM-DataDist 支持的产品形态如下当前仓库文档口径Atlas A2 训练/推理系列产品仅支持 Atlas 800I A2 推理服务器、A200I A2 Box 异构组件。该场景下 Server 内采用 HCCS 传输协议时仅支持 D2D。Atlas A3 训练/推理系列产品采用 HCCS 传输协议时不支持 Host 内存作为远端 Cache。Ascend 950PR/Ascend 950DT超节点内使用 UB 协议超节点间使用 RoCE 协议。使用前请参照《CANN 软件安装》安装好驱动、固件以及 CANN 软件并确认已安装hccn_tool工具。卡间网络检测hccn_tool 常用命令LLM-DataDist 依赖集群节点之间的 RDMA 链路使用前必须用hccn_tool查询 Device IP 并进行卡间网络检测要求各个集群上的卡间有 RDMA 链路连接否则无法使能 LLM-DataDist 能力。常用命令如下命令使用场景hccn_tool [-i %d] -link -g获取指定 Device 网口 Link 状态。-i指定 Device。样例hccn_tool -i 0 -link -ghccn_tool [-i %d] -ip -g获取 IP 地址和子网掩码。样例hccn_tool -i 0 -ip -ghccn_tool [-i %d] -ip -inet6 -g获取 IPv6 地址和子网掩码。样例hccn_tool -i 0 -ip -inet6 -ghccn_tool [-i %d] -ping -g [address %s]获取指定设备到目的地址的 ping 结果。样例hccn_tool -i 0 -ping -g address 192.168.2.1在仓库样例中也能看到hccn_tool的实际用法例如 examples/python/llm_datadist/pull_cache_sample.py 通过subprocess.run([hccn_tool, -i, str(device_id), -ip, -g])解析本机 Device IP用于构造单机场景下的 rank table这印证了-ip -g输出中包含ipaddr:关键字的实现细节。关键环境变量名称使用场景HCCL_RDMA_TC、HCCL_RDMA_SL当客户对参数面网络做了自己的规划规定了各种业务流量的类型与优先级时通过这两个环境变量设置参数面集合通信流量在网络上的流量类型和优先级以适配客户网络流量规划要求。HCCL_RDMA_RETRY_CNT、HCCL_RDMA_TIMEOUT分别对应 RDMA 硬件重试次数和重试超时时间。设置太大对网络异常反应不敏感无法感知网络故障设置太小则容易造成网络闪断直接中断业务无法被网卡硬件屏蔽。推荐按下式配置以减少网络抖动影响HCCL_RDMA_TIMEOUT log2(pull kv超时时间 * 10^6 / (HCCL_RDMA_RETRY_CNT 1) / 4.096)向上取整。当 pull kv 超时时间和HCCL_RDMA_RETRY_CNT都取默认值时HCCL_RDMA_TIMEOUT建议配置为 15。HCCL_INTRA_ROCE_ENABLE用于配置 Server 内是否使用 RoCE 环路进行多卡间的通信。AUTO_USE_UC_MEMORY控制系统是否允许算子搬移数据不经过 L2 Cache 的功能。使用 LLM-DataDist 之前如果未配置该环境变量使用过程中会将其设置为 0表示所有算子搬移数据都必须经过 L2 Cache。HCCL_INTRA_ROCE_ENABLE1在官方样例中高频出现如 examples/python/README.md 中所有双机样例均以该前缀启动用于强制使用 RoCE 环路通信同时样例要求先执行source ${HOME}/Ascend/cann/set_env.sh加载昇腾运行环境。完整样例参考以 transformers LLAMA 模型为例的 PD 分离改造官方以 transformers 的 LLAMA 模型为例展示 PD 分离前后脚本的变化点提供如何从非分离脚本改为 PD 分离脚本的参考。样例将全量模型和增量模型分离部署到不同集群节点上执行可在配套版本配套表中从npu_tuned_model/llm/llama/benchmark/pd_separate目录获取。分离脚本在整个推理流程中的服务层调度过程如下用户请求触发时服务层将请求调度到全量Prefill集群执行全量脚本推理并将增量脚本需要的信息传输到增量脚本执行节点此时全量集群节点可继续接收服务层下发的新的用户请求。增量Decode集群接收全量集群对应的请求信息拉取对应请求的 KV Cache在全量集群节点上已计算好同时按照增量模型的 batch 大小进行组 batch 操作执行增量推理。当增量集群上有请求推理完成、空出对应 batch 位置时再接收全量集群发来的新请求重复步骤 2 和 3。全量集群重复步骤 1增量集群重复步骤 2 和 3直到业务结束全量和增量集群退出。这套调度模型充分利用了 KV Cache 复用与 Continuous Batching 机制Prefill 阶段是计算密集型决定 TTFTDecode 阶段是访存密集型决定 TBTPD 分离后两阶段互不阻塞系统可以提供更稳定的 TBT。相关背景概念Prefill/Decode 阶段、KV Cache、PagedAttention、block_table、cluster_id、动态扩缩容等可参考 docs/zh/guide/python/appendices.md。可运行样例从双机 pull_cache 到多后端传输本仓库提供了 9 个 LLM-DataDist Python 样例全部位于 examples/python/llm_datadist 目录覆盖一般 Cache 传输、BlocksPA传输、角色切换、xPyD 多机扩展、异步分层传输以及 HIXL 传输后端等场景。双机执行 pull_cache 样例pull_cache_sample.py展示配置内存池场景下使用allocate_cache、双边建链link并从远端pull_cache的完整流程。双机执行命令如下device_id为要使用的设备号cluster_id为集群 ID 且在所有参与建链范围内需唯一# 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 两个进程# 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运行前需要修改样例顶部的 IP 配置将PROMPT_IP_LIST改为 Prompt 主机的各device_ipPROMPT_HOST_IP改为 Prompt 主机host_ipDECODER_IP_LIST与DECODER_HOST_IP对应改为 Decoder 主机的信息且两台机器脚本保持一致。从源码理解 pull_cache 样例的执行主线从 examples/python/llm_datadist/pull_cache_sample.py 的代码可以看到完整调用链初始化LLMDataDist(role, cluster_id)构造对象后通过LLMConfig()设置device_id、enable_cache_managerTrue与mem_pool_cfg再调用generate_options()生成配置字典并交给datadist.init(llm_options)建链cluster_rank_info {1: 0, 2: 1}表示集群 1 对应 rank 0、集群 2 对应 rank 1随后调用datadist.link(link, cluster_rank_info, rank_table)发起双边建链并通过query_register_mem_status(comm_id)轮询内存注册状态直至RegisterMemStatus.OKCache 分配Prompt 侧用CacheKey(prompt_cluster_id1, req_id0, model_id0)标识请求调用allocate_cache(cache_desc, [cache_key_0, cache_key_1])分配并关联两个请求的 KV Cache传输Decoder 侧调用cache_manager.pull_cache(cache_key_0, cache, batch_index0)按 batch 位置拉取远端 KV Cache清理传输结束后 Prompt 侧调用remove_cache_key解除 cache key 与请求的关联pull 失败时确保 cache 可释放两侧调用deallocate_cache、unlink与finalize完成资源回收。其他样例的运行方式与适用场景pull_blocks / pull_from_cache_to_blocksPA 场景下按 block 拉取pull_blocks_sample.py使用 torch 自行申请内存并双向建链pull_from_cache_to_blocks.py演示从一般 Cache 拉取到 Blocks 内存布局。双机与单机执行方式与 pull_cache 相同。push_blocks / push_cache单侧建链link_clusters方式Decoder 发起建链并 push。默认走通信域传输后端可加--transfer_backend hixl切换为 HIXL CS 后端A5Ascend 950PR/Ascend 950DT环境必须指定--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 hixlswitch_role_sample先由 Decoder 建链 pull blocks随后两侧切换角色由 Prompt 发起建链并 push blocks演示switch_role接口的角色与 Client/Server 双向切换能力。pull_blocks_xpyd_sample支持 xPyD 测试场景任意 P 个 Prompt 进程、D 个 Decoder 进程每个 Decoder 与所有 Prompt 建链并 pull blocks 到本地。--remote_ip_port参数由所有 Prompt 侧的local_ip:port以分号;连接组成。transfer_cache_async_sample单侧建链Prompt 侧发起建链并通过transfer_cache_asyncLayerSynchronizer异步分层传输 cache。hixl_transfer_backend_sample以 HIXL 作为 LLM-DataDist 传输后端完成内存注册、建链和传输Decoder 发起建链 push blocksPrompt 发起建链 pull blocks。关键配置项与接口约束LLMConfig 核心配置项LLMConfig用于构造init所需的配置字典对应 docs/zh/api/python/LLMConfig.md配置项对应底层配置说明device_idge.exec.deviceId必填当前进程 Device ID当前只支持配置一个。enable_cache_managerllm.EnableCacheManager是否开启 CacheManager 模式需配置为 True。Decode 和 Prompt 可双向拉取 Cache。Ascend 950PR/Ascend 950DT 场景不支持配置为 False。enable_remote_cache_accessible—是否开启远端 Cache 可直接访问。开启后本地缓存远端 Cache 元数据索引、内存地址等以加速 Pull更适用于 PA 场景Cache 只在初始化阶段分配/注册不会频繁变化。Atlas A3 场景不开启时仅支持 RDMA 传输协议Ascend 950PR/Ascend 950DT 不支持配置为 False。sync_kv_timeoutllm.SyncKvCacheWaitTimepull_cache/pull_blocks/push_cache/push_blocks的超时时间ms默认 1000ms。listen_ip_infollm.listenIpInfoHost 侧 IP 和端口例如192.168.1.1:26000。配置后本端即作为 Server 监听可用于单边建链。local_comm_res—本地通信资源JSON 字符串。不配置或为空串时自动生成相关信息使用集合通信通信域方式建链单卡链路上限 512配置version为1.0/1.2的 ranktable 格式时同样走通信域建链配置version为1.3推荐需要 HDK ≥ 25.5.0 且 toolkit ≥ 9.1.0时使用 HixlCS 能力建链无链路上限。配置了该 option 后若未显式配置enable_cache_manager与enable_remote_cache_accessible默认置为 True。rdma_traffic_class/rdma_service_level与HCCL_RDMA_TC/HCCL_RDMA_SL等效分别配置 RDMA 网卡 traffic class[0,255]需为 4 的整数倍默认 132与 service level[0,7]默认 4。与对应环境变量同时配置时option 优先级更高。link_total_time/link_retry_count—HCCL 建链失败的总超时时间秒[0, 2^32-1]默认 0传入 0 时读取HCCL_CONNECT_TIMEOUT默认 120s与重试次数[1,100]默认 1。transfer_backend—取值为hixl时指定 HIXL 作为传输引擎后端。使用 hixl 后端时需在 init 的 options 中指定listen_ip_info每个传输端既可作 Client 也可作 Server且与对端发起传输前需先调用link_clusters建链。global_resource_config—仅当transfer_backend为hixl时生效JSON 格式内容透传至 HIXL 引擎解析校验例如{comm_resource_config.listen_port: 26666, comm_resource_config.max_active_channels: 128}。ge_optionsge.*额外 GE 配置项其中ge.flowGraphMemMaxSize表示所有 KV Cache 占用的最大内存设置过大将压缩模型可用内存需按实际情况指定。建链方式与链路上限LLM-DataDist 提供两种建链方式对应 docs/zh/api/python/LLMDataDist.md单边建链link_clusters推荐由 Client 单侧发起是否作为 Server 与角色 Prompt/Decoder 无关设置listen_ip_info标识端口监听即为 Server 端。返回值为二元组(LLMStatusCode, List[LLMStatusCode])分别表示接口返回值与每个集群的建链结果。约束包括建议超时时间配置 200ms 以上TLS 开启时建议 2000ms 以上可用hccn_tool [-i %d] -tls -g [host]查询 TLS 状态调用前需提前注册所有内存否则建链后注册不支持远端访问。双边建链link通过建立通信域方式建链需要rank_table文件通信域内节点数量最大支持 4通信域数量建议不超过 16、最大 512最多支持 16 条链路并发建链超过 16 条底层排队。unlink为对应的断链接口query_register_mem_status配合link查询注册内存状态。Ascend 950PR/Ascend 950DT 不支持link、unlink和query_register_mem_status。建链数量过多存在内存 OOM 及 KV Cache 传输性能风险使用集合通信通信域方式建链时允许的最大通信数量为 512使用 HixlCS 能力local_comm_res配置version为1.3建链时没有链路上限限制。容器与网络约束容器场景若未配置local_comm_res或配置为空需在容器内映射/etc/hccn.conf文件或确保默认路径/usr/local/Ascend/driver/tools下存在hccn_tool两者都不满足时需将hccn_tool所在路径配置到PATH中export PATH$PATH:{hccn_tool_install_path}。使用 Device RoCE 场景时同一通信集群内 Device RoCE 地址配置需保持一致不支持 IPv6-only 节点与 IPv4/IPv6 双栈节点混合接入约束适用于 Atlas A2 与 Atlas A3 训练/推理系列产品。更进一步接口参考与示例代码的完整地图接口参考Pythondocs/zh/api/python/README.md 汇总了LLMDataDist、LLMConfig、CacheManager、Cache、LLMRole、LLMClusterInfo、CacheDesc、CacheKey、BlocksCacheKey、TransferConfig、LLMStatusCode等全部组件文档接口约束与错误码处理可查阅 docs/zh/api/python/LLMStatusCode.md。链路管理与 KV Cache 管理的接口功能与伪代码示例见 docs/zh/guide/python/functions.md其中包含一般 Cache 传输register_cache/pull_cache/transfer_cache_async与 Blocks Cache 传输register_blocks_cache/pull_blocks/push_blocks两套完整示例。底层实现参考LLM-DataDist 的初始化与链路管理实现在 src/llm_datadist/llm_datadist_v2.cc缓存管理实现在 src/llm_datadist/cache_mgr/cache_manager.cc传输后端抽象位于 src/llm_datadist/transfer_engineHIXL 传输引擎实现在 src/llm_datadist/transfer_engine/hixl_transfer_engine.cc。更多完整可运行样例除本仓库 examples/python/llm_datadist 目录外也可在配套版本的examples/python目录中获取更多代码样例。结语以 docs/zh/guide/python/quick_start.md 为主线本文完整还原了在推理框架中使能 LLM-DataDist 的五步开发流程并补充了环境准备、关键环境变量、配置项约束与可运行样例。核心要点可概括为初始化init→ 建链link_clusters/link→ 注册内存register_cache/register_blocks_cache→ 传输 KV Cachepull_*/push_*/transfer_cache_async→ 断链与释放unlink_*/finalize。建议读者结合 examples/python/llm_datadist/pull_cache_sample.py 等样例先跑通双机最小闭环再参照 docs/zh/guide/python/functions.md 与 docs/zh/api/python/LLMDataDist.md 将接口迁移到自己的推理框架中。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN HIXL LLM-DataDist Python 快速入门：从零构建大模型推理 PD 分离框架
CANN HIXL LLM-DataDist Python 快速入门从零构建大模型推理 PD 分离框架【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixlLLM-DataDist 是 CANN HIXL 单边通信库中的大模型分布式集群与数据管理组件面向昇腾集群提供高性能、零拷贝的点对点 KV Cache 传输能力。本文基于 docs/zh/guide/python/quick_start.md 展开讲解如何将 LLM-DataDist 使能到大模型推理框架中完成 PDPrefill/Decode分离式部署并配套介绍环境准备、关键环境变量、完整样例参考与底层源码佐证。读完本文你将掌握 PD 分离框架的整体开发流程、LLM-DataDist 初始化/建链/注册/传输/释放的完整接口调用链以及如何在本地运行官方样例验证整套流程。整体开发流程推理框架中的四个抽象模块为了统一描述不同推理框架的改造点LLM-DataDist 将推理框架抽象为四个模块资源初始化模块负责框架底层资源Device、通信等的初始化。KV Cache 管理模块负责 KV Cache 内存的创建、分配PA/PagedAttention 场景与销毁。模型推理模块负责实际的 Prefill / Decode 推理执行。资源释放模块负责框架退出时的资源清理。LLM-DataDist 的核心目标就是在这四个模块中以最小侵入方式使能 PD 之间高性能的 KV Cache 传输能力。整体开发流程分为五步资源初始化阶段使能 LLM-DataDist找到推理框架的资源初始化模块在该阶段调用 LLM-DataDist 的初始化接口LLMDataDist()构造 init()和建链接口link_clusters/link。KV Cache 管理阶段注册内存在 KV Cache 管理模块调用 LLM-DataDist 的 KV Cache 注册接口register_cache/register_blocks_cache将推理框架自行申请的内存注册到 LLM-DataDist 中供后续远端访问。拆分解耦 Prefill 与 Decode将推理脚本拆分为 Prefill全量脚本与 Decode增量脚本分离部署到不同的集群节点上。Decode 阶段执行前需要接收 Prefill 阶段的输出作为输入并调用 LLM-DataDist 的 KV Cache 传输接口pull_cache/pull_blocks/push_cache/push_blocks等拉取或推送 Prefill 侧缓存的 KV Cache。分别执行推理脚本在各自集群上运行 Prefill 推理脚本和 Decode 推理脚本。释放 LLM-DataDist 资源在框架的资源释放模块调用unlink_clusters或unlink断链并调用finalize()释放 LLM-DataDist 相关资源。从源码结构看这五步与 src/llm_datadist/llm_datadist_v2.cc 及 src/llm_datadist/api/llm_datadist_impl.cc 中的接口实现一一对应init/finalize/link_clusters/unlink_clusters等能力均由底层引擎调度完成。环境准备硬件形态、网络检测与环境变量支持的硬件形态LLM-DataDist 支持的产品形态如下当前仓库文档口径Atlas A2 训练/推理系列产品仅支持 Atlas 800I A2 推理服务器、A200I A2 Box 异构组件。该场景下 Server 内采用 HCCS 传输协议时仅支持 D2D。Atlas A3 训练/推理系列产品采用 HCCS 传输协议时不支持 Host 内存作为远端 Cache。Ascend 950PR/Ascend 950DT超节点内使用 UB 协议超节点间使用 RoCE 协议。使用前请参照《CANN 软件安装》安装好驱动、固件以及 CANN 软件并确认已安装hccn_tool工具。卡间网络检测hccn_tool 常用命令LLM-DataDist 依赖集群节点之间的 RDMA 链路使用前必须用hccn_tool查询 Device IP 并进行卡间网络检测要求各个集群上的卡间有 RDMA 链路连接否则无法使能 LLM-DataDist 能力。常用命令如下命令使用场景hccn_tool [-i %d] -link -g获取指定 Device 网口 Link 状态。-i指定 Device。样例hccn_tool -i 0 -link -ghccn_tool [-i %d] -ip -g获取 IP 地址和子网掩码。样例hccn_tool -i 0 -ip -ghccn_tool [-i %d] -ip -inet6 -g获取 IPv6 地址和子网掩码。样例hccn_tool -i 0 -ip -inet6 -ghccn_tool [-i %d] -ping -g [address %s]获取指定设备到目的地址的 ping 结果。样例hccn_tool -i 0 -ping -g address 192.168.2.1在仓库样例中也能看到hccn_tool的实际用法例如 examples/python/llm_datadist/pull_cache_sample.py 通过subprocess.run([hccn_tool, -i, str(device_id), -ip, -g])解析本机 Device IP用于构造单机场景下的 rank table这印证了-ip -g输出中包含ipaddr:关键字的实现细节。关键环境变量名称使用场景HCCL_RDMA_TC、HCCL_RDMA_SL当客户对参数面网络做了自己的规划规定了各种业务流量的类型与优先级时通过这两个环境变量设置参数面集合通信流量在网络上的流量类型和优先级以适配客户网络流量规划要求。HCCL_RDMA_RETRY_CNT、HCCL_RDMA_TIMEOUT分别对应 RDMA 硬件重试次数和重试超时时间。设置太大对网络异常反应不敏感无法感知网络故障设置太小则容易造成网络闪断直接中断业务无法被网卡硬件屏蔽。推荐按下式配置以减少网络抖动影响HCCL_RDMA_TIMEOUT log2(pull kv超时时间 * 10^6 / (HCCL_RDMA_RETRY_CNT 1) / 4.096)向上取整。当 pull kv 超时时间和HCCL_RDMA_RETRY_CNT都取默认值时HCCL_RDMA_TIMEOUT建议配置为 15。HCCL_INTRA_ROCE_ENABLE用于配置 Server 内是否使用 RoCE 环路进行多卡间的通信。AUTO_USE_UC_MEMORY控制系统是否允许算子搬移数据不经过 L2 Cache 的功能。使用 LLM-DataDist 之前如果未配置该环境变量使用过程中会将其设置为 0表示所有算子搬移数据都必须经过 L2 Cache。HCCL_INTRA_ROCE_ENABLE1在官方样例中高频出现如 examples/python/README.md 中所有双机样例均以该前缀启动用于强制使用 RoCE 环路通信同时样例要求先执行source ${HOME}/Ascend/cann/set_env.sh加载昇腾运行环境。完整样例参考以 transformers LLAMA 模型为例的 PD 分离改造官方以 transformers 的 LLAMA 模型为例展示 PD 分离前后脚本的变化点提供如何从非分离脚本改为 PD 分离脚本的参考。样例将全量模型和增量模型分离部署到不同集群节点上执行可在配套版本配套表中从npu_tuned_model/llm/llama/benchmark/pd_separate目录获取。分离脚本在整个推理流程中的服务层调度过程如下用户请求触发时服务层将请求调度到全量Prefill集群执行全量脚本推理并将增量脚本需要的信息传输到增量脚本执行节点此时全量集群节点可继续接收服务层下发的新的用户请求。增量Decode集群接收全量集群对应的请求信息拉取对应请求的 KV Cache在全量集群节点上已计算好同时按照增量模型的 batch 大小进行组 batch 操作执行增量推理。当增量集群上有请求推理完成、空出对应 batch 位置时再接收全量集群发来的新请求重复步骤 2 和 3。全量集群重复步骤 1增量集群重复步骤 2 和 3直到业务结束全量和增量集群退出。这套调度模型充分利用了 KV Cache 复用与 Continuous Batching 机制Prefill 阶段是计算密集型决定 TTFTDecode 阶段是访存密集型决定 TBTPD 分离后两阶段互不阻塞系统可以提供更稳定的 TBT。相关背景概念Prefill/Decode 阶段、KV Cache、PagedAttention、block_table、cluster_id、动态扩缩容等可参考 docs/zh/guide/python/appendices.md。可运行样例从双机 pull_cache 到多后端传输本仓库提供了 9 个 LLM-DataDist Python 样例全部位于 examples/python/llm_datadist 目录覆盖一般 Cache 传输、BlocksPA传输、角色切换、xPyD 多机扩展、异步分层传输以及 HIXL 传输后端等场景。双机执行 pull_cache 样例pull_cache_sample.py展示配置内存池场景下使用allocate_cache、双边建链link并从远端pull_cache的完整流程。双机执行命令如下device_id为要使用的设备号cluster_id为集群 ID 且在所有参与建链范围内需唯一# 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 两个进程# 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运行前需要修改样例顶部的 IP 配置将PROMPT_IP_LIST改为 Prompt 主机的各device_ipPROMPT_HOST_IP改为 Prompt 主机host_ipDECODER_IP_LIST与DECODER_HOST_IP对应改为 Decoder 主机的信息且两台机器脚本保持一致。从源码理解 pull_cache 样例的执行主线从 examples/python/llm_datadist/pull_cache_sample.py 的代码可以看到完整调用链初始化LLMDataDist(role, cluster_id)构造对象后通过LLMConfig()设置device_id、enable_cache_managerTrue与mem_pool_cfg再调用generate_options()生成配置字典并交给datadist.init(llm_options)建链cluster_rank_info {1: 0, 2: 1}表示集群 1 对应 rank 0、集群 2 对应 rank 1随后调用datadist.link(link, cluster_rank_info, rank_table)发起双边建链并通过query_register_mem_status(comm_id)轮询内存注册状态直至RegisterMemStatus.OKCache 分配Prompt 侧用CacheKey(prompt_cluster_id1, req_id0, model_id0)标识请求调用allocate_cache(cache_desc, [cache_key_0, cache_key_1])分配并关联两个请求的 KV Cache传输Decoder 侧调用cache_manager.pull_cache(cache_key_0, cache, batch_index0)按 batch 位置拉取远端 KV Cache清理传输结束后 Prompt 侧调用remove_cache_key解除 cache key 与请求的关联pull 失败时确保 cache 可释放两侧调用deallocate_cache、unlink与finalize完成资源回收。其他样例的运行方式与适用场景pull_blocks / pull_from_cache_to_blocksPA 场景下按 block 拉取pull_blocks_sample.py使用 torch 自行申请内存并双向建链pull_from_cache_to_blocks.py演示从一般 Cache 拉取到 Blocks 内存布局。双机与单机执行方式与 pull_cache 相同。push_blocks / push_cache单侧建链link_clusters方式Decoder 发起建链并 push。默认走通信域传输后端可加--transfer_backend hixl切换为 HIXL CS 后端A5Ascend 950PR/Ascend 950DT环境必须指定--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 hixlswitch_role_sample先由 Decoder 建链 pull blocks随后两侧切换角色由 Prompt 发起建链并 push blocks演示switch_role接口的角色与 Client/Server 双向切换能力。pull_blocks_xpyd_sample支持 xPyD 测试场景任意 P 个 Prompt 进程、D 个 Decoder 进程每个 Decoder 与所有 Prompt 建链并 pull blocks 到本地。--remote_ip_port参数由所有 Prompt 侧的local_ip:port以分号;连接组成。transfer_cache_async_sample单侧建链Prompt 侧发起建链并通过transfer_cache_asyncLayerSynchronizer异步分层传输 cache。hixl_transfer_backend_sample以 HIXL 作为 LLM-DataDist 传输后端完成内存注册、建链和传输Decoder 发起建链 push blocksPrompt 发起建链 pull blocks。关键配置项与接口约束LLMConfig 核心配置项LLMConfig用于构造init所需的配置字典对应 docs/zh/api/python/LLMConfig.md配置项对应底层配置说明device_idge.exec.deviceId必填当前进程 Device ID当前只支持配置一个。enable_cache_managerllm.EnableCacheManager是否开启 CacheManager 模式需配置为 True。Decode 和 Prompt 可双向拉取 Cache。Ascend 950PR/Ascend 950DT 场景不支持配置为 False。enable_remote_cache_accessible—是否开启远端 Cache 可直接访问。开启后本地缓存远端 Cache 元数据索引、内存地址等以加速 Pull更适用于 PA 场景Cache 只在初始化阶段分配/注册不会频繁变化。Atlas A3 场景不开启时仅支持 RDMA 传输协议Ascend 950PR/Ascend 950DT 不支持配置为 False。sync_kv_timeoutllm.SyncKvCacheWaitTimepull_cache/pull_blocks/push_cache/push_blocks的超时时间ms默认 1000ms。listen_ip_infollm.listenIpInfoHost 侧 IP 和端口例如192.168.1.1:26000。配置后本端即作为 Server 监听可用于单边建链。local_comm_res—本地通信资源JSON 字符串。不配置或为空串时自动生成相关信息使用集合通信通信域方式建链单卡链路上限 512配置version为1.0/1.2的 ranktable 格式时同样走通信域建链配置version为1.3推荐需要 HDK ≥ 25.5.0 且 toolkit ≥ 9.1.0时使用 HixlCS 能力建链无链路上限。配置了该 option 后若未显式配置enable_cache_manager与enable_remote_cache_accessible默认置为 True。rdma_traffic_class/rdma_service_level与HCCL_RDMA_TC/HCCL_RDMA_SL等效分别配置 RDMA 网卡 traffic class[0,255]需为 4 的整数倍默认 132与 service level[0,7]默认 4。与对应环境变量同时配置时option 优先级更高。link_total_time/link_retry_count—HCCL 建链失败的总超时时间秒[0, 2^32-1]默认 0传入 0 时读取HCCL_CONNECT_TIMEOUT默认 120s与重试次数[1,100]默认 1。transfer_backend—取值为hixl时指定 HIXL 作为传输引擎后端。使用 hixl 后端时需在 init 的 options 中指定listen_ip_info每个传输端既可作 Client 也可作 Server且与对端发起传输前需先调用link_clusters建链。global_resource_config—仅当transfer_backend为hixl时生效JSON 格式内容透传至 HIXL 引擎解析校验例如{comm_resource_config.listen_port: 26666, comm_resource_config.max_active_channels: 128}。ge_optionsge.*额外 GE 配置项其中ge.flowGraphMemMaxSize表示所有 KV Cache 占用的最大内存设置过大将压缩模型可用内存需按实际情况指定。建链方式与链路上限LLM-DataDist 提供两种建链方式对应 docs/zh/api/python/LLMDataDist.md单边建链link_clusters推荐由 Client 单侧发起是否作为 Server 与角色 Prompt/Decoder 无关设置listen_ip_info标识端口监听即为 Server 端。返回值为二元组(LLMStatusCode, List[LLMStatusCode])分别表示接口返回值与每个集群的建链结果。约束包括建议超时时间配置 200ms 以上TLS 开启时建议 2000ms 以上可用hccn_tool [-i %d] -tls -g [host]查询 TLS 状态调用前需提前注册所有内存否则建链后注册不支持远端访问。双边建链link通过建立通信域方式建链需要rank_table文件通信域内节点数量最大支持 4通信域数量建议不超过 16、最大 512最多支持 16 条链路并发建链超过 16 条底层排队。unlink为对应的断链接口query_register_mem_status配合link查询注册内存状态。Ascend 950PR/Ascend 950DT 不支持link、unlink和query_register_mem_status。建链数量过多存在内存 OOM 及 KV Cache 传输性能风险使用集合通信通信域方式建链时允许的最大通信数量为 512使用 HixlCS 能力local_comm_res配置version为1.3建链时没有链路上限限制。容器与网络约束容器场景若未配置local_comm_res或配置为空需在容器内映射/etc/hccn.conf文件或确保默认路径/usr/local/Ascend/driver/tools下存在hccn_tool两者都不满足时需将hccn_tool所在路径配置到PATH中export PATH$PATH:{hccn_tool_install_path}。使用 Device RoCE 场景时同一通信集群内 Device RoCE 地址配置需保持一致不支持 IPv6-only 节点与 IPv4/IPv6 双栈节点混合接入约束适用于 Atlas A2 与 Atlas A3 训练/推理系列产品。更进一步接口参考与示例代码的完整地图接口参考Pythondocs/zh/api/python/README.md 汇总了LLMDataDist、LLMConfig、CacheManager、Cache、LLMRole、LLMClusterInfo、CacheDesc、CacheKey、BlocksCacheKey、TransferConfig、LLMStatusCode等全部组件文档接口约束与错误码处理可查阅 docs/zh/api/python/LLMStatusCode.md。链路管理与 KV Cache 管理的接口功能与伪代码示例见 docs/zh/guide/python/functions.md其中包含一般 Cache 传输register_cache/pull_cache/transfer_cache_async与 Blocks Cache 传输register_blocks_cache/pull_blocks/push_blocks两套完整示例。底层实现参考LLM-DataDist 的初始化与链路管理实现在 src/llm_datadist/llm_datadist_v2.cc缓存管理实现在 src/llm_datadist/cache_mgr/cache_manager.cc传输后端抽象位于 src/llm_datadist/transfer_engineHIXL 传输引擎实现在 src/llm_datadist/transfer_engine/hixl_transfer_engine.cc。更多完整可运行样例除本仓库 examples/python/llm_datadist 目录外也可在配套版本的examples/python目录中获取更多代码样例。结语以 docs/zh/guide/python/quick_start.md 为主线本文完整还原了在推理框架中使能 LLM-DataDist 的五步开发流程并补充了环境准备、关键环境变量、配置项约束与可运行样例。核心要点可概括为初始化init→ 建链link_clusters/link→ 注册内存register_cache/register_blocks_cache→ 传输 KV Cachepull_*/push_*/transfer_cache_async→ 断链与释放unlink_*/finalize。建议读者结合 examples/python/llm_datadist/pull_cache_sample.py 等样例先跑通双机最小闭环再参照 docs/zh/guide/python/functions.md 与 docs/zh/api/python/LLMDataDist.md 将接口迁移到自己的推理框架中。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考