Tutoriel LMCache : créer une couche de cache KV évolutive pour l’inférence des LLM

L’inférence des grands modèles de langage devient de plus en plus coûteuse à mesure que les invites s’allongent. 

Les systèmes RAG, les agents de codage, les workflows multi-agents et les longues conversations renvoient souvent, encore et encore, les mêmes documents, invites système, définitions d’outils ou historiques de conversation au modèle.

Chaque fois que ce contexte partagé est traité pendant le préremplissage (prefill), le modèle génère des états clé-valeur (KV) utilisés lors de la génération de tokens. 

Recalculer ces états pour le même contexte gaspille des ressources GPU et augmente la latence.

LMCache répond à ce problème en ajoutant une couche de cache KV dédiée dans la pile d’inférence. 

Il peut stocker des états KV calculés précédemment et les rendre réutilisables entre requêtes et workers d’inférence, tout en prenant en charge le CPU, le stockage local, des backends distants et des architectures de service désagrégées.

Dans ce tutoriel, je vous montre comment fonctionne LMCache, en quoi il diffère du cache KV natif de vLLM, et où s’inscrivent des fonctionnalités comme le stockage multi-niveaux, le cache partagé, CacheBlend et la désagrégation préremplissage/décodage dans le déploiement moderne des LLM. 

Vous connecterez ensuite LMCache à vLLM, servirez IBM Granite 4.2 3B et exécuterez une expérience contrôlée pour mesurer l’impact de la réutilisation d’un large préfixe commun sur la latence d’inférence.

Qu’est-ce que LMCache ?

LMCache est une couche de gestion de cache KV open source pour l’inférence LLM. 

Elle permet de stocker les états clé-valeur créés pendant le préremplissage et de les réutiliser lorsque de futures requêtes partagent le même préfixe d’invite.

Source : LMCache – Building the foundation of AI memory tensor with KV Cache Infrastructure 

C’est différent d’un cache de réponse traditionnel. 

Un cache de réponse stocke la réponse finale générée et la renvoie quand la même requête réapparaît :

cache = {
    "What is Python?":
        "Python is a general-purpose programming language..."
}Propulsé par

LMCache intervient plus tôt dans le processus d’inférence. Au lieu de mettre en cache la réponse finale, il conserve les états d’attention KV produits pendant que le modèle traite l’invite.

Par exemple, sans cache KV réutilisable, un long préfixe partagé doit repasser par le préremplissage à chaque nouvelle question ajoutée. 

Avec LMCache, la première requête effectue le préremplissage complet et stocke les états KV résultants. Les requêtes suivantes avec le même préfixe peuvent charger ces états et ne traiter que les nouveaux tokens.

Fig. 1 : sans cache KV réutilisable, l’intégralité de l’invite est recomputée à chaque requête ; avec LMCache, les états KV mis en cache sont réutilisés et seuls les nouveaux tokens sont traités.

La valeur ajoutée croît avec la taille des fenêtres de contexte. 

Repasser quelques centaines de tokens peut coûter peu, mais traiter à répétition des dizaines de milliers de tokens partagés augmente fortement la latence et l’usage GPU.

Comment fonctionne LMCache

La manière la plus simple de comprendre LMCache est de suivre deux requêtes partageant le même préfixe.

Pour la première requête, LMCache vérifie si des états KV réutilisables existent déjà. Comme c’est la première occurrence de cette invite, la recherche aboutit à un « cache miss ».

vLLM exécute alors le préremplissage sur le GPU, crée les états KV et les transmet à LMCache pour stockage.

Pour la seconde requête, le préfixe partagé reste identique, mais la question change.

LMCache effectue une nouvelle recherche. Cette fois, le préfixe est disponible : « cache hit ». Les états mis en cache sont réutilisés et le GPU ne traite que le suffixe non mis en cache.

Fig. 2 : première requête avec un nouveau préfixe : échec de cache, donc vLLM calcule le préremplissage et stocke les états KV dans LMCache ; une requête ultérieure avec le même préfixe touche le cache et ne calcule que le nouveau suffixe.

L’essentiel est que LMCache n’exige pas que l’ensemble de la requête soit identique. C’est le préfixe réutilisable qui compte.

Cela le rend particulièrement adapté aux applications où le contexte de fond reste le même tandis que la requête utilisateur évolue.

