KVCache-Factory：KVキャッシュ圧縮の手法を一枚の評価インターフェースにまとめたリポジトリ

PyramidKVから改名した経緯と、このリポジトリが埋める穴

KVキャッシュ圧縮の研究は、手法ごとに実装リポジトリが分かれていることが多い。SnapKVのコード、H2Oのコード、量子化手法のコードをそれぞれ別々に落としてきて、同じモデル・同じデータセット・同じ予算で比較するのは手間がかかる。KVCache-Factoryはこの比較作業を一箇所に寄せることを狙ったプロジェクトで、READMEには2024年11月28日付でPyramidKVから現在の名前に改名したと書かれている。改名の理由も「多様なKVキャッシュ圧縮手法を支えるという、より広い目標を反映するため」と説明されている。

対象読者は、長文コンテキスト推論の圧縮手法を研究・検証している人である。アプリケーションに組み込むためのライブラリというより、評価ハーネスの色が強い。run_longbench.py、run_ruler.py、run_needle_in_a_haystack.py というrunnerが用意され、手法名を引数で切り替える形になっている。

手法をどう分類しているか：圧縮、退避、量子化の三系統

READMEの対応表は、手法を役割ごとに分けている。圧縮・退避の系統では、StreamingLLMがattention sinkとsliding window、H2Oがheavy-hitterトークンの保持、SnapKVがobservation windowのattention pooling、PyramidKVが層ごとのピラミッド型予算配分、AdaKVがヘッド適応型の予算配分、HeadKVがヘッド単位の検索・推論用配分という具合である。

別系統として、MiniCacheは隣接層のSLERP方向共有とマグニチュード復元、CAMはattentionに基づくvalue集約を伴うマージ、ThinKはクエリ駆動のkeyチャネル枝刈りを行う。KIVI、KVQuant、GEARは量子化で、--quant_method kivi のように指定する。GEARは追加で--rankと--outlier_ratioを受け付ける。

この分類で見落としやすいのはHeadInferである。これは圧縮ではなくロッシーでないオフロードで、ヘッド単位でKVキャッシュをCPUに退避しつつ非同期プリフェッチする。フルキャッシュを保持するため近似を行わない。つまり同じ表に並んでいても、精度を犠牲にする手法と犠牲にしない手法が混在している。

実行までの手順：cloneからLongBenchの1本目まで

インストールはREADMEに載っている通りで、git cloneのあとpip install -r requirements.txt、そしてexport PYTHONPATH="$PWD:${PYTHONPATH}"を通す。PYTHONPATHを設定する必要がある点は、パッケージとしてpip installする構成ではないことを示している。

LongBenchの実行例はこうである。

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

クイックスタートの予算は128で、PyramidKVの論文は128と2048の予算で結果を報告しているとREADMEにある。--datasetsにカンマ区切りでデータセットを渡せば部分評価ができ、省略時は16データセット全部が対象になる。scripts/scripts_longBench/eval.sh を使う場合は引数の順序が決まっていて、CUDA_VISIBLE_DEVICES、method、max_capacity_prompts、attn_implementation、source_path、model_path、merge_method、quant_method、nbits の順に並べる。

GQAレイアウトとスコア集約という地味だが効く設計

--kv_cache_granularityはquery_head（既定、従来のレイアウト）とkv_head（GQA向けの効率的なレイアウト）を選べる。kv_head側はsnapkv、pyramidkv、h2o、streamingllm、cam、l2normでサポートされ、adakvとheadkvについては「GPU検証が保留中」とREADMEに明記されている。詳細はdocs/gqa_cache_layout.mdに置かれている。

kv_headを選んだときは、クエリヘッドごとのスコアをKVヘッド単位にどう集約するかを--gqa_score_aggで決める。mean（既定）、max、sumの三択である。GQAモデルでKVヘッドを共有している以上、集約方法は圧縮の挙動そのものを変える。既定がmeanである理由はREADMEからは読み取れないので、自分のタスクでmaxやsumと比べる価値はある。

もう一つ、--mergeにはpivotとweightedというマージ戦略がある。圧縮とマージを同時に有効化できるのか、排他なのかはREADMEの記述からは確定できない。ここは実装を読むか、runnerの引数定義を確認する必要がある。

依存関係の分岐：flash-attn、MInference、eager制約

