企业官网建设流程全解析

HIXL 集成 Mooncake Store 零拷贝传输接口测试指南：batch_put/batch_get 接口详解与 Dummy Client 模式实践

【免费下载链接】hixlHIXL（Huawei 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 集成后，以下四个零拷贝相关接口的功能正确性：

⚠️关键前置条件：在调用任何零拷贝接口之前，必须先完成 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]

参数说明：

• keys（List[str]）：对象标识符列表，每个 key 唯一对应一个待写入对象；
• buffer_ptrs（List[int]）：内存地址列表，指向待写入数据的源 buffer；
• sizes（List[int]）：各 buffer 的字节大小列表；
• config（ReplicateConfig，可选）：副本复制配置，用于控制数据在集群内的复制策略。

返回值：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]

参数说明：

• keys（List[str]）：对象标识符列表；
• buffer_ptrs（List[int]）：内存地址列表，作为读取结果的目标 buffer；
• sizes（List[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]

参数说明：

• keys（List[str]）：对象标识符列表；
• all_buffer_ptrs（List[List[int]]）：内存地址的二维列表，all_buffer_ptrs[i]是第i个 key 关联的全部源 buffer 地址；
• all_sizes（List[List[int]]）：buffer 大小的二维列表，与地址一一对应；
• config（ReplicateConfig，可选）：副本复制配置。

返回值：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]

参数说明：

• keys（List[str]）：对象标识符列表；
• all_buffer_ptrs（List[List[int]]）：内存地址的二维列表，作为各 key 的读取目标；
• all_sizes（List[List[int]]）：buffer 大小的二维列表。

返回值：List[int]，每个操作实际读到的字节数列表（正数 = 成功，负数 = 错误）。

二、环境准备（已安装可跳过）

在执行用例前，需要完成以下两项基础环境准备：

1. 安装 CANN 包。样例的典型使用场景为root用户安装与使用，请确保torch_npu等依赖可用，因为 sample 依赖torch.npu.set_device()绑定设备（见 mooncake_sample_common.py 中的setup_environment）。

2. 编译安装 Mooncake Store。推荐版本v0.3.7.post2，编译时必须使用-DUSE_ASCEND_DIRECT=ON参数启用 HIXL 功能，否则示例中的昇腾零拷贝通路不可用。

三、执行测试用例

3.1 启动 mooncake_master

Mooncake 的元数据服务通过mooncake_master进程提供，集群内各 rank 通过 HTTP 元数据服务完成对象寻址。启动命令如下：

mooncake_master \ --enable_http_metadata_server=true \ --http_metadata_server_host=0.0.0.0 \ --http_metadata_server_port=8080

各参数含义：

• --enable_http_metadata_server：是否启用 HTTP 元数据服务；
• --http_metadata_server_host：监听地址，0.0.0.0表示对所有网卡开放；
• --http_metadata_server_port：HTTP 元数据服务端口，此处为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_port：PyTorch 分布式进程组（gloo 后端）的协调地址，示例中用于dist.barrier()同步；
• mooncake.store_ip：Mooncake Store 所在 IP；
• mooncake.port_start：Store 初始化端口，实际端口为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_url：gRPC 服务地址。

3.3 选择传输方式

默认传输方式由 run.sh 中的环境变量控制：

export ASCEND_GLOBAL_EVENT_ENABLE=1 export ASCEND_HOST_LOG_FILE_NUM=500 # export HCCL_INTRA_PCIE_ENABLE=1 # export HCCL_INTRA_ROCE_ENABLE=1 export MC_LOG_LEVEL=ERROR # export ASCEND_ENABLE_USE_FABRIC_MEM=1 python3 $@

传输链路选择规则如下：

• 默认走 HCCS，仅在机器内部有效，且只支持 D2D（设备到设备）传输；
• 非 D2D 传输（h2h/h2d/d2h）必须在run.sh中开启HCCL_INTRA_ROCE_ENABLE或ASCEND_ENABLE_USE_FABRIC_MEM：
  • 设置export HCCL_INTRA_ROCE_ENABLE=1选择 RDMA 作为传输方式（设置为0时机器内默认走 HCCS）；
  • 或者export ASCEND_ENABLE_USE_FABRIC_MEM=1启用 Fabric Memory 通路；
  • PCIe 模式通过export HCCL_INTRA_PCIE_ENABLE=1开启（默认注释状态）。
