文件系统后端#

文件系统后端使用 FSConnector 将 LMCache 远程缓存块存储为一个或多个 POSIX 文件系统目录下的文件。当您需要一个简单的持久远程后端，或者当多个推理进程可以通过本地磁盘、NFS、并行文件系统或容器卷访问同一挂载目录时，它非常有用。

该后端与本地存储不同。本地磁盘卸载是通过 local_disk 配置的按进程本地层。FSConnector 是通过 remote_storage_plugins 或旧版 remote_url 字段配置的远程后端，因此它与 Redis、S3、Mooncake 及其他远程连接器共用同一远程后端路径。

何时使用它#

在以下情况下使用 FSConnector：

您需要一个轻量级的持久远程后端，用于开发、示例或基准测试。
多个 LMCache 或 vLLM 进程共享一个挂载的缓存目录。
您的存储已以文件系统形式对外提供，无需额外的对象存储或键值服务。
您希望在迁移到生产后端（如 Redis、Valkey、S3、Mooncake 或 InfiniStore）之前测试远程后端的行为。

在以下情况下请避免使用：

文件系统未被所有需要读取缓存的进程共享。
您需要对象存储语义、跨区域持久性或服务级访问控制。
存储路径位于慢速网络文件系统上，且处于请求热路径中。

多个文件系统实例#

您可以通过在连接器类型后附加实例名称来配置多个命名的 fs 实例。在第一个点之前的部分仍然是连接器类型；完整的插件名称成为 extra_config 前缀。

remote_storage_plugins: ["fs.primary", "fs.backup"]
extra_config:
  remote_storage_plugin.fs.primary.base_path: "/mnt/cache-primary/lmcache"
  remote_storage_plugin.fs.backup.base_path: "/mnt/cache-backup/lmcache"
  save_chunk_meta: false

当一个部署希望为不同的缓存策略、流量类别或实验提供独立的基于文件系统的远程存储时，这非常有用。

多个基础路径#

remote_storage_plugin.<name>.base_path 可以包含一个以逗号分隔的目录列表。连接器通过对缓存块键进行哈希来选择一个目录，从而将文件分散到配置的路径中。

remote_storage_plugins: ["fs"]
extra_config:
  remote_storage_plugin.fs.base_path: "/mnt/nvme0/lmcache,/mnt/nvme1/lmcache"
  save_chunk_meta: false

当每个路径映射到独立的存储设备或挂载点时，请使用多个路径。为了获得最佳效果，请确保每个路径对需要检索相同块的 LMCache 进程可见。

旧版 `remote_url` 配置#

旧版 remote_url 形式仍受支持。主机和端口会被解析以兼容其他远程 URL 格式；FSConnector 实际只使用其中的路径部分。

chunk_size: 256
local_cpu: false
max_local_cpu_size: 1
save_unfull_chunk: false
remote_url: "fs://localhost:0/tmp/lmcache-fs"
remote_serde: "naive"
blocking_timeout_secs: 10
extra_config:
  save_chunk_meta: false

对于新部署，建议优先使用 remote_storage_plugins，因为它支持命名实例，并可按插件名称对连接器专属配置进行分组管理。

可选设置#

连接器从 extra_config 中读取以下可选设置。

fs_connector_relative_tmp_dir: 用于在原子重命名到最终块路径之前存放临时文件的相对目录。该值必须是相对的，而不是绝对的。当省略时，临时文件会在最终文件旁边创建，并带有 .tmp 后缀。
fs_connector_read_ahead_size: 加载缓存块时首次读取的字节数。若读取填满了该窗口，连接器将继续读取剩余字节。在支持预读的文件系统上，此选项可触发文件系统级预读。
fs_connector_use_odirect: 在支持的平台上启用 O_DIRECT 以执行对齐读写。当缓存块大小未对齐到文件系统块大小时，连接器将回退到普通 I/O。启用 save_chunk_meta 后，O_DIRECT 会自动关闭，因为元数据前缀不满足块对齐要求。
fs_base_path: 插件模式的兼容性回退选项。建议优先使用 remote_storage_plugin.<name>.base_path，以将配置范围限定到特定插件实例。

带可选设置的示例：

remote_storage_plugins: ["fs"]
extra_config:
  remote_storage_plugin.fs.base_path: "/data/lmcache-fs"
  fs_connector_relative_tmp_dir: ".tmp"
  fs_connector_read_ahead_size: 1048576
  fs_connector_use_odirect: true
  save_chunk_meta: false

操作说明#

确保 LMCache 进程有权限在每个配置的基础路径下创建目录和写入文件。
若缓存需要在进程重启后仍可复用，请将路径配置在持久存储上。/tmp 等临时目录便于测试使用，但可能会被操作系统自动清理。
所有需要共享缓存块的进程必须使用相同的挂载路径。若某个进程写入的是私有容器路径，其他进程将无法命中这些缓存块，即使它们使用完全相同的配置。
当工作进程可能对相同缓存块推断出不同元数据时，请保持 save_chunk_meta 启用。仅当您需要降低额外开销且各工作进程共享兼容的缓存元数据时，才可将其禁用。
有关 MP 模式 L2 存储，请参见二级 KV 存储，该文档介绍了通过 --l2-adapter 配置的 fs 和 fs_native L2 适配器。

最简 vLLM 使用示例#

使用上述任一配置编写 fs.yaml 后，以 LMCache 模式启动 vLLM：

LMCACHE_CONFIG_FILE=fs.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
    --disable-log-requests

然后发送相同的长前缀请求两次。第一次请求会将缓存块写入文件系统后端。第二次请求应报告 LMCache 命中的 token 数，并从配置的文件系统路径加载匹配的缓存块。