HIXL 集成 Mooncake Store 零拷贝传输接口测试指南batch_put/batch_get 接口详解与 Dummy Client 模式实践【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读本文面向在 CANN 昇腾集群上使用 HIXL 对接 Mooncake Store 的开发者系统讲解四个零拷贝传输接口batch_put_from、batch_get_into、batch_put_from_multi_buffers、batch_get_into_multi_buffers的接口语义、注册前置条件、环境搭建与用例执行全流程。读完本文你将掌握如何在单机单卡、单机多卡与分布式集群场景下完成 D2D / H2H / H2D / D2H 四种传输 schema 的验证并能通过 Dummy Client 模式将存储客户端从应用进程中解耦实现 RPC 共享内存的零拷贝数据通路。本指南对应的示例代码位于仓库 examples/third_parties/mooncake_store/python 目录其中 README_en.md 是测试方案主体config_example.yaml、run.sh 以及四个 sample 脚本提供了可直接运行的配套实现。一、测试目标HIXL 对接 Mooncake Store 的零拷贝接口本测试用于验证 HIXL 与 Mooncake Store 集成后以下四个零拷贝相关接口的功能正确性接口功能单次处理对象数batch_put_from将多个本地 buffer 一次性写入远端存储一批 key / buffer / sizebatch_get_into从远端存储按 key 批量读取并写入本地 buffer一批 key / buffer / sizebatch_put_from_multi_buffers每个 key 对应多个 buffer 的批量写入一批 key × 每组多 bufferbatch_get_into_multi_buffers每个 key 对应多个 buffer 的批量读取一批 key × 每组多 buffer⚠️关键前置条件在调用任何零拷贝接口之前必须先完成 buffer 注册。需要先调用 Mooncake Store 的register_buffer()完成内存注册否则零拷贝通路无法建立。这一约束在示例基类 mooncake_sample_base.py 中体现为register_buffers()方法——它会对发送 tensor 与目标 tensor 分别执行self.store.register_buffer(addr, self.register_buffer_size)之后才把地址传入批处理接口。1.1 batch_put_from批量写入def batch_put_from(self, keys: List[str], buffer_ptrs: List[int], sizes: List[int], config: ReplicateConfig None) - List[int]参数说明keysList[str]对象标识符列表每个 key 唯一对应一个待写入对象buffer_ptrsList[int]内存地址列表指向待写入数据的源 buffersizesList[int]各 buffer 的字节大小列表configReplicateConfig可选副本复制配置用于控制数据在集群内的复制策略。返回值List[int]每个操作对应的状态码列表0表示成功负数表示错误。1.2 batch_get_into批量读取def batch_get_into(self, keys: List[str], buffer_ptrs: List[int], sizes: List[int]) - List[int]参数说明keysList[str]对象标识符列表buffer_ptrsList[int]内存地址列表作为读取结果的目标 buffersizesList[int]各 buffer 的字节大小列表。返回值List[int]每个操作实际读到的字节数列表正数表示成功负数表示错误。注意与batch_put_from不同成功时返回的是字节数而非0。1.3 batch_put_from_multi_buffers每 key 多 buffer 批量写入def batch_put_from_multi_buffers(self, keys: List[str], all_buffer_ptrs: List[List[int]], all_sizes: List[List[int]], config: ReplicateConfig None) - List[int]参数说明keysList[str]对象标识符列表all_buffer_ptrsList[List[int]]内存地址的二维列表all_buffer_ptrs[i]是第i个 key 关联的全部源 buffer 地址all_sizesList[List[int]]buffer 大小的二维列表与地址一一对应configReplicateConfig可选副本复制配置。返回值List[int]每个操作的状态码列表0 成功负数 错误。1.4 batch_get_into_multi_buffers每 key 多 buffer 批量读取def batch_get_into_multi_buffers(self, keys: List[str], all_buffer_ptrs: List[List[int]], all_sizes: List[List[int]]) - List[int]参数说明keysList[str]对象标识符列表all_buffer_ptrsList[List[int]]内存地址的二维列表作为各 key 的读取目标all_sizesList[List[int]]buffer 大小的二维列表。返回值List[int]每个操作实际读到的字节数列表正数 成功负数 错误。二、环境准备已安装可跳过在执行用例前需要完成以下两项基础环境准备安装 CANN 包。样例的典型使用场景为root用户安装与使用请确保torch_npu等依赖可用因为 sample 依赖torch.npu.set_device()绑定设备见 mooncake_sample_common.py 中的setup_environment。编译安装 Mooncake Store。推荐版本v0.3.7.post2编译时必须使用-DUSE_ASCEND_DIRECTON参数启用 HIXL 功能否则示例中的昇腾零拷贝通路不可用。三、执行测试用例3.1 启动 mooncake_masterMooncake 的元数据服务通过mooncake_master进程提供集群内各 rank 通过 HTTP 元数据服务完成对象寻址。启动命令如下mooncake_master \ --enable_http_metadata_servertrue \ --http_metadata_server_host0.0.0.0 \ --http_metadata_server_port8080各参数含义--enable_http_metadata_server是否启用 HTTP 元数据服务--http_metadata_server_host监听地址0.0.0.0表示对所有网卡开放--http_metadata_server_portHTTP 元数据服务端口此处为8080需与后续配置文件中的metadata_url保持一致。3.2 配置集群与 Mooncake Store 参数参考 config_example.yaml 创建运行时配置文件其完整结构如下# distribute group config distributed: enabled: true world_size: 2 master_addr: 127.0.0.1 master_port: 29500 # Mooncake store config mooncake: store_ip: 127.0.0.1 # Mooncake store IP address port_start: 12345 # port for mooncake store init as port_start rank metadata_url: http://127.0.0.1:8080/metadata # metadata service address grpc_url: 127.0.0.1:50051 # gRPC servcide address各字段与 config.py 中的解析逻辑一一对应distributed.enabled是否启用分布式集群distributed.world_size分布式集群配置的设备数distributed.master_addr/master_portPyTorch 分布式进程组gloo 后端的协调地址示例中用于dist.barrier()同步mooncake.store_ipMooncake Store 所在 IPmooncake.port_startStore 初始化端口实际端口为port_start rank。这一点在 mooncake_sample_base.py 的init_mooncake_store()中有明确实现port self.config.mooncake_store_port_start self.config.rank即每个 rank 使用不同的端口避免冲突mooncake.metadata_url元数据服务地址需与mooncake_master的 HTTP 端口匹配mooncake.grpc_urlgRPC 服务地址。3.3 选择传输方式默认传输方式由 run.sh 中的环境变量控制export ASCEND_GLOBAL_EVENT_ENABLE1 export ASCEND_HOST_LOG_FILE_NUM500 # export HCCL_INTRA_PCIE_ENABLE1 # export HCCL_INTRA_ROCE_ENABLE1 export MC_LOG_LEVELERROR # export ASCEND_ENABLE_USE_FABRIC_MEM1 python3 $传输链路选择规则如下默认走 HCCS仅在机器内部有效且只支持 D2D设备到设备传输非 D2D 传输h2h/h2d/d2h必须在run.sh中开启HCCL_INTRA_ROCE_ENABLE或ASCEND_ENABLE_USE_FABRIC_MEM设置export HCCL_INTRA_ROCE_ENABLE1选择 RDMA 作为传输方式设置为0时机器内默认走 HCCS或者export ASCEND_ENABLE_USE_FABRIC_MEM1启用 Fabric Memory 通路PCIe 模式通过export HCCL_INTRA_PCIE_ENABLE1开启默认注释状态。注意不要同时禁用 RoCE 和 PCIe否则会出现以下解析报错[Parse] [IntraLinkType]only set HCCL_INTRA_ROCE_ENABLE, and the val is zero, pls set HCCL_INTRA_PCIE_ENABLE3.4 运行测试的命令行参数在终端执行bash run.sh **.py其中**.py为待测接口对应的样例脚本例如测试batch_put_get接口时使用batch_put_get_sample.py测试多 buffer 接口时使用batch_put_get_multi_buffers_sample.py。通过命令行传入的执行参数由 mooncake_sample_common.py 中的create_parser()定义如下参数必填类型说明device_id是int当前进程所在的 NPU 设备schema否str当前测试的传输类型默认d2d取值必须为h2h、h2d、d2h、d2d不区分大小写代码内会统一lower()config否strYAML 配置文件路径。由于当前代码已删除硬编码的初始值可以选择修改代码或通过config参数传入rank是int当前进程的 rank是每个进程的唯一标识取值范围为[0, world_size - 1]world_size否int分布式集群配置的设备数distributed否bool是否启用分布式集群说明某些参数也可以通过配置文件配置但命令行传入的优先级更高。从 config.py 的parse_args()可以看到device_id与rank永远以命令行参数覆盖配置值distributed/world_size也仅在命令行显式给出时才覆盖配置文件。schema校验逻辑mooncake_sample_common.py 的validate_schema()会拒绝不在[h2h, h2d, d2h, d2d]范围内的取值直接抛出RuntimeError: Unsupported Schema。3.5 单机单卡执行示例D2D以单机环境单卡执行batch_put_get接口对应用例、进行 D2D 数据传输为例在启动完 mooncake_master 并完成配置或在代码中硬编码对应参数之后执行以下命令bash run.sh batch_put_get_sample.py --device_id0 --schemad2d --rank0单机多卡与分布式集群场景只需参考config_example.yaml创建配置文件运行时通过config参数指定配置文件路径即可例如bash run.sh batch_put_get_sample.py --configconfig_example.yaml --device_id0 --schemad2d --rank0从 batch_put_get_sample.py 的实现可以看到完整的调用链每个 rank 构造keys格式为hello_{rank}_{block_i}_{layer}与对端 keyrank 取(rank 1) % world_size以 144 KiB 为步长推进地址先执行batch_put_from写入再barrier()同步后执行batch_get_into读取对端数据最后通过_show_results打印每个 key 读取到的字节数或错误码。3.6 多 buffer 接口示例的关键差异batch_put_get_multi_buffers_sample.py 展示了与单 buffer 批处理接口的两点差异数据组织为二维每个 key 关联 122 个 buffer61 层 × 2 段每段分别为 128 KiB 与 16 KiB地址与大小均以List[List[int]]组织副本配置显式化示例中构造了ReplicateConfig并设置config.prefer_alloc_in_same_node True倾向于在同一节点内完成数据分配随后调用batch_put_from_multi_buffers(keys, all_local_addrs, all_sizes, config)与batch_get_into_multi_buffers(keys, all_remote_addrs, all_sizes, True)。四、Dummy Client 模式可选除了默认的嵌入式模式Embedded ModeStore 直接内嵌于应用进程之外样例还支持Dummy Client 模式将客户端连接到独立运行的 Real Client 进程。4.1 Dummy / Real Client 原理Real Client作为独立进程运行完整实现 Mooncake Store 的所有功能统一处理 RPC 通信、内存管理和数据传输Dummy Client轻量级包装器嵌入在应用进程中通过 RPC 将全部操作转发给 Real Client通信机制Dummy Client 与 Real Client 之间通过RPC 共享内存通信从而在应用与存储服务之间保持零拷贝的数据传输能力。这种架构的价值在于应用进程不再直接持有 Store 的内存管理逻辑只需维护一个轻量代理重型的内存池与传输管理被下沉到独立的 Real Client 进程中。4.2 使用 Dummy Client 模式单机实例步骤 1启动 Mooncake Master若尚未启动mooncake_master \ --enable_http_metadata_servertrue \ --http_metadata_server_host0.0.0.0 \ --http_metadata_server_port8080步骤 2启动 Real Client 作为独立进程export ASCEND_ENABLE_USE_FABRIC_MEM1 export ASCEND_RT_VISIBLE_DEVICES0,1,2,3,4,5,6,7 mooncake_client \ --master_server_address127.0.0.1:50051 \ --metadata_serverhttp://127.0.0.1:8080/metadata \ --protocolascend \ --port54000 \ --host127.0.0.1 \ --global_segment_size5G各参数含义--master_server_addressMooncake master 的 gRPC 地址对应配置文件中的grpc_url--metadata_serverHTTP 元数据服务地址对应metadata_url--protocolascend使用昇腾传输协议启用 HIXL 通路的前提--port54000Real Client 对外监听的端口默认地址为127.0.0.1:54000--hostReal Client 绑定地址--global_segment_size5GReal Client 的全局内存段大小。注意ASCEND_ENABLE_USE_FABRIC_MEM1与ASCEND_RT_VISIBLE_DEVICES需在启动前导出且要确保后续传入的device id对 Real Client 进程可见即位于ASCEND_RT_VISIBLE_DEVICES列表内。步骤 3运行样例并添加--use_dummy参数bash run.sh batch_put_get_sample.py --device_id0 --schemad2d --rank0 --use_dummy4.3 Dummy Client 模式额外参数参数说明--use_dummy启用 Dummy Client 模式--real_client_addressReal Client 地址默认127.0.0.1:54000需确保device id对 Real Client 进程可用--mem_pool_sizeDummy Client 内存池大小字节可选--local_buffer_sizeDummy Client 本地缓冲区大小字节可选从源码看这些参数在 mooncake_sample_common.py 中均有默认值--real_client_address默认127.0.0.1:54000--mem_pool_size与--local_buffer_size默认0此时在 mooncake_sample_base.py 的init_mooncake_dummy_store()中回退到默认的SEGMENT_SIZE1 GiB与LOCAL_BUFFER20 MiB随后调用store.setup_dummy(mem_pool_size, local_buffer_size, real_client_address)完成 Dummy Client 初始化。4.4 Dummy 模式的内存与 schema 约束Dummy 模式在内存分配与传输类型上有两类需要注意的约束schema 限制validate_schema()规定 Dummy 模式当前仅支持h2h与d2d两种 schema其他取值h2d/d2h会直接抛出RuntimeError: Only h2h and d2d supported for Dummy/Real Clients now.内存来源差异在嵌入式模式下buffer 来自torch.ones(...).npu()或pin_memoryTrue的 CPU tensor且地址会按HCCS_ALIGNMENT2 MiB对齐后再注册而在 Dummy 模式下代码会通过self.store.alloc_from_mem_pool(alloc_size)从 Store 的内存池中分配并按FABRIC_ALIGNMENT1 GiB对齐再通过torch.frombuffer将裸指针包装为 torch tensor——这正是零拷贝通路的体现数据直接在共享内存池中流转应用侧仅拿到地址视图。五、常见问题与排错指引Q1启动报错[Parse] [IntraLinkType]only set HCCL_INTRA_ROCE_ENABLE, and the val is zero, pls set HCCL_INTRA_PCIE_ENABLE传输方式配置冲突导致。HIXL 需要至少一条可用的机内链路HCCS / RoCE / PCIe不要同时禁用 RoCE 与 PCIe按第 3.3 节在run.sh中显式开启所需链路即可。Q2非 D2D 传输h2h / h2d / d2h失败默认的 HCCS 链路仅支持 D2D。执行非 D2D schema 前必须在run.sh中开启HCCL_INTRA_ROCE_ENABLE1或ASCEND_ENABLE_USE_FABRIC_MEM1。Q3batch_get_into返回负数返回值负数表示错误码与batch_put_from的0 成功语义不同batch_get_into以“实际读取字节数正数”表示成功。可结合日志中打印的错误码排查 key 是否存在、buffer 是否已注册、目标 rank 是否已完成写入。Q4Dummy 模式初始化失败确认 Real Client 已以--protocolascend启动、--real_client_address默认127.0.0.1:54000可连通且device_id在 Real Client 进程的ASCEND_RT_VISIBLE_DEVICES范围内。Q5schema校验失败schema仅支持h2h、h2d、d2h、d2d四种取值不区分大小写Dummy 模式下进一步限制为h2h与d2d。六、总结HIXL 与 Mooncake Store 的集成通过四个零拷贝批处理接口为昇腾集群提供了对象级数据读写能力batch_put_from/batch_get_into面向单 buffer 场景batch_put_from_multi_buffers/batch_get_into_multi_buffers面向每 key 多 buffer 的分片场景。使用前必须先register_buffer()并通过run.sh正确选择 HCCS / RoCE / Fabric Memory 传输链路单机单卡可直接命令行传参单机多卡与分布式集群通过config_example.yaml风格的配置文件驱动。需要将存储客户端与业务进程解耦时可采用 Dummy / Real Client 模式通过 RPC 共享内存在不牺牲零拷贝能力的前提下完成架构拆分。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考