Prompt-Caching bei Claude: die Rechnung, die Fallen, der Nachweis

TL;DR

Ein Cache-Lesevorgang kostet etwa ein Zehntel des Grundpreises, ein Schreibvorgang das 1,25-Fache bei fünf Minuten Lebensdauer. Der Break-even liegt damit bei zwei Anfragen. In der Praxis scheitert Caching selten am Preis und fast immer an einem Byte, das sich im Prefix ändert — und das meldet Ihnen niemand.

Die eine Regel, aus der alles folgt

Prompt-Caching ist ein Prefix-Abgleich. Eine Änderung an irgendeiner Stelle des Prefix entwertet alles danach.

Der Cache-Schlüssel wird aus den exakten Bytes des gerenderten Prompts bis zum jeweiligen Haltepunkt gebildet. Ein einziges abweichendes Byte an Position N entwertet den Cache für jeden Haltepunkt ab Position N.

Die Renderreihenfolge ist fest: Werkzeuge → Systemanweisung → Nachrichten. Ein Haltepunkt auf dem letzten System-Block cached also Werkzeuge und Systemanweisung gemeinsam.

Aus dieser einen Regel folgt die gesamte Architektur: Stabiles nach vorn, Veränderliches nach hinten. Wer das umdreht, kann beliebig viele Haltepunkte setzen — es cached trotzdem nichts.

Die Rechnung

Daraus der Break-even:

Bei fünf Minuten Lebensdauer: Schreiben plus einmal Lesen kostet 1,25 + 0,1 = 1,35× gegenüber 2,0× für zwei ungecachte Anfragen. Ab der zweiten Anfrage lohnt es sich.

Bei einer Stunde Lebensdauer: 2,0 + 0,2 = 2,2× gegenüber 3,0× für drei ungecachte Anfragen. Ab der dritten.

Die Stunden-Lebensdauer hält Einträge über Lücken im Verkehr am Leben, kostet aber den doppelten Schreibpreis. Sie lohnt sich bei stoßweiser Last mit Pausen über fünf Minuten — nicht bei durchgehendem Betrieb, wo die reguläre Lebensdauer ohnehin ständig erneuert wird.

Die Falle, über die alle stolpern: die Mindestlänge

Ein Prompt unterhalb einer Mindestlänge wird stillschweigend nicht gecacht. Keine Fehlermeldung, kein Hinweis — cache_creation_input_tokens bleibt einfach auf null.

Und diese Mindestlänge ist nicht über die Modellgenerationen hinweg monoton:

Lesen Sie das zweimal. Ein Prompt mit 3.000 Token cached auf Claude Opus 5 und Claude Sonnet 5 — und cached auf Claude Opus 4.6 und Claude Haiku 4.5 nicht, obwohl beide älter beziehungsweise kleiner sind.

Praktische Folge: Wenn Sie von Opus 4.6 auf Opus 5 migrieren, fangen Prompts an zu cachen, die vorher zu kurz waren — ohne dass Sie eine Zeile ändern. Und umgekehrt: Wer auf Haiku 4.5 wechselt, um zu sparen, verliert bei mittelgroßen Prompts das Caching und zahlt womöglich mehr.

Die stillen Entwerter

Beim Durchsehen von Code lohnt sich die Suche nach diesen Mustern in allem, was in den Prefix fließt:

Der häufigste Einzelfall in Projekten, die wir übernehmen: ein Zeitstempel im Kopf der Systemanweisung. Er sieht harmlos aus und macht den gesamten nachfolgenden Prompt uncachebar.

Was wie viel entwertet

Nicht jede Parameteränderung wirft alles weg. Es gibt drei Ebenen:

Praktische Folge: Sie können tool_choice je Anfrage ändern oder den Denkmodus umschalten, ohne den Werkzeug- und System-Cache zu verlieren. Was Sie nicht mitten in einer Sitzung tun sollten, ist Werkzeuge hinzuzufügen oder das Modell zu wechseln.

Für die Systemanweisung gibt es seit Claude Opus 4.8 einen Ausweg, den man kennen sollte: Statt die Systemanweisung zu bearbeiten, hängen Sie eine {"role": "system", ...}-Nachricht hinten an messages an. Der gecachte Prefix bleibt unangetastet, und die Anweisung trägt trotzdem Betreiber-Autorität:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    system=[{"type": "text", "text": STABILE_ANWEISUNG,
             "cache_control": {"type": "ephemeral"}}],
    messages=verlauf + [
        {"role": "user", "content": nutzereingabe},
        {"role": "system", "content": "Knapper Modus — höchstens 40 Wörter."},
    ],
)

Verfügbar auf Claude Opus 5, Opus 4.8, Fable 5 und Mythos 5 — nicht auf Claude Sonnet 5. Dort führt es zu einem Fehler 400; fangen Sie ihn ab und weichen Sie auf einen Hinweis in der Nutzernachricht aus.

