LMCache-Tutorial: Eine skalierbare KV-Cache-Schicht für LLM-Inferenz aufbauen

Die Inferenz großer Sprachmodelle (LLM-Inference) wird mit wachsender Prompt-Länge zunehmend teuer. 

RAG-Systeme, Coding-Agents, Multi-Agent-Workflows und lange Gespräche schicken dem Modell häufig immer wieder dieselben Dokumente, System-Prompts, Tool-Definitionen oder Gesprächsverläufe.

Jedes Mal, wenn dieser gemeinsame Kontext im Prefill verarbeitet wird, erzeugt das Modell Key-Value-(KV)-Zustände, die während der Token-Generierung genutzt werden. 

Diese Zustände für denselben Kontext immer wieder neu zu berechnen, verschwendet GPU-Rechenzeit und erhöht die Latenz.

LMCache löst dieses Problem, indem es der Inferenz-Stack um eine dedizierte KV-Cache-Schicht erweitert. 

Es kann zuvor berechnete KV-Zustände speichern und über Anfragen und Inferenz-Worker hinweg wiederverwendbar machen und unterstützt dabei CPU, lokalen Speicher, Remote-Backends und disaggregierte Serving-Architekturen.

In diesem Tutorial zeige ich dir, wie LMCache funktioniert, wie es sich vom nativen KV-Caching von vLLM unterscheidet und wie Features wie Multi-Tier-Speicher, Shared Caching, CacheBlend sowie Prefill/Decode-Disaggregation in modernes LLM-Serving passen. 

Anschließend verbindest du LMCache mit vLLM, servest IBM Granite 4.2 3B und führst ein kontrolliertes Experiment durch, um zu messen, wie sich die Wiederverwendung eines großen gemeinsamen Prefix auf die Inferenzlatenz auswirkt.

Was ist LMCache?

LMCache ist eine Open-Source-KV-Cache-Management-Schicht für LLM-Inferenz. 

Sie ermöglicht es, während des Prefill erzeugte Key-Value-Zustände zu speichern und wiederzuverwenden, wenn zukünftige Anfragen dasselbe Prompt-Prefix teilen.

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

Das unterscheidet sich von klassischem Response-Caching. 

Ein Response-Cache speichert die finale Antwort und liefert sie zurück, wenn dieselbe Anfrage erneut erscheint:

cache = {
    "What is Python?":
        "Python is a general-purpose programming language..."
}Bereitgestellt von

LMCache setzt früher im Inferenzprozess an. Statt die finale Antwort zu cachen, speichert es die Attention-KV-Zustände, die entstehen, während das Modell den Prompt verarbeitet.

Ohne wiederverwendbares KV-Caching muss ein langes gemeinsames Prompt bei jeder neuen Frage erneut durch das Prefill. 

Mit LMCache führt die erste Anfrage das vollständige Prefill aus und speichert die resultierenden KV-Zustände. Spätere Anfragen mit demselben Prefix können diese Zustände laden und nur die neuen Tokens verarbeiten.

Abb. 1: Ohne wiederverwendbaren KV-Cache wird das gesamte Prompt bei jeder Anfrage neu berechnet; mit LMCache werden gecachte KV-Zustände wiederverwendet und nur neue Tokens verarbeitet.

Das wird mit wachsenden Kontextfenstern immer wertvoller. 

Ein paar hundert Tokens erneut zu verarbeiten, ist günstig. Zehntausende gemeinsame Tokens wiederholt zu verarbeiten, erhöht Latenz und GPU-Auslastung jedoch deutlich.

Wie LMCache funktioniert

Am einfachsten verstehst du LMCache, wenn wir zwei Anfragen mit demselben Prefix verfolgen.

Bei der ersten Anfrage prüft LMCache, ob wiederverwendbare KV-Zustände existieren. Weil der Prompt zum ersten Mal auftaucht, ergibt die Suche einen Cache-Miss.

vLLM führt dann das Prefill auf der GPU aus, erstellt die KV-Zustände und übergibt sie an LMCache zur Speicherung.

Bei der zweiten Anfrage bleibt das gemeinsame Prefix gleich, aber die Frage ändert sich.

LMCache führt erneut eine Suche aus. Dieses Mal ist das Prefix bereits vorhanden, also gibt es einen Cache-Hit. Die gecachten Zustände werden wiederverwendet, und die GPU muss nur den nicht gecachten Suffix verarbeiten.

