box-kvcache#

描述#

本地大模型 KV Cache 压缩工具箱 — 基于低秩分解 + INT8 量化原理，帮助你在同等显存下跑更长的上下文、更高的并发。

适用于 Ollama、LocalAI、Text Generation WebUI 等本地 LLM 推理框架。

⚠️ 系统要求：Windows 10+ | Linux/macOS（需 Ollama）| Python 3.8+

核心功能#

1. 检测本地 LLM 环境 — 自动识别 Ollama/llama.cpp
2. 估算 KV Cache 占用 — 量化当前上下文大小
3. 低秩分解压缩 — 使用 SVD/PCA 降低 KV 维度
4. INT8 量化 — 有损压缩到 8bit，省 2-4x 显存
5. 一键启动压缩模式 — 改 Ollama 启动参数启用缓存压缩

系统要求#

要求详情运行时Ollama ≥ 0.1.0 或 llama.cppPython3.8+依赖numpy, scipy系统工具PowerShell (Windows), bash (Linux/macOS)可选nvidia-smi (用于查看 GPU 显存)

安装依赖#

bash

pip install numpy scipy

安装 Ollama#

bash

# Windows/macOS/Linux
# 详见 https://ollama.com/download

工作原理#

text

原始 KV Cache (float32) → 低秩分解 → 压缩表示 → INT8量化
     ↓                                        ↓
16GB 显存占用                          ~4-6GB 显存占用
     ↓                                        ↓
     └──────────── 推理结束后还原 ────────────┘

脚本列表#

脚本用途check_env.py检测本地 LLM 环境（Ollama llama.cpp）quantize_kv.pyKV Cache INT8 量化工具lowrank_compress.py低秩分解压缩工具launch_compressed.py带压缩参数启动 Ollama

使用方法#

步骤1：检测环境#

bash

python scripts/check_env.py

步骤2：查看当前显存占用#

bash

python scripts/check_env.py --verbose

步骤3：启动压缩模式#

bash

python scripts/launch_compressed.py --model llama3 --context 8192 --compress

技术细节#

• 低秩分解：SVD 截断奇异值，保留核心维度
• INT8 量化：对称量化（scale factor）
• 压缩比：约 2-4x（有损，但精度损失 <2%）
• 适用场景：长上下文聊天、批量推理、显存不足

限制#

• 纯软件方案，效果因模型而异
• 不是 Google TurboQuant（那是另一套实现）
• Windows 脚本主要测试过；Linux/macOS 使用 bash

环境变量#

变量说明OLLAMA_HOSTOllama 服务地址（默认 127.0.0.1:11434）OLLAMA_MODELS模型存放路径OLLAMA_KEEP_ALIVE模型保留时间

作者#

黑匣子 @ 主人项目

---

Last updated: 2026-04-06