Zwei Fallen für Fortgeschrittene

Das 20-Block-Rückblickfenster. Jeder Haltepunkt sucht höchstens 20 Inhaltsblöcke rückwärts nach einem vorhandenen Cache-Eintrag. In agentischen Schleifen mit vielen Werkzeugaufruf- und Ergebnispaaren ist eine einzelne Runde schnell länger als 20 Blöcke — dann findet der nächste Haltepunkt den vorherigen Cache nicht und verfehlt ihn stillschweigend. Abhilfe: bei langen Runden alle etwa 15 Blöcke einen Zwischenhaltepunkt setzen.

Parallele Anfragen lesen nichts. Ein Cache-Eintrag wird erst lesbar, wenn die erste Antwort zu strömen beginnt. Wer zehn Anfragen mit identischem Prefix gleichzeitig abschickt, zahlt zehnmal den vollen Preis — keine kann lesen, was die anderen gerade schreiben. Bei Fächerverteilung also: eine Anfrage senden, das erste Token abwarten, dann die übrigen neun.

Den Nachweis führen

Raten Sie nicht, ob das Caching greift. Die Antwort sagt es Ihnen:

print(response.usage.cache_creation_input_tokens)  # in den Cache geschrieben
print(response.usage.cache_read_input_tokens)      # aus dem Cache gelesen
print(response.usage.input_tokens)                 # voll berechnet

Wenn cache_read_input_tokens über wiederholte Anfragen mit identischem Prefix bei null bleibt, ist ein stiller Entwerter am Werk — vergleichen Sie die gerenderten Prompt-Bytes zweier Anfragen und suchen Sie die Abweichung.

Ein Detail, das regelmäßig zu Fehlschlüssen führt: input_tokens ist nur der ungecachte Rest. Die Gesamtgröße des Prompts ist input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Wer eine Stunde lang einen Agenten laufen lässt und dann 4.000 input_tokens sieht, hat nicht wenig verbraucht — der Rest kam aus dem Cache. Prüfen Sie die Summe, nicht das einzelne Feld.

Häufig gestellte Fragen

Ab wie vielen Anfragen lohnt sich Prompt-Caching?

Ab der zweiten bei der Standard-Lebensdauer von fünf Minuten: Schreiben plus einmal Lesen kostet das 1,35-Fache gegenüber dem 2,0-Fachen für zwei ungecachte Anfragen. Bei einer Stunde Lebensdauer verdoppelt sich der Schreibpreis, dort liegt der Break-even bei drei Anfragen.

Warum cached mein Prompt nicht, obwohl ich cache_control gesetzt habe?

Am wahrscheinlichsten liegt er unter der Mindestlänge des Modells — die reicht von 512 Token bei Claude Opus 5 bis 4.096 bei Claude Opus 4.6 und Haiku 4.5 und ist nicht monoton über die Generationen. Darunter wird stillschweigend nicht gecacht, ohne Fehlermeldung. Zweitwahrscheinlich ist ein stiller Entwerter im Prefix, etwa ein Zeitstempel in der Systemanweisung.

Wie prüfe ich, ob der Cache tatsächlich greift?

Über response.usage.cache_read_input_tokens. Bleibt der Wert über wiederholte Anfragen mit identischem Prefix bei null, greift er nicht. Beachten Sie dabei, dass input_tokens nur den ungecachten Rest ausweist — die Gesamtgröße des Prompts ist die Summe aus ungecachten, geschriebenen und gelesenen Token.

Kann ich die Systemanweisung mitten in einer Sitzung ändern, ohne den Cache zu verlieren?

Auf Claude Opus 5, Opus 4.8, Fable 5 und Mythos 5 ja — indem Sie eine role: "system"-Nachricht hinten an das Nachrichtenfeld anhängen, statt die Systemanweisung selbst zu bearbeiten. Der gecachte Prefix bleibt dabei erhalten. Auf Claude Sonnet 5 wird das mit einem Fehler 400 abgelehnt; dort weichen Sie auf einen Hinweis in der Nutzernachricht aus.

Warum lesen parallele Anfragen den Cache nicht?

Weil ein Eintrag erst lesbar wird, wenn die erste Antwort zu strömen beginnt. Zehn gleichzeitig abgeschickte Anfragen mit identischem Prefix zahlen deshalb alle den vollen Preis. Bei Fächerverteilung schicken Sie eine Anfrage, warten das erste Token ab und starten dann die übrigen — die lesen dann, was die erste geschrieben hat.

Der nächste Schritt

Lassen Sie cache_read_input_tokens über einen Tag protokollieren und bilden Sie den Anteil an den gesamten Eingabe-Token. Liegt er unter 50 Prozent, haben Sie einen stillen Entwerter im Prefix — und den zu finden ist billiger als jede andere Kostenmaßnahme. Wir schauen gern mit drauf.