Cache de préfixe vLLM vs LMCache

vLLM prend déjà en charge le cache de préfixe automatique ; il est donc légitime de se demander pourquoi LMCache est nécessaire.

Les deux approches visent à éviter de recalculer les états KV pour des préfixes d’invite déjà traités par le modèle. 

La principale différence tient à l’emplacement du cache et à l’étendue de sa réutilisation.

Le cache de préfixe intégré de vLLM est l’option la plus simple lorsque des requêtes répétées sont traitées par le même serveur d’inférence. 

Si plusieurs requêtes commencent par les mêmes tokens, vLLM peut réutiliser les blocs KV existants au lieu de refaire tout le préremplissage.

LMCache étend cette idée au‑delà du moteur d’inférence.

Plutôt que de conserver les états KV réutilisables uniquement dans le cache propre à vLLM, LMCache introduit une couche de cache séparée qui peut stocker et déplacer des états KV sur des niveaux de stockage supplémentaires et les rendre disponibles à une architecture de service plus large.

Une façon simple de visualiser la différence :

Fig. 3 : cache de préfixe vLLM vs LMCache. LMCache ajoute une couche de cache qui étage les états KV entre mémoire CPU, SSD/NVMe local et stockage distant, au lieu de se limiter à la mémoire GPU.

Ainsi, LMCache ne remplace pas le cache KV de vLLM ; il étend la gestion du cache KV au‑delà des frontières habituelles du moteur d’inférence.

Fonctionnalités clés de LMCache

LMCache va bien au‑delà d’un simple cache en mémoire. Il est conçu pour stocker, déplacer et réutiliser des états KV entre différents niveaux de stockage et workers d’inférence.

1. Réutilisation du cache KV

La fonctionnalité principale de LMCache est la capacité à réutiliser des états KV calculés précédemment au lieu de refaire passer les mêmes tokens dans le modèle.

C’est particulièrement utile lorsque les requêtes incluent à répétition le même contexte ou un contexte similaire, comme :

• Documents récupérés
• Grandes invites système
• Contexte de dépôt (repository)
• Historique de conversation
• Définitions d’outils
• Instructions partagées entre agents

En réutilisant les états KV mis en cache, LMCache diminue les préremplissages répétés et améliore le temps jusqu’au premier token.

2. Stockage multi‑niveaux

La mémoire GPU est limitée et coûteuse, surtout avec de longs contextes.

LMCache peut déplacer les états KV hors de la mémoire GPU et les stocker sur plusieurs niveaux : mémoire CPU, SSD ou NVMe local, et stockage distant ou distribué.

Cela permet de conserver bien plus de contexte réutilisable que ce qui tiendrait en mémoire GPU, tout en rapatriant sur GPU les états KV fréquemment utilisés quand nécessaire.

3. Cache KV partagé entre workers

LMCache peut rendre des états KV mis en cache disponibles pour plusieurs workers d’inférence, au lieu de les lier à un seul processus modèle.

Par exemple, si un worker vLLM traite un long document, un autre worker peut potentiellement réutiliser les états KV mis en cache, plutôt que de recalculer le même contexte.

C’est particulièrement utile pour le service distribué, les déploiements multi‑GPU et les applications où les requêtes sont routées entre plusieurs réplicas d’inférence.

4. Intégration vLLM

LMCache s’intègre à vLLM via son interface de connecteur KV.

L’application continue de communiquer avec l’endpoint vLLM compatible OpenAI habituel, tandis que LMCache opère sous la couche d’inférence.

Les applications existantes n’ont donc pas besoin de changer la manière d’envoyer les invites ou de recevoir les réponses. LMCache gère le stockage et la récupération des KV entre vLLM et le backend de cache configuré.

5. Architecture multiprocessus

LMCache peut s’exécuter dans un processus séparé de vLLM.

Au lieu de gérer le cache au sein de chaque worker d’inférence, un serveur LMCache dédié peut gérer les états KV de façon indépendante et servir plusieurs processus vLLM.

Cette séparation entre gestion du cache et service du modèle permet à plusieurs workers de partager le même cache et facilite le dimensionnement du cache indépendamment des ressources GPU d’inférence.

6. CacheBlend

