# lakecache

**Repository Path**: hellofss/lakecache

## Basic Information

- **Project Name**: lakecache
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-01
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LakeCache

LakeCache 接入 vLLM 0.32.0，提供 **CPU 主存优先、磁盘回退、读取后回填** 的两级 KV 存储。它包含标准 Attention Chunk 缓存，以及 Qwen3.5-35B-A3B 的完整前缀与 Gated DeltaNet 状态检查点。

[十课课件](docs/课程索引.md) · [环境](docs/环境说明.md) · [精度](ACCURACY.md) · [性能](PERFORMANCE.md) · [两级存储实验](docs/两级存储实验报告.md) · [Attention / vLLM 实验](docs/早期推理链路实验报告.md)

独立项目现为 **v0.5**（写回与 L1 arena，结果见 [性能](PERFORMANCE.md)），历史剖析与回归见 [v0.4 优化报告](artifacts/optimization-20261101/report.html) 和 [v0.3 报告](artifacts/optimization-20261031/report.html)。`code/course1..10` 保留各课逐步实现的独立教学代码；根包是第 10 课汇总后的毕业版本，沿用相同的 Key、L1/L2、Connector 与租约接口。

本轮实现与课件的对应关系：

| 课程位置 | 本轮实现 | 阅读入口 |
|---|---|---|
| 第 5 课，两级恢复 | 连续对象、写回与回填 | `TieredStore.put / lease_many` |
| 第 8 课，批量搬运 | 连续字节载荷、L1 arena 一次注册、后台写回 | `PackedTransfer`、`TieredStore.put_device` |
| 第 9 课，淘汰与生命周期 | L2 字节容量 LRU、命中到恢复之间的租约 | `DiskBackend.lease_keys`、`TieredStore.reserve_prefix` |
| 第 10 课，实验判断收益 | 512 / 8K / 32K、load / store / 淘汰、LMCache 对照 | `benchmarks/compare_lmcache.py` |

第 8 课的 `PinnedPool` 在 `code/course8` 中运行，根包只保留批量路径与逐层参考路径；第 9 课沿用同一份文件租约处理 L2 淘汰。优化不增加新的必修架构或独立服务。

**阅读顺序：**先用“安装与运行”跑通 demo，再用“vLLM 接入”确认 native 与 pinned 输出一致；然后看“两级存储路径”理解 L1/L2 的写入与回退；最后用 35B 入口和回归脚本检查混合检查点。核心包不导入任何课程目录。

## 课程主线

Attention 与 KV 复用 → 真实 vLLM KV 视图 → 前缀命中 → 主存卸载 → 两级恢复 → 调度计划 → 分层加载 → 并发与性能 → Qwen3.5-35B。

早期实验：

```bash
python3 examples/attention.py --device cuda
python3 validation/kv_trace.py --mode off --layers 0 --output results/kv.json
python3 examples/host_kv.py --kv-snapshot results/kv/kv-000.pt --device cuda
python3 examples/two_level.py --shared --kv-snapshot results/kv/kv-000.pt
```

## 两级存储路径

```mermaid
flowchart LR
    Q[Token 前缀查询] --> M[共享主存 L1]
    M -->|命中| G[恢复到 GPU]
    M -->|未命中| D[磁盘 L2]
    D -->|读取并回填| M
    C[GPU gather 完整对象] --> R[L1 发布]
    R -->|后台| P[L2 写入]
```

L1 使用 `/dev/shm` 中的 tmpfs 内存页，通过 mmap 提供 CPU Tensor 视图。Scheduler 与 Worker 访问同一份索引；主存命中时不读取 `.kv` 文件。L2 对象包含全部层数据，在完整写入后发布。

| 对象 | 内容 | 接入类 |
|---|---|---|
| Attention Chunk | 同一段 Token 的全部层 KV | `lakecache.connector.MiniCacheConnector` |
| 混合检查点 | 完整 Attention 历史与前缀结束位置的 GDN 状态 | `lakecache.hybrid.HybridCheckpointConnector` |

vLLM 接入默认主存预算为 1 GiB。1056 Token 的 35B 检查点占 86,016,000 bytes，约 82 MiB。LRU 按实际分配字节淘汰，正在读取和尚未落盘的对象由区间锁保护。`pinned` 路径先发布 L1、后台写 L2；`sync` 参考路径先写 L2 再发布 L1；读取 L2 时直接读入 L1。

## 安装与运行

环境为 Linux、Python 3.12、PyTorch 2.13.0、vLLM 0.32.0。进入匹配环境后安装项目：

```bash
python3 -m pip install --no-deps --no-build-isolation -e .
python3 examples/demo.py --device cuda
python3 examples/two_level.py
python3 examples/two_level.py --shared
python3 -m unittest discover -s tests -p 'test_*.py' -v
```

两级示例依次输出 disk、memory 两次读取来源，磁盘载荷读取次数保持为 1。`--shared` 使用跨进程共享主存，默认示例使用进程内主存。

## vLLM 接入

```bash
python3 examples/vllm_demo.py --model /models/Qwen3-0.6B --mode native \
  --output results/native.json
python3 examples/vllm_demo.py --model /models/Qwen3-0.6B --mode pinned \
  --cpu-bytes 1073741824 --cache-dir /tmp/lakecache-basic \
  --output results/pinned.json
python3 tests/compare_outputs.py results/native.json results/pinned.json
```

