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 repetitive 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:

Shell

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Sie sind ein KI-Assistent, der mit der Analyse literarischer Werke beauftragt ist. Ihr Ziel ist es, aufschlussreiche Kommentare zu Themen, Charakteren und Schreibstil zu liefern.\n"
      },
      {
        "type": "text",
        "text": "<der gesamte Inhalt von Stolz und Vorurteil>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analysieren Sie die Hauptthemen in Stolz und Vorurteil."
      }
    ]
  }'

# Rufen Sie das Modell erneut mit denselben Eingaben bis zum Cache-Checkpoint auf
curl https://api.anthropic.com/v1/messages # Rest der Eingabe

JSON

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

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 zum 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:

1. Das System prüft, ob ein Prompt-Präfix bis zu einem bestimmten Cache-Breakpoint bereits aus einer kürzlichen Abfrage zwischengespeichert ist.
2. Falls gefunden, verwendet es die zwischengespeicherte Version, wodurch Verarbeitungszeit und Kosten reduziert werden.
3. 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
• Repetitive 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.

Wenn Sie feststellen, dass 5 Minuten zu kurz sind, bietet Anthropic auch eine 1-Stunden-Cache-Dauer an.

Für weitere Informationen siehe 1-Stunden-Cache-Dauer.

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.1	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
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 (deprecated)	$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 (deprecated)	$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

Die obige Tabelle spiegelt die folgenden Preismultiplikatoren für Prompt-Caching wider:

• 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

---

Wie man Prompt-Caching implementiert

Unterstützte Modelle

Prompt-Caching wird derzeit unterstützt auf:

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5 (veraltet)
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (veraltet)

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 Cache-Treffer an allen vorherigen Inhaltsblock-Grenzen (bis zu etwa 20 Blöcke vor Ihrem expliziten Breakpoint)
• Wenn 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.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (veraltet) und Claude Opus 3 (veraltet)
• 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-Minuten-Lebensdauer hat.

Verstehen der Cache-Breakpoint-Kosten

Cache-Breakpoints selbst fügen keine Kosten hinzu. 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 weiterer 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 einfach 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 Caching für diesen Teil der Anfrage zu ermöglichen.

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, die an erweiterte Thinking-Anfragen übergeben werden	✓	✓	✘	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:

• Konversationsagenten: 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.
• Verarbeitung großer Dokumente: 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 Claudes Antworten zu verfeinern. Entwickler fügen oft ein oder zwei Beispiele in den Prompt ein, aber mit Prompt-Caching können Sie noch 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, bei denen 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 Benutzern ermöglichen, Fragen dazu zu stellen.

Fehlerbehebung häufiger Probleme

Bei unerwartetem 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 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-Invalidierung 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-Invalidierungsmuster:

• 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-Invalidierung siehe Was den Cache ungültig macht.

Beispiel mit Tool-Verwendung:

Anfrage 1: Benutzer: "Wie ist das Wetter in Paris?"
Antwort: [thinking_block_1] + [tool_use block 1]

Anfrage 2: 
Benutzer: ["Wie ist das Wetter in Paris?"], 
Assistent: [thinking_block_1] + [tool_use block 1], 
Benutzer: [tool_result_1, cache=True]
Antwort: [thinking_block_2] + [text block 2]
# Anfrage 2 speichert ihren Anfrageinhalt zwischen (nicht die Antwort)
# Der Cache umfasst: Benutzernachricht, thinking_block_1, tool_use block 1 und tool_result_1

Anfrage 3:
Benutzer: ["Wie ist das Wetter in Paris?"], 
Assistent: [thinking_block_1] + [tool_use block 1], 
Benutzer: [tool_result_1, cache=True], 
Assistent: [thinking_block_2] + [text block 2], 
Benutzer: [Textantwort, cache=True]
# Nicht-Tool-Ergebnis-Benutzerblock führt dazu, dass alle Thinking-Blöcke ignoriert werden
# Diese Anfrage wird verarbeitet, als ob Thinking-Blöcke nie vorhanden gewesen wären