Le cache de préfixe traditionnel fonctionne au mieux quand les requêtes partagent le même début d’invite. 

LMCache propose aussi CacheBlend pour les charges où le contenu réutilisable peut apparaître à des positions différentes.

Par exemple, une application RAG peut récupérer les mêmes documents dans un ordre différent selon la question. 

CacheBlend peut réutiliser des portions d’états KV calculés précédemment tout en recalculant sélectivement les tokens dépendant du nouveau contexte.

Cela rend la réutilisation des KV plus utile pour le RAG, les applications multi‑documents et les workflows agentiques où les invites sont fréquemment réorganisées.

7. Désagrégation préremplissage et décodage

LMCache peut aussi faciliter le transfert d’états KV entre des workers distincts de préremplissage et de décodage.

Dans cette architecture, un groupe de GPU gère l’étape de traitement d’invite, très consommatrice en calcul, tandis qu’un autre groupe gère la génération de tokens. 

LMCache fournit la couche permettant de déplacer les états KV entre ces groupes.

Cela autorise un dimensionnement indépendant des ressources de préremplissage et de décodage et peut améliorer l’utilisation GPU dans des déploiements d’inférence de grande taille.

Prise en main de LMCache 

Maintenant que nous comprenons le fonctionnement de LMCache, connectons‑le à vLLM, un moteur d’inférence LLM haute performance conçu pour un service et une gestion mémoire efficaces.

Pour ce guide, j’utiliserai IBM Granite 4.2 3B, un modèle compact offrant d’excellentes performances pour sa taille tout en restant suffisamment léger pour des tests pratiques.

Nous exécuterons LMCache en mode multiprocessus aux côtés de vLLM et vérifierons que les états KV peuvent être réutilisés entre requêtes.

1. Préparer l’environnement

Pour ce tutoriel, nous utiliserons Python 3.12, uv, vLLM, LMCache, le client Python OpenAI, pandas et matplotlib.

Avant de commencer, assurez‑vous d’avoir :

• Un GPU NVIDIA avec les pilotes appropriés installés
• Le toolkit CUDA 13 installé et disponible sur votre système
• uv installé

Vous pouvez installer uv avec :

curl -LsSf https://astral.sh/uv/install.sh | shPropulsé par

Créez ensuite le projet :

mkdir lmcache-tutorial
cd lmcache-tutorialPropulsé par

Créez et activez un environnement virtuel Python 3.12 :

uv venv --python 3.12
source .venv/bin/activatePropulsé par

Installez les dépendances requises :

uv pip install -U \
    "lmcache==0.5.4" \
    "vllm==0.28.0" \
    openai \
    pandas \
    matplotlib \
    --torch-backend=cu130Propulsé par

Ici, nous utilisons cu130 car notre environnement est configuré avec CUDA 13. 

Si vous utilisez une autre version de CUDA, adaptez la valeur de --torch-backend au backend PyTorch compatible avec votre environnement.

Granite 4.2 utilise un parseur de raisonnement personnalisé ; téléchargez‑le depuis Hugging Face :

hf download ibm-granite/granite-4.2-3b \
    granite_thinking_parser.py \
    --local-dir .Propulsé par

Enfin, vérifiez que votre GPU et votre installation CUDA sont détectés :

nvidia-smiPropulsé par

Pour ce tutoriel, nous utilisons une NVIDIA GeForce RTX 5070 Ti avec 16 Go de VRAM. 

Le système fonctionne avec le pilote NVIDIA 580.126.09, compatible CUDA 13.0. 

2. Démarrer vLLM avec LMCache 

Nous avons besoin de deux processus : un pour le serveur LMCache et un autre pour vLLM.

Démarrez LMCache dans un premier terminal :

lmcache server \
    --host localhost \
    --port 6555 \
    --http-port 8081 \
    --l1-size-gb 20 \
    --eviction-policy LRUPropulsé par

Ici, nous utilisons :

• le port 6555 pour la communication entre vLLM et LMCache
• le port 8081 pour l’interface HTTP de LMCache
• 20 Go pour le cache L1
• LRU comme politique d’éviction

Laissez ce terminal ouvert.

Ouvrez un second terminal, activez le même environnement virtuel et supprimez la configuration de l’allocateur CUDA extensible si elle est activée :

