Prompt-Caching
Prompt-Caching ist eine leistungsstarke Funktion, die Ihre API-Nutzung optimiert, indem sie das Fortsetzen von spezifischen Präfixen in Ihren Prompts ermöglicht. Dieser Ansatz reduziert die Verarbeitungszeit und Kosten für sich wiederholende Aufgaben oder Prompts mit konsistenten Elementen erheblich.
Hier ist ein Beispiel, wie Sie Prompt-Caching mit der Messages API unter Verwendung eines cache_control
-Blocks implementieren:
In diesem Beispiel wird der gesamte Text von “Stolz und Vorurteil” mit dem cache_control
-Parameter zwischengespeichert. Dies ermöglicht die Wiederverwendung dieses großen Textes über mehrere API-Aufrufe hinweg, ohne ihn jedes Mal neu zu verarbeiten. Wenn Sie nur die Benutzernachricht ändern, können Sie verschiedene Fragen über das Buch stellen, während Sie den zwischengespeicherten Inhalt nutzen, was zu schnelleren Antworten und verbesserter Effizienz führt.
Wie Prompt-Caching funktioniert
Wenn Sie eine Anfrage mit aktiviertem Prompt-Caching senden:
- Das System überprüft, ob ein Prompt-Präfix bis zu einem bestimmten Cache-Breakpoint bereits aus einer kürzlichen Abfrage zwischengespeichert ist.
- Falls gefunden, verwendet es die zwischengespeicherte Version, wodurch Verarbeitungszeit und Kosten reduziert werden.
- Andernfalls verarbeitet es den vollständigen Prompt und speichert den Präfix zwischen, 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 konsistenten Anweisungen
- Lange mehrteilige Gespräche
Standardmäßig hat der Cache eine Lebensdauer von 5 Minuten. Der Cache wird ohne zusätzliche Kosten jedes Mal aktualisiert, wenn der zwischengespeicherte Inhalt verwendet wird.
Prompt-Caching speichert den vollständigen Präfix zwischen
Prompt-Caching referenziert den gesamten Prompt - tools
, system
und messages
(in dieser Reihenfolge) bis einschließlich des mit cache_control
bezeichneten Blocks.
Preisgestaltung
Prompt-Caching führt eine neue Preisstruktur ein. Die folgende Tabelle zeigt den Preis pro Million Token für jedes unterstützte Modell:
Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
---|---|---|---|---|---|
Claude Opus 4 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Haiku 3.5 | $0.80 / MTok | $1 / MTok | $1.6 / MTok | $0.08 / MTok | $4 / MTok |
Claude Opus 3 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Haiku 3 | $0.25 / MTok | $0.30 / MTok | $0.50 / MTok | $0.03 / MTok | $1.25 / MTok |
Hinweis:
- 5-Minuten-Cache-Schreibtoken kosten das 1,25-fache des Basis-Eingabetoken-Preises
- 1-Stunden-Cache-Schreibtoken kosten das 2-fache des Basis-Eingabetoken-Preises
- Cache-Lesetoken kosten das 0,1-fache des Basis-Eingabetoken-Preises
- Reguläre Eingabe- und Ausgabetoken werden zu Standardpreisen berechnet
Wie man Prompt-Caching implementiert
Unterstützte Modelle
Prompt-Caching wird derzeit unterstützt für:
- Claude Opus 4
- Claude Sonnet 4
- Claude Sonnet 3.7
- Claude Sonnet 3.5
- Claude Haiku 3.5
- Claude Haiku 3
- Claude Opus 3
Strukturierung Ihres Prompts
Platzieren Sie statischen Inhalt (Tool-Definitionen, Systemanweisungen, Kontext, Beispiele) am Anfang Ihres Prompts. Markieren Sie das Ende des wiederverwendbaren Inhalts für das Caching mit dem cache_control
-Parameter.
Cache-Präfixe werden in der folgenden Reihenfolge erstellt: tools
, system
, dann messages
. Diese Reihenfolge bildet eine Hierarchie, in der jede Ebene auf den vorherigen aufbaut.
Wie die automatische Präfix-Überprüfung funktioniert
Sie können nur einen Cache-Breakpoint am Ende Ihres statischen Inhalts verwenden, und das System findet automatisch den längsten übereinstimmenden Präfix. So funktioniert es:
- Wenn Sie einen
cache_control
-Breakpoint hinzufügen, überprüft das System automatisch auf Cache-Treffer an allen vorherigen Inhaltsblock-Grenzen (bis zu etwa 20 Blöcke vor Ihrem expliziten Breakpoint) - Falls eine dieser vorherigen Positionen mit zwischengespeichertem Inhalt aus früheren Anfragen übereinstimmt, verwendet das System den längsten übereinstimmenden Präfix
- Das bedeutet, Sie benötigen nicht mehrere Breakpoints nur um Caching zu ermöglichen - einer am Ende ist ausreichend
Wann mehrere Breakpoints verwendet werden sollten
Sie können bis zu 4 Cache-Breakpoints definieren, wenn Sie möchten:
- Verschiedene Abschnitte zwischenspeichern, die sich mit unterschiedlichen Häufigkeiten ändern (z.B. Tools ändern sich selten, aber Kontext wird täglich aktualisiert)
- Mehr Kontrolle darüber haben, was genau zwischengespeichert wird
- Caching für Inhalte sicherstellen, die mehr als 20 Blöcke vor Ihrem finalen Breakpoint liegen
Wichtige Einschränkung: Die automatische Präfix-Überprüfung schaut nur etwa 20 Inhaltsblöcke von jedem expliziten Breakpoint zurück. Wenn Ihr Prompt mehr als 20 Inhaltsblöcke vor Ihrem Cache-Breakpoint hat, wird Inhalt früher als das nicht auf Cache-Treffer überprüft, es sei denn, Sie fügen zusätzliche Breakpoints hinzu.
Cache-Einschränkungen
Die minimale zwischenspeicherbare Prompt-Länge beträgt:
- 1024 Token für Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 und Claude Opus 3
- 2048 Token für Claude Haiku 3.5 und Claude Haiku 3
Kürzere Prompts können nicht zwischengespeichert werden, auch wenn sie mit cache_control
markiert sind. Alle Anfragen zum Zwischenspeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Antwort-Nutzungs-Felder.
Für gleichzeitige Anfragen beachten Sie, dass ein Cache-Eintrag erst verfügbar wird, nachdem die erste Antwort beginnt. Wenn Sie Cache-Treffer für parallele Anfragen benötigen, warten Sie auf die erste Antwort, bevor Sie nachfolgende Anfragen senden.
Derzeit ist “ephemeral” der einzige unterstützte Cache-Typ, der standardmäßig eine 5-minütige Lebensdauer hat.
Verständnis der Cache-Breakpoint-Kosten
Cache-Breakpoints selbst verursachen keine Kosten. Sie werden nur belastet für:
- Cache-Schreibvorgänge: Wenn neuer Inhalt in den Cache geschrieben wird (25% mehr als Basis-Eingabetoken für 5-Minuten-TTL)
- Cache-Lesevorgänge: Wenn zwischengespeicherter Inhalt verwendet wird (10% des Basis-Eingabetoken-Preises)
- Reguläre Eingabetoken: Für jeden nicht zwischengespeicherten Inhalt
Das Hinzufügen von mehr cache_control
-Breakpoints erhöht Ihre Kosten nicht - Sie zahlen immer noch den gleichen Betrag basierend darauf, welcher Inhalt tatsächlich zwischengespeichert und gelesen wird. Die Breakpoints geben Ihnen lediglich Kontrolle darüber, welche Abschnitte unabhängig zwischengespeichert werden können.
Was zwischengespeichert werden kann
Die meisten Blöcke in der Anfrage können mit cache_control
für das Caching bestimmt werden. Dies umfasst:
- Tools: Tool-Definitionen im
tools
-Array - Systemnachrichten: Inhaltsblöcke im
system
-Array - Textnachrichten: Inhaltsblöcke im
messages.content
-Array, sowohl für Benutzer- als auch Assistenten-Turns - Bilder & Dokumente: Inhaltsblöcke im
messages.content
-Array, in Benutzer-Turns - Tool-Verwendung und Tool-Ergebnisse: Inhaltsblöcke im
messages.content
-Array, sowohl in Benutzer- als auch Assistenten-Turns
Jedes dieser Elemente kann mit cache_control
markiert werden, um das Caching für diesen Teil der Anfrage zu aktivieren.
Was nicht zwischengespeichert werden kann
Während die meisten Anfrageblöcke zwischengespeichert werden können, gibt es einige Ausnahmen:
-
Thinking-Blöcke können nicht direkt mit
cache_control
zwischengespeichert werden. Thinking-Blöcke KÖNNEN jedoch zusammen mit anderem Inhalt zwischengespeichert werden, wenn sie in vorherigen Assistenten-Turns erscheinen. Wenn sie auf diese Weise zwischengespeichert werden, zählen sie als Eingabetoken, wenn sie aus dem Cache gelesen werden. -
Sub-Inhaltsblöcke (wie Zitate) selbst können nicht direkt zwischengespeichert werden. Speichern Sie stattdessen den übergeordneten Block zwischen.
Im Fall von Zitaten können die übergeordneten Dokumentinhaltsblöcke, die als Quellmaterial für Zitate dienen, zwischengespeichert werden. Dies ermöglicht es Ihnen, Prompt-Caching mit Zitaten effektiv zu verwenden, indem Sie die Dokumente zwischenspeichern, auf die Zitate verweisen werden.
-
Leere Textblöcke können nicht zwischengespeichert werden.
Was den Cache ungültig macht
Änderungen am zwischengespeicherten Inhalt können einen Teil oder den gesamten Cache ungültig machen.
Wie in Strukturierung Ihres 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 gemacht werden. ✘ zeigt an, dass der Cache ungültig gemacht wird, während ✓ anzeigt, 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 |
Web-Suche-Umschalter | ✓ | ✘ | ✘ | Das Aktivieren/Deaktivieren der Web-Suche ändert den System-Prompt |
Zitate-Umschalter | ✓ | ✘ | ✘ | Das Aktivieren/Deaktivieren von Zitaten ändert den System-Prompt |
Tool-Auswahl | ✓ | ✓ | ✘ | Änderungen am tool_choice -Parameter betreffen nur Message-Blöcke |
Bilder | ✓ | ✓ | ✘ | Das Hinzufügen/Entfernen von Bildern irgendwo im Prompt betrifft Message-Blöcke |
Thinking-Parameter | ✓ | ✓ | ✘ | Änderungen an erweiterten Thinking-Einstellungen (aktivieren/deaktivieren, Budget) betreffen Message-Blöcke |
Nicht-Tool-Ergebnisse an erweiterte Thinking-Anfragen übergeben | ✓ | ✓ | ✘ | Wenn Nicht-Tool-Ergebnisse in Anfragen übergeben werden, während erweitertes Thinking aktiviert ist, werden alle zuvor zwischengespeicherten Thinking-Blöcke aus dem Kontext entfernt, und alle Nachrichten im Kontext, die diesen Thinking-Blöcken folgen, werden aus dem Cache entfernt. Für weitere Details siehe Caching mit Thinking-Blöcken. |
Verfolgung der Cache-Leistung
Überwachen Sie die Cache-Leistung mit diesen API-Antwortfeldern, innerhalb von usage
in der Antwort (oder message_start
-Event bei Streaming):
cache_creation_input_tokens
: Anzahl der Token, die in den Cache geschrieben wurden, als ein neuer Eintrag erstellt wurde.cache_read_input_tokens
: Anzahl der Token, die aus dem Cache für diese Anfrage abgerufen wurden.input_tokens
: Anzahl der Eingabetoken, die nicht aus dem Cache gelesen oder zum Erstellen eines Caches verwendet wurden.
Best Practices für effektives Caching
Um die Prompt-Caching-Leistung zu optimieren:
- Speichern Sie stabilen, wiederverwendbaren Inhalt wie Systemanweisungen, Hintergrundinformationen, große Kontexte oder häufige Tool-Definitionen zwischen.
- Platzieren Sie zwischengespeicherten Inhalt am Anfang des Prompts für beste Leistung.
- Verwenden Sie Cache-Breakpoints strategisch, um verschiedene zwischenspeicherbare Präfix-Abschnitte zu trennen.
- Analysieren Sie regelmäßig Cache-Trefferquoten und passen Sie Ihre Strategie nach Bedarf an.
Optimierung für verschiedene Anwendungsfälle
Passen Sie Ihre Prompt-Caching-Strategie an Ihr Szenario an:
- Gesprächsagenten: Reduzieren Sie Kosten und Latenz für erweiterte Gespräche, insbesondere solche mit langen Anweisungen oder hochgeladenen Dokumenten.
- Coding-Assistenten: Verbessern Sie Autocomplete und Codebase-Q&A, indem Sie relevante Abschnitte oder eine zusammengefasste Version der Codebase im Prompt behalten.
- Große Dokumentenverarbeitung: Integrieren Sie vollständige langformatige Materialien einschließlich Bilder in Ihren Prompt, ohne die Antwortlatenz zu erhöhen.
- Detaillierte Anweisungssätze: Teilen Sie umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um Claude’s Antworten zu verfeinern. Entwickler fügen oft ein oder zwei Beispiele in den Prompt ein, aber mit Prompt-Caching können Sie sogar bessere Leistung erzielen, indem Sie 20+ vielfältige Beispiele hochwertiger Antworten einschließen.
- Agentische Tool-Verwendung: Verbessern Sie die Leistung für Szenarien mit mehreren Tool-Aufrufen und iterativen Code-Änderungen, wo jeder Schritt typischerweise einen neuen API-Aufruf erfordert.
- Sprechen Sie mit Büchern, Papieren, Dokumentation, Podcast-Transkripten und anderen langformatigen Inhalten: Erwecken Sie jede Wissensbasis zum Leben, indem Sie das gesamte Dokument/die gesamten Dokumente in den Prompt einbetten und Benutzer Fragen dazu stellen lassen.
Fehlerbehebung häufiger Probleme
Bei uner wartetem Verhalten:
- Stellen Sie sicher, dass zwischengespeicherte Abschnitte identisch sind und mit cache_control an denselben Stellen über Aufrufe hinweg markiert sind
- Überprüfen Sie, dass Aufrufe innerhalb der Cache-Lebensdauer (standardmäßig 5 Minuten) gemacht werden
- Verifizieren Sie, dass
tool_choice
und Bildverwendung zwischen Aufrufen konsistent bleiben - Validieren Sie, dass Sie mindestens die Mindestanzahl von Token zwischenspeichern
- Das System überprüft automatisch auf Cache-Treffer an vorherigen Inhaltsblock-Grenzen (bis zu ~20 Blöcke vor Ihrem Breakpoint). Für Prompts mit mehr als 20 Inhaltsblöcken benötigen Sie möglicherweise zusätzliche
cache_control
-Parameter früher im Prompt, um sicherzustellen, dass der gesamte Inhalt zwischengespeichert werden kann
Änderungen an tool_choice
oder das Vorhandensein/Fehlen von Bildern irgendwo im Prompt machen den Cache ungültig und erfordern die Erstellung eines neuen Cache-Eintrags. Für weitere Details zur Cache-Ungültigkeit siehe Was den Cache ungültig macht.
Caching mit Thinking-Blöcken
Bei der Verwendung von erweitertem Thinking mit Prompt-Caching haben Thinking-Blöcke ein spezielles Verhalten:
Automatisches Caching zusammen mit anderem Inhalt: Während Thinking-Blöcke nicht explizit mit cache_control
markiert werden können, werden sie als Teil des Anfrageinhalts zwischengespeichert, wenn Sie nachfolgende API-Aufrufe mit Tool-Ergebnissen machen. Dies geschieht häufig während der Tool-Verwendung, wenn Sie Thinking-Blöcke zurückgeben, um das Gespräch fortzusetzen.
Eingabetoken-Zählung: Wenn Thinking-Blöcke aus dem Cache gelesen werden, zählen sie als Eingabetoken in Ihren Nutzungsmetriken. Dies ist wichtig für Kostenberechnung und Token-Budgetierung.
Cache-Ungültigkeitsmuster:
- Cache bleibt gültig, wenn nur Tool-Ergebnisse als Benutzernachrichten bereitgestellt werden
- Cache wird ungültig gemacht, wenn Nicht-Tool-Ergebnis-Benutzerinhalt hinzugefügt wird, wodurch alle vorherigen Thinking-Blöcke entfernt werden
- Dieses Caching-Verhalten tritt auch ohne explizite
cache_control
-Markierungen auf
Für weitere Details zur Cache-Ungültigkeit siehe Was den Cache ungültig macht.
Beispiel mit Tool-Verwendung:
Wenn ein Nicht-Tool-Ergebnis-Benutzerblock enthalten ist, bezeichnet er eine neue Assistenten-Schleife und alle vorherigen Thinking-Blöcke werden aus dem Kontext entfernt.
Für detailliertere Informationen siehe die erweiterte Thinking-Dokumentation.
Cache-Speicherung und -Freigabe
-
Organisationsisolation: Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen niemals Caches, auch wenn sie identische Prompts verwenden.
-
Exakte Übereinstimmung: Cache-Treffer erfordern 100% identische Prompt-Segmente, einschließlich aller Texte und Bilder bis einschließlich des mit Cache-Control markierten Blocks.
-
Ausgabetoken-Generierung: Prompt-Caching hat keine Auswirkung auf die Ausgabetoken-Generierung. Die Antwort, die Sie erhalten, ist identisch mit dem, was Sie erhalten würden, wenn Prompt-Caching nicht verwendet würde.
1-Stunden-Cache-Dauer
Wenn Sie feststellen, dass 5 Minuten zu kurz sind, bietet Anthropic auch eine 1-Stunden-Cache-Dauer an.
Der 1-Stunden-Cache befindet sich derzeit in der Beta-Phase. Um den erweiterten Cache zu verwenden, fügen Sie extended-cache-ttl-2025-04-11
als Beta-Header zu Ihrer Anfrage hinzu und schließen Sie dann ttl
in die cache_control
-Definition wie folgt ein:
Die Antwort wird detaillierte Cache-Informationen wie die folgenden enthalten:
Beachten Sie, dass das aktuelle cache_creation_input_tokens
-Feld der Summe der Werte im cache_creation
-Objekt entspricht.
Wann der 1-Stunden-Cache verwendet werden sollte
Wenn Sie Prompts haben, die in regelmäßigen Abständen verwendet werden (d.h. System-Prompts, die häufiger als alle 5 Minuten verwendet werden), verwenden Sie weiterhin den 5-Minuten-Cache, da dieser ohne zusätzliche Kosten weiterhin aktualisiert wird.
Der 1-Stunden-Cache wird am besten in den folgenden Szenarien verwendet:
- Wenn Sie Prompts haben, die wahrscheinlich seltener als alle 5 Minuten, aber häufiger als jede Stunde verwendet werden. Zum Beispiel, wenn ein agentischer Seiten-Agent länger als 5 Minuten dauert oder wenn Sie ein langes Chat-Gespräch mit einem Benutzer speichern und Sie generell erwarten, dass dieser Benutzer möglicherweise nicht in den nächsten 5 Minuten antwortet.
- Wenn Latenz wichtig ist und Ihre Folge-Prompts möglicherweise über 5 Minuten hinaus gesendet werden.
- Wenn Sie Ihre Rate-Limit-Nutzung verbessern möchten, da Cache-Treffer nicht von Ihrem Rate-Limit abgezogen werden.
Der 5-Minuten- und 1-Stunden-Cache verhalten sich bezüglich der Latenz gleich. Sie werden generell eine verbesserte Zeit-bis-zum-ersten-Token für lange Dokumente sehen.
Mischen verschiedener TTLs
Sie können sowohl 1-Stunden- als auch 5-Minuten-Cache-Kontrollen in derselben Anfrage verwenden, aber mit einer wichtigen Einschränkung: Cache-Einträge mit längerer TTL müssen vor kürzeren TTLs erscheinen (d.h. ein 1-Stunden-Cache-Eintrag muss vor allen 5-Minuten-Cache-Einträgen erscheinen).
Beim Mischen von TTLs bestimmen wir drei Abrechnungspositionen in Ihrem Prompt:
- Position
A
: Die Token-Anzahl beim höchsten Cache-Treffer (oder 0, falls keine Treffer). - Position
B
: Die Token-Anzahl beim höchsten 1-Stunden-cache_control
-Block nachA
(oder gleichA
, falls keine existieren). - Position
C
: Die Token-Anzahl beim letztencache_control
-Block.
Wenn B
und/oder C
größer als A
sind, werden sie notwendigerweise Cache-Fehlschläge sein, weil A
der höchste Cache-Treffer ist.
Sie werden belastet für:
- Cache-Lesetoken für
A
. - 1-Stunden-Cache-Schreibtoken für
(B - A)
. - 5-Minuten-Cache-Schreibtoken für
(C - B)
.
Hier sind 3 Beispiele. Dies zeigt die Eingabetoken von 3 Anfragen, von denen jede verschiedene Cache-Treffer und Cache-Fehlschläge hat. Jede hat eine andere berechnete Preisgestaltung, die in den farbigen Boxen gezeigt wird, als Ergebnis.
Prompt-Caching-Beispiele
Um Ihnen den Einstieg in Prompt-Caching zu erleichtern, haben wir ein Prompt-Caching-Kochbuch mit detaillierten Beispielen und Best Practices vorbereitet.
Unten haben wir mehrere Code-Snippets eingefügt, die verschiedene Prompt-Caching-Muster zeigen. Diese Beispiele demonstrieren, wie Sie Caching in verschiedenen Szenarien implementieren und helfen Ihnen, die praktischen Anwendungen dieser Funktion zu verstehen: