Prompt-Caching

Prompt-Caching ist eine leistungsstarke Funktion, die Ihre API-Nutzung optimiert, indem sie das Fortsetzen von bestimmten Präfixen in Ihren Prompts ermöglicht. Dieser Ansatz reduziert die Verarbeitungszeit und Kosten für sich wiederholende Aufgaben oder Prompts mit konsistenten Elementen erheblich.

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

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-20250514",
    "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 umfangreichen Textes über mehrere API-Aufrufe hinweg, ohne ihn bei jedem Aufruf erneut 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 bestimmten Cache-Breakpoint bereits aus einer kürzlichen Abfrage zwischengespeichert ist.
2. Falls gefunden, verwendet es die zwischengespeicherte Version, was die Verarbeitungszeit und Kosten reduziert.
3. Andernfalls verarbeitet es den vollständigen Prompt und speichert das Präfix zwischen, sobald die Antwort beginnt.

Dies ist besonders nützlich für:

• Prompts mit vielen Beispielen
• Große Mengen an Kontext oder Hintergrundinformationen
• Sich wiederholende Aufgaben mit konsistenten Anweisungen
• Lange Gespräche mit mehreren Gesprächsrunden

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.

​

Preisgestaltung

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

Hinweis:

• 5-Minuten-Cache-Schreib-Token kosten das 1,25-fache des Basispreises für Input-Token
• 1-Stunden-Cache-Schreib-Token kosten das 2-fache des Basispreises für Input-Token
• Cache-Lese-Token kosten das 0,1-fache des Basispreises für Input-Token
• Reguläre Input- und Output-Token werden zu Standardpreisen berechnet

​

Wie man Prompt-Caching implementiert

​

Unterstützte Modelle

Prompt-Caching wird derzeit unterstützt für:

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

Strukturierung Ihres Prompts

Platzieren Sie statische Inhalte (Tool-Definitionen, Systemanweisungen, Kontext, Beispiele) am Anfang Ihres Prompts. Markieren Sie das Ende des wiederverwendbaren Inhalts für das Caching mit dem Parameter cache_control.

Cache-Präfixe werden in folgender Reihenfolge erstellt: tools, system, dann messages.

Mit dem Parameter cache_control können Sie bis zu 4 Cache-Breakpoints definieren, wodurch Sie verschiedene wiederverwendbare Abschnitte separat zwischenspeichern können. Für jeden Breakpoint prüft das System automatisch auf Cache-Treffer an vorherigen Positionen und verwendet das längste passende Präfix, falls eines gefunden wird.

​

Cache-Einschränkungen

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

• 1024 Token für Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 und Claude Opus 3
• 2048 Token für Claude Haiku 3.5 und Claude Haiku 3

Kürzere Prompts können nicht zwischengespeichert werden, auch wenn sie mit cache_control markiert sind. 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.

Bei gleichzeitigen 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 Lebensdauer von 5 Minuten hat.

​

Was zwischengespeichert werden kann

Die meisten Blöcke in der Anfrage können mit cache_control für das Caching gekennzeichnet werden. Dazu gehören:

• 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 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 in Assistenten-Turns

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

​

Was nicht zwischengespeichert werden kann

Während die meisten 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.

• Untergeordnete Inhaltsblöcke (wie Zitate) selbst können nicht direkt zwischengespeichert werden. Stattdessen speichern Sie 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 effektiv mit Zitaten zu verwenden, indem Sie die Dokumente zwischenspeichern, auf die sich Zitate beziehen werden.

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

​

Überwachung der Cache-Leistung

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

• cache_creation_input_tokens: Anzahl der Token, die in den Cache geschrieben wurden, wenn ein neuer Eintrag erstellt wird.
• cache_read_input_tokens: Anzahl der Token, die für diese Anfrage aus dem Cache abgerufen wurden.
• input_tokens: Anzahl der Input-Token, die nicht aus dem Cache gelesen oder zum Erstellen eines Caches verwendet wurden.

​

Best Practices für effektives Caching

Um die Leistung des Prompt-Cachings zu optimieren:

• Speichern Sie stabile, wiederverwendbare Inhalte wie Systemanweisungen, Hintergrundinformationen, große Kontexte oder häufige Tool-Definitionen zwischen.
• Platzieren Sie zwischengespeicherte Inhalte 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 die Cache-Trefferquoten und passen Sie Ihre Strategie bei 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 Autovervollständigung 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 Langform-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 optimieren. Entwickler fügen oft ein oder zwei Beispiele im Prompt ein, aber mit Prompt-Caching können Sie noch bessere Leistung erzielen, indem Sie 20+ vielfältige Beispiele für qualitativ hochwertige Antworten einbeziehen.
• Agentischer Tool-Einsatz: 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.
• Gespräche mit Büchern, Papern, Dokumentationen, Podcast-Transkripten und anderen Langform-Inhalten: Beleben Sie jede Wissensbasis, indem Sie das gesamte Dokument/die gesamten Dokumente in den Prompt einbetten und Benutzer Fragen dazu stellen lassen.

​

Fehlerbehebung bei häufigen Problemen

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) erfolgen
• Stellen Sie sicher, dass tool_choice und Bildverwendung zwischen Aufrufen konsistent bleiben
• Überprüfen Sie, dass Sie mindestens die Mindestanzahl an Token zwischenspeichern
• Während das System versucht, zuvor zwischengespeicherte Inhalte an Positionen vor einem Cache-Breakpoint zu verwenden, können Sie einen zusätzlichen cache_control-Parameter verwenden, um die Cache-Suche für vorherige Teile des Prompts zu garantieren, was für Abfragen mit sehr langen Listen von Inhaltsblöcken nützlich sein kann

Beachten Sie, dass Änderungen an tool_choice oder das Vorhandensein/Fehlen von Bildern an beliebiger Stelle im Prompt den Cache ungültig machen, was die Erstellung eines neuen Cache-Eintrags erfordert.

​

Caching mit Thinking-Blöcken

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

Automatisches Caching zusammen mit anderen Inhalten: 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 durchführen. Dies geschieht häufig während der Tool-Verwendung, wenn Sie Thinking-Blöcke zurückgeben, um das Gespräch fortzusetzen.

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

Cache-Invalidierungsmuster:

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

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 Anfrage-Inhalt 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 verursacht, dass alle Thinking-Blöcke ignoriert werden
# Diese Anfrage wird verarbeitet, als ob Thinking-Blöcke nie vorhanden waren

Wenn ein Benutzerblock, der kein Tool-Ergebnis ist, enthalten ist, kennzeichnet er eine neue Assistenten-Schleife, und alle vorherigen Thinking-Blöcke werden aus dem Kontext entfernt.

Für detailliertere Informationen siehe die Dokumentation zum erweiterten Denken.

​

Cache-Speicherung und -Freigabe

• Organisations-Isolation: 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.

• Generierung von Output-Token: Prompt-Caching hat keinen Einfluss auf die Generierung von Output-Token. Die Antwort, die Sie erhalten, ist identisch mit der, die Sie erhalten würden, wenn Prompt-Caching nicht verwendet würde.

​

1-Stunden-Cache-Dauer (Beta)

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 extended-cache-ttl-2025-04-11 als Beta-Header zu Ihrer Anfrage hinzu und fügen Sie dann 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 Feld cache_creation_input_tokens der Summe der Werte im Objekt cache_creation 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 weiterhin ohne zusätzliche Kosten aktualisiert wird.

Der 1-Stunden-Cache eignet sich am besten für folgende Szenarien:

• 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 Neben-Agent länger als 5 Minuten benötigt, 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 nach mehr als 5 Minuten gesendet werden.
• Wenn Sie Ihre Rate-Limit-Nutzung verbessern möchten, da Cache-Treffer nicht von Ihrem Rate-Limit abgezogen werden.

​

Mischen verschiedener TTLs

Sie können sowohl 1-Stunden- als auch 5-Minuten-Cache-Controls in derselben Anfrage verwenden, jedoch 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 keiner existiert).
3. Position C: Die Token-Anzahl beim letzten cache_control-Block.

Ihnen werden berechnet:

1. Cache-Lese-Token für A.
2. 1-Stunden-Cache-Schreib-Token für (B - A).
3. 5-Minuten-Cache-Schreib-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-Fehltreffer hat. Jede hat eine andere berechnete Preisgestaltung, die in den farbigen Kästchen dargestellt ist.

​

Prompt-Caching-Beispiele

Um Ihnen den Einstieg in das Prompt-Caching zu erleichtern, haben wir ein Prompt-Caching-Kochbuch mit detaillierten Beispielen und Best Practices vorbereitet.

Nachfolgend haben wir mehrere Code-Snippets aufgenommen, die verschiedene Prompt-Caching-Muster zeigen. Diese Beispiele demonstrieren, wie man Caching in verschiedenen Szenarien implementiert und helfen Ihnen, die praktischen Anwendungen dieser Funktion zu verstehen:

​

FAQ