cd lmcache-tutorial
source .venv/bin/activate
unset PYTORCH_CUDA_ALLOC_CONFPropulsé par

Démarrez maintenant vLLM avec le connecteur LMCache : 

vllm serve ibm-granite/granite-4.2-3b \
  --served-model-name granite-4.2-3b \
  --dtype bfloat16 \
  --max-model-len 65536 \
  --kv-cache-dtype fp8 \
  --gpu-memory-utilization 0.90 \
  --enforce-eager \
  --max-num-seqs 1 \
  --max-num-batched-tokens 2048 \
  --no-enable-prefix-caching \
  --reasoning-parser granite_thinking_parser \
  --reasoning-parser-plugin "$(pwd)/granite_thinking_parser.py" \
  --tool-call-parser qwen3_coder \
  --enable-auto-tool-choice \
  --port 8000 \
  --kv-transfer-config \
  '{
    "kv_connector":"LMCacheMPConnector",
    "kv_connector_module_path":"lmcache.integration.vllm.lmcache_mp_connector",
    "kv_role":"kv_both",
    "kv_connector_extra_config":{
      "lmcache.mp.host":"tcp://localhost",
      "lmcache.mp.port":6555,
      "lmcache.mp.mp_transfer_mode":"lmcache_driven"
    }
  }'Propulsé par

Nous désactivons le cache de préfixe intégré de vLLM avec :

--no-enable-prefix-cachingPropulsé par

Cela permet de concentrer les expériences suivantes spécifiquement sur la réutilisation des KV via LMCache.

Une fois vLLM chargé, le modèle est disponible via son endpoint compatible OpenAI :

http://localhost:8000/v1Propulsé par

3. Vérifier LMCache avec un « cache hit » contrôlé

Nous allons maintenant réaliser une expérience simple et contrôlée pour confirmer que LMCache fonctionne.

Nous allons créer un grand préfixe partagé, vider le cache, envoyer une première fois le préfixe pour remplir LMCache, puis envoyer une autre requête avec le même préfixe mais une question différente.

Commencez par créer le client OpenAI :

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="local",
)Propulsé par

Créez ensuite un long document partagé :

base_text = """
Large language model inference consists of two main stages:
prefill and decoding.

During prefill, the model processes the input sequence and calculates
the key and value tensors used by the attention mechanism.

During autoregressive decoding, these tensors are reused so the model
does not need to recompute attention states for every previous token.

KV cache management is therefore an important part of modern LLM
serving infrastructure, particularly for long-context applications.
"""

document = base_text * 500

SYSTEM_PROMPT = f"""
You are a technical assistant.

Use only the following document to answer the user's question.

DOCUMENT:

{document}
"""Propulsé par

Répéter le document 500 fois produit un large préfixe partagé, suffisamment coûteux pour rendre visible l’effet de la réutilisation des KV.

Avant d’envoyer la première requête, videz LMCache afin de partir d’un cache vide :

import subprocess
import time

subprocess.run(
    [
        "lmcache",
        "kvcache",
        "clear",
        "--url",
        "http://localhost:8081",
    ],
    check=True,
)

time.sleep(0.5)Propulsé par

Cela garantit que la première requête est une requête à froid et ne peut pas réutiliser des états KV d’un test antérieur.

Envoyez maintenant la première requête :

prompt_1 = SYSTEM_PROMPT + """

Question:
Explain the purpose of the KV cache.
"""

start = time.perf_counter()

client.completions.create(
    model="granite-4.2-3b",
    prompt=prompt_1,
    max_tokens=100,
    temperature=0,
)

latency_1 = time.perf_counter() - startPropulsé par

C’est la requête de chauffe du cache. vLLM doit traiter le long préfixe partagé pendant le préremplissage, tandis que LMCache stocke les états KV produits.

Ensuite, gardez exactement le même préfixe partagé et ne changez que la question :

prompt_2 = SYSTEM_PROMPT + """

Question:
Explain what happens during prefill.
"""

start = time.perf_counter()

client.completions.create(
    model="granite-4.2-3b",
    prompt=prompt_2,
    max_tokens=100,
    temperature=0,
)

latency_2 = time.perf_counter() - startPropulsé par

Comme le grand préfixe est inchangé, LMCache peut réutiliser les états KV générés par la première requête au lieu de recomputer tout le préfixe.