• 注意不要同时禁用 RoCE 和 PCIe，否则会出现以下解析报错：

[Parse] [IntraLinkType]only set HCCL_INTRA_ROCE_ENABLE, and the val is zero, pls set HCCL_INTRA_PCIE_ENABLE

3.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()定义）如下：

说明：某些参数也可以通过配置文件配置，但命令行传入的优先级更高。从 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_id=0 --schema="d2d" --rank=0

单机多卡与分布式集群场景：只需参考config_example.yaml创建配置文件，运行时通过config参数指定配置文件路径即可，例如：

bash run.sh batch_put_get_sample.py --config=config_example.yaml --device_id=0 --schema="d2d" --rank=0

从 batch_put_get_sample.py 的实现可以看到完整的调用链：每个 rank 构造keys（格式为hello_{rank}_{block_i}_{layer}）与对端 key（rank 取(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 批处理接口的两点差异：

1. 数据组织为二维：每个 key 关联 122 个 buffer（61 层 × 2 段，每段分别为 128 KiB 与 16 KiB），地址与大小均以List[List[int]]组织；
2. 副本配置显式化：示例中构造了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 Mode，Store 直接内嵌于应用进程）之外，样例还支持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_server=true \ --http_metadata_server_host=0.0.0.0 \ --http_metadata_server_port=8080

步骤 2：启动 Real Client 作为独立进程：

export ASCEND_ENABLE_USE_FABRIC_MEM=1 export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 mooncake_client \ --master_server_address=127.0.0.1:50051 \ --metadata_server=http://127.0.0.1:8080/metadata \ --protocol=ascend \ --port=54000 \ --host=127.0.0.1 \ --global_segment_size=5G

各参数含义：

• --master_server_address：Mooncake master 的 gRPC 地址，对应配置文件中的grpc_url；
• --metadata_server：HTTP 元数据服务地址，对应metadata_url；
• --protocol=ascend：使用昇腾传输协议（启用 HIXL 通路的前提）；
• --port=54000：Real Client 对外监听的端口，默认地址为127.0.0.1:54000；
• --host：Real Client 绑定地址；
• --global_segment_size=5G：Real Client 的全局内存段大小。

注意：ASCEND_ENABLE_USE_FABRIC_MEM=1与ASCEND_RT_VISIBLE_DEVICES需在启动前导出，且要确保后续传入的device id对 Real Client 进程可见（即位于ASCEND_RT_VISIBLE_DEVICES列表内）。

步骤 3：运行样例并添加--use_dummy参数：

bash run.sh batch_put_get_sample.py --device_id=0 --schema="d2d" --rank=0 --use_dummy

4.3 Dummy 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_SIZE（1 GiB）与LOCAL_BUFFER（20 MiB），随后调用store.setup_dummy(mem_pool_size, local_buffer_size, real_client_address)完成 Dummy Client 初始化）。

4.4 Dummy 模式的内存与 schema 约束

Dummy 模式在内存分配与传输类型上有两类需要注意的约束：

1. schema 限制：validate_schema()规定 Dummy 模式当前仅支持h2h与d2d两种 schema，其他取值（h2d/d2h）会直接抛出RuntimeError: Only h2h and d2d supported for Dummy/Real Clients now.
2. 内存来源差异：在嵌入式模式下，buffer 来自torch.ones(...).npu()或pin_memory=True的 CPU tensor，且地址会按HCCS_ALIGNMENT（2 MiB）对齐后再注册；而在 Dummy 模式下，代码会通过self.store.alloc_from_mem_pool(alloc_size)从 Store 的内存池中分配，并按FABRIC_ALIGNMENT（1 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_ENABLE=1或ASCEND_ENABLE_USE_FABRIC_MEM=1。

Q3：batch_get_into返回负数

返回值负数表示错误码，与batch_put_from的0 = 成功语义不同，batch_get_into以“实际读取字节数（正数）”表示成功。可结合日志中打印的错误码排查 key 是否存在、buffer 是否已注册、目标 rank 是否已完成写入。

Q4：Dummy 模式初始化失败

确认 Real Client 已以--protocol=ascend启动、--real_client_address（默认127.0.0.1:54000）可连通，且device_id在 Real Client 进程的ASCEND_RT_VISIBLE_DEVICES范围内。

Q5：schema校验失败

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 + 共享内存在不牺牲零拷贝能力的前提下完成架构拆分。

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