LLM-Prompt-Caching #3: Praktisches Python-Tutorial

TL;DR — Ein OpenAI-SDK, eine base_url, jedes große LLM. Die Zahlen in diesem Artikel wurden am 2026-05-25 gegen das laufende Synthorai-Gateway mit einem stabilen System-Prompt von etwa 7.300 Tokens gemessen. Der Sinn des Gateways ist hier bescheiden und ehrlich: ein einziger Endpunkt, ein einziger Auth-Header und ein usage.cost-Feld, das Ihnen die Pflege einer anbieterspezifischen Preismatrix erspart. Die Transformer-Mathematik hinter dem Caching wird in Teil 1: Caching-Prinzipien behandelt; die anbieterspezifischen Designentscheidungen finden Sie in Teil 2: Anbietervergleich.

Serie: Teil 3 von 4 · Zuvor: Teil 1 — Caching-Prinzipien · Teil 2 — Anbietervergleich und Evaluierung · Nächster: Teil 4 — Das beste LLM nach Anwendungsfall

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 spricht das OpenAI-Übertragungsformat für jedes Modell, das es vorgelagert anbietet (GPT, Claude, Gemini, DeepSeek, Qwen). Sie ändern das model-Feld, nicht das SDK. Die Authentifizierung verwendet Authorization: Bearer <key>.

Cache-fähige Modell-IDs, die auf dem öffentlichen Gateway verfügbar sind (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 Live-Liste finden Sie unter GET /v1/models.

1. Der cache-bewusste Aufruf (auf jedem Anbieter gleich)

Sie müssen sich nicht anmelden. Für jedes Modell, das Prompt-Caching vorgelagert unterstützt, leitet das Gateway einfach die Antwort-Metadaten weiter. Zwei Felder verraten Ihnen, 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 ist die Anzahl der Eingabe-Tokens, die den vorgelagerten Präfix-Cache getroffen haben. usage.cost ist der vom Gateway berechnete Preis für diesen einzelnen Aufruf in USD — es ist nicht nötig, lokal eine anbieterspezifische Preistabelle zu führen.

Zwei Regeln, die sich aus der Architektur ergeben und für jeden Anbieter gelten:

1. Stabiler Inhalt zuerst, volatiler Inhalt zuletzt. Der Präfix wird ab Token null abgeglichen; eine einzige Byte-Änderung am Anfang macht den gesamten Präfix ungültig.
2. Halten Sie dynamische Daten aus dem System-Prompt heraus. Aktuelle Zeitstempel, Sitzungs-IDs und Anfrage-UUIDs machen alle den Cache zunichte.

Alles Folgende sind nur anbieterspezifische Beispiele desselben Musters.

2. Anthropic Claude — explizite cache_control-Markierungen

Claude gehört zur Familie der expliziten Markierungen — die API von Anthropic cached nicht automatisch. Um einen Cache-Treffer zu erzielen, markieren Sie bis zu vier cache_control-Haltepunkte in Ihrem system- oder messages-Array. Cache-Lesevorgänge kosten etwa 10 % des Eingabetarifs; Cache-Schreibvorgänge kosten 125 % (ein Aufschlag von 25 %).

Der sauberste Weg, cache_control über das Gateway zu nutzen, ist mit dem offiziellen anthropic-SDK, das auf den Anthropic-nativen Endpunkt des Gateways zeigt (der OpenAI-kompatible /chat/completions-Pfad propagiert die cache_control-Markierungen derzeit nicht — verwenden Sie /v1/messages für Claude-Caching).

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 ein gleitendes 5-Minuten-TTL (jeder Treffer schiebt das Ablaufdatum nach vorne). Für Arbeitslasten mit Leerlauflücken von mehr als 5 Minuten fordern Sie das 1-Stunden-TTL auf derselben Markierung an:

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

Geschichtete Haltepunkte. Bis zu vier Markierungen erlauben es Ihnen, „ändert sich nie” + „ändert sich selten” + „ändert sich pro Aufgabe” unabhängig voneinander zu cachen — das Beste seiner Klasse für Agenten- und RAG-Arbeitslasten, bei denen sich Prompt-Abschnitte in unterschiedlichem Takt ändern. Selbst wenn sich die letzte Schicht (z. B. abgerufene Dokumente) zwischen den Aufrufen ändert, treffen die früheren Schichten weiterhin.

Ein Modell auswählen. Verfügbare Claude-IDs auf dem Gateway mit Stand 2026-05: claude-haiku-4-5, claude-sonnet-4-5 / 4-6, claude-opus-4-5 / 4-6 / 4-7. Haiku für günstigen Chat; Sonnet für allgemeine Zwecke mit dem stärksten Agenten-Caching-Muster; Opus für die schwierigsten Reasoning-Aufgaben.

Gemessene Cache-Treffer- / Schreib- / Kein-Cache-Referenz (2026-05-25, System-Prompt von etwa 7.976 Tokens, max_tokens=64):

Der Rabatt bleibt einheitlich über die gesamte Familie hinweg bestehen. Der Schreibaufschlag liegt bei etwa 25 % über Kein-Cache (Anthropics dokumentierter Tarif); die Gewinnschwelle ist ein Cache-Treffer.

3. OpenAI GPT-5.x — automatisches Caching

OpenAI cached automatisch jede Anfrage mit einem ausreichend langen Präfix. Keine Codeänderung, keine Markierung.

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 Tokens zweimal. Zweiter Aufruf: 93 % des System-Prompts treffen den Cache, 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 Erst-Aufruf-Completion ausgeglichen wird — siehe §7 für sauberere anbieterübergreifende Zahlen.

gpt-5.4-nano zeigt den Rabatt deutlicher (44 % Kostenreduktion beim Treffer). Bei Chat-Benutzeroberflächen, bei denen Sie sich nur um die Zeit bis zum ersten Token kümmern, zählen die Streaming-Zahlen:

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

Gemessenes TTFT beim gecachten Durchlauf: 0,73 s für gpt-5.4-mini, 1,00 s für gpt-5.4-nano.

4. Google Gemini — implizites Caching

Geminis Cache ist ebenfalls automatisch, wenn Sie über das Gateway gehen. Es gibt keinen cachedContent-Erstellungsschritt, den Sie durchführen müssten.

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)

