vLLM Prefix-Caching im Eigenbetrieb: Messbar weniger Tokens

Prefix-Caching ist eine dieser Optimierungen, die im Benchmark beeindruckend klingen, im Betrieb aber erst richtig wirken, wenn man sie misst. Wir haben --enable-prefix-caching und --enable-prompt-tokens-details am 19. August 2026 auf unserem lokalen Qwen3.8-27B aktiviert — und sehen seitdem konkrete Zahlen.

Wie Prefix-Caching in vLLM funktioniert

vLLM organisiert den KV-Cache nicht linear, sondern in PagedAttention-Blöcken. Jeder Block repräsentiert einen Ausschnitt der bereits berechneten Attention. Wenn eine neue Anfrage ankommt, vergleicht vLLM deren Präfix mit den vorhandenen Blöcken. Bei einer Übereinstimmung werden die passenden Blöcke referenziert, statt neu berechnet zu werden.

Das ist besonders wertvoll für Workloads mit langem, wiederkehrendem Kontext: Systemanweisungen, RAG-Dokumente, Tool-Schemas oder wiederholte strukturelle Prompts. Der Server berechnet den gemeinsamen Teil einmal und nutzt ihn für alle folgenden Anfragen.

Die Messbarkeit war das Fehlende

Prefix-Caching ohne Sichtbarkeit ist nur halb so nützlich. Mit --enable-prompt-tokens-details liefert die API nicht nur:

"usage": {
  "prompt_tokens": 12543,
  "completion_tokens": 892,
  "total_tokens": 13435
}

sondern zusätzlich:

"usage": {
  "prompt_tokens": 12543,
  "prompt_tokens_details": {
    "cached_tokens": 11204,
    "new_tokens": 1339
  },
  "completion_tokens": 892,
  "total_tokens": 13435
}
}

Das Verhältnis von cached zu new sagt sofort, ob ein Prompt-Template gut zum Cache passt. Ein Wert wie 11.204 von 12.543 cached Tokens bedeutet, dass nur knapp 11 % des Prompts neu berechnet werden mussten.

Lokale Implementierung

Die Aktivierung erfolgt über zwei zusätzliche Flags in der vLLM-Kommandozeile:

- "--enable-prefix-caching"
- "--enable-prompt-tokens-details"

Bei Qwen3.8-27B läuft das stabil. Der --reasoning-parser qwen3 und --tool-call-parser qwen3_xml beeinflussen den Cache-Mechanismus nicht; wichtig ist nur, dass sich die Token-Repräsentation des Präfixes nicht zwischen Anfragen ändert.

Was wir beobachten

Nach vier Tagen Dauerbetrieb auf dem 4×-RTX-5090-Host zeigt der Prometheus-Endpoint des Containers:

vllm:prompt_tokens_total: rund 78 Millionen Prefill-Token
vllm:generation_tokens_total: rund 5,9 Millionen generierte Token
Prefix-Cache-Hitrate: etwa 43–45 %

Die API-Details ergänzen dieses Bild um den Cache-Anteil pro Anfrage. Dort, wo lange Dokumente oder Tool-Schemas wiederverwendet werden, liegt der cached-Anteil typischerweise zwischen 70 und 90 Prozent. Bei kurzen Ad-hoc-Anfragen nahe null — genau wie erwartet.

Besonders deutlich wird der Effekt auf dem separaten hermes-Host (192.168.180.202), wo ein einzelner RTX-5090-Agent mit aktiviertem Prefix-Caching arbeitet. Ein 150.000-Token-Wiederholprompt, bei dem Systemanweisung und Tool-Schema identisch bleiben, brach von 53,2 s auf 2,3 s ein — bei einer gemessenen Cache-Hitrate von 93,5 %.

Einschränkungen

Prefix-Caching ist kein Allheilmittel. Es bringt nichts, wenn:

jede Anfrage einen völlig anderen Kontext hat,
der Cache durch viele parallele, unterschiedliche Prompts ständig invalidiert wird,
oder die Prompt-Reihenfolge variiert (verschachtelte Präfixe werden nicht immer erkannt).

Auch der Speicherbedarf steigt leicht, weil vLLM die Cache-Blöcke länger vorhält. Auf unserem Host mit 128 GB VRAM ist das kein Thema; auf kleineren Karten kann es aber die maximal verfügbare KV-Cache-Größe marginal reduzieren.

Unsere Sicht

Prefix-Caching ist eine kostenlose Verbesserung für Workloads mit wiederkehrendem Kontext. Die wichtigste Erkenntnis: der Cache-Anteil muss messbar sein, sondern optimiert man im Blindflug. --enable-prompt-tokens-details ist der entscheidene Schalter, um den Effekt sichtbar zu machen. Wer vLLM selbst betreibt und lange Prompts wiederverwendet, sollte beide Flags aktivieren.

Weiterführende Quellen

Fragen?

Was macht --enable-prefix-caching in vLLM?+

vLLM verwaltet den Key-Value-Cache blockweise. Wenn mehrere Anfragen dasselbe Prompt-Präfix teilen — zum Beispiel Systemanweisung, Dokumentenkontext oder wiederkehrende Tool-Schemas — berechnet der Server diese Blöcke nur einmal und gibt sie wieder aus. Das spart Rechenzeit und reduziert die Latenz beim Time-to-First-Token.

Was bringt --enable-prompt-tokens-details?+

Ohne dieses Flag sieht der Aufrufer nur die Gesamtzahl der Prompt-Token. Mit dem Flag teilt vLLM die usage in cached_tokens und new_tokens auf. Damit lässt sich messen, wie viel des Prompts tatsächlich neu berechnet wurde und wie viel aus dem Cache kam.

Wo sieht man die Cached-Token in unserem Stack?+

Der Prometheus-Endpoint des vLLM-Containers liefert vllm:prompt_tokens_total und vllm:generation_tokens_total. In Verbindung mit den usage_details aus der OpenAI-kompatiblen API entsteht ein klares Bild: nach vier Tagen Betrieb lagen bei uns rund 78 Millionen Prefill-Token und knapp 6 Millionen generierte Token vor — die Verteilung zwischen cached und new zeigt, wo sich Prefix-Caching lohnt.

Lohnt sich Prefix-Caching für jeden Use-Case?+

Nein. Der Effekt ist am stärksten, wenn viele Anfragen denselben langen Kontext teilen — zum Beispiel RAG über denselben Dokumentensatz, wiederkehrende Tool-Definitionen oder lange System-Prompts. Bei kurzen, einmaligen Prompts bringt das Flag praktisch nichts und kostet nur minimalen Overhead für die Cache-Verwaltung.