CANN/hixl HIXL接口文档

HIXL接口【免费下载链接】hixlHIXLHuawei 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 异构组件。针对Ascend 950PR/Ascend 950DT不支持SendNotify和GetNotifies。HIXL构造函数函数功能创建HIXL对象。函数原型Hixl()参数说明无返回值无异常处理无约束说明无~Hixl()函数功能HIXL对象析构函数。函数原型~Hixl参数说明无返回值无异常处理无Initialize函数功能初始化HIXL在调用其他接口前需要先调用该接口。函数原型Status Initialize(const AscendString local_engine, const std::mapAscendString, AscendString options)参数说明参数名输入/输出描述local_engine输入HIXL标识在所有参与建链的范围内需要确保唯一。如果是ipv4格式为host_ip:host_port或host_ip。如果是ipv6格式为[host_ip]:host_port或[host_ip]。不建议配置为回环IP在多个HIXL交互场景回环IP容易冲突。当设置host_port且host_port0时代表当前HIXL作为Server端需要对配置端口进行侦听。如果没设置host_port或者host_port0代表是Client不启动侦听。options输入初始化参数值。具体请参考如下表格。表 1optionsAtlas A2 训练系列产品/Atlas A2 推理系列产品/Atlas A3 训练系列产品/Atlas A3 推理系列产品参数名可选/必选描述OPTION_ENABLE_USE_FABRIC_MEM可选字符串取值EnableUseFabricMem。- 0不开启Fabric Mem模式- 1开启Fabric Mem模式此option适用于需要使用HCCS进行D2RH、RH2D传输的场景。说明集群场景下该参数在所有节点需要配置为相同的值。不支持该参数与OPTION_BUFFER_POOL同时配置。仅支持Atlas A3 训练系列产品/Atlas A3 推理系列产品。OPTION_BUFFER_POOL可选字符串取值BufferPool。在需要使用中转buffer进行传输的场景下:- RDMA注册Host内存大小受限时。- 多个小块内存传输(例如128K)需要使用中转传输提升性能时。可使用此option配置中转内存池的大小取值格式为$BUFFER_NUM:$BUFFER_SIZE系统默认会配置为4:8(单位MB)可以通过配置为0:0来关闭中转内存池在有并发的场景下建议增大$BUFFER_NUM个数, 另外所有使用的地方需要配置相同的值。不支持该参数与OPTION_ENABLE_USE_FABRIC_MEM同时配置。说明不配置该参数时存在如下约束。Atlas A2 训练系列产品/Atlas A2 推理系列产品仅支持Atlas 800I A2 推理服务器、A200I A2 Box 异构组件。该场景下Server采用HCCS传输协议时仅支持D2D。OPTION_RDMA_TRAFFIC_CLASS可选字符串取值RdmaTrafficClass。用于配置RDMA网卡的traffic class。和环境变量HCCL_RDMA_TC功能如同时配置当前option优先级更高未同时配置以配置的一方为准。取值范围为[0,255]且需要配置为4的整数倍默认值为132。OPTION_RDMA_SERVICE_LEVEL可选字符串取值RdmaServiceLevel。用于配置RDMA网卡的service level。和环境变量HCCL_RDMA_SL功能相同如同时配置当前option优先级更高未同时配置以配置的一方为准。取值范围为[0, 7]默认值为4。OPTION_GLOBAL_RESOURCE_CONFIG可选字符串取值GlobalResourceConfig。用于开启并配置全局资源配置。该参数配置示例和使用约束请参考表格下方OPTION_AUTO_CONNECT可选字符串取值AutoConnect。- 0不开启Auto Connect模式- 1开启Auto Connect模式说明- 开启该选项后可跳过建链直接进行传输。- 开启该选项后传输发生异常或对端销毁后自动清理异常链路对端销毁需要心跳机制来检测心跳间隔默认10s。OPTION_LOCAL_COMM_RES可选配置本地通信资源信息格式是json格式的字符串。配置方法如下仅需配置ranktable中当前llm datadist所使用Device信息无需配置ranktable中的server_count和rank_id字段ranktable具体信息请参见《HCCL集合通信库用户指南》。该option可以不配置或配置为空串为空将自动生成相关信息。如上表格中的环境变量请参考《环境变量参考》ranktable请参考《HCCL集合通信库用户指南》。OPTION_GLOBAL_RESOURCE_CONFIG的配置示例和使用约束如下对于Fabric Mem模式仅Atlas A3 训练系列产品/Atlas A3 推理系列产品支持该参数配置示例如下{ fabric_memory.max_capacity: 128, //虚拟内存池的大小。取值范围(0, 1024]之间的整数默认值64单位TB. fabric_memory.start_address: 40, //虚拟内存池起始地址。取值范围[40, 220]之间的整数默认值40单位TB. fabric_memory.task_stream_num: 1, //配置Fabric Mem模式下单个任务使用的流数量。取值范围[1, 8]之间的整数默认值4. }对于链路池机制该参数配置示例如下{ channel_pool.max_channel: 10, //最大的链路个数。取值范围(0, 512]之间的整数默认值512 channel_pool.high_waterline: 0.3, //触发链路销毁的高水位取值范围01之间的小数需要和channel_pool.low_waterline同时配置 channel_pool.low_waterline: 0.1 //触发链路销毁的低水位取值范围01之间小数并且小于高水位 }链路池工作时实际依据链路个数判断是否进行销毁如果当前链路个数已经达到高水位对应的链路个数则选择当前链路个数-低水位对应的链路个数 条链路进行销毁如存在正在传输的任务则不会销毁再建链。相关参数计算公式如下- 高水位线对应的链路个数max(1,static_castint32_t (channel_pool.max_channelchannel_pool.high_waterline))- 低水位线对应的链路个数max(1,static_castint32_t (channel_pool.max_channelchannel_pool.low_waterline))在上述配置示例中按照计算公式高水位对应的链路个数3低水位对应的链路个数1。每次建链前会检查当前HIXL内的链路是否达到3如果已经达到选择(当前链路个数-1 )条链路进行销毁如存在正在传输的任务则不会销毁再建链。当启用链路池机制时有如下注意事项- 集群内的所有Hixl Engine都需要配置OPTION_GLOBAL_RESOURCE_CONFIG。- 当调用TransferSync或TransferAsync接口时若不存在相关链路将执行建链操作。- 会增加传输和建链的额外开销可能导致性能下降。表 2optionsAscend 950PR/Ascend 950DT | 参数名 | 可选/必选 | 描述 | | --- | --- | --- | | OPTION_LOCAL_COMM_RES | 必选 | 配置本地通信资源信息格式是json格式的字符串。配置格式参考通信资源配置字段说明。配置为空不会自动生成相关信息。 | | OPTION_GLOBAL_RESOURCE_CONFIG | 可选 | 字符串取值GlobalResourceConfig。用于开启并配置全局资源格式为json格式的字符串字段说明参考全局资源配置字段说明。 |通信资源配置字段说明| 字段名 | 数据类型 | 必选/可选 | 说明 | 支持值/填写规则 | | ---- | ---- | ---- | ---- | ---- | | version | 字符串 | 必选 | 版本号 | 1.3 | | net_instance_id | 字符串 | 必选 | 当前超节点的唯一标识 | 每个超节点唯一即可 | | endpoint_list | 数组 | 必选 | 可以使用的通信设备列表 | - | | endpoint_list[].protocol | 字符串 | 必选 | 通信协议 | roce/ub_ctp/ub_tp/uboe | | endpoint_list[].comm_id | 字符串 | 必选 | 通信标识 | protocol为ub_ctp/ub_tp时填${eid}protocol为roce时填ipv4/ipv6网卡地址protocol为uboe时填device uboe网卡ip地址 | | endpoint_list[].placement | 字符串 | 必选 | 通信设备位置 | host/device | | endpoint_list[].plane | 字符串 | 可选 | 通信设备平面 | protocol为ub_ctp/ub_tp时设备区分平面则填写每个平面唯一如plane-a/plan-b | | endpoint_list[].dst_eid | 字符串 | 可选 | 与当前通信设备连接的对端通信设备的${eid} | protocol为ub_ctp时存在full-mesh直连对端则填写对端${eid} |全局资源配置字段说明| 字段名 | 数据类型 | 必选/可选 | 说明 | 支持值/填写规则 | | ---- | ---- | ---- | ---- | ---- | | comm_resource_config.protocol_desc | 字符串数组 | 可选 | 配置通信协议以及通信设备位置 | 当前仅支持[uboe:device]表示使用uboe协议通信设备在device当没有配置OPTION_LOCAL_COMM_RES或配置的OPTION_LOCAL_COMM_RES中endpoint_list为空时会自动生成uboe的endpoint信息否则配置项不起作用. |调用示例请参考样例运行。返回值SUCCESS成功PARAM_INVALID参数错误其他失败异常处理无约束说明需要和Finalize配对使用初始化成功后任何退出前都需要先调用Finalize保证资源释放否则会出现资源释放顺序不符合预期而导致问题。初始化前需要先调用aclrtSetDevice。Finalize函数功能HIXL资源清理函数。函数原型void Finalize()参数说明无调用示例请参考样例运行。返回值无异常处理无约束说明需要和Initialize配对使用。建议在调用Finalize前链路进行断链以及对注册的内存进行解注册。Server需要等所有Client完成断链后调用如果Server提前退出Client断链以及数据传输过程会发生报错。当Client需要操作Server端地址进行远端读写Server端需要等Client完成远端读写之后才调用该接口否则会出现失败。该接口不能和其他接口并发调用。RegisterMem函数功能注册内存地址。用于TransferSync调用指定本地内存地址和远端内存地址TransferSync指定的地址可以为注册的地址子集其中本地内存地址需在当前HIXL进行注册远端内存地址需要在远端HIXL进行注册。函数原型Status RegisterMem(const MemDesc mem, MemType type, MemHandle mem_handle)参数说明参数名输入/输出描述mem输入需要注册的内存的描述信息。类型为MemDesc。type输入需要注册的内存的类型。类型为MemType。mem_handle输出注册成功返回的内存handle, 可用于内存解注册。类型为MemHandle。调用示例请参考样例运行。返回值SUCCESS成功PARAM_INVALID参数错误其他失败异常处理无约束说明在调用Connect与对端建链之前需要完成所有local内存的注册。建议单个Hixl实例注册的内存个数不超过4K个。注册数量过多可能存在device OOM风险同时注册个数越多建链耗时越长过多易出现建链超时问题需用户根据业务场景自行管控内存注册数量和大小。当HDK版本低于25.5.0时最大注册20GB的Host内存。当HDK版本大于等于25.5.0时最大注册1TB的host内存。注册内存越大占用的OS内存越多。该约束支持的型号如下- Atlas A2 训练系列产品/Atlas A2 推理系列产品- Atlas A3 训练系列产品/Atlas A3 推理系列产品注册Host内存需使用“aclrtMallocHost”进行申请该接口申请的内存地址自动对齐。该约束支持的型号如下- Atlas A2 训练系列产品/Atlas A2 推理系列产品- Atlas A3 训练系列产品/Atlas A3 推理系列产品注册Device内存使用“aclrtMalloc”进行申请如通过HCCS传输则内存分配规则需配置为ACL_MEM_MALLOC_HUGE_ONLY。该接口需要和Initialize运行在同一个线程上如需切换线程调用该接口需要在Initialize所在线程调用“aclrtGetCurrentContext”获取context并在新线程调用“aclrtSetCurrentContext”设置context。Ascend 950PR/Ascend 950DT场景下使用host RoCE网卡当前不支持注册“aclrtMallocHost”申请出来的内存可使用malloc等方式。DeregisterMem函数功能解注册内存。函数原型Status DeregisterMem(MemHandle mem_handle)参数说明参数名输入/输出描述mem_handle输入调用RegisterMem接口注册内存返回的内存handle。调用示例请参考样例运行。返回值SUCCESS成功PARAM_INVALID参数错误其他失败。异常处理无约束说明调用该接口前需要先调用Disconnect将所有链路进行断链确保所有内存不再使用。该接口需要和Initialize运行在同一个线程上如需切换线程调用该接口需要在Initialize所在线程调用“aclrtGetCurrentContext”获取context并在新线程调用“aclrtSetCurrentContext”设置context。Connect函数功能与远端HIXL进行建链。函数原型Status Connect(const AscendString remote_engine, int32_t timeout_in_millis 1000)参数说明参数名输入/输出描述remote_engine输入远端HIXL的唯一标识。remote_engine对应的HIXL需要是同一个Server。timeout_in_millis输入建链的超时时间单位ms默认值1000。调用示例请参考样例运行。返回值SUCCESS成功PARAM_INVALID参数错误TIMEOUT建链超时ALREADY_CONNECTED重复建链其他失败异常处理无。约束说明需要在Client和Server的Initialize接口初始化完成后调用。允许创建的最大通信数量512建链数量过多存在内存OOM及KV Cache传输的性能风险。该约束支持的型号如下- Atlas A2 训练系列产品/Atlas A2 推理系列产品- Atlas A3 训练系列产品/Atlas A3 推理系列产品建议超时时间配置200ms以上。调用该接口前需提前注册所有本地以及远端内存否则建链后注册不支持远端访问。容器场景需在容器内映射“/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}该接口需要和Initialize运行在同一个线程上如需切换线程调用该接口需要在Initialize所在线程调用“aclrtGetCurrentContext”获取context并在新线程调用“aclrtSetCurrentContext”设置context。Disconnect函数功能与远端HIXL进行断链。函数原型Status Disconnect(const AscendString remote_engine, int32_t timeout_in_millis 1000)参数说明参数名称输入/输出取值说明remote_engine输入远端HIXL的唯一标识。timeout_in_millis输入断链的超时时间单位ms默认值1000。调用示例请参考样例运行。返回值SUCCESS成功PARAM_INVALID参数错误NOT_CONNECTED没有与对端创建链接其他失败约束说明调用该接口之前需要先调用Initialize接口完成初始化。该接口需要和Initialize运行在同一个线程上如需切换线程调用该接口需要在Initialize所在线程调用“aclrtGetCurrentContext”获取context并在新线程调用“aclrtSetCurrentContext”设置context。TransferSync函数功能与远端HIXL进行内存传输。函数原型Status TransferSync(const AscendString remote_engine, TransferOp operation, const std::vectorTransferOpDesc op_descs, int32_t timeout_in_millis 1000)参数说明参数名称输入/输出取值说明remote_engine输入远端HIXL的唯一标识。operation输入将远端内存读到本地或者将本地内存写到远端。op_descs输入批量操作的本地以及远端地址。timeout_in_millis输入传输的超时时间单位ms默认值1000。调用示例请参考样例运行。返回值SUCCESS成功PARAM_INVALID参数错误NOT_CONNECTED没有与对端创建链接TIMEOUT传输超时RESOURCE_EXHAUSTED资源耗尽其他失败约束说明调用该接口之前需要先调用Connect接口完成与对端的建链或者在HIXL初始化时开启了链路池机制通过配置options中的OPTION_GLOBAL_RESOURCE_CONFIG参数进行开启。该约束支持的型号如下- Atlas A2 训练系列产品/Atlas A2 推理系列产品- Atlas A3 训练系列产品/Atlas A3 推理系列产品该接口需要和Initialize运行在同一个线程上如需切换线程调用该接口需要在Initialize所在线程调用“aclrtGetCurrentContext”获取context并在新线程调用“aclrtSetCurrentContext”设置context。系统默认开启中转内存池在开启中转内存池情况下op_desc中本地内存和远端内存有一个未注册就会判断为需要走中转传输模式且没有注册过的内存判断为Host内存用户需保证地址合法。该约束支持的型号如下- Atlas A2 训练系列产品/Atlas A2 推理系列产品- Atlas A3 训练系列产品/Atlas A3 推理系列产品在中转传输模式下所有op_desc的传输类型需要相同举例所有的op_desc都是本地Host内存往远端Host内存写。该约束支持的型号如下- Atlas A2 训练系列产品/Atlas A2 推理系列产品- Atlas A3 训练系列产品/Atlas A3 推理系列产品在Fabric Mem传输模式下, 所有op_descs的传输类型需要相同系统会根据第一个op_desc的内存类型判定传输方向。该约束支持的型号如下- Atlas A3 训练系列产品/Atlas A3 推理系列产品TransferAsync函数功能与远端HIXL进行批量异步内存传输。函数原型Status TransferAsync(const AscendString remote_engine, TransferOp operation, const std::vectorTransferOpDesc op_descs, const TransferArgs optional_args, TransferReq req)参数说明参数名称输入/输出取值说明remote_engine输入远端HIXL的唯一标识。operation输入将远端内存读到本地或者将本地内存写到远端。op_descs输入批量操作的本地以及远端地址。optional_args输入可选参数预留。req输出请求的句柄用户查询传输的请求状态。调用示例//初始化客户端和服务端engine并完成链接 client_engine.TransferAsync(remote_engine, operation, op_descs, optional_args, req);返回值SUCCESS成功NOT_CONNECTED没有与对端创建链接RESOURCE_EXHAUSTED资源耗尽其他失败约束说明调用该接口之前存在如下约束需要先调用Connect接口完成与对端的建链。或者在HIXL初始化时开启了链路池机制通过配置options中的OPTION_GLOBAL_RESOURCE_CONFIG参数进行开启。该约束支持的型号如下- Atlas A2 训练系列产品/Atlas A2 推理系列产品- Atlas A3 训练系列产品/Atlas A3 推理系列产品该接口需要和Initialize运行在同一个线程上如需切换线程调用该接口需要在Initialize所在线程调用“aclrtGetCurrentContext”获取context并在新线程调用“aclrtSetCurrentContext”设置context。当前异步传输仅支持直传暂不支持中转传输默认直传。在Fabric Mem传输模式下, 所有op_descs的传输类型需要相同系统会根据第一个op_desc的内存类型判定传输方向。该约束支持的型号如下- Atlas A3 训练系列产品/Atlas A3 推理系列产品GetTransferStatus函数功能获取异步内存传输的状态。函数原型Status GetTransferStatus(const TransferReq req, TransferStatus status)参数说明参数名称输入/输出取值说明req输入请求的句柄通过调用TransferAsync产生。status输出传输状态枚举值如下。- WAITING- COMPLETED- TIMEOUT暂不支持- FAILED调用示例//初始化客户端和服务端engine并完成链接 Status transfer_status client_engine.TransferAsync(remote_engine, operation, op_descs, optional_args, req); //req是TransferAsync()的输出值使用这个请求句柄进行传输状态查询 Status query_status GetTransferStatus(req, status); //对传输状态进行检查判断传输是否完成 ...返回值SUCCESS成功PARAM_INVALID参数错误NOT_CONNECTED没有与对端创建链接其他失败约束说明调用该接口之前需要先调用Connect接口完成与对端的建链。该接口需要和Initialize运行在同一个线程上如需切换线程调用该接口需要在Initialize所在线程调用“aclrtGetCurrentContext”获取context并在新线程调用“aclrtSetCurrentContext”设置context。在调用TransferAsync接口进行异步传输后需要使用该接口查询对应请求状态如果查询状态是COMPLETED或FAILED将释放相关资源。该场景下不支持再次查询。异步传输时用户自行判断是否超时如果用户判断任务超时建议调用Disconnect接口销毁链路清理相关资源。异步传输任务失败后调用该接口查询的状态和接口返回状态都是FAILED。SendNotify函数功能向远端engine发送Notify信息。函数原型Status SendNotify(const AscendString remote_engine, const NotifyDesc notify, int32_t timeout_in_millis 1000)参数说明参数名称输入/输出取值说明remote_engine输入远端Hixl的唯一标识timeout_in_millis输入发送超时时间单位ms。notify输入要发送的Notify内容。内容中的notify_msg和name长度上限均为1024字符。调用示例无返回值SUCCESS成功其他失败约束说明调用该接口之前需要先调用Connect接口完成与对端的建链。该接口需要和Initialize运行在同一个线程上如需切换线程调用该接口需要在Initialize所在线程调用“aclrtGetCurrentContext”获取context并在新线程调用“aclrtSetCurrentContext”设置context。该接口不支持Ascend 950PR/Ascend 950DT。每条链路中最多存在4096条Notify需要确保远端Hixl及时调用GetNotifies接口消费Notify防止触发上限导致发送失败。GetNotifies函数功能获取当前Hixl内所有Server收到的Notify信息并清空已收到信息。函数原型Status GetNotifies(std::vectorNotifyDesc notifies)参数说明参数名称输入/输出取值说明notifies输入存放notify信息的vector。调用示例无返回值SUCCESS成功其他失败约束说明该接口不支持Ascend 950PR/Ascend 950DT。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考