KVCache-Factory : un banc d'essai unique pour comparer les méthodes de compression du cache KV

Le problème : chaque méthode de compression KV arrive avec son propre script

Un modèle autorégressif conserve les clés et les valeurs de tous les tokens déjà traités. Sur un contexte long, cette mémoire croît linéairement et finit par saturer le GPU. La recherche a produit beaucoup de réponses : éviction des tokens peu utiles, sélection par score d'attention, compression entre couches, quantification. Le problème pratique n'est pas l'absence de méthodes, c'est que chacune est publiée avec son propre dépôt, ses propres scripts d'évaluation et ses propres conventions de nommage. Comparer deux méthodes sur le même jeu de données demande souvent de réécrire la boucle d'inférence.

KVCache-Factory attaque ce point précis. Le dépôt se présente comme un « unified playground » pour la compression, la récupération, la fusion et la quantification du cache KV. Il est issu de PyramidKV et a été renommé le 28 novembre 2024 pour refléter cette ambition plus large. Le public visé est celui qui fait de l'expérimentation : chercheur qui veut reproduire un tableau de résultats, ingénieur qui doit trancher entre deux budgets de cache. Ce n'est pas une couche d'optimisation destinée à être importée dans un service.

Une interface, quinze méthodes, des chemins d'exécution inégaux

Le tableau du README classe les méthodes par famille. FullKV sert de témoin et conserve tout le cache. StreamingLLM combine attention sink et fenêtre glissante. H2O retient les tokens à forte contribution d'attention, SnapKV regroupe l'attention sur une fenêtre d'observation. Quest stocke des minima et maxima de clés par page et sélectionne pages et tokens en fonction de la requête. NACL réduit les scores à l'encodage, Scissorhands accumule une importance historique, MiniCache partage une direction SLERP entre couches adjacentes. PyramidKV alloue un budget décroissant selon la profondeur, AdaKV et HeadKV rendent ce budget adaptatif par tête, CAM fusionne les valeurs à l'aide de l'attention, L2Norm sélectionne par norme. ThinK élague les canaux de clés, HeadInfer déporte le cache vers le CPU par tête sans approximation, MInference accélère le prefill. KIVI, KVQuant et GEAR relèvent de la quantification.

Cette unification a une limite que le README énonce lui-même : les chemins d'attention Llama et Mistral sont pris en charge pour les principales méthodes de compression, mais « some newer methods currently have narrower runner/model coverage ». Autrement dit, l'uniformité est réelle au niveau des arguments, pas garantie au niveau de chaque combinaison méthode plus modèle. La phrase invite à consulter les choix d'arguments du runner avant de lancer un gros job, ce qui est un aveu utile plutôt qu'un argument commercial.

Le mécanisme : des scores par tête, un budget réparti, un cache réécrit

Le dépôt ne remplace pas l'implémentation d'attention de transformers, il s'y greffe. transformers est épinglé à la version 4.44.2, et le README indique deux chemins possibles : FlashAttention v2 ou SDPA. Les nouvelles du 10 juin 2024 précisent que les trajets FlashAttention v2 et SDPA ont été ajoutés pour PyramidKV, SnapKV, H2O et StreamingLLM, avec la consigne de passer à --attn_implementation sdpa sur les GPU qui ne supportent pas FlashAttention v2.

Le paramètre central est --max_capacity_prompts, décrit comme le budget cible de cache KV par couche. PyramidKV ne l'applique pas couche par couche à l'identique : il redistribue le budget total selon un profil pyramidal. C'est là que se joue la différence avec une éviction uniforme, et c'est aussi ce qui rend le chiffre 128 du quickstart difficile à interpréter seul, puisque le papier PyramidKV rapporte des résultats aux budgets 128 et 2048.

