KVCache-Factory：把十幾種 KV cache 壓縮方法放進同一個評測介面

從 PyramidKV 長成方法集合，解決的是比較基準不一致

長上下文推論的 KV cache 壓縮文獻有一個共同的麻煩：每個方法都有自己的 repo、自己的評測腳本、自己對 max capacity 的定義方式。把 SnapKV 的數字和 H2O 的數字放在同一張表上，往往得先確認兩邊的 budget 是不是同一件事。KVCache-Factory 要處理的就是這個。README 說明它「started from PyramidKV and now includes multiple KV cache baselines under one evaluation interface」，2024-11-28 的公告把專案改名，理由是反映「the broader goal of supporting diverse KV cache compression methods」。

它的目標讀者是做壓縮演算法研究或必須在自家模型上重現這些方法的人。支援的方法清單裡有 eviction 類的 StreamingLLM、H2O、Scissorhands、NACL，有 retrieval 類的 SnapKV、Quest、L2Norm，有跨層壓縮的 MiniCache，有合併類的 CAM，有預算分配類的 PyramidKV、AdaKV、HeadKV，有量化路線的 KIVI、KVQuant、GEAR，還有一個定位特殊的 HeadInfer。這份清單的廣度是專案的主要賣點，同時也是它最容易被誤讀的地方。

方法清單背後的分類邏輯：壓縮、檢索、合併、量化、卸載

README 的支援方法表用 Type 欄位區分這些方法在做什麼，這個分類值得細看，因為它決定了參數怎麼下。

StreamingLLM 屬於 compression/eviction，做法是 attention sink 加上滑動視窗。H2O 是 retrieval/compression，保留 heavy-hitter token。SnapKV 同樣歸在 retrieval/compression，機制是 observation-window attention pooling。Quest 是 query-aware retrieval，靠 page 層級的 key min/max metadata 做 query-aware 的 page 與 token 選擇，這個 metadata 的維護成本是它和純 token 選擇方法的差別所在。NACL 是 encoding-time eviction，用 proxy-token 分數縮減，可選隨機 eviction。Scissorhands 是 persistence-based eviction，累積歷史重要性後在固定預算下選 pivotal token。MiniCache 走 cross-layer 路線，對相鄰層做 SLERP 方向共享，再還原 magnitude 並保留部分 token。PyramidKV 是 layer-wise 的 pyramidal budget。CAM 是 merge/compression，用 attention 資訊做 value aggregation。

HeadInfer 在表上被標為 lossless offloading，README 特別說明它「keeps the full cache (no approximation)」，做法是 head-wise 把 KV cache 卸載到 CPU 並用 async prefetch，而且要求 flash_attention_2。這一點值得記住：它和其他方法不是同一個類別的東西，把它放進壓縮方法的比較表會誤導。ThinK 是 key-cache pruning，針對 query 驅動的 key channel 剪枝，README 註明只用於 Llama LongBench 的執行。MInference 是 sparse prefill acceleration，透過外部依賴整合，不在基礎 requirements 裡。

安裝與第一個 LongBench 指令

依賴相當精簡。requirements 列出 transformers==4.44.2、torch、flash-attn>=2.4.0.post1。flash-attn 在 --attn_implementation sdpa 或 eager 時可以省略，但要做 FlashAttention v2 的實驗就必須裝，README 給的安裝方式是先裝 torch 再執行 pip install flash-attn --no-build-isolation。

安裝步驟是 clone 之後 pip install -r requirements.txt，然後把專案根目錄加進 PYTHONPATH：export PYTHONPATH="$PWD:${PYTHONPATH}"。這個 export 不是裝飾，從專案以 PYTHONPATH 為前提來看，直接跑 runner 而不設定它很可能找不到模組。

LongBench 的入口是 run_longbench.py，README 給的範例是 --method pyramidkv、--model_path 指向 Llama-3-8B-Instruct、--max_capacity_prompts 128、--attn_implementation flash_attention_2、--save_dir ./results_long_bench、--use_cache True。README 說明 quickstart 用 128 這個預算，而 PyramidKV 論文報告的是 128 與 2048 兩個預算下的結果，這意味著範例數字不是預設的評測設定。

另一個入口是 scripts/scripts_longBench/eval.sh，它的參數是位置式的，順序為 CUDA_VISIBLE_DEVICES、method、max_capacity_prompts、attn_implementation、source_path、model_path、merge_method、quant_method、nbits。範例呼叫是 bash scripts/scripts_longBench/eval.sh 0 pyramidkv 128 flash_attention_2 ./ /path/to/model none none 8。位置參數排到九個，中間還夾著兩個 none，這種介面在批次跑實驗時容易寫錯，改成直接呼叫 run_longbench.py 會比改 shell 腳本可控。

真正決定實驗成敗的幾個參數

--max_capacity_prompts 是每層的目標 KV cache 預算，PyramidKV 會把總預算重新分配到各層。預算數字直接決定壓縮率，也決定你和其他論文數字能不能對齊。

--kv_cache_granularity 有 query_head（預設，legacy layout）與 kv_head（GQA 效率較好的 layout）兩個選項。kv_head 支援 snapkv、pyramidkv、h2o、streamingllm、cam、l2norm，加上 adakv 與 headkv，但 README 對後兩者註明 GPU validation pending。相關說明放在 docs/gqa_cache_layout.md。搭配的 --gqa_score_agg 控制每個 KV head 如何聚合多個 query head 的分數，可選 mean（預設）、max、sum。