requirementsにはtransformers==4.44.2、torch、flash-attn>=2.4.0.post1が挙がっている。ただしflash-attnは--attn_implementation sdpaまたはeagerを使うなら任意で、FlashAttention v2の実験には必須とされている。インストールはtorchの後にpip install flash-attn --no-build-isolationを手動で実行する順序になっている。ビルド分離を切る必要がある点は、環境によってはここで詰まる。

MInference連携は基本のrequirementsから外されていて、pip install -r requirements-minference.txtで別途入れる。--method minferenceで有効になる。

見落としやすい制約が二つある。--method thinkはeager必須、headinferはflash_attention_2必須である。headinferは--max_capacity_promptsを無視する（圧縮ではなく退避だからである）。さらにREADMEは、LlamaとMistralのattention経路が主要な圧縮手法でサポートされている一方、新しい手法の中にはrunnerやモデルの対応範囲が狭いものがあり、大きなジョブを投げる前にrunnerの引数候補を確認するよう求めている。つまり手法名を指定できても、そのモデルで動くとは限らない。

このリポジトリが向かない場面

第一に、本番サービングの推論高速化をそのまま目的にしているわけではない。構成の中心は評価runnerとscriptsであり、提供されるのは比較のための足場である。推論エンジンに組み込むための安定したAPIが用意されているとはREADMEからは読み取れない。

第二に、手法間の公平な比較をしたい場合、量子化の系統とトークン退避の系統を同じ表で見ても意味が薄い。KIVIやKVQuantはビット幅の話であり、H2OやSnapKVはどのトークンを残すかの話である。--nbitsや--quant_backend（既定hqq）、--quant_residual_length（既定はmax_new_tokens）といった引数は量子化側にしか効かない。

第三に、新しめの手法を当てにした計画は危うい。README自身がrunner/model coverageの狭さに言及しており、adakv/headkvのkv_headレイアウトはGPU検証が保留中とされている。未検証の経路を本番判断の根拠にするのは避けたい。

比較対象としてのvLLMやHugging Face標準キャッシュとの違い

同じKVキャッシュ削減の文脈で名前が挙がるのがvLLMのPagedAttention系の実装だが、狙いが違う。vLLMはメモリ断片化を抑えてスループットを上げる serving 基盤であり、どのトークンを捨てるかという圧縮ポリシーを差し替えて研究する場所ではない。KVCache-Factoryは逆で、圧縮ポリシーを差し替えて同一データセットでスコアを並べることに重心がある。

Hugging Face transformersの標準キャッシュ（transformers==4.44.2が固定されている）はFullKVに相当する基準線として使われ、このプロジェクトでは--method FullKVがその位置を占める。圧縮手法の効果を測るにはFullKVとの差分が要るので、基準線が同じrunnerで回せることには意味がある。

どの手法が優れているかをこの記事で断定はしない。READMEにあるのはLongBenchとneedle-in-a-haystackの結果画像であり、数値は本文中に示されていない。判断するなら自分のデータセットでFullKVと並べて回すのが早い。

ライセンスと保守コストの見積もり

ライセンスはMITで、リポジトリはアーカイブされていない。最終pushは2026年8月13日と記録されている。リリースは取得できておらず、バージョン番号で固定して追従する形にはなっていない。

依存の固定が緩い点は保守コストに効く。transformersは4.44.2に固定されているが、torchとflash-attnはバージョン範囲が広く、flash-attnはビルド分離を切って手動インストールする前提である。CUDAやGPUの世代が変わるとこのビルドで詰まりやすい。requirements-minference.txtを入れる場合、MInference側の依存も別途面倒を見ることになる。

MITライセンスなので改変や再配布の制約は小さいが、同梱・参照している各手法の実装やモデルの重みには別の条件が付きうる。ここは法的助言ではないので、配布物を作る場合は各手法の出典元ライセンスを個別に確認してほしい。

編集部の結論

LongBenchやRULER、needle-in-a-haystackで複数のKVキャッシュ圧縮手法を同一条件で比較したい研究・検証担当者には向く。逆に本番推論のレイテンシ削減だけを目的とするチームには、評価スクリプト中心の構成が余計な負担になる。導入前に確認すべきは、使いたい手法がrunner側の引数候補に入っているか、そして--attn_implementationの組み合わせ制約（thinkはeager、headinferはflash_attention_2必須）を満たせるかである。

公式情報源

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