orbitkv

OrbitKV是面向LLM推理引擎的外部键值缓存层。它将vLLM和SGLang的KV缓存扩展到GPU内存之外：可复用的前缀保存在DRAM和SSD中，当匹配请求到达时恢复。所述用例包括重复文档的工作负载、共享系统提示词，以及前缀不再适合引擎GPU缓存的长时间对话。 部署模型 独立的缓存管理器每主机运行，该主机上的引擎连接到其共享缓存。引擎保留GPU内存和调度的所有权；OrbitKV管理外部副本和传输。单节点路径被描述为已在vLLM 0.29.0和SGLang 0.5.20上通过GPU测试。多节点缓存共享被标记为实验性，接口在1.0之前可能更改。 关键能力 - DRAM和SSD缓存：在GPU驱逐或引擎重启后，只要缓存管理器保持运行，前缀即可复用。 - 可选复用策略：Rust组件可在字节上限内保护复用页面，并选择性允许SSD写入；文档指出了冷复用权衡。 - 直接GPU传输：两个引擎通过CUDA IPC注册GPU缓冲区；适配器对生产CUDA流进行栅栏同步，Rust处理缓存查询、读取和传输完成。 - 模型感知恢复：缓存身份包括模型工件、计算设置和存储布局。编译的恢复规则选择注意力页面、滑动窗口和循环/卷积检查点，包括三者组合的布局。 - 有界资源使用：字节预算覆盖待处理读取、就绪页面和活动GPU传输；取消会保留已提交的I/O直至完成。 - 可观测性：Prometheus指标和可选请求时间线，附带已发布测量的复现命令。 - 实验性共享缓存：嵌入式目录分片定位对等副本，Mooncake传输引擎移动字节，etcd跟踪集群成员。 快速入门概要 根据Python和CUDA运行时构建并安装wheel，vLLM和SGLang使用独立环境。wheel包含缓存管理器和Mooncake库；管理器还需要兼容的PyTorch。第一个Python版本被描述为正在准备中，因此应在发布文档中检查包发布状态。 缓存管理器通过类似`orbitkv-cache-manager --addr 127.0.0.1:50055 --http-addr 127.0.0.1:9091 --pool-size 8gb`的命令启动。然后vLLM启用前缀缓存并配置命名OrbitKV连接器模块的KV传输配置启动；SGLang通过OrbitKV端点环境变量、页面大小以及外部链接器和基数缓存后端选项启动。通过向管理器命令添加`--ssd-cache-path`和`--ssd-cache-capacity`启用SSD缓存；管理器重启时SSD缓存会重新创建。默认SSD后端在支持的挂载上尝试原生cuFile，并回退到io_uring。`--ssd-read-path uring|cufile`覆盖项独立于存储表示选择需求恢复路径。存储编码选项包括nvCOMP ANS无损压缩、FP8和3/4位TurboQuant，通过`--storage-codec`选择；默认是精确存储，有损模式需要模型质量认证。`orbitkv_load_bytes_total`指标的上升被作为外部恢复的确认。 架构和状态 引擎适配器识别缺失状态并提供GPU目标；OrbitKV选择兼容的缓存范围，从配置的层级读取，并保留页面所有权直到GPU复制完成。新计算的KV被发布以供后续复用。同一适配器API服务于DRAM、SSD和实验性远程获取，物理放置位于缓存管理器内部。项目记录了将固定LMCache、FlexKV和Mooncake机制映射到部署和验证工作的实施计划。有界Rust成本观察、原始复制影子预测和独立SSD读取路径被描述为已实现；动态成本选择仍计划中，观察默认关闭。跨引擎字节转换、生产目录HA和KV感知请求路由被列为计划工作。 性能文档 性能被描述为取决于前缀复用、缓存容量、存储和引擎调度。报告涵盖单节点比较（原生HBM、引擎CPU缓存、OrbitKV、LMCache、FlexKV）、SSD恢复、使用Qwen3-8B主机读取和GPU传输的普通恢复、请求准备以及共享缓存认证。请求准备默认关闭：文档中的Qwen3-8B控制提高了两个引擎的吞吐量，但SGLang P95延迟回退，单H20测量不被呈现为优于其他缓存的普遍优势。基准代码和摘要位于`benches/`目录。 许可和贡献 OrbitKV根据Apache-2.0许可。文档涵盖安装、适配器配置、管理器选项、指标、故障认证、部署模式、贡献者指南、Python包细节、测试门和发布。贡献预计包括相关检查和文档更改。