--attn_implementation 除了影響速度，還帶有硬性限制。--method think 要求 eager，headinfer 要求 flash_attention_2。README 提到在沒有 FlashAttention v2 支援的 GPU 上要設 --attn_implementation sdpa。這三條限制放在一起看，某些方法組合在特定硬體上根本無法成立，選方法之前得先確認這條鏈。

量化路線由 --quant_method 開啟，可選 kivi、kvquant、gear，搭配 --nbits 指定位寬，--quant_backend 預設 hqq。--quant_residual_length 是保留全精度的 residual cache 視窗，預設等於 max_new_tokens。GEAR 另外接受 --rank 與 --outlier_ratio。進階 layout 由 --q_group_size、--axis_key、--axis_value 控制，README 說明 KIVI 的 key axis 預設為 1、value axis 預設為 0。

--datasets 接受逗號分隔的 LongBench 資料集名稱，例如 narrativeqa,qasper，不指定就預設跑完整的 16 個資料集。

覆蓋率不均與驗證狀態，是這個專案最該先看的地方

README 自己寫得很直白：Llama 與 Mistral 的 attention path 支援主要的壓縮方法，但「Some newer methods currently have narrower runner/model coverage; check the runner argument choices before launching large jobs」。這句話的意思是你不能假設方法表上的每一列都能在你手上的模型跑起來，必須去看 runner 的 argument choices。

驗證狀態也有明確標記。--kv_cache_granularity kv_head 對 adakv 與 headkv 是 GPU validation pending，也就是說這條路徑在 README 撰寫時尚未在 GPU 上驗證過。ThinK 被限定在 Llama 的 LongBench 執行。MInference 是選配依賴，要另外 pip install -r requirements-minference.txt，不在基礎環境裡。

另一個容易踩到的點是 headinfer 與 --max_capacity_prompts 的關係。README 說明 headinfer 是 lossless，忽略 --max_capacity_prompts，因為它做的是 head-wise CPU 卸載而不是壓縮。如果你把 headinfer 放進一組用不同預算掃參數的實驗裡，那個參數對它完全沒有作用，跑出來的曲線會是平的，而這不是方法本身的性質。

專案沒有檢索到任何 release，所以沒有版本化的安裝目標。要重現實驗就得鎖定 commit，而 transformers 被釘在 4.44.2 這個具體版本，升級 transformers 之前得先確認各方法的 attention path 是否還相容。

和其他做法的差異：這是評測框架，不是推論加速層

最直接的對照是 vLLM 或 Hugging Face transformers 內建的 quantized cache。vLLM 的定位是推論服務引擎，KV cache 管理（PagedAttention、prefix caching）是為了吞吐量與記憶體效率服務的，它不會讓你在同一個介面下切換十幾種研究階段的壓縮演算法。transformers 的 cache 實作則以模型相容性為主，量化選項有限。

KVCache-Factory 走的是第三條路：它把研究方法本身當成可替換的元件，用 --method 選擇，用同一組 runner 輸出結果。這樣設計的結果是，它對演算法層的細節掌握得比較細（例如 PyramidKV 的跨層預算重分配、Quest 的 page metadata、MiniCache 的 SLERP 方向共享），但在部署路徑上沒有任何承諾。你不會用它來服務線上流量。

和單一方法的原始 repo 相比，差別在於基準線。原始 repo 通常只跟 FullKV 比，而這裡的 FullKV 是表上的第一個方法，跑同一份資料集、同一組參數。這個共同基準的價值取決於那些方法是否真的都在你的環境裡跑得動，而這正是覆蓋率問題會反過來咬人的地方。

授權與維護成本

專案採用 MIT 授權。這對學術與商業使用都是相對寬鬆的條款，但這裡只陳述授權識別碼，不構成法律意見；實際使用前仍應自行確認相依套件的授權，尤其是 flash-attn 與選配的 MInference，它們各自有自己的條款。

維護成本的來源不在程式碼量，而在環境。transformers 被釘在 4.44.2，flash-attn 需要 --no-build-isolation 手動安裝，PYTHONPATH 需要手動 export，MInference 需要額外一份 requirements 檔。這四項加起來意味著建立一個可重現的環境需要一些耐心，而升級其中任何一項都可能牽動 attention path 的相容性。

README 沒有提供版本號或 release，因此沒有「升級到新版」這件事，只有「切到另一個 commit」。評估長期維護時，這比授權條款更值得納入考慮：你的實驗結果要能重現，就得把 commit hash 和那組釘死的依賴一起記錄下來。

編輯結論

如果你正在做長上下文推論的壓縮方法比較，而且願意自己讀 runner 的參數選項、自己確認某個方法在你指定的模型上是否真的跑得動，KVCache-Factory 省下的是重寫評測管線的時間。如果你要的是拿來就用的推論加速函式庫，或是需要每個方法都有同等測試覆蓋，這個專案目前的狀態不適合。動手前先確認三件事：目標方法在 runner 裡的 argument choices 是否包含你的模型架構、--attn_implementation 能否設成 flash_attention_2 或必須退回 sdpa、以及 --kv_cache_granularity kv_head 這條路徑在你的硬體上是否已被驗證，README 對 adakv 與 headkv 明講 GPU validation pending。

官方來源

1. Issues
2. License: MIT
3. README
4. Zefan-Cai/KVCache-Factory on GitHub