LMCache Weka 后端实战基于 GPUDirect Storage 的分布式 KV Cache 卸载与多实例共享指南【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache本文是 LMCache 在-process 模式in-process mode已弃用下使用 WekaFS 进行 KV Cache 卸载的实战指南。文章完整覆盖环境变量与配置文件两种配置方式、GDS 缓冲区调优要点以及从创建挂载目录到启动 vLLM 服务的端到端步骤并结合 gds_backend.py 源码剖析其底层实现帮助你理解Weka 专属优化究竟发生在哪里。注意本文描述的 LMCache in-process 模式已被标记为deprecated弃用。官方建议迁移到特性支持更全、性能更好的 LMCache MP 模式该页面在 MP 模式下的对应文档位于 mp/l2_storage/index。Overview为什么 LMCache 需要专门的 Weka 后端WekaFS 是一个高性能分布式文件系统也是 LMCache 官方支持的 KV Cache 卸载目标之一。虽然在 WekaFS 挂载点上直接使用本地文件系统后端Local Filesystem Backend也能工作但 LMCache 提供的是针对 Weka 特性专门优化过的后端其核心差异体现在两点GPUDirect StorageGDSI/OKV Cache 数据可以直接从 GPU 显存卸载到存储绕过 CPU 内存的拷贝中转显著降低卸载延迟多实例数据共享由于 WekaFS 是共享的分布式文件系统多个 LMCache 实例例如多个 vLLM worker可以读写同一份缓存的 KV 数据实现跨实例的缓存复用。从源码结构看这一后端就是 gds_backend.py 中的GdsBackend类其类注释明确写道Originally based on the open sourced WekaGdsBackend最初基于开源的 WekaGdsBackend即 Weka 是 GDS 后端最初的设计目标之一。该后端在初始化时通过读取/proc/mounts自动探测挂载点文件系统类型get_fstype见 gds_backend.py当识别到wekafs时就会切换到 Weka 专属的数据文件后缀与强制启用 GDS 的模式具体逻辑下文会详解。配置 Weka 卸载的两种方式LMCache 支持通过环境变量或配置文件两种方式启用 Weka 卸载二者完全等价可任选其一。方式一环境变量# 256 Tokens per KV Chunk export LMCACHE_CHUNK_SIZE256 # Path to Weka Mount export LMCACHE_GDS_PATH/mnt/weka/cache # GDS Buffer Size in MiB export LMCACHE_GDS_BUFFER_SIZE8192 # Disabling CPU RAM offload is sometimes recommended as the # CPU can get in the way of GPUDirect operations export LMCACHE_LOCAL_CPUFalse # GDS I/O Threads export LMCACHE_EXTRA_CONFIG{disk_io_threads: 32}方式二配置文件通过LMCACHE_CONFIG_FILEyour-lmcache-config.yaml传入示例config.yaml# 256 Tokens per KV Chunk chunk_size: 256 # Disable local CPU local_cpu: false # Path to Weka Mount gds_path: /mnt/weka/cache # GDS Buffer Size in MiB gds_buffer_size: 8192 # GDS I/O Threads extra_config: disk_io_threads: 32参数速查表参数环境变量默认值说明chunk_sizeLMCACHE_CHUNK_SIZE256每个 KV Chunk 对应的 token 数见 config.pylocal_cpuLMCACHE_LOCAL_CPUTrue是否启用 CPU RAM 卸载Weka 场景常建议关闭gds_pathLMCACHE_GDS_PATHNone必填Weka 挂载点下的缓存目录gds_buffer_sizeLMCACHE_GDS_BUFFER_SIZENone必填GDS 预注册缓冲区大小单位 MiB见 config.pyextra_config.disk_io_threadsLMCACHE_EXTRA_CONFIG4磁盘并行 I/O 线程数置 0 可禁用线程池use_gdsLMCACHE_USE_GDSTrue是否使用 GDS APIWeka 文件系统上被强制为启用见 config.pygds_backendLMCACHE_GDS_BACKENDcufile使用的 GDS 库cufileNVIDIA或hipfileAMD见 config.py从源码看gds_buffer_size会以gds_buffer_size * 1024**2即 MiB→字节换算后传给CuFileMemoryAllocator或HipFileMemoryAllocator预注册显存缓冲区见 gds_backend.py。同时该后端始终维护一个以disk_io_threads为最大并发数的线程池默认 4线程名前缀为gds-iobatched_get_blocking等批量读路径正是通过ThreadPoolExecutor.map并行下发 GDS 读请求见 gds_backend.py。GDS Buffer Size 详解显存预算的关键取舍后端当前会预注册缓冲区空间来加速 GDS 操作。关键点在于这块缓冲空间注册在 VRAM显存中因此在设置大小时必须把 vLLM 的--gpu-memory-utilization一并纳入考量。一个来自官方文档的实用经验法则对于通常拥有 80GiB 显存的 H100建议从 8GiB即gds_buffer_size: 8192起步同时设置--gpu-memory-utilization 0.85之后根据实际工作负载模型大小、上下文长度、KV 缓存需求微调。缓冲区过大可能导致显存不足触发分配失败过小则可能成为卸载吞吐的瓶颈。完整搭建示例从挂载探测到 vLLM 服务启动前置条件Prerequisites一台至少拥有一块 GPU 的机器可根据 GPU 显存调整 vLLM 实例的max-model-lenWeka 已安装并完成挂载已安装 vllm 和 lmcache参见 安装指南拥有 Hugging Face 上meta-llama/Llama-3.1-8B-Instruct的访问权限export HF_TOKENyour_hugging_face_tokenStep 1在 Weka 挂载下创建缓存目录首先查看机器上所有的 WekaFS 挂载点mount -t wekafs例如上述命令可能返回10.27.1.1/default on /mnt/weka type wekafs (rw,relatime,writecache,inode_bitsauto,readahead_kb32768,dentry_max_age_positive1000,dentry_max_age_negative0,container_nameclient)然后在挂载点下创建缓存目录目录名可任意指定mkdir /mnt/weka/cacheStep 2以 Weka 卸载模式启动 vLLM 服务器创建一个名为weka-offload.yaml的 LMCache 配置文件local_cpu: false chunk_size: 256 gds_path: /mnt/weka/cache gds_buffer_size: 8192 extra_config: disk_io_threads: 32如果你不想使用配置文件也可以取消下面脚本中前三个环境变量的注释并注释掉LMCACHE_CONFIG_FILE一行# LMCACHE_LOCAL_CPUFalse \ # LMCACHE_CHUNK_SIZE256 \ # LMCACHE_GDS_PATH/mnt/weka/cache \ # LMCACHE_GDS_BUFFER_SIZE8192 \ # LMCACHE_EXTRA_CONFIG{disk_io_threads: 32} \ LMCACHE_CONFIG_FILEweka-offload.yaml \ vllm serve \ meta-llama/Llama-3.1-8B-Instruct \ --max-model-len 65536 \ --kv-transfer-config \ {kv_connector:LMCacheConnectorV1, kv_role:kv_both}启动后vLLM 会通过LMCacheConnectorV1连接器把生成的 KV Cache 交给 LMCache 管理kv_role为kv_both表示同时承担生产者prefill 写缓存与消费者decode 读缓存的角色。源码视角Weka 专属优化到底做了什么理解配置背后的实现有助于在实际部署中排查问题。以 gds_backend.py 为线索可以梳理出以下关键机制1. 文件系统类型自动探测与 Weka 分支GdsBackend.__init__通过get_fstype(self.gds_path)读取/proc/mounts找到最长匹配的挂载点从而得到文件系统类型wekafs、ext4、tmpfs等。随后进入三分支逻辑gds_backend.pytmpfs/overlayfs自动禁用 GDS除非用户在配置里显式写了use_gds: true此时尊重用户意图wekafs记录日志 Weka filesystem detected, GDS usage is enforced强制断言use_gds为真并将数据文件后缀切换为_WEKA_DATA_FILE_SUFFIX .weka1其他类型按use_gds配置执行 GDS 或 POSIX 回退。2. Weka 专属数据文件后缀.weka1常规 GDS 后端的数据文件后缀是_DATA_FILE_SUFFIX .kvcache.safetensors而当探测到 Weka 文件系统后self.data_suffix被替换为.weka1gds_backend.py磁盘上每个缓存条目对应/{gds_path}/{l1_dir}/{l2_dir}/{urlencoded_key}{.weka1|.kvcache.safetensors}{.metadata}其中l1_dir、l2_dir取自 KV chunk 哈希的前 4 个字符每级 2 个字符形成两级目录结构以在启动扫描时并行化加载见_key_to_pathgds_backend.py。该两级目录设计是半随意的目的就是create two levels in the directory hierarchy to parallelize loading the data during initialization。3. 文件内部布局4KB 元数据头 KV 数据每个缓存文件的前_METADATA_MAX_SIZE 4096字节是元数据块前 8 字节记录 JSON 元数据长度小端Q格式其后是包含 dtype、shape、data_offsets、MemoryFormat 等信息的 JSON见pack_metadata/unpack_metadatagds_backend.py。KV 张量的实际数据从偏移_METADATA_MAX_SIZE开始写入读写时通过file_offsetoffset直接寻址见_save_gds/_load_gdsgds_backend.py这样 GDS 读写可以精确定位数据区避免每次解析整块元数据。4. 显存基址指针与 bounce buffer如果内存分配器暴露了base_pointer预注册的显存基址GDS 直接基于该基址加设备偏移读写否则退化为使用 bounce buffergds_base_pointer None路径见 gds_backend.py。这与gds_buffer_size的预注册机制直接相关。5. 测试用例验证仓库测试对 Weka 路径有专门覆盖可作为行为契约参考见 test_gds_backend.pytest_weka_initialization_suffixL418mockget_fstype返回wekafs后断言backend.data_suffix .weka1且backend.use_gds为真test_weka_disallows_disabling_gdsL475在 wekafs 上显式设置use_gds False会触发AssertionError印证了 GDS usage is enforced 的行为。此外tests/v1/data/gds.yaml 展示了一份最小可用的 GDS 测试配置chunk_size: 256、gds_path、local_cpu: False、gds_buffer_size: 128、gds_backend: cufile可以作为对照参考。使用限制与注意事项in-process 模式已弃用本文所述配置属于 LMCache 的 in-process 模式官方建议使用 LMCache MP 模式对应存储层文档见 mp/l2_storage/indexWeka 上禁止关闭 GDS一旦探测到wekafs文件系统use_gds被强制为真手动设置use_gds: false会在启动时直接断言失败显存预算联动gds_buffer_size预注册在 VRAM需与 vLLM 的--gpu-memory-utilization联合调优建议从 8GiB 0.85 起步gds_io_threads已废弃并行 I/O 线程统一使用extra_config.disk_io_threads配置默认 4可置 0 禁用CPU 卸载建议关闭官方文档建议设置local_cpu: false理由是 CPU 内存中转可能干扰 GPUDirect 操作的数据通路。若需要在不依赖 Weka 的普通文件系统本地 NVMe、NFS 等上使用同一套 GDS 卸载机制可参考同目录下的 GDS Backend 文档它覆盖了 cuFile/hipFile 选择、多盘路径分片gds_path_sharding与 POSIX 回退等更多进阶主题。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考