GDS 后端#

警告

本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 LMCache MP 模式 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 二级 KV 存储。

概述#

该后端可以与任何文件系统配合使用，无论是本地的、远程的，还是带有基于 GDS 的优化的远程文件系统。远程文件系统允许多个 LMCache 实例无缝共享数据。GDS（GPU-Direct Storage）优化用于实现从显存到存储系统的零拷贝 I/O。支持 NVIDIA cuFile 和 AMD hipFile 进行 GPU 直接存储。

配置 LMCache GDS 后端的方法#

1. 环境变量：

# 256 Tokens per KV Chunk
export LMCACHE_CHUNK_SIZE=256
# Path to store files
export LMCACHE_GDS_PATH="/mnt/gds/cache"
# GDS Buffer Size in MiB
export LMCACHE_GDS_BUFFER_SIZE="8192"
# Disabling CPU RAM offload is sometimes recommended as the
# CPU can get in the way of GPUDirect operations
export LMCACHE_LOCAL_CPU=False
# Disk I/O Threads (default: 4, set to 0 to disable)
export LMCACHE_EXTRA_CONFIG='{"disk_io_threads": 8}'

2. 配置文件:

通过 LMCACHE_CONFIG_FILE=your-lmcache-config.yaml 传入

示例 config.yaml:

# 256 Tokens per KV Chunk
chunk_size: 256
# Disable local CPU
local_cpu: false
# Path to file system, local, remote or GDS-enabled mount
gds_path: "/mnt/gds/cache"
# GDS Buffer Size in MiB
gds_buffer_size: 8192
# Disk I/O Threads (default: 4, set to 0 to disable)
extra_config:
  disk_io_threads: 8

Disk I/O Thread Pool#

The backend uses a thread pool for parallel disk I/O. The thread pool is always enabled regardless of whether GDS APIs or POSIX fallback is used, so both code paths benefit from concurrent reads and writes.

The number of worker threads is controlled by extra_config.disk_io_threads (default: 4). Increase this on fast NVMe drives for higher parallelism. Set to 0 to disable the thread pool entirely.

Environment variable:

export LMCACHE_EXTRA_CONFIG='{"disk_io_threads": 8}'

YAML 配置：

extra_config:
  disk_io_threads: 8

备注

The deprecated gds_io_threads key is no longer supported. Use disk_io_threads instead.

多路径（多设备）支持#

当系统有多个 NVMe 驱动器时，可以通过在 gds_path 中指定以逗号分隔的路径列表来分配 GDS I/O。gds_path_sharding 选项控制每个 GPU 工作线程如何选择其路径。目前仅支持 "by_gpu"（默认），该选项根据设备索引（device_id % num_paths）选择路径，因此流量在驱动器之间均匀分配，无需手动固定。

为什么这有帮助： 单个 PCIe Gen 4 x4 NVMe 的最大速度约为 7 GB/s。使用四个驱动器时，聚合带宽可以达到约 28 GB/s，满足多 GPU 系统对 KV Cache 逐出和预取的需求。

环境变量：

export LMCACHE_GDS_PATH="/mnt/nvme0/cache,/mnt/nvme1/cache,/mnt/nvme2/cache,/mnt/nvme3/cache"
export LMCACHE_GDS_PATH_SHARDING="by_gpu"

YAML 配置：

gds_path: "/mnt/nvme0/cache,/mnt/nvme1/cache,/mnt/nvme2/cache,/mnt/nvme3/cache"
gds_path_sharding: "by_gpu"

在 4-GPU 节点上使用上述配置：

  • cuda:0 写入 /mnt/nvme0/cache

  • cuda:1 写入 /mnt/nvme1/cache

  • cuda:2 写入 /mnt/nvme2/cache

  • cuda:3 写入 /mnt/nvme3/cache

如果 GPU 的数量超过路径数量，则分配会循环（例如，cuda:4 映射回 /mnt/nvme0/cache）。单个路径（没有逗号）与之前的工作方式完全相同。

所有目录在启动时会自动创建。列表中的每个路径必须位于 GDS 配置所期望的文件系统上（例如，在使用 cuFile 时，所有路径都必须位于支持 GDS 的挂载点上）。

读取行为： 在启动时，后端会扫描 所有 配置的路径以查找先前存储的 KV Cache 条目，而不考虑 GPU 亲和性。这意味着一个写入亲和性为 /mnt/nvme0/cache 的 cuda:0 工作线程仍然会发现之前由 cuda:1 写入到 /mnt/nvme1/cache 的条目。然而，写入始终会发送到单个亲和性选择的路径。

Startup scan (read):   iterate ALL gds_paths → populate hot_cache
Runtime writes:        only the affinity path  (device_id % num_paths)
Runtime reads:         look up hot_cache first; on miss, check ALL
                       gds_paths on disk → load from whichever path
                       the entry lives on

GDS 缓冲区大小说明#

后端目前预先注册缓冲区空间以加速 GDS 操作。此缓冲区空间在显存中注册，因此在设置时应考虑 --gpu-memory-utilization 选项，例如来自 vllm 的选项。例如，对于通常具有 80GiB 显存的 H100，一个好的经验法则是从 8GiB 开始，并设置 --gpu-memory-utilization 0.85，然后根据您的工作流程进行微调。