Enfin, comparez les deux temps de requête :

print(f"Cold request:   {latency_1:.3f}s")
print(f"Warm request:   {latency_2:.3f}s")
print(f"Speedup:        {latency_1 / latency_2:.2f}x")

print(
    f"Latency saved:  "
    f"{((latency_1 - latency_2) / latency_1) * 100:.1f}%"
)Propulsé par

Dans mon exécution, j’ai obtenu :

Cold request:   26.276s
Warm request:   4.402s
Speedup:        5.97x
Latency saved:  83.2%Propulsé par

La requête à chaud s’est terminée presque 6 fois plus vite, réduisant la latence de bout en bout de 83,2 %.

Les questions sont différentes ; LMCache ne met donc pas en cache la réponse finale. Il réutilise plutôt les états KV du préfixe partagé.

La première requête doit traiter l’intégralité du long préfixe pendant le préremplissage et créer ces états KV à partir de zéro. 

Lors de la seconde, LMCache récupère les états mis en cache correspondants, permettant à vLLM d’éviter la majeure partie du préremplissage répété et de se concentrer sur le nouveau suffixe.

Cela confirme que LMCache réutilise bien le préfixe partagé. 

Quand LMCache est‑il utile ?

LMCache est particulièrement utile lorsqu’une application envoie à répétition une grande quantité de contexte identique.

Parmi les cas fréquents :

Applications RAG

Un utilisateur peut poser plusieurs questions à propos du même document récupéré.

Au lieu de traiter le document en entier à chaque question, on réutilise ses états KV.

Agents de codage

Les assistants de codage envoient souvent des fichiers de dépôt, des consignes de projet et d’autres gros blocs de contexte à chaque appel modèle.

Une grande partie de ce contexte reste identique tandis que la tâche évolue.

Agents IA

Les agents réutilisent souvent de grandes invites système, des définitions d’outils, de la mémoire, des instructions et l’état d’environnement sur de nombreuses étapes.

Conversations longues

Une conversation au long cours peut renvoyer une part importante de son historique à chaque nouveau message.

Systèmes multi‑agents

Plusieurs agents peuvent partager les mêmes documents de fond ou le même contexte système tout en travaillant sur des tâches différentes.

Dans tous ces cas, le modèle revoit des informations qu’il a déjà traitées lors de requêtes précédentes.

LMCache offre un moyen de réutiliser ce travail au niveau du cache KV.

Pour conclure

LMCache traite une source majeure de gaspillage dans l’inférence en contexte long en rendant réutilisables les états KV créés pendant le préremplissage. 

Au lieu de retraiter sans cesse le même contexte partagé, le modèle réutilise le travail déjà effectué.

Nous n’incluons pas ici le code de benchmark ni les résultats détaillés, mais nous avons mené une série de tests séparés avec la même configuration. 

Les résultats sont significatifs : la réutilisation d’un large préfixe partagé a réduit la latence totale d’une requête de 26,276 secondes à 4,386 secondes. 

Le temps moyen jusqu’au premier token est passé de 22,149 secondes à 0,726 seconde, soit une amélioration de 30,54 fois. Les gains augmentent aussi avec la taille du contexte, de 3,55 fois avec environ 12 000 caractères partagés à 30,22 fois avec près de 245 000 caractères. 

En clair : plus le contexte réutilisable est important, plus LMCache évite de travail.

DeepSeek illustre bien cet enjeu dans le monde réel.

Son système de cache peut réutiliser des préfixes d’invite identiques, ce qui est particulièrement précieux pour les agents de codage qui renvoient à répétition les mêmes invites système, outils, historiques de conversation et contexte de code. 

Des taux de « cache hit » plus élevés signifient moins de calcul répété et des coûts plus faibles pour le fournisseur comme pour l’utilisateur.

La leçon principale de ce guide : accélérer l’inférence LLM ne tient pas qu’à de meilleurs GPU ou à une génération de tokens plus rapide. Il s’agit aussi de ne pas répéter inutilement le travail. 

Pour les systèmes RAG, assistants de codage, agents et autres applications à contexte long, la réutilisation du cache KV peut jouer un rôle majeur pour améliorer la latence, réduire l’usage GPU et diminuer les coûts d’inférence.