当前位置： 首页 > news >正文

HIXL LLM-DataDist接口

news 2026/5/9 15:34:56

LLM-DataDist接口

【免费下载链接】hixlHIXL（Huawei Xfer Library）是一个灵活、高效的昇腾单边通信库，面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

说明：针对Atlas A2 训练系列产品/Atlas A2 推理系列产品，仅支持Atlas 800I A2 推理服务器、A200I A2 Box 异构组件。

LlmDataDist构造函数

函数功能

创建LLM-DataDist对象。

函数原型

LlmDataDist(uint64_t cluster_id, LlmRole role)

参数说明

参数名输入/输出描述
cluster_id输入集群ID。LlmDataDist标识，在所有参与建链的范围内需要确保唯一。
role输入类型是LlmRole，该参数只用于标识当前角色，对传输过程无影响。

返回值

无

异常处理

无

约束说明

无

~LlmDataDist()

函数功能

LLM-DataDist对象析构函数。

函数原型

~LlmDataDist()

参数说明

无

返回值

无

异常处理

无

约束说明

无

Initialize

函数功能

初始化LLM-DataDist。

函数原型

Status Initialize(const std::map<AscendString, AscendString> &options)

参数说明

参数名输入/输出描述
options输入初始化参数值。具体请参考表1。

表 1options

参数名可选/必选描述
OPTION_LISTEN_IP_INFO可选配置当前option表示LLM-DataDist是Server，不配置表示Client。
当LLM-DataDist是Server时，需配置Host侧的IP地址和端口。
配置示例：如"192.168.1.1:26000"，不支持传入多个IP地址和端口。
OPTION_DEVICE_ID必选设置当前进程的Device ID，如"0"，不支持单进程多卡场景。
OPTION_SYNC_CACHE_WAIT_TIME可选kv相关操作的超时时间，单位：ms。不配置默认为1000ms。相关接口如下。

- PullKvCache
- PullKvBlocks
- PushKvCache
- PushKvBlocks
OPTION_LOCAL_COMM_RES可选配置本地通信资源信息，格式是json格式的字符串。配置方法如下：
仅需配置ranktable中当前llm datadist所使用Device信息，无需配置ranktable中的server_count和rank_id字段。该option可以不配置或配置为空串，为空将自动生成相关信息。该方法适用于如下型号：

- Atlas A2 训练系列产品/Atlas A2 推理系列产品

- Atlas A3 训练系列产品/Atlas A3 推理系列产品

Ascend 950PR/Ascend 950DT场景下，配置格式参考gitcode，同时需要使能OPTION_TRANSFER_BACKEND为hixl传输后端。该option必选，配置为空不会自动生成相关信息。
OPTION_TRANSFER_BACKEND可选配置LLM-DataDist使用的传输后端引擎，当前支持配置的后端为“hixl”。hixl传输后端使用方法如下：

- 初始化option需指定OPTION_LISTEN_IP_INFO：当配置使用hixl传输后端时，每个传输端既可作为client也可以作为server。

- 与对端发起传输前需要调用LinkLlmClusters发起建链。

如上表格中ranktable具体信息请参见《HCCL集合通信库用户指南》。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：成功
  • LLM_PARAM_INVALID：参数错误
  • 其他：失败

异常处理

无

约束说明

需要和Finalize配对使用，初始化成功后，任何退出前都需要调用Finalize保证资源释放，否则会出现资源释放顺序不符合预期而导致问题。

Finalize

函数功能

LLM-DataDist的资源释放函数。

函数原型

void Finalize()

参数说明

无

调用示例

请参考样例运行。

返回值

无

异常处理

无

约束说明

  • 需要和Initialize配对使用。
  • 当增量集群从全量集群拉取KV的时候，需要保证全量集群在增量集群完成同步KV数据之后才调用该接口，否则会出现失败。
  • 当全量集群在同步KV数据到增量集群的过程中，需要保证增量集群在全量集群完成同步KV数据之后调用该接口，否则会出现失败。
  • 该接口不能和其他接口并发调用。

