GDS 后端#

概述#

该后端可以与任何文件系统配合使用，无论是本地的、远程的，还是带有基于 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

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

多路径（多设备）支持#

当系统有多个 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 is alpha software and has been tested on limited hardware. For full installation details, see the hipFile install guide.

先决条件：

  • 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

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

# LMCACHE_LOCAL_CPU=False \
# LMCACHE_CHUNK_SIZE=256 \
# LMCACHE_GDS_PATH="/mnt/gds/cache" \
# LMCACHE_GDS_BUFFER_SIZE=8192 \
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 来映射和操作预注册的显存。