Prompt-Caching im Detail: 60–90% weniger Input-Kosten auf Brievio

Wenn du einen langen System-Prompt sendest — RAG-Kontext, einen Tool-Katalog, Agent-Regeln, Beispiele — zahlst du wahrscheinlich bei jedem Call den vollen Input-Preis. Anthropics Prompt-Caching senkt das auf 10% des Tarifs für den gecachten Teil. OpenAI macht dasselbe implizit. Die meisten Teams finden 30 Minuten Arbeit dafür lohnenswert, weil es ihre Input-Kostenzeile zuverlässig um 60–90% drückt.

Brievio reicht beide Varianten unverändert durch, gegen das echte Modell. Anthropic-Stil mit cache_control funktioniert auf der Messages-API; das automatische Caching im OpenAI-Stil funktioniert auf der Chat-Completions-API. Dieser Beitrag geht beide durch, dazu die Fallen, die Caches still und leise ungültig machen, und wie du deine Trefferquote prüfst.

Der Vorher-Nachher-Vergleich

Eine naive Schleife, die denselben 18K-Token-System-Prompt zehnmal sendet:

# Womit die meisten starten: jeder Call zahlt den kompletten Prompt erneut.
import anthropic

client = anthropic.Anthropic(
    api_key="sk-brievio-...",
    base_url="https://api.brievio.com",
)

SYSTEM = open("system-prompt.md").read()        # 18.000 Tokens an Regeln + Beispielen

# 10 Userfragen in einer Session. Jeder Call sendet den 18K-Token-System-Block.
for question in questions:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=600,
        system=SYSTEM,
        messages=[{"role": "user", "content": question}],
    )

# Kosten pro Call (nur Input): 18.000 × $3 / 1M = $0,054
# 10 Calls: $0,54 allein an Input.

Jetzt markiere den System-Block als cachebar — ein zusätzliches Feld:

# Die Lösung: markiere das statische Präfix als cachebar. Nach dem ersten Call
# zahlen Folge-Calls innerhalb von ~5 Minuten 10% des Input-Tarifs auf den
# gecachten Teil. Gleiche Antwort, 89% günstiger.
resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=600,
    system=[
        {
            "type": "text",
            "text": SYSTEM,
            "cache_control": {"type": "ephemeral"},  # als cachebar markieren
        }
    ],
    messages=[{"role": "user", "content": question}],
)

# Erster Call (Cache-Write):  18.000 × $3   / 1M = $0,054
# Calls 2–10 (Cache-Hit):     18.000 × $0,30 / 1M = $0,0054 je
# Gesamt: $0,054 + 9 × $0,0054 = $0,103  (waren $0,54 — 81% gespart)

Du hast gerade 81% der Input-Kosten dieser Session gespart. Der erste Call ist tatsächlich etwas teurer als die naive Variante (~1,25× Input-Tarif, um den Cache zu schreiben). Calls 2 bis 10 zahlen 10% des Tarifs. Der Break-even liegt bei Call 2 — ab Call 3 bist du im Plus. Bei Call 10 ist es ein Erdrutsch.

OpenAI-Stil: nichts zu tun

Wenn du das OpenAI-SDK nutzt, cacht Chat Completions das Präfix jedes Prompts über 1.024 Tokens automatisch. Kein Flag, keine Konfiguration. Dasselbe Modell hinter Brievio bekommt den Rabatt, egal ob du den Anthropic- oder OpenAI-Weg genutzt hast in:

# OpenAI-Chat-Completions-Stil — Caching läuft automatisch für Prompts ab 1024 Tokens.
# Kein Flag zu setzen. Das "usage"-Objekt sagt dir, was gecacht wurde.
from openai import OpenAI

client = OpenAI(
    api_key="sk-brievio-...",
    base_url="https://api.brievio.com/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": LONG_SYSTEM_PROMPT},  # >1024 Tokens
        {"role": "user", "content": "Latest question…"},
    ],
)

# In der Antwort:
#   resp.usage.prompt_tokens_details.cached_tokens  →  17.800
#   resp.usage.prompt_tokens                        →  18.200
# 17,8K/18,2K = 98% des Inputs kamen aus dem Cache. Die Rechnung bildet das automatisch ab.

Lies usage.prompt_tokens_details.cached_tokens, um zu sehen, wie viel aus dem Cache geliefert wurde. Größeres festes Präfix = größere Ersparnis. Die Faustregel: Ist dein System-Prompt kürzer als dein variabler User-Content, bringt Caching nicht viel. Forme den Prompt so um, dass die statischen Teile groß sind und vorn stehen.

Mehrschichtiges Caching — bis zu 4 Breakpoints

Für Agent-Schleifen, in denen sich manche Schichten schneller ändern als andere, setze mehrere cache_control-Breakpoints. Jeder ist ein Schnappschuss von allem bis zu diesem Punkt:

# Anthropic unterstützt bis zu 4 Cache-Breakpoints pro Request — nutze sie,
# um den Cache heiß zu halten, auch wenn sich spätere Schichten ändern.
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=600,
    system=[
        {"type": "text",
         "text": ROLE_AND_RULES,                      # ~3.000 Tokens
         "cache_control": {"type": "ephemeral"}},     # Breakpoint 1
        {"type": "text",
         "text": LARGE_KNOWLEDGE_BASE,                # ~15.000 Tokens, ändert sich selten
         "cache_control": {"type": "ephemeral"}},     # Breakpoint 2
    ],
    messages=[
        {"role": "user",
         "content": [
             {"type": "text",
              "text": CONVERSATION_HISTORY,           # wächst mit jedem Turn
              "cache_control": {"type": "ephemeral"}}, # Breakpoint 3
             {"type": "text", "text": new_question},
         ]},
    ],
)

