Prompt-Caching

Prompt-Caching ist eine leistungsstarke Funktion, die Ihre API-Nutzung optimiert, indem Sie von bestimmten Präfixen in Ihren Prompts fortfahren können. Dieser Ansatz reduziert die Verarbeitungszeit und Kosten für wiederholte 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:

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-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

{"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 „Pride and Prejudice" mit dem Parameter cache_control 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 und dabei 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 angegebenen Cache-Haltepunkt bereits aus einer kürzlichen Abfrage zwischengespeichert ist.
2. Falls gefunden, wird die zwischengespeicherte Version verwendet, was die 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:

Wie Sie Prompt-Caching implementieren

Prompt-Caching ist eine leistungsstarke Funktion, die Ihre API-Nutzung optimiert, indem Sie von bestimmten Präfixen in Ihren Prompts fortfahren können. Dieser Ansatz reduziert die Verarbeitungszeit und Kosten für wiederholte 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:

{"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 „Pride and Prejudice" mit dem Parameter cache_control 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 und dabei 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 angegebenen Cache-Haltepunkt bereits aus einer kürzlichen Abfrage zwischengespeichert ist.
2. Falls gefunden, wird die zwischengespeicherte Version verwendet, was die 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:

Wie Sie Prompt-Caching implementieren

Unterstützte Modelle

Prompt-Caching wird derzeit unterstützt auf:

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

Prompt-Caching ist eine leistungsstarke Funktion, die Ihre API-Nutzung optimiert, indem Sie von bestimmten Präfixen in Ihren Prompts fortfahren können. Dieser Ansatz reduziert die Verarbeitungszeit und Kosten für wiederholte Aufgaben oder Prompts mit konsistenten Elementen erheblich.

Hier ist ein Beispiel für die Implementierung von Prompt-Caching mit der Messages API unter Verwendung eines cache_control-Blocks:

{"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 „Pride and Prejudice" 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. Durch das Ändern nur der Benutzernachricht können Sie verschiedene Fragen zum Buch stellen und dabei 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 angegebenen Cache-Breakpoint bereits aus einer kürzlichen Abfrage zwischengespeichert ist.
2. Falls gefunden, wird die zwischengespeicherte Version verwendet, was die 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-Konversationen

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:

Wie man Prompt-Caching implementiert

Unterstützte Modelle

Prompt-Caching wird derzeit unterstützt auf:

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

Strukturierung Ihres Prompts

Platzieren Sie statische Inhalte (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, bei 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 die längste übereinstimmende Sequenz von zwischengespeicherten Blöcken. Das Verständnis, wie dies funktioniert, hilft Ihnen, Ihre Caching-Strategie zu optimieren.

Drei Kernprinzipien:

1. Cache-Schlüssel sind kumulativ: Wenn Sie einen Block explizit mit cache_control zwischengespeichern, wird der Cache-Hash-Schlüssel durch Hashing aller vorherigen Blöcke in der Konversation nacheinander generiert. Dies bedeutet, dass der Cache für jeden Block von allen Inhalten abhängt, die davor kamen.

2. Rückwärts-sequenzielle Überprüfung: Das System prüft auf Cache-Treffer, indem es rückwärts von Ihrem expliziten Breakpoint arbeitet und jeden vorherigen Block in umgekehrter Reihenfolge überprüft. Dies stellt sicher, dass Sie den längstmöglichen Cache-Treffer erhalten.

3. 20-Block-Lookback-Fenster: Das System prüft nur bis zu 20 Blöcke vor jedem expliziten cache_control-Breakpoint. Nach 20 Überprüfungen ohne Treffer stoppt es die Überprüfung und geht zum nächsten expliziten Breakpoint über (falls vorhanden).

Beispiel: Das Lookback-Fenster verstehen

Betrachten Sie eine Konversation mit 30 Inhaltsblöcken, bei der Sie cache_control nur auf Block 30 setzen:

• Wenn Sie Block 31 ohne Änderungen an vorherigen Blöcken senden: Das System prüft Block 30 (Treffer!). Sie erhalten einen Cache-Treffer bei Block 30, und nur Block 31 muss verarbeitet werden.

• Wenn Sie Block 25 ändern und Block 31 senden: Das System prüft rückwärts von Block 30 → 29 → 28... → 25 (kein Treffer) → 24 (Treffer!). Da Block 24 nicht geändert wurde, erhalten Sie einen Cache-Treffer bei Block 24, und nur die Blöcke 25-30 müssen neu verarbeitet werden.

• Wenn Sie Block 5 ändern und Block 31 senden: Das System prüft rückwärts von Block 30 → 29 → 28... → 11 (Überprüfung #20). Nach 20 Überprüfungen ohne Treffer stoppt es die Suche. Da Block 5 außerhalb des 20-Block-Fensters liegt, tritt kein Cache-Treffer auf und alle Blöcke müssen neu verarbeitet werden. Wenn Sie jedoch einen expliziten cache_control-Breakpoint auf Block 5 gesetzt hätten, würde das System von diesem Breakpoint aus weiterprüfen: Block 5 (kein Treffer) → Block 4 (Treffer!). Dies ermöglicht einen Cache-Treffer bei Block 4 und zeigt, warum Sie Breakpoints vor bearbeitbarem Inhalt platzieren sollten.

Wichtigste Erkenntnis: Setzen Sie immer einen expliziten Cache-Breakpoint am Ende Ihrer Konversation, um Ihre Chancen auf Cache-Treffer zu maximieren. Setzen Sie zusätzlich Breakpoints direkt vor Inhaltsblöcken, die bearbeitbar sein könnten, um sicherzustellen, dass diese Abschnitte unabhängig zwischengespeichert werden können.

Wann mehrere Breakpoints verwendet werden sollten

Sie können bis zu 4 Cache-Breakpoints definieren, wenn Sie möchten:

• Verschiedene Abschnitte zwischengespeichern, die sich mit unterschiedlichen Häufigkeiten ändern (z. B. Tools ändern sich selten, aber der 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
• Breakpoints vor bearbeitbarem Inhalt platzieren, um Cache-Treffer zu garantieren, auch wenn Änderungen außerhalb des 20-Block-Fensters auftreten

Cache-Einschränkungen

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

• 1024 Token für Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (veraltet) und Claude Opus 3 (veraltet)
• 4096 Token für Claude Haiku 4.5
• 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 gekennzeichnet sind. Alle Anfragen zum Zwischengespeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Response-Usage-Felder.

Bei gleichzeitigen Anfragen ist zu beachten, 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 Lebensdauer von 5 Minuten hat.

Cache-Einschränkungen

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

• 1024 Token für Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (veraltet) und Claude Opus 3 (veraltet)
• 4096 Token für Claude Haiku 4.5
• 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 gekennzeichnet sind. Alle Anfragen zum Zwischengespeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Response-Usage-Felder.

Bei gleichzeitigen Anfragen ist zu beachten, 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 Lebensdauer von 5 Minuten hat.

Cache-Breakpoint-Kosten verstehen

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-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 zwischengespeicherten 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 die Kontrolle darüber, welche Abschnitte unabhängig zwischengespeichert werden können.

Cache-Einschränkungen

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

• 1024 Token für Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (veraltet) und Claude Opus 3 (veraltet)
• 4096 Token für Claude Haiku 4.5
• 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 gekennzeichnet sind. Alle Anfragen zum Zwischengespeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Response-Usage-Felder.

Bei gleichzeitigen Anfragen ist zu beachten, 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 Lebensdauer von 5 Minuten hat.

Cache-Breakpoint-Kosten verstehen

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-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 zwischengespeicherten 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 die Kontrolle darüber, welche Abschnitte unabhängig zwischengespeichert werden können.

Was kann zwischengespeichert werden

Die meisten Blöcke in der Anfrage können mit cache_control zum Zwischengespeichern gekennzeichnet 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 für Assistent-Turns
• Bilder & Dokumente: Inhaltsblöcke im messages.content-Array, in Benutzer-Turns
• Tool-Nutzung und Tool-Ergebnisse: Inhaltsblöcke im messages.content-Array, sowohl für Benutzer- als auch für Assistent-Turns

Jedes dieser Elemente kann mit cache_control gekennzeichnet werden, um das Caching für diesen Teil der Anfrage zu aktivieren.

Cache-Einschränkungen

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

• 1024 Token für Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (veraltet) und Claude Opus 3 (veraltet)
• 4096 Token für Claude Haiku 4.5
• 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 gekennzeichnet sind. Alle Anfragen zum Zwischengespeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Response-Usage-Felder.

Bei gleichzeitigen Anfragen ist zu beachten, 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 Lebensdauer von 5 Minuten hat.

Cache-Breakpoint-Kosten verstehen

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-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 zwischengespeicherten 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 die Kontrolle darüber, welche Abschnitte unabhängig zwischengespeichert werden können.

Was kann zwischengespeichert werden

Die meisten Blöcke in der Anfrage können mit cache_control zum Zwischengespeichern gekennzeichnet 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 für Assistent-Turns
• Bilder & Dokumente: Inhaltsblöcke im messages.content-Array, in Benutzer-Turns
• Tool-Nutzung und Tool-Ergebnisse: Inhaltsblöcke im messages.content-Array, sowohl für Benutzer- als auch für Assistent-Turns

Jedes dieser Elemente kann mit cache_control gekennzeichnet werden, um das Caching für diesen Teil der Anfrage zu aktivieren.

Was kann nicht zwischengespeichert werden

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 Assistent-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 zwischen.

  Im Fall von Zitaten können die Top-Level-Dokumentinhaltsblö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 zwischengespeichern, auf die Zitate verweisen.

• Leere Textblöcke können nicht zwischengespeichert werden.

Cache-Einschränkungen

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

• 1024 Token für Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (veraltet) und Claude Opus 3 (veraltet)
• 4096 Token für Claude Haiku 4.5
• 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 gekennzeichnet sind. Alle Anfragen zum Zwischengespeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Response-Usage-Felder.

Bei gleichzeitigen Anfragen ist zu beachten, 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 Lebensdauer von 5 Minuten hat.

Cache-Breakpoint-Kosten verstehen

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-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 zwischengespeicherten 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 die Kontrolle darüber, welche Abschnitte unabhängig zwischengespeichert werden können.

Was kann zwischengespeichert werden

Die meisten Blöcke in der Anfrage können mit cache_control zum Zwischengespeichern gekennzeichnet 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 für Assistent-Turns
• Bilder & Dokumente: Inhaltsblöcke im messages.content-Array, in Benutzer-Turns
• Tool-Nutzung und Tool-Ergebnisse: Inhaltsblöcke im messages.content-Array, sowohl für Benutzer- als auch für Assistent-Turns

Jedes dieser Elemente kann mit cache_control gekennzeichnet werden, um das Caching für diesen Teil der Anfrage zu aktivieren.

Was kann nicht zwischengespeichert werden

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 Assistent-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 zwischen.

  Im Fall von Zitaten können die Top-Level-Dokumentinhaltsblö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 zwischengespeichern, auf die Zitate verweisen.

• Leere Textblöcke können nicht zwischengespeichert werden.

Was macht den Cache ungültig

Änderungen an zwischengespeicherten Inhalten 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 gemacht wird, während ✓ zeigt an, dass der Cache gültig bleibt.

Cache-Einschränkungen

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

• 1024 Token für Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (veraltet) und Claude Opus 3 (veraltet)
• 4096 Token für Claude Haiku 4.5
• 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 gekennzeichnet sind. Alle Anfragen zum Zwischengespeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Response-Usage-Felder.

Bei gleichzeitigen Anfragen ist zu beachten, 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 Lebensdauer von 5 Minuten hat.

Cache-Breakpoint-Kosten verstehen

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-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 zwischengespeicherten 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 die Kontrolle darüber, welche Abschnitte unabhängig zwischengespeichert werden können.

Was kann zwischengespeichert werden

Die meisten Blöcke in der Anfrage können mit cache_control zum Zwischengespeichern gekennzeichnet 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 für Assistent-Turns
• Bilder & Dokumente: Inhaltsblöcke im messages.content-Array, in Benutzer-Turns
• Tool-Nutzung und Tool-Ergebnisse: Inhaltsblöcke im messages.content-Array, sowohl für Benutzer- als auch für Assistent-Turns

Jedes dieser Elemente kann mit cache_control gekennzeichnet werden, um das Caching für diesen Teil der Anfrage zu aktivieren.

Was kann nicht zwischengespeichert werden

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 Assistent-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 zwischen.

  Im Fall von Zitaten können die Top-Level-Dokumentinhaltsblö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 zwischengespeichern, auf die Zitate verweisen.

• Leere Textblöcke können nicht zwischengespeichert werden.

Was macht den Cache ungültig

Änderungen an zwischengespeicherten Inhalten 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 gemacht wird, während ✓ zeigt an, dass der Cache gültig bleibt.

Cache-Leistung verfolgen

Überwachen Sie die Cache-Leistung mit diesen API-Response-Feldern, innerhalb von usage in der Response (oder message_start-Event, wenn 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

Cache-Einschränkungen

Die minimale zwischenspeicherbare Eingabelänge beträgt:

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

Kürzere Eingaben 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 Zwischenspeicherung verarbeitet. Um zu sehen, ob eine Eingabe zwischengespeichert wurde, siehe die Antwortnutzungs-Felder.

Beachten Sie bei gleichzeitigen Anfragen, 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 Lebensdauer von 5 Minuten hat.

Cache-Breakpoint-Kosten verstehen

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-Eingabe-Token für 5-Minuten-TTL)
• Cache-Lesevorgänge: Wenn zwischengespeicherter Inhalt verwendet wird (10% des Basis-Eingabe-Token-Preises)
• Reguläre Eingabe-Token: Für nicht zwischengespeicherten Inhalt

Das Hinzufügen weiterer 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 die Kontrolle darüber, welche Abschnitte unabhängig voneinander zwischengespeichert werden können.

Was kann zwischengespeichert werden

Die meisten Blöcke in der Anfrage können mit cache_control zum Zwischenspeichern gekennzeichnet werden. Dies umfasst:

• Tools: Tool-Definitionen im tools-Array
• Systemmeldungen: Inhaltsblöcke im system-Array
• Textmeldungen: Inhaltsblöcke im messages.content-Array für Benutzer- und Assistent-Turns
• Bilder & Dokumente: Inhaltsblöcke im messages.content-Array in Benutzer-Turns
• Tool-Nutzung und Tool-Ergebnisse: Inhaltsblöcke im messages.content-Array in Benutzer- und Assistent-Turns

Jedes dieser Elemente kann mit cache_control gekennzeichnet werden, um das Zwischenspeichern für diesen Teil der Anfrage zu aktivieren.

Was kann nicht zwischengespeichert werden

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 Assistent-Turns erscheinen. Wenn sie auf diese Weise zwischengespeichert werden, zählen sie als Eingabe-Token beim Lesen aus dem Cache.

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

  Im Fall von Zitaten können die Top-Level-Dokumentinhaltsblö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 Textblöcke können nicht zwischengespeichert werden.

Was macht den Cache ungültig

Änderungen an zwischengespeichertem Inhalt können einen Teil oder den gesamten Cache ungültig machen.

Wie in Strukturierung Ihrer Eingabe 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 ✓ anzeigt, dass der Cache gültig bleibt.

Cache-Leistung verfolgen

Ü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 Eingabe-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

Best Practices für effektives Caching

Um die Prompt-Caching-Leistung zu optimieren:

• Speichern Sie stabile, wiederverwendbare Inhalte wie Systemaufforderungen, Hintergrundinformationen, große Kontexte oder häufige Tool-Definitionen zwischen.
• Platzieren Sie zwischengespeicherte Inhalte am Anfang der Eingabe für beste Leistung.
• Verwenden Sie Cache-Breakpoints strategisch, um verschiedene zwischenspeicherbare Präfix-Abschnitte zu trennen.
• Setzen Sie Cache-Breakpoints am Ende von Gesprächen und direkt vor bearbeitbarem Inhalt, um Cache-Hit-Raten zu maximieren, besonders wenn Sie mit Eingaben arbeiten, die mehr als 20 Inhaltsblöcke haben.
• Analysieren Sie regelmäßig Cache-Hit-Raten 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, besonders solche mit langen Anweisungen oder hochgeladenen Dokumenten.
• Coding-Assistenten: Verbessern Sie Autovervollständigung und Codebase-Q&A, indem Sie relevante Abschnitte oder eine zusammengefasste Version der Codebase in der Eingabe behalten.
• Verarbeitung großer Dokumente: Integrieren Sie vollständiges Langform-Material einschließlich Bilder in Ihre Eingabe, ohne die Antwortlatenz zu erhöhen.
• Detaillierte Anweisungssätze: Teilen Sie umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um Claudes Antworten zu optimieren. Entwickler fügen normalerweise ein oder zwei Beispiele in die Eingabe ein, aber mit Prompt-Caching können Sie noch bessere Leistung erzielen, indem Sie 20+ vielfältige Beispiele hochwertiger Antworten einbeziehen.
• Agentic Tool-Nutzung: 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 Langform-Inhalten: Bringen Sie jede Wissensdatenbank zum Leben, indem Sie das/die gesamte(n) Dokument(e) in die Eingabe einbetten und Benutzer es/sie befragen lassen.

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, besonders solche mit langen Anweisungen oder hochgeladenen Dokumenten.
• Coding-Assistenten: Verbessern Sie Autovervollständigung und Codebase-Q&A, indem Sie relevante Abschnitte oder eine zusammengefasste Version der Codebase in der Eingabe behalten.
• Verarbeitung großer Dokumente: Integrieren Sie vollständiges Langform-Material einschließlich Bilder in Ihre Eingabe, ohne die Antwortlatenz zu erhöhen.
• Detaillierte Anweisungssätze: Teilen Sie umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um Claudes Antworten zu optimieren. Entwickler fügen normalerweise ein oder zwei Beispiele in die Eingabe ein, aber mit Prompt-Caching können Sie noch bessere Leistung erzielen, indem Sie 20+ vielfältige Beispiele hochwertiger Antworten einbeziehen.
• Agentic Tool-Nutzung: 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 Langform-Inhalten: Bringen Sie jede Wissensdatenbank zum Leben, indem Sie das/die gesamte(n) Dokument(e) in die Eingabe einbetten und Benutzer es/sie befragen lassen.

Behebung häufiger Probleme

Wenn Sie unerwartetetes Verhalten erleben:

• Stellen Sie sicher, dass zwischengespeicherte Abschnitte identisch sind und mit cache_control an den gleichen Stellen über Aufrufe hinweg gekennzeichnet sind
• Überprüfen Sie, dass Aufrufe innerhalb der Cache-Lebensdauer erfolgen (standardmäßig 5 Minuten)
• Überprüfen Sie, dass tool_choice und Bildnutzung zwischen Aufrufen konsistent bleiben
• Validieren Sie, dass Sie mindestens die Mindestanzahl von Token zwischenspeichern
• Das System überprüft automatisch auf Cache-Treffer bei vorherigen Inhaltsblock-Grenzen (bis zu ~20 Blöcke vor Ihrem Breakpoint). Für Eingaben mit mehr als 20 Inhaltsblöcken benötigen Sie möglicherweise zusätzliche cache_control-Parameter früher in der Eingabe, um sicherzustellen, dass alle Inhalte zwischengespeichert werden können
• Überprüfen Sie, dass die Schlüssel in Ihren tool_use-Inhaltsblöcken eine stabile Reihenfolge haben, da einige Sprachen (z. B. Swift, Go) die Schlüsselreihenfolge während der JSON-Konvertierung randomisieren und Caches unterbrechen

Caching mit Thinking-Blöcken

Bei Verwendung von erweitertem Denken mit Prompt-Caching haben Thinking-Blöcke ein spezielles Verhalten:

Automatisches Caching zusammen mit anderen Inhalten: Obwohl Thinking-Blöcke nicht explizit mit cache_control gekennzeichnet werden können, werden sie als Teil des Anfrageinhalts zwischengespeichert, wenn Sie nachfolgende API-Aufrufe mit Tool-Ergebnissen durchführen. Dies geschieht häufig während der Tool-Nutzung, wenn Sie Thinking-Blöcke zurückgeben, um das Gespräch fortzusetzen.

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

Cache-Ungültigkeitsmuster:

• Der Cache bleibt gültig, wenn nur Tool-Ergebnisse als Benutzermeldungen bereitgestellt werden
• Der Cache wird ungültig, wenn Nicht-Tool-Ergebnis-Benutzerinhalte hinzugefügt werden, was dazu führt, dass alle vorherigen Thinking-Blöcke entfernt werden
• Dieses Caching-Verhalten tritt auch ohne explizite cache_control-Markierungen auf

Weitere Details zur Cache-Ungültigmachung finden Sie unter Was macht den Cache ungültig.

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 Nicht-Tool-Ergebnis-Benutzerblock enthalten ist, kennzeichnet er eine neue Assistent-Schleife und alle vorherigen Thinking-Blöcke werden aus dem Kontext entfernt.

Weitere detaillierte Informationen finden Sie in der Dokumentation zum erweiterten Denken.

Cache-Speicherung und -Freigabe

• Organisationsisolation: Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen niemals Caches, auch wenn sie identische Eingaben verwenden.

• Exakte Übereinstimmung: Cache-Treffer erfordern 100% identische Eingabesegmente, einschließlich aller Texte und Bilder bis zu und einschließlich des mit Cache-Kontrolle gekennzeichneten Blocks.

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

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, besonders solche mit langen Anweisungen oder hochgeladenen Dokumenten.
• Coding-Assistenten: Verbessern Sie Autovervollständigung und Codebase-Q&A, indem Sie relevante Abschnitte oder eine zusammengefasste Version der Codebase in der Eingabe behalten.
• Verarbeitung großer Dokumente: Integrieren Sie vollständiges Langform-Material einschließlich Bilder in Ihre Eingabe, ohne die Antwortlatenz zu erhöhen.
• Detaillierte Anweisungssätze: Teilen Sie umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um Claudes Antworten zu optimieren. Entwickler fügen normalerweise ein oder zwei Beispiele in die Eingabe ein, aber mit Prompt-Caching können Sie noch bessere Leistung erzielen, indem Sie 20+ vielfältige Beispiele hochwertiger Antworten einbeziehen.
• Agentic Tool-Nutzung: 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 Langform-Inhalten: Bringen Sie jede Wissensdatenbank zum Leben, indem Sie das/die gesamte(n) Dokument(e) in die Eingabe einbetten und Benutzer es/sie befragen lassen.

Behebung häufiger Probleme

Wenn Sie unerwartetetes Verhalten erleben:

• Stellen Sie sicher, dass zwischengespeicherte Abschnitte identisch sind und mit cache_control an den gleichen Stellen über Aufrufe hinweg gekennzeichnet sind
• Überprüfen Sie, dass Aufrufe innerhalb der Cache-Lebensdauer erfolgen (standardmäßig 5 Minuten)
• Überprüfen Sie, dass tool_choice und Bildnutzung zwischen Aufrufen konsistent bleiben
• Validieren Sie, dass Sie mindestens die Mindestanzahl von Token zwischenspeichern
• Das System überprüft automatisch auf Cache-Treffer bei vorherigen Inhaltsblock-Grenzen (bis zu ~20 Blöcke vor Ihrem Breakpoint). Für Eingaben mit mehr als 20 Inhaltsblöcken benötigen Sie möglicherweise zusätzliche cache_control-Parameter früher in der Eingabe, um sicherzustellen, dass alle Inhalte zwischengespeichert werden können
• Überprüfen Sie, dass die Schlüssel in Ihren tool_use-Inhaltsblöcken eine stabile Reihenfolge haben, da einige Sprachen (z. B. Swift, Go) die Schlüsselreihenfolge während der JSON-Konvertierung randomisieren und Caches unterbrechen

Caching mit Thinking-Blöcken

Bei Verwendung von erweitertem Denken mit Prompt-Caching haben Thinking-Blöcke ein spezielles Verhalten:

Automatisches Caching zusammen mit anderen Inhalten: Obwohl Thinking-Blöcke nicht explizit mit cache_control gekennzeichnet werden können, werden sie als Teil des Anfrageinhalts zwischengespeichert, wenn Sie nachfolgende API-Aufrufe mit Tool-Ergebnissen durchführen. Dies geschieht häufig während der Tool-Nutzung, wenn Sie Thinking-Blöcke zurückgeben, um das Gespräch fortzusetzen.

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

Cache-Ungültigkeitsmuster:

• Der Cache bleibt gültig, wenn nur Tool-Ergebnisse als Benutzermeldungen bereitgestellt werden
• Der Cache wird ungültig, wenn Nicht-Tool-Ergebnis-Benutzerinhalte hinzugefügt werden, was dazu führt, dass alle vorherigen Thinking-Blöcke entfernt werden
• Dieses Caching-Verhalten tritt auch ohne explizite cache_control-Markierungen auf

Weitere Details zur Cache-Ungültigmachung finden Sie unter Was macht den Cache ungültig.

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 Nicht-Tool-Ergebnis-Benutzerblock enthalten ist, kennzeichnet er eine neue Assistent-Schleife und alle vorherigen Thinking-Blöcke werden aus dem Kontext entfernt.

Weitere detaillierte Informationen finden Sie in der Dokumentation zum erweiterten Denken.

Cache-Speicherung und -Freigabe

• Organisationsisolation: Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen niemals Caches, auch wenn sie identische Eingaben verwenden.

• Exakte Übereinstimmung: Cache-Treffer erfordern 100% identische Eingabesegmente, einschließlich aller Texte und Bilder bis zu und einschließlich des mit Cache-Kontrolle gekennzeichneten Blocks.

• Ausgabe-Token-Generierung: Prompt-Caching hat keine Auswirkung auf die Ausgabe-Token-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 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": "5m" | "1h"
}

Die Antwort enthält detaillierte Cache-Informationen wie die folgende:

{
    "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 Feld cache_creation_input_tokens der Summe der Werte im Objekt cache_creation entspricht.

Wann sollte der 1-Stunden-Cache verwendet werden

Wenn Sie Eingaben haben, die in regelmäßigen Abständen verwendet werden (d. h. Systemaufforderungen, 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 Eingaben 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 innerhalb der nächsten 5 Minuten antwortet.
• Wenn Latenz wichtig ist und Ihre nachfolgenden Eingaben möglicherweise über 5 Minuten hinaus gesendet werden.
• Wenn Sie Ihre Ratenlimit-Auslastung verbessern möchten, da Cache-Treffer nicht gegen Ihr Ratenlimit abgezogen werden.

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, besonders solche mit langen Anweisungen oder hochgeladenen Dokumenten.
• Coding-Assistenten: Verbessern Sie Autovervollständigung und Codebase-Fragen, indem Sie relevante Abschnitte oder eine zusammengefasste Version der Codebase im Prompt behalten.
• Verarbeitung großer Dokumente: Integrieren Sie vollständiges Langform-Material 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 optimieren. 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 Langform-Inhalten: Bringen Sie jede Wissensdatenbank zum Leben, indem Sie das/die gesamte(n) Dokument(e) in den Prompt einbetten und Benutzer es/sie befragen lassen.

Behebung häufiger Probleme

Wenn Sie unerwartet Verhalten feststellen:

• Stellen Sie sicher, dass zwischengespeicherte Abschnitte identisch sind und mit cache_control an denselben Stellen über Aufrufe hinweg gekennzeichnet sind
• Überprüfen Sie, dass Aufrufe innerhalb der Cache-Lebensdauer erfolgen (standardmäßig 5 Minuten)
• Überprüfen Sie, dass tool_choice und die Bildnutzung zwischen Aufrufen konsistent bleiben
• Validieren Sie, dass Sie mindestens die Mindestanzahl von Token zwischenspeichern
• Das System prüft automatisch auf Cache-Treffer bei vorherigen Content-Block-Grenzen (bis zu ~20 Blöcke vor Ihrem Breakpoint). Bei Prompts mit mehr als 20 Content-Blöcken müssen Sie möglicherweise zusätzliche cache_control-Parameter früher im Prompt hinzufügen, um sicherzustellen, dass alle Inhalte zwischengespeichert werden können
• Überprüfen Sie, dass die Schlüssel in Ihren tool_use Content-Blöcken eine stabile Reihenfolge haben, da einige Sprachen (z. B. Swift, Go) die Schlüsselreihenfolge während der JSON-Konvertierung randomisieren und Caches unterbrechen

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 zwischengespeichert, wenn Sie nachfolgende API-Aufrufe mit Tool-Ergebnissen durchführen. Dies geschieht häufig während 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-Token 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 Nicht-Tool-Ergebnis-Benutzerinhalte hinzugefügt werden, was dazu führt, dass alle vorherigen Thinking Blocks entfernt werden
• Dieses Caching-Verhalten tritt auch ohne explizite cache_control-Markierungen auf

Weitere Details zur Cache-Invalidierung finden Sie unter Was macht den Cache ungültig.

Beispiel mit Tool Use:

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 Nicht-Tool-Ergebnis-Benutzerblock enthalten ist, kennzeichnet er eine neue Assistant-Schleife und alle vorherigen Thinking Blocks werden aus dem Kontext entfernt.

Weitere detaillierte Informationen finden Sie in der Extended-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 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.

1-Stunden-Cache-Dauer

Wenn Sie feststellen, dass 5 Minuten zu kurz sind, bietet Anthropic auch eine 1-Stunden-Cache-Dauer gegen zusätzliche Gebühren 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 enthält detaillierte Cache-Informationen wie die folgende:

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

Wenn Sie Prompts haben, die regelmäßig 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 Gebühren 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-Treffer 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 (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 vorhanden sind).
3. Position C: Die Token-Anzahl beim letzten cache_control-Block.

Ihnen werden berechnet:

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

Hier sind 3 Beispiele. Dies zeigt die Input-Token von 3 Anfragen, von denen jede unterschiedliche Cache-Treffer und Cache-Misses hat. Jede hat eine unterschiedliche berechnete Preisgestaltung, die in den farbigen Kästchen angezeigt wird.

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.

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

Häufig gestellte Fragen