Abb. 2: Erste Anfrage mit neuem Prefix verfehlt den Cache, daher berechnet vLLM das Prefill und speichert die KV-Zustände in LMCache; eine Wiederholungsanfrage mit demselben Prefix trifft den Cache und berechnet nur den neuen Suffix.

Wichtig ist: LMCache verlangt nicht, dass die gesamte Anfrage identisch ist. Entscheidend ist das wiederverwendbare Prefix.

Damit eignet es sich besonders für Anwendungen, bei denen der Hintergrundkontext gleich bleibt, während sich die Nutzerfrage ändert.

vLLM Prefix-Cache vs. LMCache

vLLM unterstützt bereits automatisches Prefix-Caching. Da liegt die Frage nahe, wozu LMCache überhaupt gebraucht wird.

Beide Ansätze wollen vermeiden, KV-Zustände für Prompt-Prefixe neu zu berechnen, die das Modell schon gesehen hat. 

Der Hauptunterschied liegt darin, wo der Cache lebt und wie breit er wiederverwendet werden kann.

Der eingebaute Prefix-Cache von vLLM ist die einfachere Option, wenn wiederholte Anfragen vom selben Inferenz-Server bearbeitet werden. 

Beginnen mehrere Anfragen mit denselben Tokens, kann vLLM vorhandene KV-Blöcke wiederverwenden, statt das gesamte Prefill erneut auszuführen.

LMCache erweitert diese Idee über die Inferenz-Engine hinaus.

Anstatt wiederverwendbare KV-Zustände nur im vLLM-eigenen Cache zu halten, führt LMCache eine separate Cache-Schicht ein, die KV-Zustände über zusätzliche Speichertiers speichern und verschieben und sie einer breiteren Serving-Architektur verfügbar machen kann.

Eine einfache Denkhilfe für den Unterschied ist:

Abb. 3: vLLM-Prefix-Caching vs. LMCache. LMCache ergänzt eine Cache-Schicht, die KV-Zustände über CPU-Speicher, lokale SSD/NVMe und Remote-Speicher tiered, statt nur GPU-Speicher zu nutzen.

LMCache ersetzt also nicht das KV-Caching in vLLM, sondern erweitert das KV-Cache-Management über die üblichen Grenzen der Inferenz-Engine hinaus.

Kernfunktionen von LMCache

LMCache ist mehr als ein einfacher In-Memory-Cache. Es wurde entwickelt, um KV-Zustände über verschiedene Speichertiers und Inferenz-Worker zu speichern, zu bewegen und wiederzuverwenden.

1. KV-Cache-Wiederverwendung

Die Hauptfunktion von LMCache ist die Wiederverwendung zuvor berechneter KV-Zustände, anstatt dieselben Tokens erneut durchs Modell zu schicken.

Das ist besonders nützlich, wenn Anfragen wiederholt denselben oder ähnlichen Kontext enthalten, zum Beispiel:

• Abgerufene Dokumente
• Große System-Prompts
• Repository-Kontext
• Gesprächsverläufe
• Tool-Definitionen
• Geteilte Instruktionen zwischen Agents

Durch die Wiederverwendung gecachter KV-Zustände kann LMCache wiederholte Prefill-Berechnungen reduzieren und die Time-to-First-Token verbessern.

2. Multi-Tier-Speicher

GPU-Speicher ist begrenzt und teuer, insbesondere bei langen Kontexten.

LMCache kann KV-Zustände über den GPU-Speicher hinaus verschieben und über mehrere Tiers ablegen, einschließlich CPU-Speicher, lokale SSD- oder NVMe-Laufwerke sowie Remote- oder verteilte Speicher.

So lässt sich deutlich mehr wiederverwendbarer Kontext vorhalten, als in den GPU-Speicher passen würde, während häufig genutzte KV-Zustände bei Bedarf wieder zur GPU zurückbefördert werden.

3. Gemeinsamer KV-Cache über Worker hinweg

LMCache kann gecachte KV-Zustände mehreren Inferenz-Workern zugänglich machen, statt sie an einen einzelnen Modellprozess zu binden.

Wenn z. B. ein vLLM-Worker ein langes Dokument verarbeitet, kann ein anderer Worker die gecachten KV-Zustände potenziell wiederverwenden, statt denselben Kontext neu zu berechnen.

