Prompt-Caching

Prompt-Caching optimiert Ihre API-Nutzung, indem es das Fortsetzen von bestimmten Präfixen in Ihren Prompts ermöglicht. Dies reduziert erheblich die Verarbeitungszeit und Kosten für wiederholte Aufgaben oder Prompts mit konsistenten Elementen.

Es gibt zwei Möglichkeiten, Prompt-Caching zu aktivieren:

• Automatisches Caching: Fügen Sie ein einzelnes cache_control-Feld auf der obersten Ebene Ihrer Anfrage hinzu. Das System wendet den Cache-Breakpoint automatisch auf den letzten zwischenspeicherbaren Block an und verschiebt ihn nach vorne, wenn Gespräche wachsen. Am besten für Multi-Turn-Gespräche, bei denen der wachsende Nachrichtenverlauf automatisch zwischengespeichert werden sollte.
• Explizite Cache-Breakpoints: Platzieren Sie cache_control direkt auf einzelnen Inhaltsblöcken für präzise Kontrolle darüber, was genau zwischengespeichert wird.

Der einfachste Weg zum Einstieg ist automatisches Caching:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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())

Mit automatischem Caching speichert das System alle Inhalte bis einschließlich des letzten zwischenspeicherbaren Blocks. Bei nachfolgenden Anfragen mit demselben Präfix wird der zwischengespeicherte Inhalt automatisch wiederverwendet.

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 angegebenen Cache-Breakpoint bereits aus einer kürzlichen Abfrage zwischengespeichert ist.
2. Falls gefunden, wird die zwischengespeicherte Version verwendet, was Verarbeitungszeit und Kosten reduziert.
3. Andernfalls wird der vollständige Prompt verarbeitet und das Präfix zwischengespeichert, sobald die Antwort beginnt.

Dies ist besonders nützlich für:

• Prompts mit vielen Beispielen
• Große Mengen an Kontext oder Hintergrundinformationen
• Wiederholte Aufgaben mit konsistenten Anweisungen
• Lange Multi-Turn-Gespräche

Standardmäßig hat der Cache eine Lebensdauer von 5 Minuten. Der Cache wird ohne zusätzliche Kosten aktualisiert, jedes Mal wenn der zwischengespeicherte Inhalt verwendet wird.

Preisgestaltung

Prompt-Caching führt eine neue Preisstruktur ein. Die folgende Tabelle zeigt den Preis pro Million Token für jedes unterstützte Modell:

Unterstützte Modelle

Prompt-Caching (sowohl automatisch als auch explizit) wird auf allen aktiven Claude-Modellen unterstützt.

Automatisches Caching

Automatisches Caching ist der einfachste Weg, Prompt-Caching zu aktivieren. Anstatt cache_control auf einzelnen Inhaltsblöcken zu platzieren, fügen Sie ein einzelnes cache_control-Feld auf der obersten Ebene Ihres Anfragebody hinzu. Das System wendet den Cache-Breakpoint automatisch auf den letzten zwischenspeicherbaren Block an.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 Multi-Turn-Gesprächen funktioniert

Mit automatischem Caching bewegt sich der Cache-Punkt automatisch nach vorne, wenn Gespräche wachsen. Jede neue Anfrage speichert alles bis zum letzten zwischenspeicherbaren Block, und vorheriger Inhalt wird aus dem Cache gelesen.

Der Cache-Breakpoint bewegt sich automatisch zum letzten zwischenspeicherbaren Block in jeder Anfrage, sodass Sie keine cache_control-Markierungen aktualisieren müssen, wenn das Gespräch wächst.

TTL-Unterstützung

Standardmäßig verwendet automatisches Caching ein 5-Minuten-TTL. Sie können ein 1-Stunden-TTL zum 2-fachen Preis der Basis-Input-Token angeben:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

Kombination mit Block-Level-Caching

Automatisches Caching ist kompatibel mit expliziten Cache-Breakpoints. Bei gemeinsamer Verwendung nutzt der automatische Cache-Breakpoint einen der 4 verfügbaren Breakpoint-Slots.

Dies ermöglicht es Ihnen, beide Ansätze zu kombinieren. Verwenden Sie beispielsweise explizite Breakpoints, um Ihren System-Prompt und Tools unabhängig zu speichern, während automatisches Caching das Gespräch verwaltet:

{
  "model": "claude-opus-4-7",
  "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 bleibt gleich

Automatisches Caching nutzt die gleiche zugrunde liegende Caching-Infrastruktur. Preisgestaltung, minimale Token-Schwellenwerte, Kontextordnungsanforderungen und das 20-Block-Lookback-Fenster gelten genauso wie bei expliziten Breakpoints.

Grenzfälle

• Falls der letzte Block bereits ein explizites cache_control mit demselben TTL hat, ist automatisches Caching ein No-Op.
• Falls der letzte Block ein explizites cache_control mit einem anderen TTL hat, gibt die API einen 400-Fehler zurück.
• Falls 4 explizite Block-Level-Breakpoints bereits vorhanden sind, gibt die API einen 400-Fehler zurück (keine Slots mehr für automatisches Caching).
• Falls der letzte Block kein geeignetes Ziel für einen automatischen Cache-Breakpoint ist, geht das System stillschweigend rückwärts, um den nächsten geeigneten Block zu finden. Falls keiner gefunden wird, wird Caching übersprungen.

Explizite Cache-Breakpoints

Für mehr Kontrolle über das Caching können Sie cache_control direkt auf einzelnen Inhaltsblöcken platzieren. Dies ist nützlich, wenn Sie verschiedene Abschnitte zwischenspeichern müssen, die sich mit unterschiedlichen Häufigkeiten ändern, oder wenn Sie präzise Kontrolle darüber benötigen, was genau zwischengespeichert wird.

Strukturierung Ihres Prompts

Platzieren Sie statische Inhalte (Tool-Definitionen, System-Anweisungen, Kontext, Beispiele) am Anfang Ihres Prompts. Markieren Sie das Ende des wiederverwendbaren Inhalts zum Zwischenspeichern mit dem cache_control-Parameter.

Cache-Präfixe werden in der folgenden Reihenfolge erstellt: tools, system, dann messages. Diese Reihenfolge bildet eine Hierarchie, bei der jede Ebene auf den vorherigen aufbaut.

Wie automatische Präfix-Überprüfung funktioniert

Sie können nur einen Cache-Breakpoint am Ende Ihres statischen Inhalts verwenden, und das System findet automatisch das längste Präfix, das eine vorherige Anfrage bereits in den Cache geschrieben hat. Das Verständnis, wie dies funktioniert, hilft Ihnen, Ihre Caching-Strategie zu optimieren.

Drei Kernprinzipien:

1. Cache-Schreibvorgänge erfolgen nur an Ihrem Breakpoint. Das Markieren eines Blocks mit cache_control schreibt genau einen Cache-Eintrag: einen Hash des Präfix, das bei 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 das Ändern eines Blocks am oder vor dem Breakpoint bei der nächsten Anfrage einen anderen Hash.

2. 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 Ihrem Breakpoint und prüft auf einen übereinstimmenden Cache-Eintrag. Falls keiner vorhanden ist, geht es rückwärts einen Block nach dem anderen vor und prüft, ob der Präfix-Hash an jeder früheren Position mit etwas übereinstimmt, das bereits im Cache vorhanden ist. Es sucht nach vorherigen Schreibvorgängen, nicht nach stabilem Inhalt.

3. Das Lookback-Fenster beträgt 20 Blöcke. Das System prüft höchstens 20 Positionen pro Breakpoint, wobei der Breakpoint selbst als erste zählt. Falls das System keinen übereinstimmenden Eintrag in diesem Fenster findet, stoppt die Überprüfung (oder setzt sich vom nächsten expliziten Breakpoint fort, falls vorhanden).

Beispiel: Lookback in einem wachsenden Gespräch

Sie fügen jede Runde neue Blöcke an und setzen cache_control auf den letzten Block jeder Anfrage:

• Runde 1: 10 Blöcke, Breakpoint auf Block 10. Keine vorherigen Cache-Einträge vorhanden. 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 von Runde 1. Cache-Hit 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 von Runde 2 bei Block 15 liegt eine Position außerhalb des Fensters, daher gibt es keinen Cache-Hit. Das Hinzufügen eines zweiten Breakpoints bei Block 15 startet ein zweites Lookback-Fenster dort, das den Eintrag von Runde 2 findet.

Häufiger Fehler: Breakpoint auf Inhalt, der sich bei jeder Anfrage ändert

Ihr Prompt hat einen großen statischen System-Kontext (Blöcke 1 bis 5), gefolgt von einem Pro-Anfrage-Block mit einem Zeitstempel und der Benutzernachricht (Block 6). Sie setzen cache_control auf Block 6:

• Anfrage 1: Cache-Schreibvorgang bei Block 6. Der Hash enthält den Zeitstempel.
• Anfrage 2: Der Zeitstempel unterscheidet sich, daher unterscheidet sich der Präfix-Hash bei Block 6. Das Lookback geht durch die Blöcke 5, 4, 3, 2 und 1, aber das System hat an keiner dieser Positionen einen Eintrag geschrieben. Kein Cache-Hit. Sie zahlen für einen frischen Cache-Schreibvorgang bei jeder Anfrage und erhalten nie einen Lesezugriff.

Das Lookback findet keinen stabilen Inhalt hinter Ihrem Breakpoint und speichert ihn. Es findet Einträge, die vorherige Anfragen bereits geschrieben haben, und Schreibvorgänge erfolgen nur an Breakpoints. Verschieben Sie cache_control zu Block 5, dem letzten Block, der über Anfragen hinweg gleich bleibt, und jede nachfolgende Anfrage liest das zwischengespeicherte Präfix. Automatisches Caching fällt in die gleiche Falle: Es platziert den Breakpoint auf dem letzten zwischenspeicherbaren Block, der in dieser Struktur derjenige ist, der sich bei jeder Anfrage ändert, also verwenden Sie stattdessen einen expliziten Breakpoint auf Block 5.

Wichtigste Erkenntnis: Platzieren Sie cache_control auf dem letzten Block, dessen Präfix über die Anfragen hinweg identisch ist, die Sie einen Cache teilen möchten. In einem wachsenden Gespräch funktioniert der letzte Block, solange jede Runde weniger als 20 Blöcke hinzufügt: Früherer Inhalt ändert sich nie, daher findet das Lookback der nächsten Anfrage den vorherigen Schreibvorgang. Für einen Prompt mit einem variierenden Suffix (Zeitstempel, Pro-Anfrage-Kontext, die eingehende Nachricht) platzieren Sie den Breakpoint am Ende des statischen Präfix, nicht auf dem variierenden Block.

Wann mehrere Breakpoints verwendet werden

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 der Kontext wird täglich aktualisiert)
• Mehr Kontrolle über genau das haben, was zwischengespeichert wird
• Sicherstellen, dass ein Cache-Hit erfolgt, wenn ein wachsendes Gespräch Ihren Breakpoint 20 oder mehr Blöcke über den letzten Cache-Schreibvorgang hinaus verschiebt

