LLM-Prompt-Caching mit Python: ein praxisnahes Code-Tutorial

TL;DR — Ein OpenAI SDK, eine base_url, alle wichtigen LLMs. Die Zahlen in diesem Artikel wurden am 2026-05-25 am produktiven Synthorai-Gateway mit einem stabilen System-Prompt von rund 7.300 Token gemessen. Der Nutzen des Gateways ist dabei bewusst überschaubar: ein Endpoint, ein Auth-Header und ein usage.cost-Feld, durch das keine eigene Preismatrix pro Anbieter gepflegt werden muss. Die Transformer-Grundlagen des Cachings behandelt Teil 1: Grundlagen des Cachings; die unterschiedlichen Ansätze der Anbieter stehen in Teil 2: Anbietervergleich.

Reihe: Teil 3 von 5 · Bisher: Teil 1 — Grundlagen des Cachings · Teil 2 — Anbietervergleich und Bewertung · Als Nächstes: Teil 4 — Das passende LLM für jeden Anwendungsfall · Teil 5 — LangChain-Integration

0. Einrichtung

pip install openai

# common.py — reused across every example
import os, time
from openai import OpenAI

oai = OpenAI(
    api_key=os.environ["SYNTHORAI_KEY"],
    base_url="https://synthorai.io/v1",
)

Das Gateway verwendet für alle angebundenen Modelle das Wire-Format von OpenAI, darunter GPT, Claude, Gemini, DeepSeek und Qwen. Geändert wird nur das model-Feld, nicht das SDK. Die Authentifizierung erfolgt über Authorization: Bearer <key>.

Auf dem öffentlichen Gateway verfügbare Modell-IDs mit Cache-Unterstützung (Stand 2026-05): claude-haiku-4-5, claude-sonnet-4-5 / 4-6, claude-opus-4-5 / 4-6 / 4-7, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5.5-pro, gemini-2.5-flash, gemini-2.5-pro, gemini-3.1-pro-preview, deepseek-v4-flash, qwen3-max, qwen3.5-flash. Die vollständige aktuelle Liste liefert GET /v1/models.

1. Der Cache-fähige Aufruf bei allen Anbietern

Caching muss nicht separat aktiviert werden. Unterstützt ein Modell upstream Prompt-Caching, reicht das Gateway die Metadaten der Antwort durch. Zwei Felder zeigen, was passiert ist:

resp = oai.chat.completions.create(
    model="gpt-5.4-mini",
    max_tokens=128,
    messages=[
        {"role": "system", "content": LONG_STABLE_PROMPT},   # ~7K tokens
        {"role": "user",   "content": "First question"},
    ],
)
print(resp.usage.prompt_tokens_details.cached_tokens)   # cache hit count
print(resp.usage.cost)                                  # USD, gateway-computed

cached_tokens gibt an, wie viele Input-Token im Prefix-Cache des Upstream-Anbieters gefunden wurden. usage.cost enthält die vom Gateway berechneten Kosten dieses einzelnen Aufrufs in USD. Eine lokale Preistabelle pro Anbieter ist damit nicht nötig.

Aus der Architektur ergeben sich zwei Regeln, die für alle Anbieter gelten:

1. Statische Inhalte nach vorn, variable Inhalte nach hinten. Der Prefix wird ab Token null verglichen. Schon eine Änderung von einem Byte am Anfang macht den gesamten Prefix ungültig.
2. Dynamische Daten gehören nicht in den System-Prompt. Aktuelle Zeitstempel, Session-IDs und Request-UUIDs verhindern einen Cache-Hit.

Die folgenden Abschnitte zeigen denselben Ansatz für die einzelnen Anbieter.

2. Anthropic Claude — Explizite cache_control-Marker

Claude gehört zur Familie mit expliziten Markern. Die Anthropic API cached nicht automatisch. Für einen Cache-Hit können im system- oder messages-Array bis zu vier cache_control-Breakpoints gesetzt werden. Cache-Reads kosten rund 10% des regulären Input-Preises, Cache-Writes 125% und damit 25% mehr.

Am einfachsten lässt sich cache_control über das Gateway nutzen, indem das offizielle anthropic SDK auf den Anthropic-nativen Endpoint des Gateways zeigt. Der OpenAI-kompatible Pfad /chat/completions reicht cache_control-Marker derzeit nicht weiter. Für Claude-Caching muss /v1/messages verwendet werden.

import os
from anthropic import Anthropic

anth = Anthropic(
    api_key=os.environ["SYNTHORAI_KEY"],
    base_url="https://synthorai.io/",   # SDK appends /v1/messages
)