Un second axe concerne la disposition du cache. --kv_cache_granularity accepte query_head (valeur par défaut, présentée comme l'ancienne disposition) ou kv_head, décrit comme efficace pour GQA et pris en charge par snapkv, pyramidkv, h2o, streamingllm, cam, l2norm, ainsi que adakv et headkv, avec une validation GPU annoncée comme en attente. Quand ce mode est actif, --gqa_score_agg décide comment les scores des têtes de requête sont agrégés par tête KV : mean par défaut, max ou sum. Le README renvoie à docs/gqa_cache_layout.md pour le détail, et les runners RULER et needle-in-a-haystack acceptent les mêmes drapeaux.

Mise en route : trois commandes et un fichier de script

L'installation tient en quatre lignes. Le dépôt se clone, on installe requirements.txt, puis on exporte PYTHONPATH pour que les modules internes soient trouvables :

git clone https://github.com/Zefan-Cai/KVCache-Factory.git cd KVCache-Factory pip install -r requirements.txt export PYTHONPATH="$PWD:${PYTHONPATH}"

flash-attn est optionnel si vous restez en sdpa ou eager, mais requis pour les expériences FlashAttention v2. Le README précise qu'il faut l'installer après torch, avec pip install flash-attn --no-build-isolation. L'intégration MInference est tenue à l'écart des dépendances de base et s'installe via pip install -r requirements-minference.txt.

L'exemple LongBench du README fixe CUDA_VISIBLE_DEVICES, puis appelle run_longbench.py avec --method pyramidkv, --model_path, --max_capacity_prompts 128, --attn_implementation flash_attention_2, --save_dir ./results_long_bench et --use_cache True. Le script scripts/scripts_longBench/eval.sh accepte une forme positionnelle dont l'ordre est documenté : CUDA_VISIBLE_DEVICES, method, max_capacity_prompts, attn_implementation, source_path, model_path, merge_method, quant_method, nbits. Un exemple donné est bash scripts/scripts_longBench/eval.sh 0 pyramidkv 128 flash_attention_2 ./ /path/to/model none none 8. Les jeux de données se restreignent avec --datasets narrativeqa,qasper, sinon la liste complète de 16 jeux est utilisée.

Les contraintes qui décident du choix de méthode

Deux contraintes sautent aux yeux dans les arguments. La première : --method think exige --attn_implementation eager. ThinK élague des canaux de clés et ne peut donc pas tourner avec les deux chemins d'attention rapides. La seconde : headinfer ignore --max_capacity_prompts et requiert flash_attention_2. Ce n'est pas un détail de configuration, c'est un changement de nature. HeadInfer ne compresse rien : il déporte le cache par tête vers le CPU avec préchargement asynchrone et conserve le cache complet. Le README le classe explicitement comme « lossless » et sans approximation. Une comparaison entre headinfer et pyramidkv à budget égal n'a donc pas de sens, puisque le premier ne consomme pas ce budget.

La quantification suit sa propre logique. --quant_method accepte kivi, kvquant ou gear, --nbits fixe la largeur, --quant_backend vaut hqq par défaut. --quant_residual_length définit la fenêtre de cache résiduelle en pleine précision et vaut max_new_tokens par défaut, ce qui peut être coûteux en mémoire sur une génération longue. GEAR accepte en plus --rank et --outlier_ratio ; KIVI utilise par défaut l'axe 1 pour les clés et l'axe 0 pour les valeurs, modifiable via --axis_key et --axis_value. Ces réglages sont exposés mais le README ne fournit pas de valeurs recommandées au-delà des défauts, ce qui laisse l'utilisateur seul face au compromis entre précision et mémoire.

Là où le dépôt ne suffit pas

Le README ne dit rien de la latence, du débit ni de la mémoire réellement mesurée pour chaque méthode. Il affiche deux figures, une comparaison LongBench et un résultat needle-in-a-haystack, sans chiffres dans le texte. Impossible donc de savoir depuis la documentation seule quelle méthode gagne sur quel budget, ni quel est le coût en temps de la sélection par page de Quest ou de la fusion de CAM. C'est une lacune pour un projet dont l'argument est la comparaison.

Autre point : aucune release n'apparaît dans les informations disponibles, et le dépôt n'expose pas de page d'accueil. Le dernier push est daté du 13 août 2026. Le projet n'est pas archivé, mais l'absence de version taguée signifie que vous dépendrez d'un commit de main. Pour un travail de reproduction, c'est acceptable si vous notez le commit. Pour une dépendance de service, c'est un risque de dérive silencieuse, d'autant que transformers est épinglé à 4.44.2 et que toute montée de version devra être testée contre les chemins d'attention personnalisés.

Enfin, le dépôt n'est pas le bon outil si vous cherchez une solution clé en main pour réduire la mémoire en production. Il faut écrire un script, choisir un runner, gérer des chemins de modèles locaux, et accepter que la couverture dépende de la méthode. Le README le signale lui-même pour les méthodes récentes.

Face à vLLM : bibliothèque d'exécution contre banc de mesure

L'alternative la plus évidente pour servir un modèle à contexte long est vLLM, qui implémente la gestion de mémoire paginée du cache KV au niveau du moteur d'inférence. La différence d'approche est structurelle. vLLM optimise l'exécution : il alloue le cache par blocs, partage les pages entre séquences et vise le débit en service. KVCache-Factory ne cherche pas à servir des requêtes concurrentes ; il instrumente l'attention pour appliquer une politique d'éviction, de sélection ou de fusion, puis mesure l'effet sur des jeux de données de compréhension longue.

Autrement dit, vLLM répond à « comment exécuter ce modèle plus efficacement », KVCache-Factory répond à « quelle politique de compression préserve le mieux la qualité, et à quel budget ». Les deux ne s'excluent pas conceptuellement, mais le dépôt ne fournit aucun chemin d'intégration vers un moteur de service. Si votre besoin est de réduire la facture GPU d'une API existante, regarder du côté d'un moteur d'inférence est plus direct. Si votre besoin est de produire un tableau comparatif défendable entre PyramidKV, SnapKV et H2O sur LongBench, le dépôt est construit pour cela.

Licence et coût de maintenance

Le dépôt est publié sous licence MIT. Concrètement, cela autorise la réutilisation, la modification et la redistribution, y compris dans un produit propriétaire, à condition de conserver l'avis de copyright et le texte de la licence. Cette description est informative et ne constitue pas un avis juridique : les modèles que vous chargez avec --model_path ont leurs propres licences, et c'est cette combinaison qu'il faut vérifier avant toute redistribution.

Sur la maintenance, les éléments disponibles sont limités. Le projet a été renommé fin novembre 2024, a reçu le support multi-GPU pour les grands modèles dont Llama-3-70B-Instruct le 25 juin 2024, et les chemins FlashAttention v2 plus SDPA le 10 juin 2024. Aucune release n'est listée. La dépendance à transformers==4.44.2 est le principal coût caché : les API d'attention de cette bibliothèque bougent, et un fork qui s'y accroche demande une vérification à chaque mise à jour. Le fait que --kv_cache_granularity kv_head soit annoncé avec une validation GPU en attente pour adakv et headkv indique que certains chemins sont arrivés avant d'être validés sur matériel. Prévoyez de tester vous-même ces combinaisons plutôt que de vous fier au tableau des méthodes.

Conclusion éditoriale

KVCache-Factory convient à qui doit comparer plusieurs politiques de compression KV sur LongBench, RULER ou needle-in-a-haystack avec un seul jeu d'arguments. Il ne convient pas à qui veut une bibliothèque de production stable : la couverture des runners varie selon les méthodes, la validation GPU de --kv_cache_granularity kv_head est annoncée comme en attente, et le dépôt n'a publié aucune release. Avant de vous engager, vérifiez le choix de --attn_implementation pour la méthode visée, puis confirmez que le runner accepte bien la méthode et le modèle que vous comptez utiliser.

Sources officielles

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