Verständnis der Cache-Breakpoint-Kosten

Cache-Breakpoints selbst verursachen keine Kosten. Sie werden nur berechnet für:

• Cache-Schreibvorgänge: Wenn neuer Inhalt in den Cache geschrieben wird (25% mehr als Basis-Input-Token für 5-Minuten-TTL)
• Cache-Lesevorgänge: Wenn zwischengespeicherter Inhalt verwendet wird (10% des Basis-Input-Token-Preises)
• Reguläre Input-Token: Für jeden nicht zwischenspeicherten Inhalt

Das Hinzufügen von mehr cache_control-Breakpoints erhöht Ihre Kosten nicht - Sie zahlen immer noch den gleichen Betrag basierend auf dem Inhalt, der tatsächlich zwischengespeichert und gelesen wird. Die Breakpoints geben Ihnen einfach Kontrolle darüber, welche Abschnitte unabhängig zwischengespeichert werden können.

Caching-Strategien und Überlegungen

Cache-Einschränkungen

Die minimale zwischenspeicherbare Prompt-Länge beträgt:

• 4096 Token für Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 und Claude Opus 4.5
• 2048 Token für Claude Sonnet 4.6
• 1024 Token für Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4 und Claude Sonnet 3.7 (veraltet)
• 4096 Token für Claude Haiku 4.5
• 2048 Token für Claude Haiku 3.5 (veraltet) und Claude Haiku 3