msg = anth.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    system=[
        {"type": "text", "text": SYSTEM_INSTRUCTIONS,
         "cache_control": {"type": "ephemeral"}},       # BP 1: never changes
        {"type": "text", "text": TOOL_DESCRIPTIONS,
         "cache_control": {"type": "ephemeral"}},       # BP 2: rarely changes
        {"type": "text", "text": RETRIEVED_DOCUMENTS},  # changes per call — not cached
    ],
    messages=[{"role": "user", "content": question}],
)

print(msg.usage)
# Usage(input_tokens=18, output_tokens=64,
#       cache_creation_input_tokens=0, cache_read_input_tokens=8123,
#       cost=...)

TTL-Optionen. {"type": "ephemeral"} verwendet standardmäßig eine gleitende TTL von 5 Minuten. Jeder Hit verschiebt den Ablaufzeitpunkt nach hinten. Bei Workloads mit Pausen von mehr als 5 Minuten kann am selben Marker eine TTL von 1 Stunde angefordert werden:

"cache_control": {"type": "ephemeral", "ttl": "1h"}

Gestaffelte Breakpoints. Mit bis zu vier Markern lassen sich Abschnitte, die sich nie, selten oder pro Task ändern, unabhängig voneinander cachen. Das eignet sich besonders für Agent- und RAG-Workloads, bei denen sich einzelne Prompt-Abschnitte unterschiedlich häufig ändern. Selbst wenn sich die letzte Ebene, etwa abgerufene Dokumente, zwischen den Aufrufen ändert, treffen die vorherigen Ebenen weiterhin den Cache.

Modellauswahl. Stand 2026-05 sind folgende Claude-IDs auf dem Gateway verfügbar: claude-haiku-4-5, claude-sonnet-4-5 / 4-6, claude-opus-4-5 / 4-6 / 4-7. Haiku eignet sich für günstige Chats, Sonnet als Allrounder mit dem stärksten Caching-Muster für Agents und Opus für besonders anspruchsvolle Reasoning-Aufgaben.

Gemessene Referenzwerte für Cache-Hit, Write und Aufruf ohne Cache (2026-05-25, System-Prompt mit rund 7.976 Token, max_tokens=64):

Der Rabatt ist über die gesamte Modellfamilie hinweg nahezu gleich. Ein Write kostet ungefähr 25% mehr als ein Aufruf ohne Cache, entsprechend der dokumentierten Preisstruktur von Anthropic. Der Break-even ist bereits mit einem Cache-Hit erreicht.

3. OpenAI GPT-5.x — Automatisches Caching

OpenAI cached jede Anfrage mit einem ausreichend langen Prefix automatisch. Weder Codeänderungen noch Marker sind nötig.

def ask_gpt(question: str):
    t0 = time.perf_counter()
    resp = oai.chat.completions.create(
        model="gpt-5.4-mini",
        max_tokens=64,
        messages=[
            {"role": "system", "content": LONG_STABLE_PROMPT},
            {"role": "user",   "content": question},
        ],
    )
    return resp, time.perf_counter() - t0

r1, t1 = ask_gpt("Which export formats are supported?")
r2, t2 = ask_gpt("How long is the refund window for annual plans?")

print(t1, r1.usage.prompt_tokens_details.cached_tokens, r1.usage.cost)
# 3.63   0       0.00267
print(t2, r2.usage.prompt_tokens_details.cached_tokens, r2.usage.cost)
# 1.23   6400    0.00257

Derselbe Prompt mit 6.887 Token wird zweimal gesendet. Beim zweiten Aufruf treffen 93% des System-Prompts den Cache, und die Gesamtlatenz sinkt von 3.6 s auf 1.2 s. Die Kosten ändern sich hier kaum, weil der Cache-Rabatt durch eine längere Completion des ersten Aufrufs ausgeglichen wird. §7 enthält besser vergleichbare Zahlen über mehrere Anbieter hinweg.

Bei gpt-5.4-nano ist der Rabatt deutlicher sichtbar: Der Cache-Hit senkt die Kosten um 44%. Bei Chat-UIs zählt vor allem die Zeit bis zum ersten Token. Dafür sind die Streaming-Werte entscheidend:

def ttft(model, question):
    t0 = time.perf_counter()
    stream = oai.chat.completions.create(
        model=model, max_tokens=64,
        messages=[
            {"role": "system", "content": LONG_STABLE_PROMPT},
            {"role": "user",   "content": question},
        ],
        stream=True, stream_options={"include_usage": True},
    )
    for ev in stream:
        if ev.choices and ev.choices[0].delta and ev.choices[0].delta.content:
            return time.perf_counter() - t0     # first content token