Wenn ein Nicht-Tool-Ergebnis-Benutzerblock eingeschlossen wird, 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.

Um den erweiterten Cache zu verwenden, fügen Sie ttl in die cache_control-Definition wie folgt ein:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

Die Antwort wird detaillierte Cache-Informationen wie die folgenden enthalten:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

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 weiter aktualisiert wird.

Der 1-Stunden-Cache wird am besten in den folgenden Szenarien verwendet:

• Wenn Sie Prompts haben, die wahrscheinlich weniger häufig 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 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:

1. Position A: Die Token-Anzahl beim höchsten Cache-Treffer (oder 0, wenn keine Treffer).
2. Position B: Die Token-Anzahl beim höchsten 1-Stunden-cache_control-Block nach A (oder gleich A, wenn keine existieren).
3. Position C: Die Token-Anzahl beim letzten cache_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:

1. Cache-Lesetoken für A.
2. 1-Stunden-Cache-Schreibtoken für (B - A).
3. 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 Kästen 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:

Beispiel für großen Kontext-Cache

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "Sie sind ein KI-Assistent, der mit der Analyse von Rechtsdokumenten beauftragt ist."
        },
        {
            "type": "text",
            "text": "Hier ist der vollständige Text einer komplexen Rechtsvereinbarung: [Fügen Sie hier den vollständigen Text einer 50-seitigen Rechtsvereinbarung ein]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Was sind die wichtigsten Bedingungen und Konditionen in dieser Vereinbarung?"
        }
    ]
}'

Dieses Beispiel demonstriert die grundlegende Verwendung von Prompt-Caching und speichert den vollständigen Text der Rechtsvereinbarung als Präfix zwischen, während die Benutzeranweisung nicht zwischengespeichert bleibt.

Für die erste Anfrage:

• input_tokens: Anzahl der Token nur in der Benutzernachricht
• cache_creation_input_tokens: Anzahl der Token in der gesamten Systemnachricht, einschließlich des Rechtsdokuments
• cache_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 Benutzernachricht
• cache_creation_input_tokens: 0 (keine neue Cache-Erstellung)
• cache_read_input_tokens: Anzahl der Token in der gesamten zwischengespeicherten Systemnachricht

Zwischenspeichern von Tool-Definitionen

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Das aktuelle Wetter an einem bestimmten Ort abrufen",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Die Stadt und der Staat, z.B. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Die Temperatureinheit, entweder celsius oder fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # viele weitere Tools
        {
            "name": "get_time",
            "description": "Die aktuelle Zeit in einer bestimmten Zeitzone abrufen",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "Der IANA-Zeitzonenname, z.B. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Wie ist das Wetter und die Zeit in New York?"
        }
    ]
}'

In diesem Beispiel demonstrieren wir das Zwischenspeichern von Tool-Definitionen.

Der cache_control-Parameter wird auf das finale Tool (get_time) platziert, um alle Tools als Teil des statischen Präfixes zu bezeichnen.

Das bedeutet, dass alle Tool-Definitionen, einschließlich get_weather und aller anderen vor get_time definierten Tools, als ein einziger Präfix zwischengespeichert werden.

Dieser Ansatz ist nützlich, wenn Sie einen konsistenten Satz von Tools haben, die Sie über mehrere Anfragen hinweg wiederverwenden möchten, ohne sie jedes Mal neu zu verarbeiten.

Für die erste Anfrage:

• input_tokens: Anzahl der Token in der Benutzernachricht
• cache_creation_input_tokens: Anzahl der Token in allen Tool-Definitionen und System-Prompt
• cache_read_input_tokens: 0 (kein Cache-Treffer bei der ersten Anfrage)

Für nachfolgende Anfragen innerhalb der Cache-Lebensdauer:

• input_tokens: Anzahl der Token in der Benutzernachricht
• cache_creation_input_tokens: 0 (keine neue Cache-Erstellung)
• cache_read_input_tokens: Anzahl der Token in allen zwischengespeicherten Tool-Definitionen und System-Prompt