Kürzere Prompts können nicht zwischengespeichert werden, auch wenn sie mit cache_control gekennzeichnet sind. Alle Anfragen zum Zwischenspeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet, und es wird kein Fehler zurückgegeben. Um zu überprüfen, ob ein Prompt zwischengespeichert wurde, überprüfen Sie die Antwort-Nutzungs-Felder: Falls sowohl cache_creation_input_tokens als auch cache_read_input_tokens 0 sind, wurde der Prompt nicht zwischengespeichert (wahrscheinlich weil er die minimale Längeanforderung nicht erfüllt).

Falls Ihr Prompt knapp unter dem Minimum für das Modell liegt, das Sie verwenden, ist das Erweitern des zwischenspeicherten Inhalts, um den Schwellenwert zu erreichen, oft lohnenswert. Cache-Lesevorgänge kosten erheblich weniger als nicht zwischengespeicherte Input-Token, daher kann das Erreichen des Minimums die Kosten für häufig wiederverwendete Prompts reduzieren.

Für gleichzeitige Anfragen ist zu beachten, dass ein Cache-Eintrag erst verfügbar wird, nachdem die erste Antwort beginnt. Falls Sie Cache-Hits 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 Lebensdauer von 5 Minuten hat.

Was zwischengespeichert werden kann

Die meisten Blöcke in der Anfrage können zwischengespeichert werden. Dies umfasst:

• Tools: Tool-Definitionen im tools-Array
• System-Nachrichten: Inhaltsblöcke im system-Array
• Text-Nachrichten: Inhaltsblöcke im messages.content-Array, sowohl für Benutzer- als auch für Assistenten-Turns
• Bilder & Dokumente: Inhaltsblöcke im messages.content-Array, in Benutzer-Turns
• Tool-Nutzung und Tool-Ergebnisse: Inhaltsblöcke im messages.content-Array, sowohl in Benutzer- als auch in Assistenten-Turns

Jedes dieser Elemente kann zwischengespeichert werden, entweder automatisch oder durch Markierung mit cache_control.

Was nicht zwischengespeichert werden kann

Während die meisten Anfrage-Blö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 anderen Inhalten zwischengespeichert werden, wenn sie in vorherigen Assistenten-Turns erscheinen. Wenn sie auf diese Weise zwischengespeichert werden, zählen sie als Input-Token, wenn sie aus dem Cache gelesen werden.

• Sub-Content-Blöcke (wie Zitate) können nicht direkt zwischengespeichert werden. Speichern Sie stattdessen den Top-Level-Block.

  Im Fall von Zitaten können die Top-Level-Dokument-Inhaltsblöcke, die als Quellmaterial für Zitate dienen, zwischengespeichert werden. Dies ermöglicht es Ihnen, Prompt-Caching mit Zitaten effektiv zu nutzen, indem Sie die Dokumente zwischenspeichern, auf die Zitate verweisen.

• Leere Text-Blöcke können nicht zwischengespeichert werden.

Was den Cache ungültig macht

Änderungen an zwischenspeichertem 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 Cache durch verschiedene Arten von Änderungen ungültig gemacht werden. ✘ zeigt an, dass der Cache ungültig ist, während ✓ zeigt, dass der Cache gültig bleibt.

Verfolgung der Cache-Leistung

Überwachen Sie die Cache-Leistung mit diesen API-Antwortfeldern, innerhalb von usage in der Antwort (oder message_start-Ereignis bei Streaming):

• cache_creation_input_tokens: Anzahl der Token, die beim Erstellen eines neuen Eintrags in den Cache geschrieben werden.
• cache_read_input_tokens: Anzahl der Token, die für diese Anfrage aus dem Cache abgerufen werden.
• input_tokens: Anzahl der Input-Token, die nicht aus dem Cache gelesen oder zum Erstellen eines Cache verwendet wurden (d. h. Token nach dem letzten Cache-Breakpoint).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Caching mit Thinking Blocks

Bei Verwendung von Extended Thinking mit Prompt Caching haben Thinking Blocks ein spezielles Verhalten:

Automatisches Caching neben anderen Inhalten: Obwohl Thinking Blocks nicht explizit mit cache_control gekennzeichnet werden können, werden sie als Teil des Request-Inhalts gecacht, wenn Sie nachfolgende API-Aufrufe mit Tool-Ergebnissen durchführen. Dies geschieht häufig bei der Tool-Nutzung, wenn Sie Thinking Blocks zurückgeben, um das Gespräch fortzusetzen.

