Prompt-Caching
Cache Prompt-Präfixe mit cache_control, um Kosten und Latenz zu senken – mit automatischem Caching oder expliziten Breakpoints mit 5-Minuten- oder 1-Stunden-TTLs.
Nutzung unterscheidet sich je nach Produkt
cache_control, auf oberster Ebene oder für einzelne Blöcke.„Prompt caching“ (Prompt-Caching) optimiert deine API-Nutzung, indem es der API die Wiederaufnahme ab bestimmten Präfixen in deinen Prompts ermöglicht. Dies reduziert die Verarbeitungszeit und die Kosten für sich wiederholende Aufgaben oder Prompts mit gleichbleibenden Elementen erheblich.
Es gibt zwei Möglichkeiten, Prompt-Caching zu aktivieren:
- Automatisches Caching: Füge ein einzelnes
cache_control-Feld auf der obersten Ebene deiner Anfrage hinzu. Das System wendet den Cache-Breakpoint automatisch auf den letzten cachebaren Block an und verschiebt ihn nach vorne, während Gespräche wachsen. Am besten geeignet für Gespräche mit mehreren Runden, bei denen der wachsende Nachrichtenverlauf automatisch gecacht werden soll. - Explizite Cache-Breakpoints: Platziere
cache_controldirekt auf einzelnen Content-Blöcken, um genau steuern zu können, was gecacht wird.
Eine Möglichkeit für den Einstieg ist das automatische Caching:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages=[
{
"role": "user",
"content": "Analyze the major themes in 'Pride and Prejudice'.",
}
],
)
print(response.usage.model_dump_json())Beim automatischen Caching cacht das System alle Inhalte bis einschließlich des letzten cachebaren Blocks. Bei nachfolgenden Anfragen mit demselben Präfix werden gecachte Inhalte automatisch wiederverwendet.
Wie Prompt-Caching funktioniert
Wenn du eine Anfrage mit aktiviertem Prompt-Caching sendest:
- Prüft das System, ob ein Prompt-Präfix bis zu einem angegebenen Cache-Breakpoint bereits aus einer kürzlichen Abfrage gecacht ist.
- Falls gefunden, verwendet es die gecachte Version, was Verarbeitungszeit und Kosten reduziert.
- Andernfalls verarbeitet es den vollständigen Prompt und cacht das Präfix, sobald die Antwort beginnt.
Dies ist besonders nützlich für:
- Prompts mit vielen Beispielen
- Große Mengen an Kontext oder Hintergrundinformationen
- Sich wiederholende Aufgaben mit gleichbleibenden Anweisungen
- Lange Gespräche mit mehreren Runden
Standardmäßig hat der Cache eine Lebensdauer von 5 Minuten. Der Cache wird bei jeder Verwendung der gecachten Inhalte ohne zusätzliche Kosten aufgefrischt.
Die Lebensdauer wird ab dem Start der Anfrage gemessen, die den Cache-Eintrag schreibt oder liest, nicht ab dem Ende ihrer Antwort. Die Zeit, die für das Generieren einer Antwort benötigt wird, zählt zur Lebensdauer: Wenn das Streaming einer Antwort 4 Minuten dauert, muss eine Folgeanfrage, die dasselbe gecachte Präfix wiederverwendet, innerhalb von etwa 1 Minute nach Abschluss dieser Antwort starten.
Wenn dir 5 Minuten zu kurz sind, kannst du gegen Aufpreis eine 1-Stunden-Cache-Dauer verwenden (siehe Preise).
Prompt-Caching umfasst das vollständige Präfix: tools, system und messages (in dieser Reihenfolge), bis einschließlich des mit cache_control gekennzeichneten Blocks.
Preise
Prompt-Caching hat eine eigene Preisstruktur. Die folgende Tabelle zeigt den Preis pro Million Token für jedes unterstützte Modell:
| Modell | Basis-Tokens | Prompt-Caching | |||
|---|---|---|---|---|---|
| Name | Eingabe | Ausgabe | 5-Min.-Schreibvorgänge | Schreibvorgänge (1 Std.) | Treffer und Aktualisierungen |
Claude Fable 5.2For demanding reasoning and long-horizon agentic work | 8 $ / MTok | 40 $ / MTok | 10 $ / MTok | 16 $ / MTok | 0,20 $ / MTok1 |
Claude Opus 5.5For long-running agentic coding and knowledge work | 4 $ / MTok | 20 $ / MTok | 5 $ / MTok | 8 $ / MTok | 0,20 $ / MTok2 |
Claude Sonnet 5.5The best combination of speed and intelligence | 2 $ / MTok | 10 $ / MTok | 2,50 $ / MTok | 4 $ / MTok | 0,10 $ / MTok2 |
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing | 0,10 $ / MTokfür Prompts mit bis zu 100.000 Tokens | 0,50 $ / MTok | 0,125 $ / MTok | 0,20 $ / MTok | 0,01 $ / MTok |
0,50 $ / MTokfür Prompts mit mehr als 100.000 Tokens | 2,50 $ / MTok | 0,625 $ / MTok | 1 $ / MTok | 0,05 $ / MTok | |
8 $ / MTok | 40 $ / MTok | 10 $ / MTok | 16 $ / MTok | 0,20 $ / MTok1 | |
10 $ / MTok | 50 $ / MTok | 12,50 $ / MTok | 20 $ / MTok | 0,25 $ / MTok1 | |
10 $ / MTok | 50 $ / MTok | 12,50 $ / MTok | 20 $ / MTok | 0,25 $ / MTok1 | |
10 $ / MTok | 50 $ / MTok | 12,50 $ / MTok | 20 $ / MTok | 1 $ / MTok | |
10 $ / MTok | 50 $ / MTok | 12,50 $ / MTok | 20 $ / MTok | 1 $ / MTok | |
5 $ / MTok | 25 $ / MTok | 6,25 $ / MTok | 10 $ / MTok | 0,50 $ / MTok | |
5 $ / MTok | 25 $ / MTok | 6,25 $ / MTok | 10 $ / MTok | 0,50 $ / MTok | |
5 $ / MTok | 25 $ / MTok | 6,25 $ / MTok | 10 $ / MTok | 0,50 $ / MTok | |
5 $ / MTok | 25 $ / MTok | 6,25 $ / MTok | 10 $ / MTok | 0,50 $ / MTok | |
5 $ / MTok | 25 $ / MTok | 6,25 $ / MTok | 10 $ / MTok | 0,50 $ / MTok | |
Claude Opus 4.1 | 15 $ / MTok | 75 $ / MTok | 18,75 $ / MTok | 30 $ / MTok | 1,50 $ / MTok |
Claude Opus 4 | 15 $ / MTok | 75 $ / MTok | 18,75 $ / MTok | 30 $ / MTok | 1,50 $ / MTok |
2 $ / MTok | 10 $ / MTok | 2,50 $ / MTok | 4 $ / MTok | 0,20 $ / MTok | |
3 $ / MTok | 15 $ / MTok | 3,75 $ / MTok | 6 $ / MTok | 0,30 $ / MTok | |
3 $ / MTok | 15 $ / MTok | 3,75 $ / MTok | 6 $ / MTok | 0,30 $ / MTok | |
Claude Sonnet 4 | 3 $ / MTok | 15 $ / MTok | 3,75 $ / MTok | 6 $ / MTok | 0,30 $ / MTok |
1 $ / MTok | 5 $ / MTok | 1,25 $ / MTok | 2 $ / MTok | 0,10 $ / MTok | |
1 Cache-Treffer und -Aktualisierungen bei Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1 und Claude Mythos 5.1 werden mit 0,025x des Basispreises für Input berechnet.
2 Cache-Treffer und -Aktualisierungen bei Claude Opus 5.5 und Claude Sonnet 5.5 werden mit 0,05x des Basispreises für Input berechnet.
Für alle anderen Modelle gilt der Standardmultiplikator von 0,1x.
Unterstützte Modelle
Prompt-Caching (sowohl automatisch als auch explizit) wird auf allen aktiven Claude-Modellen unterstützt.
Automatisches Caching
Automatisches Caching aktiviert Prompt-Caching mit einem einzigen Feld. Anstatt cache_control auf einzelnen Content-Blöcken zu platzieren, fügst du ein einzelnes cache_control-Feld auf der obersten Ebene deines Request-Bodys hinzu. Das System wendet den Cache-Breakpoint automatisch auf den letzten cachebaren Block an.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",
messages=[
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{
"role": "assistant",
"content": "Nice to meet you, Alex! How can I help with your ML work today?",
},
{"role": "user", "content": "What did I say I work on?"},
],
)
print(response.usage.model_dump_json())Wie automatisches Caching in Gesprächen mit mehreren Runden funktioniert
Beim automatischen Caching wandert der Cache-Punkt automatisch nach vorne, während Gespräche wachsen. Jede neue Anfrage cacht alles bis zum letzten cachebaren Block, und vorherige Inhalte werden aus dem Cache gelesen.
| Anfrage | Inhalt | Cache-Verhalten |
|---|---|---|
| Anfrage 1 | System + User(1) + Asst(1) + User(2) ◀ Cache | Alles wird in den Cache geschrieben |
| Anfrage 2 | System + User(1) + Asst(1) + User(2) + Asst(2) + User(3) ◀ Cache | System bis User(2) aus dem Cache gelesen; Asst(2) + User(3) in den Cache geschrieben |
| Anfrage 3 | System + User(1) + Asst(1) + User(2) + Asst(2) + User(3) + Asst(3) + User(4) ◀ Cache | System bis User(3) aus dem Cache gelesen; Asst(3) + User(4) in den Cache geschrieben |
Der Cache-Breakpoint wandert in jeder Anfrage automatisch zum letzten cachebaren Block, sodass du keine cache_control-Markierungen aktualisieren musst, während das Gespräch wächst.
TTL-Unterstützung
Standardmäßig verwendet automatisches Caching eine 5-Minuten-TTL. Du kannst eine 1-Stunden-TTL zum 2-Fachen des Basispreises für Input-Token angeben:
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }Kombination mit Caching auf Blockebene
Automatisches Caching ist mit expliziten Cache-Breakpoints kompatibel. Bei gemeinsamer Verwendung belegt der automatische Cache-Breakpoint einen der 4 verfügbaren Breakpoint-Slots.
So kannst du beide Ansätze kombinieren. Verwende zum Beispiel einen expliziten Breakpoint, um deinen System-Prompt zu cachen, während das automatische Caching das Gespräch übernimmt:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}Was gleich bleibt
Automatisches Caching nutzt dieselbe zugrunde liegende Caching-Infrastruktur. Preise, Mindest-Token-Schwellenwerte, Anforderungen an die Kontextreihenfolge und das 20-Block-Lookback-Fenster gelten genauso wie bei expliziten Breakpoints.
Sonderfälle
- Wenn der letzte Block bereits ein explizites
cache_controlmit derselben TTL hat, bewirkt das automatische Caching nichts. - Wenn der letzte Block ein explizites
cache_controlmit einer anderen TTL hat, gibt die API einen 400-Fehler zurück. - Wenn bereits 4 explizite Breakpoints auf Blockebene existieren, gibt die API einen 400-Fehler zurück (keine Slots mehr für automatisches Caching frei).
- Wenn der letzte Block nicht als Ziel für einen automatischen Cache-Breakpoint geeignet ist, geht das System stillschweigend rückwärts, um den nächstgelegenen geeigneten Block zu finden. Wird keiner gefunden, wird das Caching übersprungen.
Explizite Cache-Breakpoints
Für mehr Kontrolle über das Caching kannst du cache_control direkt auf einzelnen Content-Blöcken platzieren. Das ist nützlich, wenn du verschiedene Abschnitte cachen musst, die sich unterschiedlich häufig ändern, oder wenn du genau steuern möchtest, was gecacht wird.
Strukturierung deines Prompts
Platziere statische Inhalte (Tool-Definitionen, Systemanweisungen, Kontext, Beispiele) am Anfang deines Prompts. Markiere das Ende des wiederverwendbaren Inhalts für das Caching mit dem Parameter cache_control.
Cache-Präfixe werden in folgender Reihenfolge erstellt: tools, system, dann messages. Diese Reihenfolge bildet eine Hierarchie, in der jede Ebene auf den vorherigen aufbaut.
Wie die automatische Präfixprüfung funktioniert
Es reicht, einen einzigen Cache-Breakpoint am Ende deiner statischen Inhalte zu verwenden, und das System findet automatisch das längste Präfix, das eine vorherige Anfrage bereits in den Cache geschrieben hat. Wenn du verstehst, wie das funktioniert, kannst du deine Caching-Strategie optimieren.
Drei Grundprinzipien:
-
Cache-Writes erfolgen nur an deinem Breakpoint. Das Markieren eines Blocks mit
cache_controlschreibt genau einen Cache-Eintrag: einen Hash des Präfixes, das an diesem Block endet. Das System schreibt keine Einträge für frühere Positionen. Da der Hash kumulativ ist und alles bis einschließlich des Breakpoints abdeckt, erzeugt jede Änderung an einem Block am oder vor dem Breakpoint bei der nächsten Anfrage einen anderen Hash. -
Cache-Lesevorgänge suchen rückwärts nach Einträgen, die vorherige Anfragen geschrieben haben. Bei jeder Anfrage berechnet das System den Präfix-Hash an deinem Breakpoint und prüft, ob ein passender Cache-Eintrag existiert. Wenn keiner existiert, geht es Block für Block rückwärts und prüft, ob der Präfix-Hash an jeder früheren Position mit etwas übereinstimmt, das sich bereits im Cache befindet. Es sucht nach vorherigen Schreibvorgängen, nicht nach stabilen Inhalten.
-
Das Lookback-Fenster umfasst 20 Blöcke. Das System prüft für jeden Breakpoint höchstens 20 Positionen, wobei der Breakpoint selbst als erste zählt. Findet das System in diesem Fenster keinen passenden Eintrag, endet die Prüfung (oder wird am nächsten expliziten Breakpoint fortgesetzt, falls vorhanden). In der Claude API zählt eine Folge aufeinanderfolgender
tool_use-Blöcke als eine Position, ebenso eine Folge aufeinanderfolgendertool_result-Blöcke, sodass eine Runde mit vielen parallelen Tool-Aufrufen den Eintrag der vorherigen Anfrage nicht allein aus dem Fenster verdrängt.
Beispiel: Lookback in einem wachsenden Gespräch
Du hängst in jeder Runde neue Blöcke an und setzt cache_control auf den letzten Block jeder Anfrage:
- Runde 1: 10 Blöcke, Breakpoint auf Block 10. Es existieren keine vorherigen Cache-Einträge. Das System schreibt einen Eintrag bei Block 10.
- Runde 2: 15 Blöcke, Breakpoint auf Block 15. Block 15 hat keinen Eintrag, also geht das System zurück zu Block 10 und findet den Eintrag aus Runde 1. Cache-Treffer bei Block 10. Das System verarbeitet nur die Blöcke 11 bis 15 neu und schreibt einen neuen Eintrag bei Block 15.
- Runde 3: 35 Blöcke, Breakpoint auf Block 35. Das System prüft 20 Positionen (Blöcke 35 bis 16) und findet nichts. Der Eintrag aus Runde 2 bei Block 15 liegt eine Position außerhalb des Fensters, daher gibt es keinen Cache-Treffer. Ein zweiter Breakpoint bei Block 15 startet dort ein zweites Lookback-Fenster, das den Eintrag aus Runde 2 findet.
Häufiger Fehler: Breakpoint auf Inhalten, die sich bei jeder Anfrage ändern
Dein Prompt hat einen großen statischen Systemkontext (Blöcke 1 bis 5), gefolgt von einem anfragespezifischen Block mit einem Zeitstempel und der Benutzernachricht (Block 6). Du setzt cache_control auf Block 6:
- Anfrage 1: Cache-Write bei Block 6. Der Hash enthält den Zeitstempel.
- Anfrage 2: Der Zeitstempel ist ein anderer, daher unterscheidet sich der Präfix-Hash bei Block 6. Der Lookback durchläuft die Blöcke 5, 4, 3, 2 und 1, aber das System hat an keiner dieser Positionen je einen Eintrag geschrieben. Kein Cache-Treffer. Du zahlst bei jeder Anfrage für einen neuen Cache-Schreibvorgang und erhältst nie einen Lesevorgang.
Der Lookback findet keine stabilen Inhalte hinter deinem Breakpoint und cacht sie. Er findet Einträge, die vorherige Anfragen bereits geschrieben haben, und Schreibvorgänge erfolgen nur an Breakpoints. Verschiebe cache_control auf Block 5, den letzten Block, der über Anfragen hinweg gleich bleibt, und jede nachfolgende Anfrage liest das gecachte Präfix. Automatisches Caching hat dasselbe Problem: Es setzt den Breakpoint auf den letzten cachebaren Block, der in dieser Struktur derjenige ist, der sich bei jeder Anfrage ändert. Verwende daher stattdessen einen expliziten Breakpoint auf Block 5.
Wichtigste Erkenntnis: Platziere cache_control auf dem letzten Block, dessen Präfix über die Anfragen hinweg identisch ist, die sich einen Cache teilen sollen. In einem wachsenden Gespräch funktioniert der letzte Block, solange jede Runde weniger als 20 Blöcke hinzufügt: Frühere Inhalte ändern sich nie, sodass der Lookback der nächsten Anfrage den vorherigen Schreibvorgang findet. Bei einem Prompt mit variierendem Suffix (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht) platzierst du den Breakpoint am Ende des statischen Präfixes, nicht auf dem variierenden Block.
Wann mehrere Breakpoints sinnvoll sind
Du kannst bis zu 4 Cache-Breakpoints definieren, wenn du:
- Verschiedene Abschnitte cachen möchtest, die sich unterschiedlich häufig ändern (zum Beispiel ändern sich Tools selten, aber der Kontext wird täglich aktualisiert)
- Mehr Kontrolle darüber haben möchtest, was genau gecacht wird
- Einen Cache-Treffer sicherstellen möchtest, wenn ein wachsendes Gespräch deinen Breakpoint 20 oder mehr Blöcke über den letzten Cache-Write hinausschiebt
Kosten von Cache-Breakpoints verstehen
Cache-Breakpoints selbst verursachen keine Kosten. In Rechnung gestellt werden dir nur:
- Cache-Writes: Wenn neue Inhalte in den Cache geschrieben werden (25 Prozent mehr als Basis-Input-Token bei 5-Minuten-TTL)
- Cache-Reads: Wenn gecachte Inhalte verwendet werden (10 Prozent des Basispreises für Input-Token, mit modellspezifischen Ausnahmen)
- Reguläre Input-Token: Für alle nicht gecachten Inhalte
Das Hinzufügen weiterer cache_control-Breakpoints erhöht deine Kosten nicht; du zahlst weiterhin denselben Betrag, basierend darauf, welche Inhalte tatsächlich gecacht und gelesen werden. Die Breakpoints geben dir Kontrolle darüber, welche Abschnitte unabhängig voneinander gecacht werden können.
Caching-Strategien und Überlegungen
Cache-Einschränkungen
In der Claude API, auf Claude Platform on AWS, Claude Models on Google Cloud (Google managed) und Microsoft Foundry beträgt die minimale cachebare Prompt-Länge:
- 512 Token für Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, Claude Mythos 5 und Claude Haiku 5.5
- 2.048 Token für Claude Mythos Preview und Claude Opus 4.7
- 4.096 Token für Claude Opus 4.6 und Claude Opus 4.5
- 1.024 Token für Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 (abgekündigt), Claude Opus 4.1 (eingestellt, außer auf Claude Models on Google Cloud (Google managed) und Bedrock), Claude Opus 4 (eingestellt, außer auf Claude Models on Google Cloud (Google managed)) und Claude Sonnet 4 (eingestellt, außer auf Claude Models on Google Cloud (Google managed) und Bedrock)
- 4.096 Token für Claude Haiku 4.5
Diese Mindestwerte gelten auf jeder dieser Plattformen, auf der das Modell verfügbar ist.
Kürzere Prompts können nicht gecacht werden, selbst wenn sie mit cache_control markiert sind. Alle Anfragen, weniger als diese Anzahl an Token zu cachen, werden ohne Caching verarbeitet, und es wird kein Fehler zurückgegeben. Um zu prüfen, ob ein Prompt gecacht wurde, sieh dir die Usage-Felder der Antwort an: Wenn sowohl cache_creation_input_tokens als auch cache_read_input_tokens 0 sind, wurde der Prompt nicht gecacht (wahrscheinlich, weil er die Mindestlänge nicht erreicht hat).
Wenn dein Prompt knapp unter dem Mindestwert für dein Modell und deine Plattform liegt, lohnt es sich oft, den gecachten Inhalt zu erweitern, um den Schwellenwert zu erreichen. Cache-Reads kosten deutlich weniger als nicht gecachte Input-Token, sodass das Erreichen des Mindestwerts die Kosten für häufig wiederverwendete Prompts senken kann.
Beachte bei gleichzeitigen Anfragen, dass ein Cache-Eintrag erst verfügbar wird, nachdem die erste Antwort beginnt. Wenn du Cache-Treffer für parallele Anfragen benötigst, warte auf die erste Antwort, bevor du nachfolgende Anfragen sendest.
ephemeral ist der einzige unterstützte Cache-Typ, der standardmäßig eine Lebensdauer von 5 Minuten hat.
Was gecacht werden kann
Die meisten Blöcke in der Anfrage können gecacht werden. Dazu gehören:
- Tools: Tool-Definitionen im
tools-Array - Systemnachrichten: Content-Blöcke im
system-Array - Textnachrichten: Content-Blöcke im
messages.content-Array, sowohl für Benutzer- als auch für Assistenten-Runden - Bilder und Dokumente: Content-Blöcke im
messages.content-Array, in Benutzer-Runden - Tool-Nutzung und Tool-Ergebnisse: Content-Blöcke im
messages.content-Array, sowohl in Benutzer- als auch in Assistenten-Runden
Jedes dieser Elemente kann gecacht werden, entweder automatisch oder indem du es mit cache_control markierst.
Was nicht gecacht werden kann
Obwohl die meisten Request-Blöcke gecacht werden können, gibt es einige Ausnahmen:
-
Thinking-Blöcke können nicht direkt mit
cache_controlgecacht werden. Thinking-Blöcke KÖNNEN jedoch zusammen mit anderen Inhalten gecacht werden, wenn sie in vorherigen Assistenten-Runden erscheinen. Wenn sie auf diese Weise gecacht werden, ZÄHLEN sie beim Lesen aus dem Cache als Input-Token. -
Untergeordnete Content-Blöcke (wie Zitate) selbst können nicht direkt gecacht werden. Cache stattdessen den Block der obersten Ebene.
Im Fall von Zitaten können die Dokument-Content-Blöcke der obersten Ebene, die als Quellmaterial für Zitate dienen, gecacht werden. So kannst du Prompt-Caching mit Zitaten effektiv nutzen, indem du die Dokumente cachst, auf die die Zitate verweisen.
-
Leere Textblöcke können nicht gecacht werden.
Was den Cache ungültig macht
Änderungen an gecachten Inhalten können den Cache teilweise oder vollständig ungültig machen.
Wie unter Strukturierung deines Prompts beschrieben, folgt der Cache der Hierarchie: tools → system → messages. Änderungen auf jeder Ebene machen diese Ebene und alle nachfolgenden Ebenen ungültig.
Die folgende Tabelle zeigt, welche Teile des Caches durch verschiedene Arten von Änderungen ungültig werden. ✘ bedeutet, dass der Cache ungültig wird, während ✓ bedeutet, dass der Cache gültig bleibt.
| Was sich ändert | Tools-Cache | System-Cache | Messages-Cache | Auswirkung |
|---|---|---|---|---|
| Tool-Definitionen | ✘ | ✘ | ✘ | Das Ändern von Tool-Definitionen (Namen, Beschreibungen, Parameter) macht den gesamten Cache ungültig |
| Websuche-Umschalter | ✓ | ✘ | ✘ | Das Aktivieren/Deaktivieren der Websuche ändert den System-Prompt |
| Zitate-Umschalter | ✓ | ✘ | ✘ | Das Aktivieren/Deaktivieren von Zitaten ändert den System-Prompt |
| Geschwindigkeitseinstellung | ✓ | ✘ | ✘ | Der Wechsel zwischen speed: "fast" und Standardgeschwindigkeit macht System- und Messages-Caches ungültig |
| Tool-Auswahl | ✓ | ✓ | ✘ | Änderungen am Parameter tool_choice betreffen nur Nachrichtenblöcke |
| Bilder | ✓ | ✓ | ✘ | Das Hinzufügen/Entfernen von Bildern an beliebiger Stelle im Prompt betrifft Nachrichtenblöcke |
| Thinking-Parameter | Modellspezifisch | Modellspezifisch | ✘ | Die Thinking-Konfiguration (Modus und budget_tokens im erweiterten Modus) wird in den Prompt eingefügt, daher macht eine Änderung immer Nachrichtenblöcke ungültig; Tool- und System-Caches werden ebenfalls ungültig bei Modellen, die die Konfiguration vor ihnen einfügen. Siehe Nachdenken und Prompt-Caching. |
| Effort-Einstellung | Modellspezifisch | Modellspezifisch | ✘ | Das Ändern des Werts von output_config.effort kann Nachrichtenblöcke ungültig machen und bei einigen Modellen auch Tool- und System-Caches (siehe Nachdenken und Prompt-Caching). Effort explizit auf den Standardwert des Modells zu setzen, ist gleichbedeutend mit dem Weglassen und macht nichts ungültig. Bei Modellen, die Effort pro Nachricht unterstützen, lässt eine Effort-Änderung, die in einer role: "system"-Nachricht innerhalb von messages übermittelt wird, das gecachte Präfix intakt. |
| Nicht-Tool-Ergebnisse in Anfragen mit Nachdenken | ✓ | ✓ | Modellspezifisch | Bei Claude Opus 4.5 und späteren Opus-Modellen, Claude Sonnet 4.6 und späteren Sonnet-Modellen, Claude Haiku 5.5 sowie jedem Modell von Claude Fable und Claude Mythos werden Thinking-Blöcke standardmäßig beibehalten, sodass der Cache gültig bleibt (✓). Bei anderen Modellen werden alle zuvor gecachten Thinking-Blöcke aus dem Kontext entfernt, und alle Nachrichten, die auf diese Thinking-Blöcke folgen, werden aus dem Cache entfernt (✘). Weitere Details findest du unter Caching mit Thinking-Blöcken. |
| Weggelassene Thinking-Blöcke | ✓ | ✓ | ✘ | Wenn die API einen Thinking-Block weglässt, der in dieser Anfrage nicht bewahrt wird, ändert sich das gecachte Präfix in dieser Anfrage ab der Position dieses Blocks. Blöcke, die das empfangende Modell lesen kann und die unverändert zurückgegeben werden, lassen den Cache intakt. |
Bei Modellen, die Tool-Änderungen mitten im Gespräch unterstützen, kannst du mit dem Beta-Header inline-tools-2026-09-15 mitten in einem Gespräch ein Tool hinzufügen oder die Definition eines Tools ändern, ohne tools zu bearbeiten. Sende die Definition in einem tool_addition-Block in einer Systemnachricht mitten im Gespräch und lass tools genau so, wie du es ursprünglich gesendet hast. Das gecachte Präfix stimmt weiterhin überein, sodass nur die angehängte Nachricht als neue Eingabe verarbeitet wird. Die einzige Ausnahme ist ein tools-Array ohne nicht zurückgestelltes Tool; dort kostet das erste auf diese Weise definierte Tool in dieser Anfrage einen vollständigen Cache-Miss. Siehe Tools in einer Nachricht definieren.
Cache-Performance überwachen
Überwache die Cache-Performance mit diesen API-Antwortfeldern innerhalb von usage in der Antwort (oder im message_start-Event beim Streaming):
cache_creation_input_tokens: Anzahl der Token, die beim Erstellen eines neuen Eintrags in den Cache geschrieben wurdencache_read_input_tokens: Anzahl der Token, die für diese Anfrage aus dem Cache abgerufen wurdeninput_tokens: Anzahl der Input-Token, die weder aus einem Cache gelesen noch zum Erstellen eines Caches verwendet wurden (also Token nach dem letzten Cache-Breakpoint)
Caching mit Thinking-Blöcken
Wenn du Nachdenken mit Prompt-Caching verwendest, verhalten sich Thinking-Blöcke besonders:
Automatisches Caching zusammen mit anderen Inhalten: Obwohl Thinking-Blöcke nicht explizit mit cache_control markiert werden können, werden sie als Teil des Request-Inhalts gecacht, wenn du nachfolgende API-Aufrufe mit Tool-Ergebnissen machst. Dies geschieht häufig während der Tool-Nutzung, wenn du Thinking-Blöcke zurückgibst, um das Gespräch fortzusetzen.
Zählung der Input-Token: Wenn Thinking-Blöcke aus dem Cache gelesen werden, zählen sie in deinen Nutzungsmetriken als Input-Token. Dies ist wichtig für die Kostenberechnung und die Token-Budgetierung.
Muster der Cache-Invalidierung:
- Der Cache bleibt gültig, wenn nur Tool-Ergebnisse als Benutzernachrichten bereitgestellt werden.
- Bei Claude Opus 4.5 und späteren Opus-Modellen, Claude Sonnet 4.6 und späteren Sonnet-Modellen, Claude Haiku 5.5 sowie jedem Modell von Claude Fable und Claude Mythos werden Thinking-Blöcke standardmäßig beibehalten, selbst wenn Benutzerinhalte hinzugefügt werden, die keine Tool-Ergebnisse sind, sodass der Cache gültig bleibt.
- Bei anderen Modellen macht das Hinzufügen von Benutzerinhalten, die keine Tool-Ergebnisse sind, den Cache ungültig und entfernt alle vorherigen Thinking-Blöcke aus dem Kontext.
- Dieses Caching-Verhalten tritt auch ohne explizite
cache_control-Markierungen auf.
Weitere Details zur Cache-Invalidierung findest du unter Was den Cache ungültig macht.
Beispiel mit Tool-Nutzung:
Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]
Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1
Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)Bei den Modellen, die früheres Nachdenken beibehalten, bleiben vorherige Thinking-Blöcke standardmäßig im Kontext und sind weiterhin Teil des gecachten Präfixes. Bei anderen Modellen werden an diesem Punkt alle vorherigen Thinking-Blöcke aus dem Kontext entfernt.
Ausführlichere Informationen findest du unter Nachdenken und Prompt-Caching.
Cache-Speicherung und -Freigabe
Für Prompt-Caching gelten diese Regeln:
-
Isolation nach Organisation: Verschiedene Organisationen teilen niemals Caches, selbst wenn sie identische Prompts verwenden.
-
Isolation nach Workspace: In der Claude API, auf Claude Platform on AWS und Microsoft Foundry sind Caches zusätzlich zwischen Workspaces isoliert. Auf diesen Plattformen baut jeder Workspace seinen eigenen Cache auf. Auf Claude Models on Google Cloud (Google managed) und Amazon Bedrock sind Caches nur nach Organisation isoliert.
-
Exakte Übereinstimmung: Cache-Treffer erfordern 100 % identische Prompt-Segmente, einschließlich aller Texte und Bilder bis einschließlich des mit Cache-Steuerung markierten Blocks.
-
Generierung von Output-Token: Prompt-Caching hat keinen Einfluss auf die Generierung von Output-Token. Die Antwort, die du erhältst, ist identisch mit der, die du ohne Prompt-Caching erhalten würdest.
Best Practices für effektives Caching
So optimierst du die Performance des Prompt-Cachings:
- Beginne bei Gesprächen mit mehreren Runden mit automatischem Caching. Es übernimmt die Verwaltung der Breakpoints automatisch.
- Verwende explizite Breakpoints auf Blockebene, wenn du verschiedene Abschnitte mit unterschiedlicher Änderungshäufigkeit cachen musst.
- Cache stabile, wiederverwendbare Inhalte wie Systemanweisungen, Hintergrundinformationen, große Kontexte oder häufig verwendete Tool-Definitionen.
- Platziere gecachte Inhalte am Anfang des Prompts, um die beste Performance zu erzielen.
- Setze Cache-Breakpoints strategisch ein, um verschiedene cachebare Präfix-Abschnitte voneinander zu trennen.
- Platziere den Breakpoint auf dem letzten Block, der über Anfragen hinweg identisch bleibt. Bei einem Prompt mit statischem Präfix und variierendem Suffix (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht) ist das das Ende des Präfixes, nicht der variierende Block.
- Analysiere regelmäßig die Cache-Trefferquoten und passe deine Strategie bei Bedarf an.
Optimierung für verschiedene Anwendungsfälle
Passe deine Prompt-Caching-Strategie an dein Szenario an:
- Konversationelle Agenten: Reduziere Kosten und Latenz bei langen Gesprächen, insbesondere bei solchen mit langen Anweisungen oder hochgeladenen Dokumenten.
- Coding-Assistenten: Verbessere Autovervollständigung und Fragen und Antworten zur Codebasis, indem du relevante Abschnitte oder eine zusammengefasste Version der Codebasis im Prompt hältst.
- Verarbeitung großer Dokumente: Binde vollständiges, umfangreiches Material einschließlich Bildern in deinen Prompt ein, ohne die Antwortlatenz zu erhöhen.
- Detaillierte Anweisungssätze: Teile umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um die Antworten von Claude feinabzustimmen. Entwickler fügen oft ein oder zwei Beispiele in den Prompt ein, aber mit Prompt-Caching kannst du eine noch bessere Performance erzielen, indem du mehr als 20 vielfältige Beispiele hochwertiger Antworten einfügst.
- Agentische Tool-Nutzung: Verbessere die Performance in Szenarien mit mehreren Tool-Aufrufen und iterativen Codeänderungen, bei denen jeder Schritt typischerweise einen neuen API-Aufruf erfordert.
- Bücher, Fachartikel, Dokumentationen, Podcast-Transkripte und andere umfangreiche Inhalte: Mache jede Wissensdatenbank interaktiv, indem du das gesamte Dokument bzw. die gesamten Dokumente in den Prompt einbettest und Benutzer Fragen dazu stellen lässt.
Behebung häufiger Probleme
Wenn du unerwartetes Verhalten feststellst:
- Stelle sicher, dass gecachte Abschnitte über Aufrufe hinweg identisch sind. Prüfe bei expliziten Breakpoints, ob sich die
cache_control-Markierungen an denselben Stellen befinden. - Prüfe, ob die Aufrufe innerhalb der Cache-Lebensdauer (standardmäßig 5 Minuten) erfolgen.
- Prüfe, ob
tool_choice, die Verwendung von Bildern, die Thinking-Konfiguration undoutput_config.effortzwischen den Aufrufen konsistent bleiben. - Stelle sicher, dass du mindestens die Mindestanzahl an Token für dein Modell und deine Plattform cachst (siehe Cache-Einschränkungen).
- Vergewissere dich, dass dein Breakpoint auf einem Block liegt, der über Anfragen hinweg identisch bleibt. Cache-Writes erfolgen nur am Breakpoint, und wenn sich dieser Block ändert (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht), stimmt der Präfix-Hash nie überein. Der Lookback findet keine stabilen Inhalte hinter dem Breakpoint; er findet nur Einträge, die frühere Anfragen an ihren eigenen Breakpoints geschrieben haben.
- Prüfe, ob die Schlüssel in deinen
tool_use-Content-Blöcken eine stabile Reihenfolge haben, da einige Sprachen (zum Beispiel Swift, Go) die Schlüsselreihenfolge bei der JSON-Konvertierung zufällig anordnen und dadurch Caches zerstören. - Verwende die Cache-Diagnose, damit die API aufeinanderfolgende Anfragen vergleicht und meldet, welcher Teil des Prompts abgewichen ist.
1-Stunden-Cache-Dauer
Wenn dir 5 Minuten zu kurz sind, bietet Anthropic auch eine Cache-Dauer von 1 Stunde gegen Aufpreis an (siehe Preise). Die 1-Stunden-Dauer ist auf jeder Plattform verfügbar, die Prompt-Caching unterstützt.
Um den erweiterten Cache zu verwenden, füge ttl wie folgt in die cache_control-Definition ein:
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}Die Antwort enthält detaillierte Cache-Informationen wie die folgenden:
{
"usage": {
"input_tokens": 2048,
"cache_read_input_tokens": 1800,
"cache_creation_input_tokens": 248,
"output_tokens": 503,
"cache_creation": {
"ephemeral_5m_input_tokens": 148,
"ephemeral_1h_input_tokens": 100
}
}
}Das Feld cache_creation_input_tokens entspricht der Summe der Werte im cache_creation-Objekt.
Wenn du bei der Verwendung von Server-Tools wie der Websuche ephemeral_5m_input_tokens-Schreibvorgänge siehst, die du nicht angefordert hast, siehe Server-Tool-Ergebnisse werden automatisch gecacht.
Wann der 1-Stunden-Cache sinnvoll ist
Wenn du einen Prompt in regelmäßigem Rhythmus verwendest (zum Beispiel einen System-Prompt, den du häufiger als alle 5 Minuten sendest), verwende weiterhin den 5-Minuten-Cache, da dieser weiterhin ohne zusätzliche Kosten aufgefrischt wird.
Der 1-Stunden-Cache eignet sich am besten für die folgenden Szenarien:
- Wenn du Prompts hast, die voraussichtlich seltener als alle 5 Minuten, aber häufiger als jede Stunde verwendet werden. Zum Beispiel, wenn ein agentischer Neben-Agent länger als 5 Minuten braucht, oder wenn du ein langes Chat-Gespräch mit einem Benutzer speicherst und generell damit rechnest, dass dieser Benutzer in den nächsten 5 Minuten möglicherweise nicht antwortet.
- Wenn Latenz wichtig ist und deine Folge-Prompts möglicherweise erst nach mehr als 5 Minuten gesendet werden.
- Wenn du die Auslastung deines Ratenlimits verbessern möchtest, da Cache-Treffer nicht auf dein Ratenlimit angerechnet werden.
Verschiedene TTLs mischen
Du kannst 1-Stunden- und 5-Minuten-Cache-Controls in derselben Anfrage verwenden, allerdings mit einer wichtigen Einschränkung: Cache-Einträge mit längerer TTL müssen vor kürzeren TTLs erscheinen (das heißt, ein 1-Stunden-Cache-Eintrag muss vor allen 5-Minuten-Cache-Einträgen erscheinen).
Beim Mischen von TTLs bestimmt die Claude API drei Abrechnungspositionen in deinem Prompt:
- Position
A: Die Token-Anzahl beim letzten Cache-Treffer in deinem Prompt (oder 0, wenn es keine Treffer gibt).- Ein Treffer auf einen mit einer 5-Minuten-TTL gecachten Eintrag wird nicht als Treffer gewertet, wenn ein
cache_control-Block mit 1-Stunden-TTL, der im Prompt nach diesem Eintrag steht, ein Cache-Miss ist. - Eine Anfrage, die einen mit einer 5-Minuten-TTL gecachten Eintrag liest, startet die 5-Minuten-Lebensdauer des Eintrags neu, auch wenn die Anfrage jetzt
"ttl": "1h"setzt.
- Ein Treffer auf einen mit einer 5-Minuten-TTL gecachten Eintrag wird nicht als Treffer gewertet, wenn ein
- Position
B: Die Token-Anzahl beim letzten 1-Stunden-cache_control-Block nachA(oder gleichA, wenn keiner existiert). - Position
C: Die Token-Anzahl beim letztencache_control-Block.
Dir wird Folgendes berechnet:
- Cache-Lese-Token für
A. - 1-Stunden-Cache-Schreib-Token für
(B - A). - 5-Minuten-Cache-Schreib-Token für
(C - B).
Hier sind drei Beispielanfragen, jede mit unterschiedlichen Cache-Treffern und Cache-Misses. Jede hat einen unterschiedlich berechneten Preis, der in den Kästen angezeigt wird.
Vorwärmen des Caches
„Cache pre-warming“ (Vorwärmen des Caches) ermöglicht es dir, deinen System-Prompt oder deine Tool-Definitionen in den Prompt-Cache zu laden, bevor ein Benutzer eine echte Anfrage auslöst. Dadurch kann sich die Latenzeinbuße durch einen Cache-Miss bei der ersten Benutzerinteraktion verringern, was die „time-to-first-token“ (Zeit bis zum ersten Token), oder TTFT, für latenzempfindliche Anwendungen senkt.
Funktionsweise
Setze max_tokens: 0 in deiner Anfrage. Die API liest deinen Prompt in das Modell ein und schreibt den Cache an jedem cache_control-Breakpoint, kehrt dann sofort zurück, ohne eine Ausgabe zu generieren. Die Antwort enthält ein leeres content-Array, stop_reason: "max_tokens" und einen vollständig befüllten usage-Block.
Platziere den cache_control-Breakpoint auf dem letzten Block, der mit der Folgeanfrage geteilt wird (typischerweise dein System-Prompt oder deine Tool-Definitionen), nicht auf der Platzhalter-Benutzernachricht. Andernfalls ist der Cache-Eintrag an den Platzhalter gebunden, und die Folgeanfrage trifft ihn nicht. Verwende außerdem dieselbe Nachdenken-Konfiguration und denselben output_config.effort wie in deinen Folgeanfragen: Diese Werte werden in den Prompt gerendert (siehe Was den Cache ungültig macht), sodass ein Vorwärmen mit einer anderen Konfiguration einen Eintrag schreiben kann, den dein echter Traffic nie trifft. Das bedeutet, dass du einen expliziten Cache-Breakpoint statt automatischem Caching verwenden solltest, da automatisches Caching den Breakpoint auf den letzten Block setzt, der hier der Platzhalter ist. Die Platzhalter-Benutzernachricht kann eine beliebige Zeichenkette mit Inhalt ohne reine Leerzeichen sein (die Beispiele hier verwenden "warmup"); ihr Inhalt wird in das Modell eingelesen, aber nie beantwortet.
client = anthropic.Anthropic()
# Löse dies aus, bevor Nutzer kommen, um den gemeinsamen System-Prompt-Cache vorzuwärmen.
prewarm = client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=[
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason) # "max_tokens"
print(prewarm.content) # []
print(prewarm.usage)Die API gibt ein leeres content-Array zurück:
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [],
"model": "claude-opus-5-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 5120,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"iterations": [
{
"input_tokens": 8,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 5120,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"type": "message"
}
],
"output_tokens": 0,
"service_tier": "standard",
"inference_geo": "global"
}
}Typisches Nutzungsmuster
Sende eine Vorwärm-Anfrage, wenn deine Anwendung startet (oder in einem geplanten Intervall), und sende dann echte Benutzeranfragen, nachdem das Vorwärmen abgeschlossen ist:
client = anthropic.Anthropic()
SYSTEM_PROMPT = [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
]
def prewarm_cache() -> None:
"""Call this at application startup or on a scheduled interval."""
client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "warmup"}],
)
def respond(user_message: str) -> anthropic.types.Message:
"""The real user request; benefits from a warm cache."""
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": user_message}],
)
# Wärme den Cache auf, bevor Nutzer-Traffic eintrifft.
prewarm_cache()
# Wenn der Nutzer später eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
response = respond("How do I implement a binary search tree?")
for block in response.content:
if block.type == "text":
print(block.text)Beachte, dass die Cache-TTL weiterhin gilt. Für den standardmäßigen 5-Minuten-Cache solltest du mindestens alle 5 Minuten eine neue Vorwärm-Anfrage senden, um den Cache warm zu halten. Für längere Pausen zwischen Benutzeranfragen verwende stattdessen die 1-Stunden-Cache-Dauer.
Einschränkungen
Eine max_tokens: 0-Anfrage wird mit einem invalid_request_error abgelehnt, wenn eine der folgenden Optionen gesetzt ist, da jede davon eine Ausgabe voraussetzt, die ein Budget von null Token nicht erzeugen kann:
stream: true- Erweitertes Nachdenken (
thinking.type: "enabled") - Strukturierte Ausgaben (
output_config.format) tool_choicemit{"type": "tool", ...}oder{"type": "any"}
max_tokens: 0 wird auch innerhalb einer Message Batches-Anfrage abgelehnt. Das Vorwärmen zielt auf die Zeit bis zum ersten Token ab, die bei der Batch-Verarbeitung keine Rolle spielt, und ein während der Batch-Verarbeitung geschriebener Cache-Eintrag würde wahrscheinlich ablaufen, bevor die Folgeanfrage ausgeführt wird.
Ersetzen des max_tokens=1-Workarounds
Einige Anwendungen senden Anfragen mit max_tokens: 1, um den Cache vorzuwärmen. Bevorzuge max_tokens: 0, wo die Anfrage es zulässt: Es wird keine Ausgabe erzeugt, sodass es keine Ein-Token-Antwort zu verwerfen gibt, keine Ausgabe-Token in Rechnung gestellt werden und die Absicht der Anfrage eindeutig ist.
Beispiele für Prompt-Caching
Um dir den Einstieg in das Prompt-Caching zu erleichtern, bietet das Prompt-Caching-Rezept im Claude Cookbook ausführliche Beispiele und Best Practices.
Die folgenden Code-Snippets zeigen verschiedene Prompt-Caching-Muster. Diese Beispiele demonstrieren, wie Caching in verschiedenen Szenarien implementiert wird, und helfen dir, die praktischen Anwendungen dieser Funktion zu verstehen:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing legal documents.",
},
{
"type": "text",
"text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "What are the key terms and conditions in this agreement?",
}
],
)
print(response.usage.model_dump_json())Dieses Beispiel demonstriert die grundlegende Nutzung von Prompt-Caching, wobei der vollständige Text der Rechtsvereinbarung als Präfix gecacht wird, während die Benutzeranweisung ungecacht bleibt.
Für die erste Anfrage:
input_tokens: Anzahl der Token nur in der Benutzernachrichtcache_creation_input_tokens: Anzahl der Token in der gesamten Systemnachricht, einschließlich des Rechtsdokumentscache_read_input_tokens: 0 (kein Cache-Treffer bei der ersten Anfrage)
Für nachfolgende Anfragen innerhalb der Cache-Lebensdauer:
input_tokens: Anzahl der Token nur in der Benutzernachrichtcache_creation_input_tokens: 0 (keine neue Cache-Erstellung)cache_read_input_tokens: Anzahl der Token in der gesamten gecachten Systemnachricht
Tool-Definitionen können gecacht werden, indem du cache_control auf das letzte Tool in deinem tools-Array setzt. Alle Tools, die vor diesem Tool definiert sind, einschließlich dieses Tools selbst, werden als ein einziges Präfix gecacht.
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": { "location": { "type": "string" } },
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": { "timezone": { "type": "string" } },
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}Bei der ersten Anfrage spiegelt cache_creation_input_tokens die Token-Anzahl aller Tool-Definitionen wider. Bei nachfolgenden Anfragen innerhalb der Cache-Lebensdauer erscheinen diese Token stattdessen unter cache_read_input_tokens.
Für Details zum Zusammenspiel von Tool-Definitionen, defer_loading und Cache-Invalidierung siehe Tool-Nutzung mit Prompt-Caching.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "...long system prompt",
"cache_control": {"type": "ephemeral"},
}
],
messages=[
# ...bisherige lange Konversation
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, can you tell me more about the solar system?",
}
],
},
{
"role": "assistant",
"content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
},
{
"role": "user",
"content": [
{"type": "text", "text": "Good to know."},
{
"type": "text",
"text": "Tell me more about Mars.",
"cache_control": {"type": "ephemeral"},
},
],
},
],
)
print(response.usage.model_dump_json())Dieses Beispiel demonstriert, wie Prompt-Caching in einer mehrstufigen Konversation verwendet wird.
In jedem Durchgang wird der letzte Block der letzten Nachricht mit cache_control markiert, damit die Konversation inkrementell gecacht werden kann. Das System sucht automatisch die längste zuvor gecachte Sequenz von Blöcken für Folgenachrichten und verwendet sie. Blöcke, die in einem früheren Durchgang mit cache_control markiert wurden, werden nicht erneut markiert, aber eine Anfrage innerhalb von 5 Minuten liest sie trotzdem aus dem Cache und frischt ihre Lebensdauer auf.
Der cache_control-Parameter ist außerdem auf der Systemnachricht platziert. Wenn die Systemnachricht nach mehr als 5 Minuten ohne Verwendung aus dem Cache verdrängt wird, nimmt die nächste Anfrage sie wieder in den Cache auf.
Dieser Ansatz ist nützlich, um den Kontext in laufenden Konversationen beizubehalten, ohne dieselben Informationen wiederholt zu verarbeiten.
Wenn dies korrekt eingerichtet ist, solltest du in der Usage-Antwort jeder Anfrage Folgendes sehen:
input_tokens: Anzahl der Token in der neuen Benutzernachricht (minimal)cache_creation_input_tokens: Anzahl der Token in den neuen Assistenten- und Benutzerdurchgängencache_read_input_tokens: Anzahl der Token in der Konversation bis zum vorherigen Durchgang
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{
"name": "search_documents",
"description": "Search through the knowledge base",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"],
},
},
{
"name": "get_document",
"description": "Retrieve a specific document by ID",
"input_schema": {
"type": "object",
"properties": {
"doc_id": {"type": "string", "description": "Document ID"}
},
"required": ["doc_id"],
},
"cache_control": {"type": "ephemeral"},
},
],
system=[
{
"type": "text",
"text": """You are a helpful research assistant with access to a document knowledge base.
# Instructions
- Always search for relevant documents before answering
- Provide citations for your sources
- Be objective and accurate in your responses
- If multiple documents contain relevant information, synthesize them
- Acknowledge when information is not available in the knowledge base""",
"cache_control": {"type": "ephemeral"},
},
{
"type": "text",
"text": """# Knowledge Base Context
Here are the relevant documents for this conversation:
## Document 1: Solar System Overview
The solar system consists of the Sun and all objects that orbit it...
## Document 2: Planetary Characteristics
Each planet has unique features. Mercury is the smallest planet...
## Document 3: Mars Exploration
Mars has been a target of exploration for decades...
[Additional documents...]""",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Can you search for information about Mars rovers?",
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "tool_1",
"name": "search_documents",
"input": {"query": "Mars rovers"},
}
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "tool_1",
"content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}
],
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
}
],
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Yes, please tell me about the Perseverance rover specifically.",
"cache_control": {"type": "ephemeral"},
}
],
},
],
)
print(response.usage.model_dump_json())Dieses umfassende Beispiel demonstriert, wie alle 4 verfügbaren Cache-Breakpoints verwendet werden, um verschiedene Teile deines Prompts zu optimieren:
-
Tools-Cache (Cache-Breakpoint 1): Der
cache_control-Parameter auf der letzten Tool-Definition cacht alle Tool-Definitionen. -
Cache für wiederverwendbare Anweisungen (Cache-Breakpoint 2): Die statischen Anweisungen im System-Prompt werden separat gecacht. Diese Anweisungen ändern sich zwischen Anfragen selten.
-
RAG-Kontext-Cache (Cache-Breakpoint 3): Die Dokumente der Wissensdatenbank werden unabhängig gecacht, sodass du die RAG-Dokumente aktualisieren kannst, ohne den Cache für Tools oder Anweisungen ungültig zu machen.
-
Cache für den Konversationsverlauf (Cache-Breakpoint 4): Die letzte Benutzernachricht wird mit
cache_controlmarkiert, um das inkrementelle Caching der Konversation während ihres Verlaufs zu ermöglichen.
Dieser Ansatz bietet maximale Flexibilität:
- Wenn du einen neuen Durchgang an die Konversation anhängst, ohne früheren Inhalt zu ändern, werden alle vier Cache-Segmente wiederverwendet.
- Wenn du die RAG-Dokumente aktualisierst, aber dieselben Tools und Anweisungen beibehältst, werden die ersten beiden Cache-Segmente wiederverwendet.
- Wenn du die Konversation änderst, aber dieselben Tools, Anweisungen und Dokumente beibehältst, werden die ersten drei Segmente wiederverwendet.
- Änderungen an einem beliebigen Breakpoint machen dieses Segment und alles danach ungültig, während frühere gecachte Segmente gültig bleiben.
Für die erste Anfrage:
input_tokens: Minimal (Token nach dem letzten Cache-Breakpoint, in diesem Beispiel nahe 0)cache_creation_input_tokens: Token in allen gecachten Segmenten (Tools + Anweisungen + RAG-Dokumente + Konversationsverlauf)cache_read_input_tokens: 0 (keine Cache-Treffer)
Für nachfolgende Anfragen mit nur einer neuen Benutzernachricht (und dem vierten Breakpoint, der wie im Beispiel auf diese neue letzte Nachricht verschoben wurde):
input_tokens: Minimal (Token nach dem letzten Cache-Breakpoint, in diesem Beispiel nahe 0)cache_creation_input_tokens: Token in der neuen Benutzernachricht und dem vorherigen Assistentendurchgang (das neue Konversationssegment, das gecacht wird)cache_read_input_tokens: Alle zuvor gecachten Token (Tools + Anweisungen + RAG-Dokumente + vorherige Konversation)
Dieses Muster ist besonders leistungsstark für:
- RAG-Anwendungen mit großen Dokumentkontexten
- Agentensysteme, die mehrere Tools verwenden
- Lang laufende Konversationen, die den Kontext beibehalten müssen
- Anwendungen, die verschiedene Teile des Prompts unabhängig voneinander optimieren müssen
Datenaufbewahrung
Prompt-Caching (sowohl automatisch als auch explizit) ist ZDR-berechtigt. Anthropic speichert nicht den Rohtext deiner Prompts oder der Antworten von Claude.
KV-Cache-Repräsentationen (Key-Value) und kryptografische Hashes von gecachtem Inhalt werden nur im Arbeitsspeicher gehalten und nicht im Ruhezustand gespeichert. Gecachte Einträge haben eine Mindestlebensdauer von 5 Minuten (Standard) oder 1 Stunde (erweitert), nach der sie zeitnah, aber nicht sofort gelöscht werden.
Cache-Einträge sind zwischen Organisationen isoliert und auf einigen Plattformen auch zwischen Workspaces innerhalb einer Organisation.
FAQ
In den meisten Fällen reicht ein einzelner Cache-Breakpoint am Ende deines statischen Inhalts aus. Cache-Schreibvorgänge erfolgen nur an dem Block, den du markierst. Platziere ihn auf dem letzten Block, der über Anfragen hinweg identisch bleibt, und jede nachfolgende Anfrage liest denselben Eintrag. Wenn ein späterer Block mit jeder Anfrage variiert (ein Zeitstempel, die eingehende Nachricht), setze den Breakpoint davor, auf den letzten stabilen Block.
Du brauchst mehrere Breakpoints nur, wenn:
- Eine wachsende Konversation deinen Breakpoint 20 oder mehr Blöcke über den letzten Cache-Schreibvorgang hinaus verschiebt, wodurch der vorherige Eintrag außerhalb des Lookback-Fensters liegt
- Du Abschnitte, die sich in unterschiedlicher Häufigkeit ändern, unabhängig voneinander cachen möchtest
- Du zur Kostenoptimierung explizite Kontrolle darüber benötigst, was gecacht wird
Beispiel: Wenn du Systemanweisungen (ändern sich selten) und RAG-Kontext (ändert sich täglich) hast, könntest du zwei Breakpoints verwenden, um sie separat zu cachen.
Nein, Cache-Breakpoints selbst sind kostenlos. Du zahlst nur für:
- Das Schreiben von Inhalten in den Cache (25 Prozent mehr als Basis-Eingabe-Token bei 5-Minuten-TTL)
- Das Lesen aus dem Cache (ein Bruchteil des Basispreises für Eingabe-Token)
- Reguläre Eingabe-Token für nicht gecachten Inhalt
Die Anzahl der Breakpoints beeinflusst die Preisgestaltung nicht; nur die Menge des gecachten und gelesenen Inhalts zählt.
Die Usage-Antwort enthält drei separate Felder für Eingabe-Token, die zusammen deine gesamte Eingabe darstellen:
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokenscache_read_input_tokens: Aus dem Cache abgerufene Token (alles vor Cache-Breakpoints, das gecacht war)cache_creation_input_tokens: Neue Token, die in den Cache geschrieben werden (an Cache-Breakpoints)input_tokens: Token nach dem letzten Cache-Breakpoint, die nicht gecacht sind
Wichtig: input_tokens repräsentiert NICHT alle Eingabe-Token, sondern nur den Teil nach deinem letzten Cache-Breakpoint. Wenn du gecachten Inhalt hast, ist input_tokens typischerweise viel kleiner als deine gesamte Eingabe.
Beispiel: Mit einem gecachten Dokument von 200k Token und einer Benutzerfrage mit 50 Token:
cache_read_input_tokens: 200.000cache_creation_input_tokens: 0input_tokens: 50- Gesamt: 200.050 Token
Diese Aufschlüsselung ist entscheidend, um sowohl deine Kosten als auch deine Ratenlimit-Nutzung zu verstehen. Siehe Cache-Performance überwachen für weitere Details.
Die standardmäßige Mindestlebensdauer (TTL) des Caches beträgt 5 Minuten. Diese Lebensdauer wird jedes Mal aufgefrischt, wenn der gecachte Inhalt verwendet wird.
Wenn dir 5 Minuten zu kurz sind, bietet Anthropic auch eine 1-Stunden-Cache-TTL an.
Die Lebensdauer wird ab dem Beginn der Anfrage gemessen, die den Cache-Eintrag schreibt oder liest, nicht ab dem Ende ihrer Antwort. Die Zeit, die für die Generierung einer Antwort aufgewendet wird, zählt zur Lebensdauer, sodass das Zeitfenster, in dem eine Folgeanfrage den Cache wiederverwenden kann, die Lebensdauer abzüglich der Generierungszeit ist.
Wenn deine Anfragen lange Antworten erzeugen und die nächste Anfrage möglicherweise erst nach Ablauf der Lebensdauer beginnt, verwende die 1-Stunden-Cache-TTL.
Du kannst bis zu 4 Cache-Breakpoints (mithilfe von cache_control-Parametern) in deinem Prompt definieren.
Prompt-Caching wird auf allen aktiven Claude-Modellen unterstützt.
Das Ändern von Nachdenken-Parametern (Wechseln des Modus oder Ändern des Budgets im erweiterten Modus) macht gecachte Nachrichtenpräfixe ungültig und kann auch gecachte System-Prompts und Tools ungültig machen, da die Nachdenken-Konfiguration in den Prompt gerendert wird. Das Ändern des Werts output_config.effort kann dasselbe bewirken.
Weitere Details zur Cache-Invalidierung findest du unter Was den Cache ungültig macht.
Mehr zum Nachdenken, einschließlich seines Zusammenspiels mit Tool-Nutzung und Prompt-Caching, findest du unter Nachdenken und Prompt-Caching.
Am einfachsten fügst du "cache_control": {"type": "ephemeral"} auf der obersten Ebene deines Request-Bodys hinzu (automatisches Caching). Alternativ fügst du mindestens einen cache_control-Breakpoint auf einzelnen Inhaltsblöcken ein (explizite Cache-Breakpoints).
Ja, Prompt-Caching kann zusammen mit anderen API-Funktionen wie Tool-Nutzung und Vision-Fähigkeiten verwendet werden. Allerdings bricht das Ändern, ob Bilder in einem Prompt enthalten sind, oder das Modifizieren von Einstellungen zur Tool-Nutzung den Cache.
Weitere Details zur Cache-Invalidierung findest du unter Was den Cache ungültig macht.
Prompt-Caching hat eine eigene Preisstruktur: 5-Minuten-Cache-Schreibvorgänge kosten 25 Prozent mehr als Basis-Eingabe-Token, 1-Stunden-Cache-Schreibvorgänge kosten das 2-Fache der Basis-Eingabe-Token und Cache-Treffer kosten einen Bruchteil des Basispreises für Eingabe-Token, mit einem Multiplikator pro Modell.
Es gibt keine Möglichkeit, den Cache manuell zu leeren. Gecachte Präfixe laufen automatisch nach mindestens 5 Minuten Inaktivität ab.
Du kannst die Cache-Leistung mithilfe der Felder cache_creation_input_tokens und cache_read_input_tokens in der API-Antwort überwachen.
Siehe Was den Cache ungültig macht für weitere Details zur Cache-Invalidierung, einschließlich einer Liste von Änderungen, die das Erstellen eines neuen Cache-Eintrags erfordern.
Prompt-Caching ist mit strengen Maßnahmen für Datenschutz und Datentrennung konzipiert:
-
Cache-Schlüssel werden mithilfe eines kryptografischen Hashes der Prompts bis zum Cache-Control-Punkt generiert. Das bedeutet, dass nur Anfragen mit identischen Prompts auf einen bestimmten Cache zugreifen können.
-
Caches werden niemals zwischen Organisationen geteilt, selbst bei identischen Prompts. Auf einigen Plattformen sind sie zusätzlich nach Workspace innerhalb einer Organisation isoliert.
-
Der Caching-Mechanismus ist darauf ausgelegt, die Integrität und Privatsphäre jeder einzelnen Konversation oder jedes einzelnen Kontexts zu wahren.
-
Es ist sicher,
cache_controlan beliebiger Stelle in deinen Prompts zu verwenden. Damit Caching Lesevorgänge erzeugt, platziere den Breakpoint am Ende eines stabilen Präfixes: Wenn du ihn auf einen Block setzt, der sich bei jeder Anfrage ändert (etwa einen Zeitstempel oder die beliebige Eingabe des Benutzers), wird jedes Mal ein neuer Eintrag geschrieben, der nie getroffen wird.
Diese Maßnahmen stellen sicher, dass Prompt-Caching Datenschutz und Sicherheit gewährleistet und gleichzeitig Leistungsvorteile bietet.
Ja, du kannst Prompt-Caching mit deinen Message Batches API-Anfragen verwenden. Da asynchrone Batch-Anfragen jedoch gleichzeitig und in beliebiger Reihenfolge verarbeitet werden können, werden Cache-Treffer nach dem Best-Effort-Prinzip bereitgestellt.
Der 1-Stunden-Cache kann helfen, deine Cache-Treffer zu verbessern. Die kosteneffektivste Art, ihn zu nutzen, ist folgende:
- Sammle eine Gruppe von Nachrichtenanfragen, die ein gemeinsames Präfix haben.
- Sende eine Batch-Anfrage mit einer einzigen Anfrage, die dieses gemeinsame Präfix und einen 1-Stunden-Cache-Block enthält. Dadurch wird das Präfix in den 1-Stunden-Cache geschrieben.
- Sobald dies abgeschlossen ist, reiche die restlichen Anfragen ein. Du musst den Job überwachen, um zu wissen, wann er abgeschlossen ist.
Dies ist typischerweise besser als die Verwendung des 5-Minuten-Caches, da Batch-Anfragen häufig zwischen 5 Minuten und 1 Stunde bis zum Abschluss benötigen.
Dieser Fehler tritt typischerweise auf, wenn du dein SDK aktualisiert hast oder veraltete Codebeispiele verwendest. Prompt-Caching ist über client.messages verfügbar, ohne das Beta-Präfix. Statt:
client.beta.prompt_caching.messages.create(**params)Verwende:
client.messages.create(**params)Dieser Fehler tritt typischerweise auf, wenn du dein SDK aktualisiert hast oder veraltete Codebeispiele verwendest. Prompt-Caching ist über client.messages verfügbar, ohne das Beta-Präfix. Statt:
client.beta.promptCaching.messages.create(/* ... */);Verwende:
client.messages.create(/* ... */);Verfügbarkeit
Claude API
- APIs
- Messages API
- Managed Agents Beta
- Modelle
- Alle Modelle
Amazon Bedrock
- API
- Messages API
- Modelle
- Alle Modelle
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelle
- Alle Modelle
Claude Platform on AWS
- APIs
- Messages API
- Managed Agents Beta
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Anthropic managed)
- APIs
- Messages API
- Managed Agents Beta
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelle
- Alle Modelle
Microsoft Foundry
- API
- Messages API
- Modelle
- Alle Modelle
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/messages
Ausgenommen: Abgedeckte Modelle
Deine Prompts und die Ausgaben von Claude werden nicht gespeichert. KV-Cache-Repräsentationen und kryptografische Hashes werden für die Cache-TTL im Arbeitsspeicher gehalten und nach Ablauf umgehend gelöscht. Mehr erfahren
War diese Seite hilfreich?