KVCache-Factory: ein einheitliches Testfeld für KV-Cache-Kompression

Welches Problem die Sammlung adressiert

Der KV-Cache wächst linear mit der Kontextlänge und belegt während der Generierung GPU-Speicher, der für Gewichte und Aktivierungen fehlt. Genau an dieser Stelle setzt das Projekt an: Es sammelt Verfahren, die den Cache kürzen, quantisieren, zwischen Ebenen teilen oder auf die CPU auslagern, und stellt sie unter eine gemeinsame Evaluationsoberfläche. Das ist der eigentliche Nutzen. Wer SnapKV gegen PyramidKV gegen H2O messen will, muss die Implementierungen nicht aus drei Repositories zusammenführen, sondern wechselt das Argument --method. Das Projekt ist aus PyramidKV hervorgegangen und wurde am 28.11.2024 umbenannt, um die breitere Ausrichtung sichtbar zu machen. Adressiert sind damit in erster Linie Forschende und Ingenieure, die Long-Context-Inferenz auf einer begrenzten Zahl von GPUs untersuchen und reproduzierbare Zahlen brauchen.

Ein Aufruf, viele Verfahren: der Mechanismus

Die Einheitlichkeit liegt in der Argumentebene, nicht in einer gemeinsamen Abstraktionsschicht, die aus dem README hervorginge. Der Einstiegspunkt run_longbench.py nimmt --method entgegen und wählt darüber das Verfahren: FullKV, pyramidkv, snapkv, streamingllm, h2o, cam, l2norm, adakv, headkv, think, headinfer oder minference. Die Methoden unterscheiden sich konzeptionell deutlich. StreamingLLM behält Attention-Sinks plus ein gleitendes Fenster, H2O behält Heavy-Hitter-Token, SnapKV poolt Aufmerksamkeit über ein Beobachtungsfenster, Quest arbeitet mit Seiten-Metadaten aus Minimum und Maximum der Keys und wählt zur Query passende Seiten aus, Scissorhands akkumuliert historische Wichtigkeit, MiniCache teilt Richtungen zwischen benachbarten Ebenen per SLERP, PyramidKV verteilt das Budget schichtweise pyramidal, AdaKV und HeadKV passen das Budget pro Head an. KIVI, KVQuant und GEAR kommen über --quant_method dazu. HeadInfer fällt aus diesem Raster: Es komprimiert nicht, sondern lagert den Cache head-weise auf die CPU aus und lädt asynchron nach, was der README als verlustfrei bezeichnet. Diese Bandbreite ist der Kern des Projekts, aber sie erklärt auch, warum die Konfiguration so viele Schalter hat.

Installation und der erste LongBench-Lauf

Die Installation folgt dem üblichen Muster: Repository klonen, pip install -r requirements.txt, danach export PYTHONPATH="$PWD:${PYTHONPATH}". Die Anforderungen nennen transformers==4.44.2, torch und flash-attn>=2.4.0.post1. FlashAttention ist optional, solange man --attn_implementation sdpa oder eager setzt, für die FlashAttention-v2-Experimente aber erforderlich und laut README nach torch manuell mit pip install flash-attn --no-build-isolation zu installieren. Der dokumentierte Beispielaufruf setzt CUDA_VISIBLE_DEVICES=0 und ruft run_longbench.py mit --method pyramidkv, --model_path, --max_capacity_prompts 128, --attn_implementation flash_attention_2, --save_dir ./results_long_bench und --use_cache True auf. Wichtig ist die Unterscheidung der Budgets: Der Schnellstart nutzt 128, das PyramidKV-Papier berichtet Ergebnisse bei 128 und 2048. Wer das verwechselt, vergleicht gegen einen anderen Betriebspunkt. Der Hilfsskript-Aufruf bash scripts/scripts_longBench/eval.sh erwartet neun Positionsargumente in fester Reihenfolge: CUDA_VISIBLE_DEVICES, method, max_capacity_prompts, attn_implementation, source_path, model_path, merge_method, quant_method, nbits. Diese Reihenfolge ist eine Fehlerquelle, weil vertauschte Argumente nicht zwingend eine Fehlermeldung erzeugen.

GQA-Layout, Score-Aggregation und Quantisierung

Für Modelle mit Grouped-Query-Attention gibt es --kv_cache_granularity mit den Werten query_head (Standard, altes Layout) und kv_head. Der kv_head-Pfad ist laut README für snapkv, pyramidkv, h2o, streamingllm, cam und l2norm unterstützt, bei adakv und headkv steht die GPU-Validierung noch aus. Dazu gehört --gqa_score_agg mit mean, max oder sum, das festlegt, wie Bewertungen pro Query-Head auf einen KV-Head verdichtet werden. Das ist eine Designentscheidung mit Folgen: mean glättet Ausreißer weg, max hebt sie hervor, und die Wahl beeinflusst, welche Token überleben. Die Details stehen in docs/gqa_cache_layout.md. Für die Quantisierung gibt es --nbits, --quant_backend (Standard hqq), --quant_residual_length (Standard max_new_tokens) sowie --q_group_size, --axis_key und --axis_value; KIVI verwendet laut README standardmäßig Achse 1 für Keys und Achse 0 für Values. Der vollpräzise Restcache-Fenster über --quant_residual_length ist ein Kompromiss: Er kostet Speicher, den die Quantisierung gerade einsparen sollte.

Wo die Abdeckung endet

Der README ist an einer Stelle ungewöhnlich deutlich: Llama- und Mistral-Attention-Pfade werden für die wichtigsten Kompressionsmethoden unterstützt, einige neuere Methoden haben derzeit aber eine schmalere Runner- und Modellabdeckung, und man solle die Argumentauswahl des Runners prüfen, bevor man große Jobs startet. Das ist die zentrale Einschränkung des Projekts. Ein Verfahren in der Tabelle zu sehen heißt nicht, dass es auf dem eigenen Modell läuft. Dazu kommen harte Kopplungen: --method think verlangt --attn_implementation eager, headinfer verlangt flash_attention_2 und ignoriert --max_capacity_prompts, MInference wird über --method minference aktiviert und ist nicht in den Basisabhängigkeiten enthalten, sondern über pip install -r requirements-minference.txt nachzuinstallieren. Ein weiterer Punkt: Es gibt keine abgerufenen Releases. Wer das Repository einsetzt, arbeitet gegen den Branch main, nicht gegen eine versionierte Ausgabe. Für einen reproduzierbaren Vergleich über Monate hinweg ist das ein reales Risiko, weil sich Argumente und Standardwerte ohne Versionssprung ändern können.

Was man stattdessen greifen könnte

Die naheliegende Alternative ist, direkt bei der Originalimplementierung einer einzelnen Methode zu bleiben, etwa beim ursprünglichen PyramidKV-Repository. Der Unterschied liegt nicht in der Qualität der Kompression, sondern im Zuschnitt: Eine Einzelimplementierung bringt typischerweise nur einen Auswertungspfad für genau dieses Verfahren mit, während KVCache-Factory mehrere Verfahren hinter demselben --method-Schalter und derselben LongBench-Auswertung bündelt. Wer nur PyramidKV braucht und dessen Skripte bereits reproduziert hat, gewinnt durch den Wechsel nichts und übernimmt zusätzlich die Abhängigkeit von transformers==4.44.2 sowie die breitere Argumentfläche. Umgekehrt ist der Vergleich über mehrere Methoden genau der Punkt, an dem eine Sammlung ihre Berechtigung hat, weil unterschiedliche Token-Auswahlregeln auf identischen Läufen sonst kaum fair gegenüberzustellen sind. Ein zweiter Weg wäre, den Cache gar nicht zu komprimieren, sondern über headinfer auszulagern; das ist laut README verlustfrei, verschiebt das Problem aber von Rechenzeit zu Bandbreite und setzt flash_attention_2 voraus.

Pflegeaufwand und Lizenz

Das Repository steht unter der MIT-Lizenz, was die Weitergabe und Anpassung im Rahmen der Lizenzbedingungen erlaubt; eine Rechtsberatung ist das nicht, und bei mitgelieferten Fremdkomponenten wie der optionalen MInference-Abhängigkeit lohnt ein Blick auf deren eigene Bedingungen. Der Pflegeaufwand ist schwer abzuschätzen. Der letzte Push liegt laut Metadaten im August 2026, Releases wurden nicht abgerufen. Die Anforderung transformers==4.44.2 ist fest gepinnt, was die Umgebung stabil hält, aber Upgrades von transformers blockiert, bis das Projekt nachzieht. flash-attn>=2.4.0.post1 muss manuell nach torch installiert werden, was auf neuen CUDA-Versionen regelmäßig Zeit kostet. Wer das Projekt forkt, übernimmt damit eine Umgebung mit gepinnter Transformers-Version, einer manuell zu bauenden FlashAttention-Abhängigkeit und ohne Release-Tags als Anker.

Redaktionelles Fazit

Sinnvoll ist das Repository für Forschende und Ingenieure, die mehrere KV-Cache-Verfahren auf denselben LongBench- oder RULER-Läufen vergleichen wollen, statt jede Methode in einer eigenen Codebasis nachzubauen. Wer einen einzelnen produktiven Inferenzpfad mit stabilem Betrieb sucht, ist hier falsch, weil die Abdeckung von Modellen und Runnern laut README uneinheitlich ist und kein Release vorliegt. Vor dem ersten großen Lauf sollte man die Argumentliste des jeweiligen Runners prüfen, weil der README ausdrücklich darauf hinweist, dass neuere Methoden eine schmalere Modell- und Runner-Abdeckung haben.

Offizielle Quellen

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