Fortsetzen eines mehrteiligen Gesprächs

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...langer System-Prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hallo, können Sie mir mehr über das Sonnensystem erzählen?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Sicherlich! Das Sonnensystem ist die Sammlung von Himmelskörpern, die unsere Sonne umkreisen. Es besteht aus acht Planeten, zahlreichen Monden, Asteroiden, Kometen und anderen Objekten. Die Planeten, in der Reihenfolge von der Sonne am nächsten bis am weitesten entfernt, sind: Merkur, Venus, Erde, Mars, Jupiter, Saturn, Uranus und Neptun. Jeder Planet hat seine eigenen einzigartigen Eigenschaften und Merkmale. Gibt es einen bestimmten Aspekt des Sonnensystems, über den Sie mehr wissen möchten?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Gut zu wissen."
                },
                {
                    "type": "text",
                    "text": "Erzählen Sie mir mehr über den Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

In diesem Beispiel demonstrieren wir, wie man Prompt-Caching in einem mehrteiligen Gespräch verwendet.

Während jedes Turns markieren wir den finalen Block der finalen Nachricht mit cache_control, damit das Gespräch inkrementell zwischengespeichert werden kann. Das System wird automatisch den längsten zuvor zwischengespeicherten Präfix für Folgenachrichten nachschlagen und verwenden. Das heißt, Blöcke, die zuvor mit einem cache_control-Block markiert waren, werden später nicht mit diesem markiert, aber sie werden immer noch als Cache-Treffer (und auch als Cache-Aktualisierung!) betrachtet, wenn sie innerhalb von 5 Minuten getroffen werden.

Zusätzlich beachten Sie, dass der cache_control-Parameter auf die Systemnachricht platziert wird. Dies soll sicherstellen, dass wenn dies aus dem Cache entfernt wird (nachdem es mehr als 5 Minuten nicht verwendet wurde), es bei der nächsten Anfrage wieder zum Cache hinzugefügt wird.

Dieser Ansatz ist nützlich für die Aufrechterhaltung des Kontexts in laufenden Gesprächen, ohne wiederholt dieselben Informationen zu verarbeiten.

Wenn dies richtig eingerichtet ist, sollten Sie das Folgende in der Nutzungsantwort jeder Anfrage sehen:

• input_tokens: Anzahl der Token in der neuen Benutzernachricht (wird minimal sein)
• cache_creation_input_tokens: Anzahl der Token in den neuen Assistenten- und Benutzer-Turns
• cache_read_input_tokens: Anzahl der Token im Gespräch bis zum vorherigen Turn

Alles zusammenfügen: Mehrere Cache-Breakpoints

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Durch die Wissensbasis suchen",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Suchanfrage"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Ein spezifisches Dokument nach ID abrufen",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Dokument-ID"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "Sie sind ein hilfreicher Forschungsassistent mit Zugang zu einer Dokument-Wissensbasis.\n\n# Anweisungen\n- Suchen Sie immer nach relevanten Dokumenten, bevor Sie antworten\n- Geben Sie Zitate für Ihre Quellen an\n- Seien Sie objektiv und genau in Ihren Antworten\n- Wenn mehrere Dokumente relevante Informationen enthalten, synthetisieren Sie sie\n- Erkennen Sie an, wenn Informationen in der Wissensbasis nicht verfügbar sind",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Wissensbasis-Kontext\n\nHier sind die relevanten Dokumente für dieses Gespräch:\n\n## Dokument 1: Sonnensystem-Überblick\nDas Sonnensystem besteht aus der Sonne und allen Objekten, die sie umkreisen...\n\n## Dokument 2: Planeteneigenschaften\nJeder Planet hat einzigartige Merkmale. Merkur ist der kleinste Planet...\n\n## Dokument 3: Mars-Erforschung\nDer Mars ist seit Jahrzehnten ein Ziel der Erforschung...\n\n[Zusätzliche Dokumente...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Können Sie nach Informationen über Mars-Rover suchen?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars-Rover"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "3 relevante Dokumente gefunden: Dokument 3 (Mars-Erforschung), Dokument 7 (Rover-Technologie), Dokument 9 (Missionsgeschichte)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Ich habe 3 relevante Dokumente über Mars-Rover gefunden. Lassen Sie mich weitere Details aus dem Mars-Erforschungsdokument abrufen."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Ja, bitte erzählen Sie mir speziell über den Perseverance-Rover.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

Dieses umfassende Beispiel demonstriert, wie man alle 4 verfügbaren Cache-Breakpoints verwendet, um verschiedene Teile Ihres Prompts zu optimieren:

1. Tools-Cache (Cache-Breakpoint 1): Der cache_control-Parameter auf der letzten Tool-Definition speichert alle Tool-Definitionen zwischen.

2. Wiederverwendbare Anweisungen-Cache (Cache-Breakpoint 2): Die statischen Anweisungen im System-Prompt werden separat zwischengespeichert. Diese Anweisungen ändern sich selten zwischen Anfragen.

3. RAG-Kontext-Cache (Cache-Breakpoint 3): Die Wissensbasis-Dokumente werden unabhängig zwischengespeichert, wodurch Sie die RAG-Dokumente aktualisieren können, ohne den Tools- oder Anweisungen-Cache ungültig zu machen.

4. Gesprächsverlauf-Cache (Cache-Breakpoint 4): Die Antwort des Assistenten ist mit cache_control markiert, um inkrementelles Caching des Gesprächs während seines Fortschreitens zu ermöglichen.

Dieser Ansatz bietet maximale Flexibilität:

• Wenn Sie nur die finale Benutzernachricht aktualisieren, werden alle vier Cache-Segmente wiederverwendet
• Wenn Sie die RAG-Dokumente aktualisieren, aber dieselben Tools und Anweisungen beibehalten, werden die ersten beiden Cache-Segmente wiederverwendet
• Wenn Sie das Gespräch ändern, aber dieselben Tools, Anweisungen und Dokumente beibehalten, werden die ersten drei Segmente wiederverwendet
• Jeder Cache-Breakpoint kann unabhängig ungültig gemacht werden, basierend darauf, was sich in Ihrer Anwendung ändert

Für die erste Anfrage:

• input_tokens: Token in der finalen Benutzernachricht
• cache_creation_input_tokens: Token in allen zwischengespeicherten Segmenten (Tools + Anweisungen + RAG-Dokumente + Gesprächsverlauf)
• cache_read_input_tokens: 0 (keine Cache-Treffer)

Für nachfolgende Anfragen mit nur einer neuen Benutzernachricht:

• input_tokens: Token nur in der neuen Benutzernachricht
• cache_creation_input_tokens: Alle neuen Token, die zum Gesprächsverlauf hinzugefügt wurden
• cache_read_input_tokens: Alle zuvor zwischengespeicherten Token (Tools + Anweisungen + RAG-Dokumente + vorheriges Gespräch)

Dieses Muster ist besonders mächtig für:

• RAG-Anwendungen mit großen Dokumentkontexten
• Agentensysteme, die mehrere Tools verwenden
• Langanhaltende Gespräche, die Kontext beibehalten müssen
• Anwendungen, die verschiedene Teile des Prompts unabhängig optimieren müssen

---

FAQ

Benötige ich mehrere Cache-Breakpoints oder ist einer am Ende ausreichend?

In den meisten Fällen ist ein einziger Cache-Breakpoint am Ende Ihres statischen Inhalts ausreichend. Das System überprüft automatisch Cache-Treffer an allen vorherigen Inhaltsblock-Grenzen (bis zu 20 Blöcke vor Ihrem Breakpoint) und verwendet den längsten übereinstimmenden Präfix.

Sie benötigen nur mehrere Breakpoints, wenn:

• Sie mehr als 20 Inhaltsblöcke vor Ihrem gewünschten Cache-Punkt haben
• Sie Abschnitte zwischenspeichern möchten, die sich mit unterschiedlichen Häufigkeiten unabhängig aktualisieren
• Sie explizite Kontrolle darüber benötigen, was für Kostenoptimierung zwischengespeichert wird

Beispiel: Wenn Sie Systemanweisungen (ändern sich selten) und RAG-Kontext (ändert sich täglich) haben, könnten Sie zwei Breakpoints verwenden, um sie separat zwischenzuspeichern.

Fügen Cache-Breakpoints zusätzliche Kosten hinzu?

Nein, Cache-Breakpoints selbst sind kostenlos. Sie zahlen nur für:

• Das Schreiben von Inhalt in den Cache (25% mehr als Basis-Eingabetoken für 5-Minuten-TTL)
• Das Lesen aus dem Cache (10% des Basis-Eingabetoken-Preises)
• Reguläre Eingabetoken für nicht zwischengespeicherten Inhalt

Die Anzahl der Breakpoints beeinflusst die Preisgestaltung nicht - nur die Menge des zwischengespeicherten und gelesenen Inhalts ist wichtig.

Was ist die Cache-Lebensdauer?

Die standardmäßige minimale Lebensdauer (TTL) des Caches beträgt 5 Minuten. Diese Lebensdauer wird jedes Mal aktualisiert, wenn der zwischengespeicherte Inhalt verwendet wird.

Wenn Sie feststellen, dass 5 Minuten zu kurz sind, bietet Anthropic auch eine 1-Stunden-Cache-TTL an.

Wie viele Cache-Breakpoints kann ich verwenden?

Sie können bis zu 4 Cache-Breakpoints (mit cache_control-Parametern) in Ihrem Prompt definieren.

Ist Prompt-Caching für alle Modelle verfügbar?

Nein, Prompt-Caching ist derzeit nur für Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (veraltet), Claude Haiku 3.5, Claude Haiku 3 und Claude Opus 3 (veraltet) verfügbar.

Wie funktioniert Prompt-Caching mit erweitertem Thinking?

Zwischengespeicherte System-Prompts und Tools werden wiederverwendet, wenn sich Thinking-Parameter ändern. Thinking-Änderungen (Aktivieren/Deaktivieren oder Budget-Änderungen) machen jedoch zuvor zwischengespeicherte Prompt-Präfixe mit Messages-Inhalt ungültig.

Für weitere Details zur Cache-Invalidierung siehe Was den Cache ungültig macht.

Für mehr über erweitertes Thinking, einschließlich seiner Interaktion mit Tool-Verwendung und Prompt-Caching, siehe die erweiterte Thinking-Dokumentation.

Wie aktiviere ich Prompt-Caching?

Um Prompt-Caching zu aktivieren, fügen Sie mindestens einen cache_control-Breakpoint in Ihre API-Anfrage ein.

Kann ich Prompt-Caching mit anderen API-Funktionen verwenden?

Ja, Prompt-Caching kann zusammen mit anderen API-Funktionen wie Tool-Verwendung und Vision-Fähigkeiten verwendet werden. Das Ändern, ob Bilder in einem Prompt vorhanden sind, oder das Modifizieren von Tool-Verwendungseinstellungen wird jedoch den Cache brechen.

Für weitere Details zur Cache-Invalidierung siehe Was den Cache ungültig macht.

Wie beeinflusst Prompt-Caching die Preisgestaltung?

Prompt-Caching führt eine neue Preisstruktur ein, bei der Cache-Schreibvorgänge 25% mehr als Basis-Eingabetoken kosten, während Cache-Treffer nur 10% des Basis-Eingabetoken-Preises kosten.

Kann ich den Cache manuell löschen?

Derzeit gibt es keine Möglichkeit, den Cache manuell zu löschen. Zwischengespeicherte Präfixe laufen automatisch nach mindestens 5 Minuten Inaktivität ab.

Wie kann ich die Effektivität meiner Caching-Strategie verfolgen?

Sie können die Cache-Leistung mit den Feldern cache_creation_input_tokens und cache_read_input_tokens in der API-Antwort überwachen.

Was kann den Cache brechen?

Siehe Was den Cache ungültig macht für weitere Details zur Cache-Invalidierung, einschließlich einer Liste von Änderungen, die die Erstellung eines neuen Cache-Eintrags erfordern.

Wie handhabt Prompt-Caching Datenschutz und Datentrennung?

Prompt-Caching ist mit starken Datenschutz- und Datentrennungsmaßnahmen konzipiert:

1. Cache-Schlüssel werden mit einem kryptographischen Hash der Prompts bis zum Cache-Control-Punkt generiert. Das bedeutet, nur Anfragen mit identischen Prompts können auf einen spezifischen Cache zugreifen.

2. Caches sind organisationsspezifisch. Benutzer innerhalb derselben Organisation können auf denselben Cache zugreifen, wenn sie identische Prompts verwenden, aber Caches werden nicht zwischen verschiedenen Organisationen geteilt, auch nicht für identische Prompts.

3. Der Caching-Mechanismus ist darauf ausgelegt, die Integrität und den Datenschutz jedes einzigartigen Gesprächs oder Kontexts zu wahren.

4. Es ist sicher, cache_control überall in Ihren Prompts zu verwenden. Für Kosteneffizienz ist es besser, hochvariable Teile (z.B. beliebige Benutzereingaben) vom Caching auszuschließen.

Diese Maßnahmen stellen sicher, dass Prompt-Caching Datenschutz und Sicherheit wahrt, während es Leistungsvorteile bietet.

Kann ich Prompt-Caching mit der Batches API verwenden?

Ja, es ist möglich, Prompt-Caching mit Ihren Batches API-Anfragen zu verwenden. Da asynchrone Batch-Anfragen jedoch gleichzeitig und in beliebiger Reihenfolge verarbeitet werden können, werden Cache-Treffer nach bestem Bemühen bereitgestellt.

Der 1-Stunden-Cache kann helfen, Ihre Cache-Treffer zu verbessern. Der kosteneffektivste Weg, ihn zu verwenden, ist folgender:

• Sammeln Sie eine Reihe von Message-Anfragen, die einen gemeinsamen Präfix haben.
• Senden Sie eine Batch-Anfrage mit nur einer einzigen Anfrage, die diesen gemeinsamen Präfix und einen 1-Stunden-Cache-Block hat. Dies wird in den 1-Stunden-Cache geschrieben.
• Sobald dies abgeschlossen ist, reichen Sie die restlichen Anfragen ein. Sie müssen den Job überwachen, um zu wissen, wann er abgeschlossen ist.

Dies ist typischerweise besser als die Verwendung des 5-Minuten-Caches, einfach weil es üblich ist, dass Batch-Anfragen zwischen 5 Minuten und 1 Stunde dauern. Wir erwägen Möglichkeiten, diese Cache-Trefferquoten zu verbessern und diesen Prozess unkomplizierter zu gestalten.

Warum sehe ich den Fehler `AttributeError: 'Beta' object has no attribute 'prompt_caching'` in Python?

Dieser Fehler tritt typischerweise auf, wenn Sie Ihr SDK aktualisiert haben oder veraltete Code-Beispiele verwenden. Prompt-Caching ist jetzt allgemein verfügbar, daher benötigen Sie das Beta-Präfix nicht mehr. Anstatt:

Python

python client.beta.prompt_caching.messages.create(...)

Verwenden Sie einfach:

Python

python client.messages.create(...)

Warum sehe ich 'TypeError: Cannot read properties of undefined (reading 'messages')'?

Dieser Fehler tritt typischerweise auf, wenn Sie Ihr SDK aktualisiert haben oder veraltete Code-Beispiele verwenden. Prompt-Caching ist jetzt allgemein verfügbar, daher benötigen Sie das Beta-Präfix nicht mehr. Anstatt:

TypeScript

client.beta.promptCaching.messages.create(...)

Verwenden Sie einfach:

client.messages.create(...)