Zefan-Cai GitHub avatar

KVCache-Factory

Python
KV 缓存压缩工具Zefan-Cai最近推送 2026年8月13日
模型推理与部署MIT1,3941814 issues

AI 分析 · 由大模型根据 README 与仓库数据生成 · 2026年11月18日

统一评测多种 KV Cache 压缩方法的开源工具库。

KVCache-Factory 是一个面向长上下文 LLM 推理的 KV Cache 压缩、检索、合并与量化方法的统一实验平台。项目最初源自 PyramidKV,现已把 StreamingLLM、H2O、SnapKV、Quest、KIVI 等多种方法整合到同一套评测接口下,方便横向对比。

推荐指数

4.0

想系统对比 KV Cache 压缩方法的研究者和工程师值得一试,但需要一定的显存和配置经验。

总 Star 排名

#2849

雷达追踪的 3,958 个 AI 仓库中

创建于

2024

2024年6月5日

核心亮点

  • 1方法覆盖广

    内置 FullKV、StreamingLLM、H2O、SnapKV、PyramidKV、KIVI 等十余种压缩与量化方法。

  • 2统一评测接口

    同一套命令行参数即可切换方法,在 LongBench、RULER、大海捞针等基准上对比。

  • 3支持大模型多卡

    提供多 GPU 推理支持,可运行 Llama-3-70B-Instruct 等大模型。

  • 4注意力可视化

    附带 notebook 和 viztools,可复现并定制注意力图,帮助理解缓存冗余。

  • 5量化与卸载可选

    支持 KIVI/KVQuant/GEAR 量化,以及 HeadInfer 无损 CPU 卸载路径。

适用场景

  • 方法选型对比

    例如:在同一模型和数据集上分别跑 PyramidKV 与 SnapKV,比较压缩率与精度损失。

  • 长上下文推理优化

    例如:给 Llama-3-8B-Instruct 设置 128 的缓存预算,降低长文档问答的显存占用。

  • 学术复现实验

    例如:按论文设置预算 128 或 2048,在 LongBench 上复现 PyramidKV 的结果。

  • 注意力机制研究

    例如:用 visualization.ipynb 观察模型在多文档提示上的注意力分布。

它是怎么工作的

  1. 第 1 步

    加载模型

    通过 Hugging Face 或本地路径加载 Llama、Mistral 等自回归模型。

  2. 第 2 步

    替换缓存策略

    按 --method 参数启用对应的压缩、检索、合并或量化逻辑。

  3. 第 3 步

    设定缓存预算

    用 --max_capacity_prompts 控制每层 KV 缓存容量,PyramidKV 会按层重新分配。

  4. 第 4 步

    运行基准评测

    在 LongBench、RULER 或大海捞针任务上生成结果并保存到指定目录。

快速上手

  1. 1

    安装依赖

    克隆仓库并安装 requirements.txt,设置 PYTHONPATH。

    git clone https://github.com/Zefan-Cai/KVCache-Factory.git && cd KVCache-Factory && pip install -r requirements.txt && export PYTHONPATH="$PWD:${PYTHONPATH}"
  2. 2

    可选安装 FlashAttention

    需要 FlashAttention v2 时手动安装,否则可用 sdpa 后端。

    pip install flash-attn --no-build-isolation
  3. 3

    跑 LongBench 评测

    以 PyramidKV、128 预算在 Llama-3-8B-Instruct 上评测。

    python3 run_longbench.py --method pyramidkv --model_path /path/to/Llama-3-8B-Instruct --max_capacity_prompts 128 --attn_implementation flash_attention_2 --save_dir ./results_long_bench --use_cache True

适合谁

  • 研究 KV Cache 压缩的科研人员
  • 需要优化长上下文推理显存的工程师
  • 想复现相关论文结果的学生

不太适合

  • 只想开箱即用部署推理服务的用户
  • 没有 GPU 环境的开发者

成熟度

  • 活跃度2026 年仍有更新,star 约 1.4k,issue 仅 4 个。
  • 文档README 列出方法表、参数说明和安装步骤,较完整。
  • 社区有 181 个 fork,但 issue 讨论量不大。
  • 上手难度需配置 CUDA、FlashAttention 和模型路径,参数较多。

同类项目怎么选

  • PyramidKV本项目的前身,只聚焦金字塔式分层预算分配这一种方法。
  • SnapKV单一压缩方法实现,本项目把它作为可切换的基线之一。
  • H2O只实现重击 token 保留策略,本项目将其纳入统一评测框架。

使用前注意

  • · 依赖特定版本的 transformers 和 flash-attn,环境配置成本较高。
  • · 部分新方法的 runner 和模型覆盖较窄,大规模实验前需确认参数支持。
  • · 需要足够的 GPU 显存,大模型需多卡或 CPU 卸载方案。
  • · 采用 MIT 许可,可商用,但引用相关方法时需遵守各自论文要求。

主题标签

kv-cachekv-cache-compressionllm