使用 AMD hipFile#

备注

hipFile 是 alpha 版软件，仅在有限的硬件上进行了测试。有关完整的安装细节，请参见 hipFile 安装指南。

前提条件：

  • ROCm >= 7.2 和 amdgpu-dkms >= 30.20.1 （请参阅 ROCm 快速安装指南）

  • 支持的存储： 仅限本地 NVMe 驱动器

  • 支持的文件系统： ext4（以 data=ordered 挂载）和 xfs

  • 内核： CONFIG_PCI_P2PDMA 必须启用

快速安装（Ubuntu 24.04）：

sudo apt install libmount-dev wget

# Install nightly hipFile packages
wget https://github.com/ROCm/hipFile/releases/download/nightly/hipfile_0.2.0.70200-nightly.9999.24.04_amd64.deb
wget https://github.com/ROCm/hipFile/releases/download/nightly/hipfile-dev_0.2.0.70200-nightly.9999.24.04_amd64.deb
sudo dpkg -i hipfile-dev_0.2.0.70200-nightly.9999.24.04_amd64.deb hipfile_0.2.0.70200-nightly.9999.24.04_amd64.deb

您可以通过运行以下命令来验证 HIP 库和内核是否支持 AIS（AMD Infinity Storage）：

/opt/rocm/bin/ais-check

成功的输出将显示 Kernel P2PDMA support、HIP runtime 和 amdgpu 的值为 True。

LMCache 配置：

要使用 AMD hipFile 而不是 NVIDIA cuFile，请设置 GDS 后端：

环境变量：

export LMCACHE_GDS_BACKEND=hipfile

配置文件：

gds_backend: "hipfile"

注意：gds_buffer_size 配置用于 cuFile 和 hipFile 缓冲区。

设置示例#

前提条件：

  • 一台至少配备一个 GPU 的机器。您可以根据您的显存调整 vllm 实例的最大模型长度。

  • 一个挂载的文件系统。支持 GDS 的文件系统效果最佳。

  • vllm 和 lmcache 已安装 (安装指南)

  • Hugging Face 访问 meta-llama/Llama-3.1-8B-Instruct

export HF_TOKEN=your_hugging_face_token

步骤 1. 在您的文件系统挂载下创建缓存目录：

要查找系统中支持 GDS 的所有文件系统类型，请使用 NVIDIA 的 gdscheck：

sudo /usr/local/cuda-*/gds/tools/gdscheck -p

请向您的存储供应商咨询如何挂载远程文件系统。

（例如，如果您想使用支持 GDS 的 NFS 驱动程序，可以尝试修改过的 [NFS stack](https://vastnfs.vastdata.com/)，这是一个与任何标准 [NFS RDMA](https://datatracker.ietf.org/doc/html/rfc5532) 服务器兼容的开源驱动程序。将来会在这里添加更多特定于供应商的说明。）

在文件系统挂载下创建一个目录（这里的名称是任意的）：

mkdir /mnt/gds/cache

步骤 2. 启动一个启用文件后端的 vLLM 服务器：

创建一个名为 gds-backend.yaml 的 lmcache 配置文件

local_cpu: false
chunk_size: 256
gds_path: "/mnt/gds/cache"
gds_buffer_size: 8192
extra_config:
  disk_io_threads: 8

如果您不想使用配置文件，请取消注释前面三个环境变量，然后注释掉下面的 LMCACHE_CONFIG_FILE：

# LMCACHE_LOCAL_CPU=False \
# LMCACHE_CHUNK_SIZE=256 \
# LMCACHE_GDS_PATH="/mnt/gds/cache" \
# LMCACHE_GDS_BUFFER_SIZE=8192 \
# LMCACHE_EXTRA_CONFIG='{"disk_io_threads": 8}' \
LMCACHE_CONFIG_FILE="gds-backend.yaml" \
vllm serve \
    meta-llama/Llama-3.1-8B-Instruct \
    --max-model-len 65536 \
    --kv-transfer-config \
    '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'

POSIX 回退#

在某些情况下，libcufile 实现了自己的内部 POSIX 回退，而 GdsBackend 并不知情。在其他情况下，可能会抛出类似 RuntimeError: cuFileHandleRegister failed (cuFile err=5030, cuda_err=0) 的错误。因此，当 GDS API 的使用不成功时，可以配置后端回退到其自己的 POSIX 实现。

要强制 GdsBackend 在任何情况下都不使用 GDS API，您可以通过配置覆盖其行为：

use_gds: false

或者通过环境变量：

LMCACHE_USE_GDS=False

gds_backend 字段（默认值：cufile）用于选择使用哪个 GDS 库。支持的后端有 cufile（NVIDIA cuFile）和 hipfile（AMD hipFile）：

use_gds: true
gds_backend: "cufile"   # or "hipfile"

请注意，在此模式下，它仍将使用 CUDA API 来映射和操作预注册的显存。