Ein gemessener Treffer auf gemini-2.5-flash für einen System-Prompt von etwa 7.300 Tokens: 7.140 gecachte Tokens (97 %), die Kosten sinken von $0.00198 auf $0.00024 — 88 % günstiger für diesen Durchlauf.

Zwei Fallstricke, die man kennen sollte:

• Geminis *-pro-Varianten sind Reasoning-Modelle. Bei kleinem max_tokens sehen Sie oft completion_tokens=0, weil das Budget durch verstecktes Denken verbraucht wird. Erhöhen Sie max_tokens auf ≥256 für alles, was dem Benutzer zugewandt ist.
• Das TTL des impliziten Caches ist kurz und nicht offiziell spezifiziert. In unserem Test gelang ein Treffer zwischen zwei Aufrufen im Abstand von 5 s; ein dritter Aufruf etwa 10 s später verfehlte manchmal. Entwickeln Sie keine Logik, die den Treffer voraussetzt; prüfen Sie cached_tokens und degradieren Sie elegant.

5. DeepSeek-v4-flash — plattengestützter Auto-Cache

DeepSeeks Auto-Cache überlebt länger als die im GPU-Speicher residenten Caches anderer Anbieter. Dieselbe Aufrufform:

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

Streaming-TTFT beim gecachten Durchlauf: 2,93 s. DeepSeek ist nicht die Option mit der geringsten Latenz in diesem Set — die Vorteile liegen bei den Kosten und der Tatsache, dass der Cache über stundenlange Lücken hinweg warm bleibt.

6. Alibaba Qwen — Treffer 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

In unserem Testlauf beobachteter Vorbehalt: cached_tokens meldet einen Treffer (7.040 von 7.234 = 97 %), aber usage.cost sank beim gecachten Durchlauf nicht (immer noch ≈ $0.0055). Das bedeutet, dass der vorgelagerte Cache-Treffer stattfand (schnelleres TTFT, 1,53 s gegenüber 3,03 s kalt), aber das Kostenfeld des Gateways für diesen Anbieter spiegelte den Cache-Tarif-Rabatt an diesem Datum noch nicht wider. Wenn Sie bei Qwen kostensensibel sind, beobachten Sie cached_tokens und vertrauen Sie den vorgelagerten Preisseiten, bis sich dies normalisiert.

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

Einzelner sequenzieller Lauf. Stabiler System-Prompt mit 7.284 Zeichen (etwa 6.900–7.300 Tokens je nach Tokenizer). max_tokens=64. Ein Fehlschlag-Aufruf, unmittelbar gefolgt von einem Treffer-Aufruf.

Die Auto-Cache-Anbieter (keine Markierung erforderlich):