# Ändert sich CONVERSATION_HISTORY, treffen Breakpoint 1+2 weiterhin den Cache.
# Nur Breakpoint 3 + die neue Frage zahlen den vollen Input-Tarif.

Der Cache-Key ist das gesamte Präfix. Füge an Position N ein Token hinzu, und jeder Breakpoint an oder nach N wird ungültig. Die Reihenfolge zählt: stabilster Inhalt zuerst. Die Regel-Schicht sollte sich selten ändern; die Wissensbasis wird wöchentlich aktualisiert; die Konversation wächst mit jedem Turn.

Häufige Wege, Caching still und leise zu zerstören

• Das aktuelle Datum oder eine request_id im Prompt. Jeder Call ist ein neues Präfix, die Cache-Trefferquote liegt bei 0%. Hashe deine Prompt-Inputs und vergleiche sie über Calls hinweg.
• Nicht-deterministischer Aufbau des System-Prompts. Baust du das System aus einem Dict, zählt die Iterationsreihenfolge des Dicts in manchen Python-Versionen. Sortiere die Keys explizit.
• Die Cache-Lebensdauer beträgt ~5 Minuten. Spärliche Traffic-Muster (ein Call alle 10 Minuten) bekommen null Treffer. Bündle die Calls entweder, oder nimm den Verlust hin.
• Das 1.024-Token-Minimum. Unter 1K Tokens greift das Caching im OpenAI-Stil nicht. Fasse kleine statische Fragmente zu einem einzigen längeren Präfix zusammen.
• Tools / Function-Definitionen sind Teil des Präfix. Ein neues Tool im Katalog macht den Cache für alle ungültig. Halte den Tool-Katalog stabil; versioniere ihn.

Die Trefferquote überprüfen

Caching, das du nicht sehen kannst, ist kein Engineering — es ist Hoffen. Logge usage bei jedem Call:

# Lies immer usage. Ist cached_tokens 0, obwohl du einen Treffer erwartet hast,
# stimmt etwas nicht — meist ein nicht-deterministisches Präfix.
resp = client.messages.create(...)
u = resp.usage
print({
    "input_uncached":  u.input_tokens,
    "input_cache_read": u.cache_read_input_tokens,
    "input_cache_write": u.cache_creation_input_tokens,
    "output": u.output_tokens,
})

# Eine häufige Falle: das heutige Datum oder eine request_id im System-Prompt
# macht den Cache still und leise ungültig. Hashe deine Inputs; prüfe, dass
# cache_read_input_tokens beim 2. identischen Call nicht null ist.

Im Brievio-Dashboard zeigt die Usage-Seite die Cache-Aufteilung pro Modell und Tag. Siehst du cache_read_input_tokens als Anteil am gesamten Input wachsen, funktioniert das Caching. Bleibt es bei 0 oder schwankt wild, geh die Fallen-Liste oben durch.

Was es auf Brievio tatsächlich kostet

Der Cache-Tarif jedes Modells ist auf der Pricing-Seite veröffentlicht:

• Anthropic-Modelle: Cache-Reads kosten 10% des Input-Tarifs. Cache-Writes werden zum Input-Tarif abgerechnet — kein Upstream-Aufschlag.
• OpenAI- / Gemini-Modelle: Cache-Reads kosten 20% des Input-Tarifs (das von den Anbietern veröffentlichte Verhältnis).
• Alle Cache-Preise spiegeln Brievios Liste wider — rund 15% unter dem offiziellen Tarif des Anbieters. Ein Cache-Read auf Sonnet 4.6 bei Brievio kostet also $3 × 0,95 × 0,10 = $0,285 pro 1M Tokens. Etwa 10× günstiger als der ungecachte Input-Tarif.

Wann Caching nicht die Antwort ist

Ein paar Fälle, in denen sich die Arbeit nicht lohnt:

• Kurze Prompts (<1K Tokens insgesamt). Der Overhead dominiert; lass es einfach.
• Einmalige Aufgaben ohne wiederkehrenden Traffic. Der erste Call ist etwas teurer — Caching zahlt sich erst ab Call 2 aus.
• Viel Output, wenig Input (kreatives Schreiben, Code-Generierung). Der Input ist ohnehin nur ein kleiner Teil der Rechnung. Konzentriere dich stattdessen auf Output-Budget-Deckel.

Für alles andere — RAG-Chatbots, Agents mit festem Tool-Katalog, Klassifizierer über einer statischen Rubrik, Pipelines für strukturierte Extraktion mit konsistenten Few-Shots — ist Caching die Optimierung mit dem höchsten ROI, die du an einem einzigen Nachmittag ausliefern kannst. Kombiniere es mit den vier anderen Techniken in unserem Playbook zur Kostenoptimierung und 70% Kostensenkung sind realistisch — ohne einen einzigen Kompromiss bei der Output-Qualität.

Schon auf Brievio? Öffne /app/usage und prüfe die Cache-Spalte für dein größtes Modell. Steht sie auf null, lässt du Geld liegen. Vollständige Anleitung: /docs/caching.