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, wie man Prompt-Caching mit der Messages API unter Verwendung eines cache_control Blocks implementiert:

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-3-7-sonnet-20250219",
    "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” mithilfe des cache_control Parameters zwischengespeichert. Dies ermöglicht die Wiederverwendung dieses umfangreichen Textes über mehrere API-Aufrufe hinweg, ohne ihn jedes Mal neu verarbeiten zu müssen. Wenn Sie nur die Benutzernachricht ändern, können Sie verschiedene Fragen über das 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, wird die zwischengespeicherte Version verwendet, was die Verarbeitungszeit und Kosten reduziert.
3. Andernfalls wird der vollständige Prompt verarbeitet und der 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
• Sich wiederholende Aufgaben mit konsistenten Anweisungen
• Lange Mehrfach-Turn-Konversationen

Der Cache hat eine Mindestlebensdauer von 5 Minuten, die bei jeder Verwendung des zwischengespeicherten Inhalts erneuert wird.

​

Preisgestaltung

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

Hinweis:

• Cache-Schreib-Token sind 25% teurer als Basis-Input-Token
• Cache-Lese-Token sind 90% günstiger als Basis-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 von:

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

​

Strukturierung Ihres Prompts

Platzieren Sie statische Inhalte (Tool-Definitionen, System-Anweisungen, 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 folgender Reihenfolge erstellt: tools, system, dann messages.

Mit dem cache_control Parameter 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 den längsten passenden Präfix, wenn einer gefunden wird.

​

Cache-Einschränkungen

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

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

Kürzere Prompts können nicht zwischengespeichert werden, auch wenn sie mit cache_control markiert sind. Alle Anfragen zum Caching von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Antwort-Usage 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 mit dem Senden nachfolgender Anfragen, bis die erste Antwort vorliegt.

Der Cache hat eine Mindestlebensdauer (TTL) von 5 Minuten. Derzeit ist “ephemeral” der einzige unterstützte Cache-Typ, der dieser minimalen 5-Minuten-Lebensdauer entspricht.

​

Was kann zwischengespeichert werden

Jeder Block in der Anfrage kann mit cache_control für das Caching gekennzeichnet werden. Dies umfasst:

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

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

​

Überwachung der Cache-Leistung

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

• cache_creation_input_tokens: Anzahl der Token, die beim Erstellen eines neuen Eintrags in den Cache geschrieben wurden.
• 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 Cache verwendet wurden.

​

Best Practices für effektives Caching

Um die Prompt-Caching-Leistung zu optimieren:

• Cachen Sie stabile, wiederverwendbare Inhalte wie System-Anweisungen, Hintergrundinformationen, große Kontexte oder häufige Tool-Definitionen.
• Platzieren Sie gecachte Inhalte am Anfang des Prompts für beste Leistung.
• Nutzen Sie Cache-Breakpoints strategisch, um verschiedene cacheable Präfix-Abschnitte zu trennen.
• Analysieren Sie regelmäßig Cache-Trefferraten und passen Sie Ihre Strategie bei Bedarf an.

​

Optimierung für verschiedene Anwendungsfälle

Passen Sie Ihre Prompt-Caching-Strategie an Ihr Szenario an:

• Konversations-Agenten: 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 im Prompt behalten.
• Verarbeitung großer Dokumente: Integrieren Sie vollständiges Langform-Material einschließlich Bilder in Ihren Prompt ohne Erhöhung der Antwortlatenz.
• Detaillierte Anweisungssätze: Teilen Sie umfangreiche Listen von Anweisungen, Prozeduren und Beispielen, um Claudes Antworten zu verfeinern. Entwickler fügen oft ein oder zwei Beispiele in den Prompt ein, aber mit Prompt-Caching können Sie noch bessere Leistung erzielen, indem Sie 20+ diverse Beispiele für qualitativ hochwertige Antworten einbinden.
• Agentische Tool-Nutzung: Verbessern Sie die Leistung für Szenarien mit mehreren Tool-Aufrufen und iterativen Code-Änderungen, bei denen jeder Schritt typischerweise einen neuen API-Aufruf erfordert.
• Sprechen Sie mit Büchern, Papern, Dokumentationen, Podcast-Transkripten und anderen Langform-Inhalten: Bringen Sie jede Wissensbasis zum Leben, indem Sie das gesamte Dokument/die Dokumente in den Prompt einbetten und Benutzer Fragen dazu stellen lassen.

​

Fehlerbehebung häufiger Probleme

Bei unerwartetem Verhalten:

• Stellen Sie sicher, dass gecachte Abschnitte identisch sind und mit cache_control an denselben Stellen über Aufrufe hinweg markiert sind
• Prüfen Sie, ob Aufrufe innerhalb der 5-minütigen Cache-Lebensdauer erfolgen
• Überprüfen Sie, dass tool_choice und Bildverwendung zwischen Aufrufen konsistent bleiben
• Validieren Sie, dass Sie mindestens die Mindestanzahl an Token cachen
• Während das System versucht, zuvor gecachte Inhalte an Positionen vor einem Cache-Breakpoint zu verwenden, können Sie einen zusätzlichen cache_control Parameter verwenden, um Cache-Lookup für vorherige Teile des Prompts zu garantieren, was bei 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 irgendwo im Prompt den Cache ungültig machen und die Erstellung eines neuen Cache-Eintrags erfordern.

​

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. Derselbe Block muss während Cache-Lese- und Erstellungsvorgängen mit cache_control markiert sein.

• Output-Token-Generierung: Prompt-Caching hat keinen Einfluss auf die Output-Token-Generierung. Die Antwort, die Sie erhalten, wird identisch sein mit der, die Sie ohne Prompt-Caching erhalten würden.

​

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents."
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

​

FAQ

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

python client.messages.create(...)

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

client.messages.create(...)