Mooncake Store#

一个由原生 C++ Mooncake Store 连接器支持的 L2 适配器。使用 Mooncake 进行高性能分布式 KV Cache 存储，并支持 RDMA。

当 Mooncake 配置为 "protocol": "rdma" 时，LMCache 还必须有一个有效的连续 L1 内存区域可用。分布式存储管理器会在 MP 模式下自动将此 L1 内存描述符传递给适配器工厂。如果描述符缺失或无效，适配器创建将失败并抛出 ValueError，而不是默默地回退到非 RDMA 路径。

前提条件——启用 Mooncake 支持的构建：

Mooncake 扩展默认不构建。您必须显式启用它：

BUILD_MOONCAKE=1 pip install -e . --verbose

BUILD_MOONCAKE 环境变量控制编译：

BUILD_MOONCAKE=1: 启用 Mooncake C++ 扩展。
BUILD_MOONCAKE=0: 强制禁用（优先级最高），即使 MOONCAKE_INCLUDE_DIR 已设置。
未设置：回退到检查 MOONCAKE_INCLUDE_DIR 以保持向后兼容。如果 MOONCAKE_INCLUDE_DIR 也未设置，则跳过该扩展。

如果系统包含路径中未安装 Mooncake 头文件（例如，/usr/local/include），则必须显式指向它们：

BUILD_MOONCAKE=1 \
MOONCAKE_INCLUDE_DIR=/path/to/mooncake/include \
MOONCAKE_LIB_DIR=/path/to/mooncake/lib \
pip install -e . --verbose

LMCache 专有字段：

num_workers: 共享池的 C++ 工作线程数量（默认 4，必须大于 0）。
per_op_workers (dict[str, int], 可选)：将操作类型键映射到专用工作线程数的字典。支持的键：
- "lookup" — 用于 EXISTS 操作的线程。
- "retrieve" — 处理 GET / 加载操作的线程。
- "store" — 处理 SET / 放置操作的线程。
- "delete" — 用于 DELETE 操作的线程。
未在字典中列出的操作类型键将使用共享的 num_workers 池。无需设置所有键——您只需配置需要专用池的操作类型即可。

Mooncake 字段：

JSON 配置中的所有其他键（除了 type, num_workers, per_op_workers 和 eviction）都将原样转发给 Mooncake 的 setup_internal(ConfigDict)。有关可用的设置键（例如 local_hostname, metadata_server, master_server_addr, protocol, rdma_devices, global_segment_size），请参阅 Mooncake 文档。

配置示例：

# Shared pool (default)
--l2-adapter '{
  "type": "mooncake_store",
  "num_workers": 4,
  "local_hostname": "node01",
  "metadata_server": "http://localhost:8080/metadata",
  "master_server_addr": "localhost:50051",
  "protocol": "tcp",
  "local_buffer_size": "3221225472",
  "global_segment_size": "3221225472"
}'

# Per-operation pools (GET-heavy workload)
--l2-adapter '{
  "type": "mooncake_store",
  "per_op_workers": {
    "lookup": 2,
    "retrieve": 16,
    "store": 4
  },
  "local_hostname": "node01",
  "metadata_server": "http://localhost:8080/metadata",
  "master_server_addr": "localhost:50051",
  "protocol": "tcp"
}'

有关完整的 Mooncake 设置说明（主服务、元数据服务器等），请参阅 Mooncake 。

RDMA 注意事项：

protocol: "rdma" 需要一个有效的 LMCache L1 内存描述符。
使用 protocol: "rdma" 时，建议通过 --no-l1-use-lazy 禁用延迟 L1 分配，以便在 Mooncake 注册前完整分配 L1 缓冲区。
protocol: "tcp" 不需要 L1 预注册。
如果 Mooncake RDMA 初始化在适配器创建时失败，请验证 LMCache L1 内存是否已启用，并确保描述符具有非零指针和大小。