Input Token Zählung: Wenn Thinking Blocks aus dem Cache gelesen werden, zählen sie als Input Tokens in Ihren Nutzungsmetriken. Dies ist wichtig für die Kostenberechnung und Token-Budgetierung.

Cache-Invalidierungsmuster:

• Der Cache bleibt gültig, wenn nur Tool-Ergebnisse als Benutzernachrichten bereitgestellt werden
• Der Cache wird ungültig, wenn Benutzinhalte hinzugefügt werden, die keine Tool-Ergebnisse sind, wodurch alle vorherigen Thinking Blocks entfernt werden
• Dieses Caching-Verhalten tritt auch ohne explizite cache_control Marker auf

Weitere Details zur Cache-Invalidierung finden Sie unter What invalidates the cache.

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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Wenn ein Benutzblock hinzugefügt wird, der kein Tool-Ergebnis ist, wird eine neue Assistant-Schleife eingeleitet und alle vorherigen Thinking Blocks werden aus dem Kontext entfernt.

Weitere detaillierte Informationen finden Sie in der Extended Thinking Dokumentation.

Cache-Speicherung und Freigabe

• Organisations-Isolation: Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen sich niemals Caches, auch wenn sie identische Prompts verwenden.

• Exakte Übereinstimmung: Cache Hits erfordern 100% identische Prompt-Segmente, einschließlich aller Texte und Bilder bis zu und einschließlich des Blocks, der mit Cache-Kontrolle gekennzeichnet ist.

• Output Token Generierung: Prompt Caching hat keine Auswirkung auf die Output Token Generierung. Die Antwort, die Sie erhalten, ist identisch mit dem, was Sie erhalten würden, wenn Prompt Caching nicht verwendet würde.

Best Practices für effektives Caching

Um die Leistung des Prompt Caching zu optimieren:

• Beginnen Sie mit automatischem Caching für Multi-Turn-Gespräche. Es verwaltet Breakpoint-Management automatisch.
• Verwenden Sie explizite Block-Level-Breakpoints, wenn Sie verschiedene Abschnitte mit unterschiedlichen Änderungsfrequenzen cachen müssen.
• Cachen Sie stabile, wiederverwendbare Inhalte wie Systeminstruktionen, Hintergrundinformationen, große Kontexte oder häufige Tool-Definitionen.
• Platzieren Sie gecachte Inhalte am Anfang des Prompts für beste Leistung.
• Verwenden Sie Cache Breakpoints strategisch, um verschiedene cacheable Präfix-Abschnitte zu trennen.
• Platzieren Sie den Breakpoint auf dem letzten Block, der über Requests hinweg identisch bleibt. Für einen Prompt mit einem statischen Präfix und einem variierenden Suffix (Zeitstempel, Pro-Request-Kontext, die eingehende Nachricht) ist das das Ende des Präfix, nicht der variierende Block.
• Analysieren Sie regelmäßig Cache Hit Rates und passen Sie Ihre Strategie nach Bedarf an.

Optimierung für verschiedene Anwendungsfälle

Passen Sie Ihre Prompt Caching Strategie an Ihr Szenario an:

• Conversational Agents: Reduzieren Sie Kosten und Latenz für erweiterte Gespräche, besonders solche mit langen Anweisungen oder hochgeladenen Dokumenten.
• Coding Assistants: 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ändiges langformatiges Material einschließlich Bilder in Ihren Prompt, ohne die Response-Latenz zu erhöhen.
• Detaillierte Anweisungssätze: Teilen Sie umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um Claudes Antworten zu verfeinern. Entwickler fügen normalerweise 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 von hochwertigen Antworten einbeziehen.
• Agentic Tool Use: Verbessern Sie die Leistung für Szenarien mit mehreren Tool-Aufrufen und iterativen Code-Änderungen, bei denen jeder Schritt normalerweise einen neuen API-Aufruf erfordert.
• Sprechen Sie mit Büchern, Papieren, Dokumentation, Podcast-Transkripten und anderen langformatigen Inhalten: Bringen Sie jede Wissensdatenbank zum Leben, indem Sie das gesamte Dokument (die Dokumente) in den Prompt einbetten und Benutzer es befragen lassen.

Fehlerbehebung bei häufigen Problemen

Wenn Sie unerwartet Verhalten feststellen:

• Stellen Sie sicher, dass gecachte Abschnitte über Aufrufe hinweg identisch sind. Überprüfen Sie für explizite Breakpoints, dass cache_control Marker an denselben Stellen sind
• Überprüfen Sie, dass Aufrufe innerhalb der Cache-Lebensdauer durchgeführt werden (standardmäßig 5 Minuten)
• Überprüfen Sie, dass tool_choice und Bildnutzung zwischen Aufrufen konsistent bleiben
• Validieren Sie, dass Sie mindestens die Mindestanzahl von Tokens für das Modell cachen, das Sie verwenden (siehe Cache limitations). Längenbezogene Caching-Fehler sind stumm: Die Anfrage ist erfolgreich, aber sowohl cache_creation_input_tokens als auch cache_read_input_tokens sind 0
• Bestätigen Sie, dass Ihr Breakpoint auf einem Block liegt, der über Requests hinweg identisch bleibt. Cache-Schreibvorgänge erfolgen nur am Breakpoint, und wenn sich dieser Block ändert (Zeitstempel, Pro-Request-Kontext, die eingehende Nachricht), stimmt der Präfix-Hash niemals überein. Der Lookback findet keinen stabilen Inhalt hinter dem Breakpoint; er findet nur Einträge, die frühere Anfragen an ihren eigenen Breakpoints geschrieben haben
• Überprüfen Sie, dass die Schlüssel in Ihren tool_use Inhaltsblöcken stabile Reihenfolge haben, da einige Sprachen (zum Beispiel Swift, Go) die Schlüsselreihenfolge während der JSON-Konvertierung randomisieren und Caches unterbrechen

1-Stunden-Cache-Dauer

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

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

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

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

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "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 sollte der 1-Stunden-Cache verwendet werden

Wenn Sie Prompts haben, die in regelmäßigen Abständen verwendet werden (das heißt, 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 agentic Side-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 nachfolgenden Prompts möglicherweise über 5 Minuten hinaus gesendet werden.
• Wenn Sie Ihre Rate-Limit-Auslastung verbessern möchten, da Cache Hits nicht gegen Ihr Rate Limit abgezogen werden.

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 (das heißt, ein 1-Stunden-Cache-Eintrag muss vor allen 5-Minuten-Cache-Einträgen erscheinen).

Beim Mischen von TTLs bestimmt die API drei Abrechnungspositionen in Ihrem Prompt:

1. Position A: Die Token-Anzahl beim höchsten Cache Hit (oder 0, wenn keine Hits).
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.

Ihnen werden berechnet:

1. Cache Read Tokens für A.
2. 1-Stunden-Cache Write Tokens für (B - A).
3. 5-Minuten-Cache Write Tokens für (C - B).

Hier sind 3 Beispiele. Dies zeigt die Input Tokens von 3 Anfragen, von denen jede unterschiedliche Cache Hits und Cache Misses hat. Jede hat eine unterschiedliche berechnete Preisgestaltung, die in den farbigen Feldern angezeigt wird.

Beispiele für Prompt-Caching

Um Ihnen den Einstieg in das Prompt-Caching zu erleichtern, bietet das Prompt-Caching-Cookbook detaillierte Beispiele und Best Practices.

Die folgenden Code-Snippets zeigen verschiedene Prompt-Caching-Muster. Diese Beispiele demonstrieren, wie Sie Caching in verschiedenen Szenarien implementieren und helfen Ihnen, die praktischen Anwendungen dieser Funktion zu verstehen:

Datenspeicherung

Prompt Caching (sowohl automatisch als auch explizit) ist ZDR-berechtigt. Anthropic speichert den Rohtext Ihrer Prompts oder Claude's Antworten nicht.

KV (Key-Value) Cache-Darstellungen und kryptografische Hashes von zwischengespeicherten Inhalten werden nur im Speicher gehalten und nicht dauerhaft gespeichert. Zwischengespeicherte Einträge haben eine Mindestlebensdauer von 5 Minuten (Standard) oder 60 Minuten (erweitert), danach werden sie umgehend, aber nicht sofort gelöscht. Cache-Einträge sind zwischen Organisationen isoliert.

Für ZDR-Berechtigung über alle Funktionen hinweg siehe API und Datenspeicherung.

Häufig gestellte Fragen