配置项位于 `kv_connector_extra_config`：

| 字段 | 含义 |
|---|---|
| `cache_dir` | L2 目录及缓存命名空间 |
| `cpu_bytes` | L1 容量，默认 1 GiB；0 为磁盘后端 |
| `disk_capacity_bytes` | L2 已提交 `.kv` 文件的字节上限；默认不限，设置后自动 LRU 淘汰，跳过活跃请求租约 |
| `ram_dir` | 共享主存根目录，默认 `/dev/shm/lakecache` |
| `chunk_size` | 普通 Attention Chunk 的 Token 数 |
| `checkpoint_tokens` | 混合检查点的 Token 边界 |
| `transfer` | `pinned`：批量搬运与写回；`sync`：逐层参考路径 |
| `verify_load` | 逐层比较恢复后的 GPU 数据 |

Pinned 路径每批最多 256 MiB，用一个 Triton kernel 完成全部层的 gather/scatter。`wait_for_save` 只在 GPU 上 gather 后返回；D2H 进入共享 L1 arena（整块只做一次 `cudaHostRegister`）、发布、写盘都在后台线程完成，`shutdown` 等待写回结束。磁盘对象为头部加连续字节，写临时文件后硬链接发布，不做 `fsync` 和校验和：崩溃可能丢失最近的 Chunk，不会暴露写了一半的对象；读取只检查 magic、key 和长度。冷读用 16 个线程直接读入 L1，每块读完立即 H2D。加载时 H2D 在独立 stream 上写入两块交替的 GPU 缓冲，与上一批的 scatter 重叠。

启用 8 GiB L2 容量限制：

```bash
python3 examples/vllm_demo.py --model /models/Qwen3-0.6B --mode pinned \
  --cpu-bytes 1073741824 --disk-bytes 8589934592 \
  --cache-dir /tmp/lakecache-v05 --output results/bounded.json
```

`--disk-bytes` 同样适用于混合检查点 demo 和服务入口。Scheduler 在报告命中前取得磁盘前缀租约，Worker 完成恢复前对象不会被淘汰；请求结束或取消后释放，进程退出时内核自动释放。若对象过大或其他对象都被租约占用，本次缓存写入跳过，推理继续。容量只计已提交对象（含头部），索引和有界临时写入另计；L1 可保留已被 L2 淘汰的副本，但不会对这些副本承诺跨进程恢复。修改容量或升级写入器时使用新缓存目录。

## Qwen3.5-35B-A3B

完整 40 层文字路径，单张 H100 80GB，BF16。检查点包含 10 层 Attention KV 和 30 层 GDN 卷积、递归状态。GDN 的 FP32 状态以原始字节保存。

```bash
python3 examples/hybrid_demo.py --mode checkpoint --full-logprobs \
  --tier-phases warm,cold,rewarm --cpu-bytes 1073741824 \
  --cache-dir /tmp/lakecache-qwen35 --output results/phases.json
```

三个阶段分别运行主存热命中、清空 L1 后读取 L2、回填后再次读取 L1。每次请求前重置 GPU 原生前缀缓存。事件中的 `tier`、`disk_payload_reads` 和 `promotions` 记录实际存储路径。

## 精度和性能回归

```bash
python3 tools/regress_two_level.py --output artifacts/two_level
```

该命令构建并安装 Wheel，在没有项目源码包与课程目录的临时目录执行测试，再运行两级恢复精度和流式性能实验。完整词表分布按 Token ID 排列，压缩后按内容哈希去重保存。

v0.2 历史结果见 [精度回归](ACCURACY.md) 和 [性能回归](PERFORMANCE.md)。原始命令、来源事件、完整分布和 Wheel 位于 `artifacts/two_level/`；v0.3 的结果与安装包位于 `artifacts/optimization-20261031/`，v0.4 位于 `artifacts/optimization-20261101/`。

## 项目结构

```text
lakecache/       核心包：索引、主存、磁盘、传输与 Connector
examples/        缓存、两级存储、真实模型入口
tests/           数值、容量、租约和跨进程测试
benchmarks/      LMCache 对照、流式请求与服务启动
validation/      完整词表分布和固定批次比较
code/course1..10/ 各课独立源码
docs/            课件、环境与实验报告
tools/           安装包回归、逐课验证与实验报告
artifacts/       回归数据、日志、时间线和 Wheel
```

## 第 7～10 课逐课端到端实验

第 5 课跑通两级恢复原型，第 6 课展开调度计划，第 7～10 课分别使用自己的 Connector 和独立源码启动真实 vLLM。

```bash
python3 tools/regress_course_e2e.py --courses 7,8,9,10
python3 tools/report_course_e2e.py
```

第 7 课比较 RAM、磁盘回退和重启复用；第 8 课测量流式 TTFT；第 9 课运行 HTTP 并发、取消和固定批次数值对照；第 10 课验证完整 35B 模型。结果见 [逐课端到端实验](docs/逐课端到端实验报告.md)，原始数据位于 `artifacts/course_e2e/`。