Gemessene TTFT beim Cache-Hit: 0.73 s für gpt-5.4-mini, 1.00 s für gpt-5.4-nano.

4. Google Gemini — Implizites Caching

Auch Gemini cached über das Gateway automatisch. Ein separater Schritt zum Anlegen von cachedContent ist nicht erforderlich.

r = oai.chat.completions.create(
    model="gemini-2.5-flash",
    max_tokens=128,
    messages=[
        {"role": "system", "content": LONG_STABLE_PROMPT},
        {"role": "user",   "content": "Summarize section 6 in two bullets."},
    ],
)
print(r.usage.prompt_tokens_details.cached_tokens, r.usage.cost)

Bei einem gemessenen Hit mit gemini-2.5-flash und einem System-Prompt von rund 7.300 Token kamen 7.140 Token aus dem Cache (97%). Die Kosten sanken von $0.00198 auf $0.00024, also um 88%.

Zwei Besonderheiten:

• Die *-pro-Varianten von Gemini sind Reasoning-Modelle. Bei einem kleinen max_tokens steht häufig completion_tokens=0, weil das gesamte Budget für internes Reasoning verbraucht wird. Für nutzerseitige Antworten sollte max_tokens auf ≥256 gesetzt werden.
• Die implizite Cache-TTL ist kurz und nicht offiziell spezifiziert. Im Test funktionierte ein Hit bei zwei Aufrufen im Abstand von 5 s. Ein dritter Aufruf nach rund 10 s verfehlte den Cache teilweise bereits. Die Anwendungslogik darf einen Hit nicht voraussetzen. Stattdessen sollte sie cached_tokens prüfen und bei einem Miss sauber weiterarbeiten.

5. DeepSeek-v4-flash — Automatischer, festplattenbasierter Cache

Der automatische Cache von DeepSeek bleibt länger erhalten als die GPU-Memory-Caches anderer Anbieter. Der Aufruf bleibt identisch:

r1 = oai.chat.completions.create(
    model="deepseek-v4-flash", max_tokens=128,
    messages=[{"role": "system", "content": LONG_STABLE_PROMPT},
              {"role": "user",   "content": "Q1"}],
)
# r1.usage.cost = $0.00091, cached_tokens = 0

r2 = oai.chat.completions.create(
    model="deepseek-v4-flash", max_tokens=128,
    messages=[{"role": "system", "content": LONG_STABLE_PROMPT},
              {"role": "user",   "content": "Q2"}],
)
# r2.usage.cost = $0.00023, cached_tokens = 6784  →  74% saved

Die Streaming-TTFT beim Cache-Hit lag bei 2.93 s. DeepSeek bietet in dieser Gruppe nicht die niedrigste Latenz. Die Vorteile liegen bei den Kosten und darin, dass der Cache auch über stundenlange Pausen hinweg warm bleibt.

6. Alibaba Qwen — Hit gemeldet, Rabatt variabel

r = oai.chat.completions.create(
    model="qwen3-max", max_tokens=128,
    messages=[{"role": "system", "content": LONG_STABLE_PROMPT},
              {"role": "user",   "content": "Q1"}],
)
print(r.usage.prompt_tokens_details.cached_tokens, r.usage.cost)
# 7040    0.00549

Bei unserem Test meldete cached_tokens einen Hit von 7.040 aus 7.234 Token, also 97%. usage.cost sank beim Cache-Hit jedoch nicht und blieb bei etwa $0.0055. Der Upstream-Cache wurde getroffen, was die schnellere TTFT von 1.53 s gegenüber 3.03 s bei kaltem Cache zeigt. Das Kostenfeld des Gateways spiegelte den Cache-Rabatt dieses Anbieters zu diesem Zeitpunkt aber noch nicht wider. Wer die Kosten bei Qwen genau verfolgen muss, sollte cached_tokens überwachen und sich bis zur Behebung auf die Preisseiten des Upstream-Anbieters stützen.

7. Anbieterübergreifender Benchmark (gemessen am 2026-05-25)

Ein einzelner sequenzieller Durchlauf. Stabiler System-Prompt mit 7.284 Zeichen und je nach Tokenizer rund 6.900 bis 7.300 Token. max_tokens=64. Auf einen Miss folgte unmittelbar ein Hit.

Anbieter mit automatischem Cache, für die kein Marker nötig ist:

* Beim Miss von gpt-5.4-mini umfasste die Completion 44 Token, beim Hit dagegen 19. Der Kostenunterschied vermischt daher den Cache-Rabatt mit der unterschiedlichen Completion-Länge. Die gesunkene Latenz von 3.63 auf 1.23 s ist hier aussagekräftiger. † Kosten des Streaming-Durchlaufs, bei dem cached_tokens gemeldet wurde. Beim Durchlauf ohne Streaming lieferte Gemini gelegentlich cached_tokens=null, und die Kosten sanken nicht. Die Gateway-Metadaten für Gemini sind derzeit uneinheitlich. Wenn cached_tokens vorhanden ist, ist dieses Feld maßgeblich. ‡ Die Reasoning-Modelle *-pro und *-flash von Gemini liefern bei einem kleinen max_tokens häufig keine Content-Token. Die TTFT ist bei diesem Budget daher nicht aussagekräftig. Für Produktionsmessungen muss max_tokens erhöht werden. § Siehe §6: Der Upstream-Cache wurde getroffen und die Latenz sank. Das Feld usage.cost des Gateways bildete den Rabatt für qwen3-max an diesem Tag jedoch nicht ab.

Anthropic Claude arbeitet mit expliziten Markern. Die Werte stehen in einer separaten Tabelle, weil der Rabatt erst durch cache_control aktiviert wird. Das entsprechende Muster zeigt §2. Gemessen wurden Cache-Write und Cache-Read mit demselben Prompt:

Die eigenen Werte werden je nach Region, Tageszeit und Cache-Wärme der Prefixes anderer Mandanten abweichen. Das war ein einzelner Durchlauf an einem einzelnen Tag, keine allgemeingültige Benchmark-Referenz.

8. Checkliste vor dem Produktivstart

Vor dem Deployment eines Cache-fähigen Prompts:

1. Statische Inhalte zuerst — System-Prompt, Wissensbasis und Tool-Schemas gehören an den Anfang von messages.
2. Variable Inhalte zuletzt — User-Input, abgerufene Dokumente und Zeitstempel gehören ans Ende.
3. Keine dynamischen Variablen in system — aktuelle Uhrzeit, User-ID und zufällige Seeds machen den Prefix unbrauchbar.
4. Bei jedem Aufruf cached_tokens loggen. Liegt die Hit-Rate in Produktion unter 50%, ist der Prefix nicht stabil. Dann müssen die Prompts der Misses geprüft werden.
5. Nicht auf einen einzelnen erfolgreichen Hit verlassen. TTLs sind kurz. Die Architektur sollte von hit_rate ∈ [0, 1) ausgehen, nicht von einem garantierten Hit.

9. TTL-gerechte Muster

Der häufigste Fehler in Produktion ist nicht, dass Caching vergessen wurde. Meist liegt die Hit-Rate bei 12%, weil die Requests nicht innerhalb des TTL-Fensters eintreffen.

8.1 Sessiongebundene Workloads (Chat, IDE-Assistenten)

Das natürliche Anfrageintervall liegt deutlich unter der TTL. Bei einer passenden Prompt-Struktur bleibt der Cache von selbst warm. Weitere Mechanismen sind nicht nötig.

8.2 Heartbeat für Batch-Jobs und Cron

Angenommen, ein täglicher Report startet um 09:00 und ruft das Modell innerhalb von 3 Minuten 50-mal auf. Der erste Cache-Write um 09:00 ist verloren, weil der Cache über Nacht kalt geworden ist. Ab 08:55 kann alle TTL/2 ein „Ping“ mit 1 Token und dem gecachten Prefix gesendet werden, um den Cache warm zu halten:

def keepalive():
    oai.chat.completions.create(
        model="gpt-5.4-mini",
        max_tokens=1,
        messages=[
            {"role": "system", "content": LONG_STABLE_PROMPT},
            {"role": "user",   "content": "."},
        ],
    )

Die Kosten pro Ping ergeben sich aus der Zahl der Input-Token multipliziert mit dem Cache-Preis. Für unseren Prefix mit 7K Token auf gpt-5.4-mini sind das ungefähr $0.0026. Das ist deutlich günstiger, als beim Batch-Job für den vollständigen Prefill der ersten 50 echten Aufrufe zu zahlen.

8.3 Selten abgefragte Dokumente

Bei Dokumenten, die nur sporadisch abgefragt werden, etwa einmal pro Stunde über den Tag verteilt, sind In-Memory-Caches meistens kalt. Zum Zeitpunkt der Veröffentlichung stellt das Gateway keinen gehosteten Endpoint zum expliziten Anlegen eines Caches bereit. Für lange TTLs eignet sich deepseek-v4-flash, dessen festplattenbasierter Cache in der Praxis auch stundenlange Pausen übersteht. Alternativ kann Googles native cachedContent API direkt und außerhalb des Gateways aufgerufen werden.

10. Was das Gateway tatsächlich bietet