Das ist besonders nützlich für verteiltes Serving, Multi-GPU-Deployments und Anwendungen, bei denen Anfragen über mehrere Inferenz-Replikas geroutet werden.

4. vLLM-Integration

LMCache integriert sich über die KV-Connector-Schnittstelle in vLLM.

Die Anwendung kann weiterhin mit dem OpenAI-kompatiblen vLLM-Endpoint kommunizieren, während LMCache unterhalb der Inferenzschicht arbeitet.

Bestehende Anwendungen müssen also weder das Senden von Prompts noch den Empfang von Antworten ändern. LMCache übernimmt die KV-Speicherung und -Abrufe zwischen vLLM und dem konfigurierten Cache-Backend.

5. Multiprozess-Architektur

LMCache kann als separater Prozess von vLLM laufen.

Anstatt das Cache-Management in jedem Inferenz-Worker zu belassen, kann ein dedizierter LMCache-Server KV-Zustände unabhängig verwalten und mehreren vLLM-Prozessen dienen.

Das trennt Cache-Management vom Model-Serving, erlaubt das Teilen desselben Caches über mehrere Worker und erleichtert es, die Cache-Kapazität unabhängig von den GPU-Inferenzressourcen zu skalieren.

6. CacheBlend

Traditionelles Prefix-Caching funktioniert am besten, wenn Anfragen denselben Prompt-Anfang teilen. 

LMCache bietet mit CacheBlend Unterstützung für Workloads, bei denen wiederverwendbare Inhalte an unterschiedlichen Positionen auftauchen können.

Ein RAG-System könnte z. B. dieselben Dokumente in unterschiedlicher Reihenfolge für verschiedene Fragen abrufen. 

CacheBlend kann Teile zuvor berechneter KV-Zustände wiederverwenden und selektiv nur die Tokens neu berechnen, die vom neuen Kontext abhängen.

So wird die KV-Wiederverwendung für RAG, Multi-Dokument-Anwendungen und agentische Workflows nützlicher, in denen Prompts häufig umgeordnet werden.

7. Prefill- und Decode-Disaggregation

LMCache kann zudem KV-Zustände zwischen separaten Prefill- und Decode-Workern übertragen.

In dieser Architektur verarbeitet eine GPU-Gruppe die rechenintensive Prompt-Phase, während eine andere die Token-Generierung übernimmt. 

LMCache stellt die Schicht bereit, über die die resultierenden KV-Zustände zwischen ihnen bewegt werden.

So lassen sich Prefill- und Decoding-Ressourcen unabhängig skalieren und die GPU-Auslastung in größeren Inferenz-Deployments verbessern.

Erste Schritte mit LMCache 

Jetzt, da wir LMCache verstanden haben, verbinden wir es mit vLLM, einer leistungsstarken LLM-Inferenz-Engine für effizientes Serving und Speichermanagement.

Für diese Anleitung nutze ich IBM Granite 4.2 3B, ein kompaktes Modell mit starker Leistung für seine Größe, das sich gut für Praxistests eignet.

Wir betreiben LMCache im Multiprozess-Modus neben vLLM und überprüfen, dass KV-Zustände über Anfragen hinweg wiederverwendet werden können.

1. Umgebung einrichten

Für dieses Tutorial verwenden wir Python 3.12, uv, vLLM, LMCache, den OpenAI-Python-Client, pandas und matplotlib.

Stelle vorab sicher, dass du Folgendes hast:

• Eine NVIDIA-GPU mit passenden Treibern
• Das CUDA-13-Toolkit installiert und im System verfügbar
• uv installiert

Du kannst uv so installieren:

curl -LsSf https://astral.sh/uv/install.sh | shBereitgestellt von

Dann erstelle das Projekt:

mkdir lmcache-tutorial
cd lmcache-tutorialBereitgestellt von

Erstelle und aktiviere eine Python-3.12-virtuelle Umgebung:

uv venv --python 3.12
source .venv/bin/activateBereitgestellt von

Installiere die benötigten Abhängigkeiten:

uv pip install -U \
    "lmcache==0.5.4" \
    "vllm==0.28.0" \
    openai \
    pandas \
    matplotlib \
    --torch-backend=cu130Bereitgestellt von