SetRole

函数功能

设置LLM-DataDist的角色。

函数原型

Status SetRole(LlmRole role, const std::map<AscendString, AscendString> &options = {})

参数说明

参数名输入/输出描述
role输入角色类型，类型为LlmRole。
options输入设置角色的参数，当前支持的参数请参见表1。(#table1987921348)。

表 1配置项

配置项可选/必选描述
OPTION_LISTEN_IP_INFO可选- 当LLM-DataDist初始化是Client时，如果需要切换为Server，则配置该option为侦听的Host的IP地址和端口，配置示例："192.168.1.1:26000"。否则不需要配置。
- 当LLM-DataDist初始化是Server时，若不配置该option，则表示切换为Client。若配置了该option，则表示当前仍是Server，如果配置的端口号与初始化不一致，以当前配置为准。配置示例："192.168.1.1:26001"。
- 该配置项指定hixl传输后端时，不支持通过SetRole变更侦听端口。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：设置角色成功
  • LLM_PARAM_INVALID：参数错误
  • LLM_EXIST_LINK：存在残留链路资源
  • 其他：失败

异常处理

无

约束说明

使用前需与当前DataDist的链路进行断链。

LinkLlmClusters

函数功能

在LlmDataDist之间执行建链，Client端调用。

函数原型

Status LinkLlmClusters(const std::vector<ClusterInfo> &clusters, std::vector<Status> &rets, int32_t timeout_in_millis = 1000)

参数说明

参数名输入/输出描述
clusters输入需要建链的集群信息。类型为ClusterInfo。需要配置ClusterInfo中的remote_cluster_id和remote_ip_infos信息，若Initialize(LlmDataDist)未指定OPTION_LOCAL_COMM_RES, 需额外配置local_ip_infos，每个ClusterInfo的local_ip_infos和remote_ip_infos仅支持配置一个ip_info。
rets输出每个cluster建链结果。
timeout_in_millis输入建链超时时间，单位ms。默认1000ms。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：只有所有clusters建链成功，接口才会返回成功。
  • 其他：建链失败，需要查看rets每个cluster的建链结果。

异常处理

  • LLM_ALREADY_LINK：当前的cluster已经和远端cluster建立了链接。
  • LLM_LINK_FAILED：建链失败。

约束说明

  • 调用该接口前，需要先在Client和Server调用Initialize接口完成初始化。

  • 允许创建的最大通信数量=512，建链数量过多存在内存OOM及KV Cache传输的性能风险。该约束支持的型号如下：
    - Atlas A2 训练系列产品/Atlas A2 推理系列产品
    - Atlas A3 训练系列产品/Atlas A3 推理系列产品

  • 建议超时时间配置为200ms以上。如果TLS处于开启状态，建议超时时间配置为2000ms以上。查询TLS状态可以使用如下命令：

    hccn_tool [-i %d] -tls -g [host]

  • 调用该接口前Client和Server需提前注册所有内存，否则建链后注册不支持远端访问。

  • 容器场景若未配置OPTION_LOCAL_COMM_RES或配置为空，需在容器内映射“/etc/hccn.conf”文件或者确保默认路径“/usr/local/Ascend/driver/tools”下存在hccn_tool，如果两者都不能满足，则需要用户将hccn_tool所在路径配置到PATH中。配置实例如下，hccn_tool_install_path表示hccn_tool所在路径。该约束支持的型号如下：
    - Atlas A2 训练系列产品/Atlas A2 推理系列产品
    - Atlas A3 训练系列产品/Atlas A3 推理系列产品

    export PATH=$PATH:{hccn_tool_install_path}

UnlinkLlmClusters

函数功能

在LlmDataDist之间执行断链。

函数原型

Status UnlinkLlmClusters(const std::vector<ClusterInfo> &clusters, std::vector<Status> &rets, int32_t timeout_in_millis = 1000, bool force_flag = false)

参数说明

参数名输入/输出描述
clusters输入需要断链的cluster信息。类型为ClusterInfo。
rets输出每个cluster断链结果。
timeout_in_millis输入断链超时时间，单位ms。
force_flag输入是否为强制断链。默认为否。
强制断链仅强制拆除本端链接，所以两端都要调用。
非强制断链在Client端发起，不存在故障时两端链路都会拆除。但在存在链路故障时还需要在Server端发起调用强制断链，耗时长。

调用示例

请参考样例运行。

返回值

  • SUCCESS：只有所有clusters断链成功，接口才会返回成功。
  • 其他：执行断链失败，需要查看rets每个cluster的断链结果。

异常处理

LLM_UNLINK_FAILED：断链失败。

约束说明

调用该接口前，需要先调用Initialize接口完成初始化。

PullKvCache

函数功能

从远端节点拉取Cache到本地Cache。

函数原型

Status PullKvCache(const CacheIndex &src_cache_index, const Cache &dst_cache, uint32_t batch_index = 0U, int64_t size = -1, const KvCacheExtParam &ext_param = {})

参数说明

参数名称输入/输出取值说明
src_cache_index输入远端源Cache的索引。
dst_cache输入本地目的Cache。仅需指定调用RegisterKvCache返回的cache_id。
batch_index输入本地目的batch的下标。
size输入设置为>0的整数，表示要拉取的大小，单位字节。
或设置为-1，表示完整拉取。
默认为-1。
ext_param输入当前支持ext_param中src_layer_range的second与first的差值和dst_layer_range的second与first的差值一致。src_layer_range和dst_layer_range的first和second默认值都是-1，表示全部的层。取值范围都是[0, 最大可用层索引]，且first小于等于second。 最大可用层索引值的计算公式如下。
(CacheDesc::num_tensors / KvCacheExtParam::tensor_num_per_layer) - 1
当前支持tensor_num_per_layer取值范围是[1, 当前cache的tensor总数]，默认值为2。当src_layer_range或dst_layer_range取值为非默认值时， tensor_num_per_layer可以保持默认值，也可以输入其他值，输入其他值的时，tensor_num_per_layer的取值还需要被当前cache的tensor总数整除。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：成功
  • LLM_PARAM_INVALID：参数错误
  • LLM_NOT_YET_LINK：与远端cluster没有建链
  • LLM_TIMEOUT：拉取超时
  • LLM_KV_CACHE_NOT_EXIST：本地或远端KV Cache不存在
  • 其他：失败

约束说明

该接口调用之前，需要先调用LinkLlmClusters接口完成初始化。

PullKvBlocks

函数功能

通过block列表的方式，从远端节点拉取Cache到本地Cache。

函数原型

Status PullKvBlocks(const CacheIndex &src_cache_index, const Cache &dst_cache, const std::vector<uint64_t> &src_blocks, const std::vector<uint64_t> &dst_blocks, const KvCacheExtParam &ext_param = {})

参数说明

参数名称输入/输出取值说明
src_cache_index输入远端源Cache的索引。
dst_cache输入本地目的Cache。仅需指定调用RegisterKvCache返回的cache_id。
src_blocks输入远端源Cache的block index列表。
dst_blocks输入本地目的Cache的block index列表。
ext_param输入当前支持ext_param中src_layer_range的second与first的差值和dst_layer_range的second与first的差值一致。src_layer_range和dst_layer_range的first和second默认值都是-1，表示全部的层。取值范围都是[0, 最大可用层索引]，且first小于等于second。 最大可用层索引值的计算公式如下。
(CacheDesc::num_tensors / KvCacheExtParam::tensor_num_per_layer) - 1
当前支持tensor_num_per_layer取值范围是[1, 当前cache的tensor总数]，默认值为2。当src_layer_range或dst_layer_range取值为非默认值时， tensor_num_per_layer可以保持默认值，也可以输入其他值，输入其他值的时，tensor_num_per_layer的取值还需要被当前cache的tensor总数整除。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：成功
  • LLM_PARAM_INVALID：参数错误
  • LLM_NOT_YET_LINK：与远端cluster没有建链
  • LLM_TIMEOUT：拉取超时
  • LLM_KV_CACHE_NOT_EXIST：远端KV Cache不存在
  • 其他：失败

约束说明

该接口调用之前，需要先调用LinkLlmClusters接口完成初始化。

PushKvCache

函数功能

推送Cache到远端节点。

函数原型

Status PushKvCache(const Cache &src_cache, const CacheIndex &dst_cache_index, uint32_t src_batch_index = 0U, int64_t size = -1, const KvCacheExtParam &ext_param = {});

参数说明

参数名称输入/输出取值说明
src_cache输入本地目的Cache。仅需指定调用RegisterKvCache返回的cache_id。
dst_cache_index输入远端目的Cache的索引。
src_batch_index输入本地源batch的下标。
size输入当前只支持默认值-1。
ext_param输入当前支持ext_param中src_layer_range的second与first的差值和dst_layer_range的second与first的差值一致。src_layer_range和dst_layer_range的first和second默认值都是-1，表示全部的层。取值范围都是[0, 最大可用层索引]，且first小于等于second。 最大可用层索引值的计算公式如下。
(CacheDesc::num_tensors / KvCacheExtParam::tensor_num_per_layer) - 1
当前支持tensor_num_per_layer取值范围是[1, 当前cache的tensor总数]，默认值为2。当src_layer_range或dst_layer_range取值为非默认值时， tensor_num_per_layer可以保持默认值，也可以输入其他值，输入其他值的时，tensor_num_per_layer的取值还需要被当前cache的tensor总数整除。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：成功
  • LLM_PARAM_INVALID：参数错误
  • LLM_NOT_YET_LINK：与远端cluster没有建链
  • LLM_TIMEOUT：推送超时
  • LLM_KV_CACHE_NOT_EXIST：本地或远端KV Cache不存在
  • 其他：失败

约束说明

该接口调用之前，需要先调用LinkLlmClusters接口完成初始化。

PushKvBlocks

函数功能

通过block列表的方式，推送Cache到远端节点。

函数原型

Status PushKvBlocks(const Cache &src_cache, const CacheIndex &dst_cache_index, const std::vector<uint64_t> &src_blocks, const std::vector<uint64_t> &dst_blocks, const KvCacheExtParam &ext_param = {});

参数说明

参数名称输入/输出取值说明
src_cache输入本地目的Cache。仅需指定调用RegisterKvCache返回的cache_id。
dst_cache_index输入远端目的Cache的索引。
src_blocks输入源Cache的block index列表。
dst_blocks输入目的Cache的block index列表。
ext_param输入当前支持ext_param中src_layer_range的second与first的差值和dst_layer_range的second与first的差值一致。src_layer_range和dst_layer_range的first和second默认值都是-1，表示全部的层。取值范围都是[0, 最大可用层索引]，且first小于等于second。 最大可用层索引值的计算公式如下。
(CacheDesc::num_tensors / KvCacheExtParam::tensor_num_per_layer) - 1
当前支持tensor_num_per_layer取值范围是[1, 当前cache的tensor总数]，默认值为2。当src_layer_range或dst_layer_range取值为非默认值时， tensor_num_per_layer可以保持默认值，也可以输入其他值，输入其他值的时，tensor_num_per_layer的取值还需要被当前cache的tensor总数整除。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：成功
  • LLM_PARAM_INVALID：参数错误
  • LLM_NOT_YET_LINK：与远端cluster没有建链
  • LLM_TIMEOUT：推送超时
  • LLM_KV_CACHE_NOT_EXIST：本地或远端KV Cache不存在
  • 其他：失败

约束说明

该接口调用之前，需要先调用LinkLlmClusters接口完成初始化。

RegisterKvCache

函数功能

注册本地KV Cache内存。

函数原型

Status RegisterKvCache(const CacheDesc &cache_desc, const std::vector<uint64_t> &addrs, const RegisterCfg &cfg, int64_t &cache_id);

参数说明

参数名称输入/输出取值说明
cache_desc输入本地Cache的描述信息。
addrs输入本地Cache的地址。地址个数不超过240。
cfg输入预留参数。
cache_id输出注册的Cache的ID。可用于后续调用传输kv接口时构造Cache。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：成功
  • 其他：失败

约束说明

需要在Initialize接口初始化完成后调用。

当HDK版本低于25.5.0时，最大注册20GB的Host内存。当HDK版本大于等于25.5.0时，最大注册1TB的host内存。注册内存越大，占用的OS内存越多。该约束支持的型号如下：

  • Atlas A2 训练系列产品/Atlas A2 推理系列产品
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品

UnregisterKvCache

函数功能

解除注册本地KV Cache内存。

函数原型

Status UnregisterKvCache(int64_t cache_id);

参数说明

参数名称输入/输出取值说明
cache_id输入本地注册生成的cache ID。若指定的cache_id不存在默认返回成功。

调用示例

请参考样例运行。

返回值

  • LLM_SUCCESS：成功
  • 其他：失败

约束说明

调用该接口前，需要先调用Initialize接口完成初始化。cache_id必须为RegisterKvCache接口返回的值。

【免费下载链接】hixlHIXL（Huawei Xfer Library）是一个灵活、高效的昇腾单边通信库，面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

http://www.jsqmd.com/news/783733/

相关文章：

  • C++ ONNX Runtime 实战：为什么我的 session-＞Run 在跨函数调用时就崩溃了？
  • CANN/AMCT OFMR大模型量化
  • OpenClaw爬虫框架实战：从Awesome清单到自动化数据采集系统构建
  • 国内主流氯化镁生产厂家综合实力排行及选型指南 - 奔跑123
  • ngx_close_accepted_connection
  • 别再画丑图了！用Mermaid的gitGraph在Markdown里画专业Git分支图（附VSCode插件配置）
  • 基于OpenClaw构建多AI智能体协作平台：从数字生命蒸馏到理想国决策
  • 告别粘连字符！用Halcon的partition_dynamic算子精准分割OCR区域（附完整代码）
  • AI音乐生成技术解析：从符号与音频生成到混合模型实战
  • 向量引擎、deepseek v4、GPT Image 2、api key：Agent 时代最值钱的不是模型，是会调度的人
  • 外资阀门品牌2026市场介绍：米勒（Miller） - 米勒阀门
  • 基于微环谐振器的光子AI推理加速器：原理、设计与挑战
  • CANN算子测试竞赛中山大学软工小队提交
  • CANN/pypto lt函数API文档
  • 如何免费获取网盘高速下载：LinkSwift 九大平台直链解析终极指南
  • AI水下目标检测：从传统图像处理到深度学习部署实战
  • 工业盐技术选型指南：优质厂家的核心筛选维度 - 奔跑123
  • 别再只会用ref_table了！ABAP ALV里给自定义字段加F4搜索帮助的完整流程（附代码）
  • 深入SplaTAM代码：手把手解析3D高斯溅射（3DGS）如何与SLAM框架在Python/CUDA层协同工作
  • CANN/AMCT HiFloat8量化算法
  • 2026 全国节能建筑围护材料优质厂家 TOP5 榜单——聚焦聚氨酯复合板、聚氨酯封边岩棉夹芯板、聚氨酯夹芯板全国供应商 - 深度智识库
  • 2026年原创视频素材平台评测：国内项目与海外素材库的选型记录 - Fzzf_23
  • Ubuntu SCP传文件总失败？从ifconfig查IP到防火墙设置，保姆级排错指南
  • CANN LJForceFused算子测试报告
  • CANN/hcomm 算法分析器工具指南
  • CANN/pto-isa标量算术操作
  • 从C语言到机器码：用RV32I指令集手写一个简单的加法函数（附完整汇编代码）
  • 2026年原创视频素材平台清单：个人、企业和专业团队适用 - Fzzf_23
  • DAO治理自动化引擎：tomorrowDAO-skill架构解析与安全实践
  • CANN ops-math安全声明