Die Behauptung, das Gateway „übernehme das Caching“, wäre irreführend. Das Caching findet auf Modellebene statt. Das Gateway macht lediglich die vorhandenen Funktionen zugänglich. Gegenüber der direkten Nutzung der nativen SDKs der einzelnen Anbieter bietet es drei konkrete Vorteile:

1. Eine base_url, ein Auth-Header, alle Modelle. Nur das model-Feld wird ausgetauscht, der Aufruf bleibt unverändert. Das gilt für das messages-Array ebenso wie für die Struktur des usage-Felds. Für fünf Anbieter müssen keine fünf SDKs eingebunden werden.
2. usage.cost in USD pro Aufruf. Das Gateway berechnet die Kosten anhand der aktuellen Upstream-Preise und fügt sie jeder Antwort hinzu. Damit entfällt eine Preismatrix im eigenen Code, ebenso wie das Abonnieren von Preisänderungen jedes einzelnen Anbieters.
3. Einheitliches cached_tokens-Feld. Anthropic meldet Cache-Hits als cache_read_input_tokens, OpenAI als prompt_tokens_details.cached_tokens und DeepSeek als prompt_cache_hit_tokens. Das Gateway normalisiert diese Angaben auf das OpenAI-Format, sodass der Observability-Code keine anbieterspezifischen Verzweigungen braucht.

Mehr steckt nicht dahinter. Wann gecacht werden sollte, wie Prompts aufgebaut sein müssen und welches Modell passt, behandelt der nächste Artikel.

Als Nächstes: Teil 4 — Das beste LLM nach Anwendungsfall auswählen: Chat, API und AI Agents — eine Entscheidungsmatrix, die Workload-Typen den passenden Modellen und Caching-Strategien zuordnet, einschließlich Kostenrechnung.

FAQ

Warum das OpenAI SDK für Modelle anderer Anbieter verwenden? Das Gateway verwendet für alle angebundenen Anbieter das Wire-Format von OpenAI. Das offizielle openai SDK bietet typisierte Antworten, automatische Retries und Hilfsfunktionen für Streaming. Fünf eigene HTTP-Clients zu implementieren bringt keinen Vorteil.

Funktioniert Caching auch mit Streaming-Antworten? Ja. Das usage-Objekt im letzten Chunk enthält die Anzahl der Cache-Hits, sofern stream_options={"include_usage": True} gesetzt ist. Der Latenzvorteil ist beim Streaming besonders sichtbar, weil Nutzer vor allem die TTFT wahrnehmen.

Welcher Anbieter bietet für meinen Workload den größten Cache-Rabatt? Bei den Preisen von 2026-05 und einer Hit-Rate von mindestens 70% sind gemini-2.5-flash und deepseek-v4-flash in der Tabelle aus §7 am günstigsten. gpt-5.4-mini bietet die beste TTFT. Für den dokumentierten Cache-Rabatt von 90% bei Claude können bis zu vier cache_control-Breakpoints gesetzt werden, siehe §2. Derselbe Benchmark sollte mit dem eigenen Prompt ausgeführt werden. Das dauert einen Tag und erfordert keine mehrwöchige Migration.

Wann brauche ich cache_control-Marker? Nur bei Aufrufen von Anthropic Claude, siehe §2. OpenAI, Gemini, DeepSeek und Qwen cachen upstream jeden ausreichend langen Prefix automatisch. Dafür ist kein Marker nötig; das Feld wird bei diesen Anbietern stillschweigend ignoriert.

Wie aktuell sind diese Zahlen? Sie wurden am 2026-05-25 auf dem öffentlichen Gateway gemessen. Sie sind ein einzelner Datenpunkt. Preise und Latenzen ändern sich mit jedem Release-Zyklus.

Wie sieht es mit Anthropic Claude aus? Claude wird über das Gateway mit expliziten cache_control-Markern unterstützt. Dafür wird das anthropic SDK mit base_url="https://synthorai.io/" verwendet; das SDK hängt /v1/messages an. Der OpenAI-kompatible Pfad /chat/completions reicht die Marker derzeit nicht weiter. Für Claude-Caching muss daher der in §2 gezeigte Anthropic-native Pfad verwendet werden.

Quellen und Verifikation: Alle Zahlen wurden am 2026-05-25 mit Version 2.38.0 des openai SDK gegen https://synthorai.io/v1 gemessen. Preisseiten der Anbieter: Prompt-Caching bei Anthropic · Prompt-Caching bei OpenAI · Context-Caching bei Google Gemini · DeepSeek-Leitfaden zum KV-Cache · Alibaba-Bailian-Context-Cache.

← Zurück zum Blog