* Die Completion des Fehlschlag-Aufrufs von gpt-5.4-mini hatte 44 Tokens gegenüber 19 beim Treffer — das Kostendelta vermischt den Cache-Rabatt mit dem Unterschied in der Completion-Länge. Der Latenzabfall (3,63 → 1,23 s) ist hier das sauberere Signal. † Kosten des Streaming-Durchlaufs (bei dem cached_tokens gemeldet wurde); der Nicht-Stream-Durchlauf gab für Gemini gelegentlich cached_tokens=null zurück und die Kosten sanken nicht. Die Gateway-Metadaten für Gemini sind derzeit inkonsistent — vertrauen Sie cached_tokens, wenn vorhanden. ‡ Geminis *-pro / *-flash-Reasoning-Modelle geben bei kleinem max_tokens oft null Inhalts-Tokens aus, sodass TTFT bei diesem Budget bedeutungslos ist. Erhöhen Sie max_tokens, wenn Sie dies in der Produktion messen. § Siehe §6 — der vorgelagerte Cache-Treffer fand statt (Latenz sank), aber das usage.cost-Feld des Gateways spiegelte den Rabatt für qwen3-max an diesem Datum nicht wider.

Anthropic Claude wird durch explizite Markierungen gesteuert; die Zahlen stehen in einer separaten Tabelle, weil der Rabatt über cache_control optional ist (siehe §2 für das Muster). Derselbe Prompt, gemessenes Cache-Schreiben gegenüber Cache-Lesen:

Ihre Zahlen werden je nach Region, Tageszeit und Wärme der Präfixe anderer Tenants abweichen. Einzellauf, Einzeldatum — zitieren Sie diese nicht als Benchmark-Evangelium.

8. Checkliste vor dem Start

Bevor Sie einen cache-bewussten Prompt ausliefern:

1. Stabiler Inhalt zuerst — System-Prompt, Wissensdatenbank, Tool-Schemata oben in messages.
2. Volatiler Inhalt zuletzt — Benutzereingabe, abgerufene Dokumente, Zeitstempel unten.
3. Keine dynamischen Variablen in system — aktuelle Zeit, Benutzer-ID, Zufalls-Seeds zerstören Ihren Präfix.
4. Protokollieren Sie cached_tokens bei jedem Aufruf. Wenn die Trefferrate in der Produktion unter 50 % liegt, ist Ihr Präfix nicht wirklich stabil. Untersuchen Sie die Prompts, die verfehlen.
5. Vertrauen Sie nicht einem einzelnen Treffer-Durchlauf. TTLs sind kurz; entwerfen Sie für hit_rate ∈ [0, 1) statt für „immer Treffer”.

9. TTL-bewusste Muster

Der häufigste Fehlermodus in der Produktion ist nicht „Ich habe vergessen, das Caching zu aktivieren” — es ist „Meine Trefferrate liegt bei 12 %, weil meine Anfragen nicht tatsächlich innerhalb des TTL-Fensters ankommen”.

8.1 Sitzungsgebundene Arbeitslasten (Chat, IDE-Assistenten)

Der natürliche Takt liegt deutlich unter dem TTL. Strukturieren Sie Ihren Prompt richtig und der Cache bleibt von selbst warm — entwickeln Sie nichts anderes.

8.2 Heartbeat für Batch / Cron

Wenn Sie einen täglichen Bericht um 09:00 Uhr ausführen, der Ihr Modell 50-mal in einem 3-minütigen Schub aufruft, ist das erste Cache-Schreiben um 09:00 Uhr verschwendet, weil der Cache über Nacht kalt wurde. Senden Sie ab 08:55 Uhr alle TTL/2 einen 1-Token-„Ping” mit dem gecachten Präfix, um ihn 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 betragen Eingabe-Tokens × Cache-Tarif, was für unseren 7K-Token-Präfix auf gpt-5.4-mini etwa $0.0026 sind — weit weniger, als Ihren Batch-Job das volle Prefill auf den ersten 50 echten Aufrufen zahlen zu lassen.

8.3 Kaltspeicher-Dokumente

Bei Dokumenten, die sporadisch abgefragt werden (einmal pro Stunde über den Tag verteilt), sind In-Memory-Caches die meiste Zeit kalt. Zum Zeitpunkt des Schreibens stellt das Gateway keinen gehosteten Endpunkt zur Erstellung eines expliziten Caches bereit — für Anforderungen mit langem TTL verwenden Sie deepseek-v4-flash (plattengestützt; überlebt in der Praxis stundenlange Lücken) oder rufen Sie die native cachedContent-API von Google direkt außerhalb des Gateways auf.

10. Was das Gateway tatsächlich beiträgt

Es wäre unehrlich zu behaupten, das Gateway „erledigt das Caching für Sie”. Caching geschieht auf der Modellebene — das Gateway legt offen, was dort ist. Was es tatsächlich hinzufügt, gemessen an der direkten Nutzung des nativen SDK jedes Anbieters, sind drei Dinge:

1. Eine base_url, ein Auth-Header, jedes Modell. Tauschen Sie das model-Feld aus, und die Aufrufform bleibt unverändert. Dasselbe messages-Array, dieselbe usage-Feldstruktur. Sie tragen nicht fünf SDKs für fünf Anbieter.
2. usage.cost in USD pro Aufruf. Das Gateway berechnet die Dollar-Kosten anhand der aktuellen vorgelagerten Tarife und nimmt sie in jede Antwort auf. Sie pflegen keine Preismatrix in Ihrem Code und müssen sich nicht für anbieterspezifische Preisänderungs-Benachrichtigungen anmelden.
3. Ein einheitliches cached_tokens-Feld. Anthropic meldet Cache-Treffer als cache_read_input_tokens, OpenAI als prompt_tokens_details.cached_tokens, DeepSeek als prompt_cache_hit_tokens. Das Gateway normalisiert diese in das OpenAI-Format, sodass Ihr Observability-Code nicht nach Anbieter verzweigt.

Das ist der gesamte Pitch. Alles andere — wann gecacht werden soll, wie Prompts strukturiert werden, welches Modell ausgewählt wird — ist Gegenstand des nächsten Artikels.

Nächster: Teil 4 — Wie man das beste LLM nach Anwendungsfall auswählt: Chat, API und KI-Agenten — eine Entscheidungsmatrix, die den Arbeitslasttyp dem optimalen Modell + der Caching-Strategie zuordnet, mit Kostenberechnung.

FAQ

Warum das OpenAI-SDK für Nicht-OpenAI-Modelle verwenden? Das Gateway spricht das OpenAI-Übertragungsformat für jeden Anbieter, den es anbietet. Das offizielle openai-SDK liefert Ihnen typisierte Antworten, automatische Wiederholungen und Streaming-Helfer — es gibt keinen Grund, fünf HTTP-Clients von Hand zu schreiben.

Funktioniert Caching mit Streaming-Antworten? Ja. Das usage-Objekt im letzten Chunk meldet die Cache-Trefferzahlen (wenn Sie stream_options={"include_usage": True} übergeben). Der Latenzgewinn ist beim Streaming am sichtbarsten, weil das TTFT das ist, was Benutzer sehen.

Welcher Anbieter hat den tiefsten Cache-Rabatt für meine Arbeitslast? Zu den Preisen von 2026-05 und bei einer Trefferrate von über 70 % sind gemini-2.5-flash und deepseek-v4-flash in der Tabelle von §7 die günstigsten. gpt-5.4-mini gewinnt beim TTFT. Für Claudes dokumentierten 90-%-Cache-Rabatt markieren Sie bis zu vier cache_control-Haltepunkte (siehe §2). Führen Sie denselben Benchmark gegen Ihren eigenen Prompt aus — das ist eine Aufgabe von einem Tag, keine mehrwöchige Migration.

Wann brauche ich cache_control-Markierungen? Nur beim Aufruf von Anthropic Claude — siehe §2. Für OpenAI/Gemini/DeepSeek/Qwen cached der vorgelagerte Anbieter automatisch jeden ausreichend langen Präfix, sodass keine Markierung erforderlich ist; das Feld wird bei diesen Anbietern stillschweigend ignoriert.

Wie aktuell sind diese Zahlen? Gemessen am 2026-05-25 auf dem öffentlichen Gateway. Behandeln Sie sie als einen einzelnen Datenpunkt — Preise und Latenz ändern sich mit jedem Release-Zyklus.

Was ist mit Anthropic Claude? Claude wird über das Gateway mit expliziten cache_control-Markierungen unterstützt — verwenden Sie das anthropic-SDK mit base_url="https://synthorai.io/" (das SDK fügt /v1/messages an). Der OpenAI-kompatible /chat/completions-Pfad propagiert die Markierungen heute nicht; speziell für Claude-Caching verwenden Sie den Anthropic-nativen Pfad, der in §2 gezeigt wird.

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

← Zurück zum Blog