Hier verwenden wir cu130, weil unsere Umgebung mit CUDA 13 eingerichtet ist. 

Wenn du eine andere CUDA-Version nutzt, passe den Wert von --torch-backend an das kompatible PyTorch-Backend deiner Umgebung an.

Granite 4.2 verwendet einen eigenen Reasoning-Parser. Lade ihn daher von Hugging Face herunter:

hf download ibm-granite/granite-4.2-3b \
    granite_thinking_parser.py \
    --local-dir .Bereitgestellt von

Prüfe abschließend, ob GPU und CUDA-Installation erkannt werden:

nvidia-smiBereitgestellt von

Für dieses Tutorial verwenden wir eine NVIDIA GeForce RTX 5070 Ti mit 16 GB VRAM. 

Das System läuft mit NVIDIA-Treiber 580.126.09 und unterstützt CUDA 13.0. 

2. vLLM mit LMCache starten 

Wir benötigen zwei laufende Prozesse: einen für den LMCache-Server und einen für vLLM.

Starte LMCache im ersten Terminal:

lmcache server \
    --host localhost \
    --port 6555 \
    --http-port 8081 \
    --l1-size-gb 20 \
    --eviction-policy LRUBereitgestellt von

Hier nutzen wir:

• Port 6555 für die Kommunikation zwischen vLLM und LMCache
• Port 8081 für die HTTP-Schnittstelle von LMCache
• 20 GB für den L1-Cache
• LRU als Eviction-Policy

Lass dieses Terminal geöffnet.

Öffne ein zweites Terminal, aktiviere dieselbe virtuelle Umgebung und entferne die Konfiguration des erweiterbaren CUDA-Allocators, falls gesetzt:

cd lmcache-tutorial
source .venv/bin/activate
unset PYTORCH_CUDA_ALLOC_CONFBereitgestellt von

Starte nun vLLM mit dem LMCache-Connector: 

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"
    }
  }'Bereitgestellt von

Wir deaktivieren das eingebaute Prefix-Caching von vLLM mit:

--no-enable-prefix-cachingBereitgestellt von

So konzentrieren sich die folgenden Experimente gezielt auf die KV-Wiederverwendung durch LMCache.

Sobald vLLM geladen ist, ist das Modell über den OpenAI-kompatiblen Endpoint erreichbar:

http://localhost:8000/v1Bereitgestellt von

3. LMCache mit einem kontrollierten Cache-Hit prüfen

Wir führen nun ein einfaches, kontrolliertes Experiment durch, um zu bestätigen, dass LMCache funktioniert.

Wir erstellen ein großes gemeinsames Prefix, leeren den Cache, senden das Prefix einmal, um LMCache zu befüllen, und schicken dann eine weitere Anfrage mit demselben Prefix, aber anderer Frage.

Erstelle zuerst den OpenAI-Client:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="local",
)Bereitgestellt von

