AI 分析 · 由大模型根据 README 与仓库数据生成 · 2026年11月18日
统一评测多种 KV Cache 压缩方法的开源工具库。
KVCache-Factory 是一个面向长上下文 LLM 推理的 KV Cache 压缩、检索、合并与量化方法的统一实验平台。项目最初源自 PyramidKV,现已把 StreamingLLM、H2O、SnapKV、Quest、KIVI 等多种方法整合到同一套评测接口下,方便横向对比。
推荐指数
想系统对比 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 步
加载模型
通过 Hugging Face 或本地路径加载 Llama、Mistral 等自回归模型。
第 2 步
替换缓存策略
按 --method 参数启用对应的压缩、检索、合并或量化逻辑。
第 3 步
设定缓存预算
用 --max_capacity_prompts 控制每层 KV 缓存容量,PyramidKV 会按层重新分配。
第 4 步
运行基准评测
在 LongBench、RULER 或大海捞针任务上生成结果并保存到指定目录。
快速上手
- 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
可选安装 FlashAttention
需要 FlashAttention v2 时手动安装,否则可用 sdpa 后端。
pip install flash-attn --no-build-isolation - 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 许可,可商用,但引用相关方法时需遵守各自论文要求。
