Home.zh

English | Русский | 中文

kv-persistence

面向 vLLM 的持久化 KV 缓存 —— 服务重启不再意味着重新计算整个历史。

kv-persistence 将 vLLM 计算出的提示词 KV 块保存到 NVMe 磁盘，并在重启后恢复。 任何 OpenAI 兼容客户端中 10 万–100 万 token 的会话 —— 过去每次重启 都要重新预填充几十分钟 —— 现在直接复用缓存而不是重新计算。

聊天客户端 → vLLM (TP4) → LMCacheMPConnector → lmcache 服务（独立进程）
       → L2 持久层（nixl_store_dynamic，POSIX）→ NVMe

为什么需要

• vLLM 内置的前缀缓存存放在 GPU 显存中，随进程一起消失。承载大量会话的服务 每次重启都意味着重新预填充全部历史。
• 持久层将可复用的 KV 块保存在 NVMe 上。vLLM 重启（甚至缓存服务重启）不会 清除数据：查找未命中时会落到磁盘，索引在启动时惰性重建。

保证什么

• 跨重启持久化 —— 数据既能通过 vLLM 重启，也能通过缓存服务完整重启的考验 （场景 A 和 B，见持久化与恢复）。
• 受限存储 —— 硬上限（默认 1.5 TB，实际边界为共享 VM 磁盘上的可用空间，同盘还装着 Docker 镜像与模型权重），配合自动软阈值（90%） 淘汰。缓存绝不会在启动时自动清空。
• 兼容性命名空间 —— 模型版本、分词器、KV 数据类型和聊天模板都是缓存键的 一部分。不兼容的配置绝不会互相读取 KV 数据；任何不确定性都会导致缓存未命中， 而非错误命中。
• 无损存储 —— L2 层只支持无损。块以逐字节精确方式存储 （LMCACHE_L2_SERDE=none，默认）或以无损 zstd/lz4 压缩存储；有损量化 （fp8 / turboquant / lbq）在启动时被拒绝。每个帧携带 CRC32：损坏会被检测 并报告为缓存未命中，绝不会作为错误的 KV 返回。
• 可选的 Prometheus + Grafana 监控 —— 官方 LMCache 可观测性栈 （OTel Collector + Tempo + Prometheus + Grafana）随 observability/ 提供， 一条命令即可启动；缓存不依赖它也能完整工作。
• 模型无关内核 —— 缓存策略层与模型集成分离；新增模型只需添加配置，无需改代码。

状态

实现已完成，离线测试全部通过（143 个单元测试 + 另 34 个离线集成/配置测试 = 160 通过，2 跳过；共收集 177 个 —— 另有 sikkatu/recipes 仓库 302 通过 / 307 收集）。在 GPU 主机上以 MiMo-V2.6-Pro 进行的验收测试已封装为 scripts/test-recovery.sh / scripts/benchmark.sh，由运维方执行。 未验证的功能都如实标注 —— 未经测试的东西绝不宣称可用。

从这里开始

• 快速开始 —— 安装、配置、启动、验证（一条直线路径）
• 架构 —— 各组件如何配合，故障模型
• 配置 —— cache.env、identity.env、lmcache-server.env 的每一项
• 持久化与恢复 —— 验收场景，如何证明磁盘命中
• 存储与淘汰 —— 预算、配额、淘汰、去重
• 配方集成 —— sikkatu/recipes 启动脚本中的 KV_PERSIST=1
• 安全 —— 权限、端点、数据处理
• 故障排查 —— 出现异常时该检查什么
• FAQ —— 常见问题简答

仓库：github.com/sikkatu/kv-persistence（Apache-2.0 + NOTICE：分支和使用者必须注明 sikkatu / kv-persistence；见文件 NOTICE）。