Als Nächstes erstellst du ein langes gemeinsames Dokument:

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}
"""Bereitgestellt von

Durch die 500-fache Wiederholung entsteht ein großes gemeinsames Prefix, dessen Wiederverwendung den Effekt sichtbar macht.

Leere vor der ersten Anfrage den LMCache, damit wir mit einem leeren Cache starten:

import subprocess
import time

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

time.sleep(0.5)Bereitgestellt von

So stellst du sicher, dass die erste Anfrage eine Cold-Cache-Anfrage ist und keine KV-Zustände aus früheren Tests nutzen kann.

Sende nun die erste Anfrage:

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() - startBereitgestellt von

Das ist die Cache-Warming-Anfrage. vLLM muss das lange gemeinsame Prefix im Prefill verarbeiten, während LMCache die entstehenden KV-Zustände speichert.

Als Nächstes bleibt das gemeinsame Prefix exakt gleich; wir ändern nur die Frage:

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() - startBereitgestellt von

Weil das große Prefix unverändert ist, kann LMCache die KV-Zustände der ersten Anfrage wiederverwenden, statt das komplette Prefix neu zu berechnen.

Vergleiche zum Schluss die beiden Antwortzeiten:

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}%"
)Bereitgestellt von

Mein Lauf ergab:

Cold request:   26.276s
Warm request:   4.402s
Speedup:        5.97x
Latency saved:  83.2%Bereitgestellt von

Die Warm-Anfrage war fast 6× schneller und senkte die End-to-End-Latenz um 83,2%.

Die Fragen sind unterschiedlich, LMCache cached also nicht die finale Antwort. Es wiederverwendet die für das gemeinsame Prefix erzeugten KV-Zustände.

Die erste Anfrage muss das gesamte lange Prefix im Prefill verarbeiten und diese KV-Zustände von Grund auf berechnen. 

Bei der zweiten Anfrage ruft LMCache die passenden gecachten Zustände ab, sodass vLLM den Großteil der wiederholten Prefill-Arbeit überspringen und sich auf den neuen Suffix konzentrieren kann.

Damit ist bestätigt, dass LMCache das gemeinsame Prefix erfolgreich wiederverwendet. 

Wann ist LMCache nützlich?

LMCache ist besonders nützlich, wenn eine Anwendung wiederholt große Mengen identischen Kontexts sendet.

Häufige Beispiele sind:

RAG-Anwendungen

Ein:e Nutzer:in stellt mehrere Fragen zu demselben abgerufenen Dokument.

Statt das gesamte Dokument für jede Frage neu zu verarbeiten, können dessen KV-Zustände wiederverwendet werden.

Coding-Agents

Coding-Assistenten schicken bei jedem Modellaufruf häufig Repository-Dateien, Projektanweisungen und andere große Kontexte mit.

Vieles davon bleibt gleich, während die Aufgabe wechselt.

KI-Agents

Agents wiederverwenden oft große System-Prompts, Tool-Definitionen, Memory, Instruktionen und Zustände der Umgebung über viele Schritte.

Lange Gespräche

Ein langes Gespräch sendet bei jeder neuen Nachricht häufig einen großen Teil seiner Historie erneut.

Multi-Agent-Systeme

Mehrere Agents teilen sich dieselben Hintergrunddokumente oder denselben Systemkontext, während sie an unterschiedlichen Aufgaben arbeiten.

In all diesen Fällen wird dem Modell wiederholt Information gezeigt, die es bereits bei früheren Anfragen verarbeitet hat.

LMCache bietet eine Möglichkeit, diese Arbeit auf KV-Cache-Ebene wiederzuverwenden.

Fazit

LMCache reduziert eine große Verschwendungsquelle bei Long-Context-Inferenz, indem es die im Prefill erzeugten KV-Zustände wiederverwendbar macht. 

Anstatt denselben gemeinsamen Kontext immer wieder zu verarbeiten, kann das Modell bereits erledigte Arbeit nutzen.

Wir haben in diesem Tutorial weder den Benchmark-Code noch detaillierte Ergebnisse aufgenommen, aber mit demselben Setup eigene Tests durchgeführt. 

Die Ergebnisse waren deutlich: Die Wiederverwendung eines großen gemeinsamen Prefix senkte die Gesamtlatenz einer Anfrage von 26,276 Sekunden auf 4,386 Sekunden. 

Die durchschnittliche Time-to-First-Token sank von 22,149 Sekunden auf 0,726 Sekunden, eine 30,54×-Verbesserung. Die Vorteile wuchsen mit der Kontextgröße: von 3,55× bei ca. 12.000 gemeinsamen Zeichen auf 30,22× bei rund 245.000 Zeichen. 

Einfach gesagt: Je mehr Kontext wiederverwendet werden kann, desto mehr Arbeit kann LMCache einsparen.

DeepSeek ist ein gutes Praxisbeispiel dafür, warum das zählt.

Das Caching-System kann passende Prompt-Prefixe wiederverwenden – besonders wertvoll für Coding-Agents, die wiederholt dieselben System-Prompts, Tools, Gesprächshistorien und Code-Kontexte senden. 

Höhere Cache-Hit-Raten bedeuten weniger wiederholte Berechnung und geringere Kosten – für Anbieter und Nutzende.

Die wichtigste Erkenntnis: Schnellere LLM-Inferenz hängt nicht nur von besseren GPUs oder schnellerer Token-Generierung ab. Es geht auch darum, unnötige Wiederholungsarbeit zu vermeiden. 

Für RAG-Systeme, Coding-Assistenten, Agents und andere Long-Context-Anwendungen kann wiederverwendbares KV-Caching ein wichtiger Hebel für geringere Latenz, weniger GPU-Nutzung und niedrigere Inferenzkosten sein.