执行摘要

此 PR 为 MooncakeStoreConnector 添加了磁盘层 KV 卸载支持，引入 standalone-store 模式将 CPU 池和 SSD 分片独立到外部进程，并完善了配置验证、预算管理和运行时可观测性。修改涉及 5 个文件，新增 ~1385 行，已在 4×GB200 节点上端到端验证。

功能与动机

基于 PR #40900 的 MooncakeStoreConnector 允许将 KV 缓存卸载到 CPU 内存，但 CPU 内存仍然有限。此 PR 利用 Mooncake 的 DirectIO（io_uring）路径，将 KV 缓存进一步卸载到本地 NVMe SSD，从而在不增加 GPU 或 CPU 内存的情况下大幅扩展有效缓存容量。PR body 中提供了完整的架构图和在 4×GB200 节点上 Qwen3-8B 的验证数据（49.6 GB 从 SSD 回读，0 失败 key）。

实现拆解

1. 配置扩展与验证：MooncakeStoreConfig 新增 mode（embedded/standalone-store）和 enable_offload 字段，__post_init__ 执行双向约束（例如 standalone-store 要求 global_segment_size==0）。

2. 磁盘卸载分片路径：KVCacheStoreRecvingThread 中新增三条核心逻辑：

   • 预算计算：_estimate_disk_offload_staging_bytes 和 _get_usable_disk_offload_buffer_budget_bytes 基于 DirectIO 对齐要求计算 staging 需求。
   • 分片拆分：_split_disk_offload_load_batches 将超过预算的 key 列表拆分为多个小批次。
   • 响应分类：_classify_replica_tier / _get_replica_tiers_by_key 按 memory/disk 层级分类 replica，配合 _call_replica_predicate 决定是否发起请求。

3. RDMA 设备选择：新增 rdma_utils.py，提供 normalize_string_override、get_current_physical_gpu_index、get_configured_preferred_segment 和 get_configured_worker_rnic。后者支持逗号分隔的设备名称列表，根据当前物理 GPU 索引选择合适的 RNIC，避免多 rank 共享同一网卡导致的带宽争用。

4. 环境变量注册：envs.py 新增 4 个环境变量：VLLM_MOONCAKE_STORE_TIER_LOG（控制 tier 摘要日志）、VLLM_MOONCAKE_DISK_STAGING_USABLE_RATIO（DirectIO 预算利用率）、MOONCAKE_PREFERRED_SEGMENT（首选 owner segment）和 MOONCAKE_REQUESTER_LOCAL_HOSTNAME（覆盖注册 hostname）。

5. 测试与文档：test_mooncake_store_worker.py 新增 ~30 个测试，覆盖磁盘卸载分片、配置校验矩阵、RNIC 选择、tier 日志输出。文档 mooncake_store_connector_usage.md 新增完整的磁盘卸载章节，包含 mooncake_master、mooncake_client 和 vLLM 的配置示例。

MooncakeStoreConfig 配置验证（worker.py）

@dataclass
class MooncakeStoreConfig:
    """MooncakeDistributedStore 配置。
    mode: embedded（默认）表示每个 rank 贡献 CPU 内存；
          standalone-store 表示 rank 贡献 0，由外部 mooncake_client 拥有内存和 SSD。
    """
    metadata_server: str
    master_server_address: str
    protocol: str
    device_name: str
    mode: MooncakeMode = "embedded"
    global_segment_size: int = DEFAULT_GLOBAL_SEGMENT_SIZE
    local_buffer_size: int = DEFAULT_LOCAL_BUFFER_SIZE
    enable_offload: bool = False
​
    def __post_init__(self) -> None:
        if self.mode not in ("embedded", "standalone-store"):
            raise ValueError(f"unknown Mooncake mode: {self.mode!r}")
        if self.local_buffer_size <= 0:
            raise ValueError("local_buffer_size must be > 0")
        if self.mode == "embedded" and self.global_segment_size == 0:
            raise ValueError("embedded mode requires global_segment_size > 0")
        if self.mode == "standalone-store" and self.global_segment_size != 0:
            raise ValueError("standalone-store mode requires global_segment_size == 0")

磁盘卸载预算计算（worker.py）

import math
​
_DIRECT_IO_ALIGNMENT = 4096
_DIRECT_IO_PADDING_BYTES = 8192
​
def _align_up(value: int, alignment: int) -> int:
    """向上对齐到 alignment 的整数倍。"""
    return (value + alignment - 1) // alignment * alignment
​
def _estimate_disk_offload_staging_bytes(size_list: list[int]) -> int:
    """估算从磁盘加载 size_list 中所有块所需的 staging 缓冲区总字节数。
​
    Mooncake 的 DirectIO AllocateBatch 要求每个块对齐到 4096，
    并且每个块额外附加 8192 的填充。
    """
    return sum(
        _align_up(size, _DIRECT_IO_ALIGNMENT) + _DIRECT_IO_PADDING_BYTES
        for size in size_list
    )

RNIC 选择逻辑（rdma_utils.py）

def _get_explicit_worker_rnic(device_list: str) -> str:
    """根据逗号分隔的设备列表和当前物理 GPU 索引选择 RNIC。"""
    entries = [entry.strip() for entry in device_list.split(",")]
    if any(not entry for entry in entries):
        raise ValueError("device_name contains an empty RDMA device entry")
    if len(entries) == 1:
        return entries[0]
​
    gpu_index = get_current_physical_gpu_index()
    if gpu_index is None:
        raise RuntimeError("could not determine local physical GPU index")
    if gpu_index >= len(entries):
        raise ValueError(
            f"device list does not cover local GPU {gpu_index}: {device_list}"
        )
    device_name = entries[gpu_index]
    logger.info(
        "Mooncake selected worker RNIC %s for local GPU %s",
        device_name,
        gpu_index,
    )
    return device_name

评论区精华

• 正确性风险：gemini-code-assist 警示“当单个 key 的 staging 预算不足以一次性加载时，标记请求完成将导致消费者读取无效数据”，指出这是一个可能导致静默数据损坏的严重问题。
• IPC 隔离：gemini-code-assist 和 chatgpt-codex-connector 均指出用 hostname 替代 uid 破坏了多用户环境下的 IPC 隔离。
• 布尔解析陷阱：chatgpt-codex-connector 发现 bool(enable_offload) 会把 "false" 字符串解析为 True，建议严格解析。
• 命名改进：ivanium 建议将模式名称 real-client/owner-client 改为 embedded/standalone-store，此建议已在第二版 commit 中被采纳。

风险与影响

• 静默数据损坏：若 DirectIO 预算小于单个最大 key，加载路径可能无声跳过，需确保预算下限。修复已在第二版 commit 中通过增加断言缓解。
• 多用户 IPC 冲突：get_zmq_rpc_path_lookup 中移除 uid 的改动在 review 后已修复。
• 配置语义：enable_offload 的布尔解析已改为严格类型检查。
• 用户迁移成本：现有用户需要更新 mooncake_config.json 添加 mode 和 enable_offload 字段，但默认为 embedded 和 false，向后兼容。

关联脉络

• PR #40900：此 PR 的基础，首次引入 MooncakeStoreConnector（仅 CPU）。当前 PR 在其上新增磁盘卸载和双模式拓扑，使 MooncakeStoreConnector 成为一个更完整的 KV 缓存分层存储方案。
• RFC Issue #38：PR body 中提及但未完成关联，可能与 KV 连接器的整体路线图相关。