> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Leitfaden zum Claude-Kontext-Caching > Speichern Sie wiederverwendete Prompt-Präfixe über die Claude Messages API oder die OpenAI-kompatible Chat Completions API zwischen, um die Token-Kosten für die wiederholte Verarbeitung langer Inhalte zu senken. Claude Context Cache eignet sich für die Wiederverwendung langer Präfixe wie System-Prompts, Dokumente, Codebasen oder Gesprächsverläufe. Nachdem Sie einem stabilen Präfix `cache_control` hinzugefügt haben, erstellt die erste Anfrage einen Cache und nachfolgende Anfragen können den noch gültigen Cache lesen. Legen Sie zunächst Ihren API-Schlüssel fest: ```bash theme={null} export API_KEY="IHR_API_SCHLUESSEL" ``` Die Beispiele in diesem Leitfaden verwenden `claude-sonnet-5`. Ob andere Modelle Context Cache unterstützen, erfahren Sie in der Modelldokumentation der Plattform. ## Anwendungsfälle Wenn mehrere Anfragen wiederholt dieselben umfangreichen Inhalte enthalten, können Sie einen stabilen Präfix zwischenspeichern, zum Beispiel: * Einen langen System-Prompt * Eine feste Wissensdatenbank oder Produktdokumentation * Einen unveränderten Gesprächsverlauf aus mehreren Dialogrunden * Wiederverwendete Codebasen, Tool-Definitionen und Anweisungen Context Cache eignet sich für Anfragen, bei denen der Inhalt am Anfang unverändert bleibt, während sich die abschließende Frage fortlaufend ändert. ## Claude Messages API ### 5-Minuten-Cache Fügen Sie `cache_control` zu dem Inhaltsblock hinzu, der zwischengespeichert werden soll: ```bash theme={null} curl "https://api.apimart.ai/v1/messages" \ -H "x-api-key: $API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 1024, "system": [ { "type": "text", "text": "Fügen Sie hier den langen Präfix ein, der wiederverwendet werden soll...", "cache_control": { "type": "ephemeral" } } ], "messages": [ { "role": "user", "content": "Beantworten Sie die Frage anhand des obigen Inhalts." } ] }' ``` `system` muss als Array von Inhaltsblöcken angegeben werden. Bei einem `system`-String kann `cache_control` nicht hinzugefügt werden. Wenn `ttl` weggelassen wird, beträgt die Cache-Gültigkeitsdauer standardmäßig 5 Minuten. ### 1-Stunden-Cache Für einen 1-Stunden-Cache müssen Sie zusätzlich den Anfrage-Header `anthropic-beta` senden und `ttl` auf `1h` setzen: ```bash theme={null} curl "https://api.apimart.ai/v1/messages" \ -H "x-api-key: $API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: extended-cache-ttl-2025-04-11" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 1024, "system": [ { "type": "text", "text": "Fügen Sie hier den langen Präfix ein, der wiederverwendet werden soll...", "cache_control": { "type": "ephemeral", "ttl": "1h" } } ], "messages": [ { "role": "user", "content": "Beantworten Sie die Frage anhand des obigen Inhalts." } ] }' ``` Unterstützte TTL-Werte: | TTL | Bedeutung | | ---- | ---------------------------------------------------------------------------------------------------- | | `5m` | 5 Minuten zwischenspeichern; wird verwendet, wenn `ttl` weggelassen wird | | `1h` | 1 Stunde zwischenspeichern; der entsprechende `anthropic-beta`-Header muss ebenfalls gesendet werden | ### Felder zur Nutzung in der Antwort Die Claude Messages API gibt gewöhnliche Eingabe-, Cache-Schreib- und Cache-Lese-Token getrennt im Objekt `usage` zurück: ```json theme={null} { "usage": { "input_tokens": 23, "cache_creation_input_tokens": 2619, "cache_read_input_tokens": 0, "cache_creation": { "ephemeral_5m_input_tokens": 2619, "ephemeral_1h_input_tokens": 0 }, "output_tokens": 24 } } ``` Die Gesamtzahl der Eingabe-Token wird wie folgt berechnet: ```text theme={null} input_tokens + cache_creation_input_tokens + cache_read_input_tokens ``` Diese drei Werte überschneiden sich nicht. Bei der ersten Anfrage ist in der Regel `cache_creation_input_tokens > 0`; wenn Sie denselben stabilen Präfix erneut senden, sollte `cache_read_input_tokens > 0` sein. ## OpenAI-kompatible API ### Anfragebeispiel Bei der Verwendung des Caches über `/v1/chat/completions` wird `cache_control` ähnlich wie bei der Claude Messages API angegeben: ```bash theme={null} curl "https://api.apimart.ai/v1/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 1024, "messages": [ { "role": "system", "content": [ { "type": "text", "text": "Fügen Sie hier den langen Präfix ein, der wiederverwendet werden soll...", "cache_control": { "type": "ephemeral" } } ] }, { "role": "user", "content": "Beantworten Sie die Frage anhand des obigen Inhalts." } ] }' ``` ### 1-Stunden-Cache Das OpenAI-kompatible Format unterstützt ebenfalls einen 1-Stunden-Cache. Fügen Sie einfach den Anfrage-Header `anthropic-beta` hinzu und setzen Sie in `cache_control` den Wert `ttl: "1h"`: ```bash theme={null} -H "anthropic-beta: extended-cache-ttl-2025-04-11" ``` ```json theme={null} "cache_control": { "type": "ephemeral", "ttl": "1h" } ``` ### `content` muss ein Array sein Im OpenAI-kompatiblen Format muss `cache_control` innerhalb eines konkreten Inhaltsblocks stehen. Es kann nicht an eine Nachricht mit String-Inhalt angehängt werden. ```json theme={null} { "role": "system", "content": "Fügen Sie hier den langen Präfix ein...", "cache_control": { "type": "ephemeral" } } ``` Die obige Schreibweise aktiviert den Cache nicht, führt aber auch nicht zu einem Anfragefehler. Die korrekte Schreibweise lautet: ```json theme={null} { "role": "system", "content": [ { "type": "text", "text": "Fügen Sie hier den langen Präfix ein...", "cache_control": { "type": "ephemeral" } } ] } ``` Wenn `content` als String angegeben wird, wird die Cache-Markierung ignoriert und der Eingabeinhalt weiterhin als gewöhnliche Eingabe verarbeitet. Prüfen Sie anhand der Cache-Nutzungsfelder in der Antwort, ob der Cache getroffen wurde. ### `user`- oder `assistant`-Inhaltsblöcke zwischenspeichern Sie können `cache_control` auch in einem Inhaltsblock einer `user`- oder `assistant`-Nachricht platzieren, um lange Dokumente oder einen Präfix aus mehreren Dialogrunden zwischenzuspeichern: ```json theme={null} { "role": "user", "content": [ { "type": "text", "text": "Fügen Sie hier das lange Dokument ein, das wiederverwendet werden soll...", "cache_control": { "type": "ephemeral" } }, { "type": "text", "text": "Fassen Sie die drei wichtigsten Punkte des obigen Dokuments zusammen." } ] } ``` Teilen Sie den stabilen Inhalt und die aktuelle Frage in unterschiedliche Inhaltsblöcke auf und fügen Sie `cache_control` nur dem stabilen Inhaltsblock hinzu. ### Felder zur Nutzung in der Antwort Das OpenAI-kompatible Format meldet die Cache-Nutzung über andere Felder: ```json theme={null} { "usage": { "prompt_tokens": 1942, "completion_tokens": 22, "prompt_tokens_details": { "cached_tokens": 1921, "cache_write_tokens": 0 }, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0 } } ``` Feldzuordnung: | Bedeutung | Claude Messages API | OpenAI-kompatible API | | ------------------------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | Gesamteingabe | Summe der drei Eingabefelder | `prompt_tokens` | | Cache-Lesevorgang | `cache_read_input_tokens` | `prompt_tokens_details.cached_tokens` | | Allgemeines Feld für Cache-Schreibvorgänge | `cache_creation_input_tokens` | `prompt_tokens_details.cache_write_tokens` (nur belegt, wenn keine TTL-Aufschlüsselung vorhanden ist) | | Schreibvorgang in den 5-Minuten-Cache | `cache_creation.ephemeral_5m_input_tokens` | `claude_cache_creation_5_m_tokens` | | Schreibvorgang in den 1-Stunden-Cache | `cache_creation.ephemeral_1h_input_tokens` | `claude_cache_creation_1_h_tokens` | | Ausgabe | `output_tokens` | `completion_tokens` | Wenn `prompt_tokens_details.cache_write_tokens` den Wert `0` hat, prüfen Sie trotzdem `claude_cache_creation_5_m_tokens` und `claude_cache_creation_1_h_tokens`. Wenn Felder mit TTL-Aufschlüsselung vorhanden sind, wird die Cache-Schreibmenge über das entsprechende Feld zurückgegeben. In `claude_cache_creation_5_m_tokens` und `claude_cache_creation_1_h_tokens` stehen Unterstriche zwischen der Zahl und der Einheit. Verwenden Sie die Feldnamen genau so, wie sie in der Antwort zurückgegeben werden. Die OpenAI-kompatible API kann auch dann eine SSE-Streaming-Antwort zurückgeben, wenn Sie `stream: true` nicht ausdrücklich übergeben. Der Client sollte `chat.completion.chunk` verarbeiten können. Die Nutzung steht im letzten Datenblock, der `usage` enthält. ## Bedingungen für einen Cache-Treffer ### Der Präfix erreicht die Mindestlänge Der Cache-Präfix des Beispielmodells muss in der Regel mindestens etwa 1024 Token umfassen. Bei einem kürzeren Präfix kann die Cache-Markierung ohne Fehlermeldung ignoriert werden. ### Der Präfix bleibt bytegenau identisch Text, Leerzeichen, Zeilenumbrüche und die Reihenfolge der Inhaltsblöcke im Cache-Präfix müssen unverändert bleiben. Fügen Sie dem stabilen Präfix keine dynamischen Inhalte wie Zeitstempel, zufällige IDs oder Anfragezähler hinzu. ### Die Anfrage hat keine Modellablehnung ausgelöst Wenn die Anfrage eine Modellablehnung auslöst, kann die Antwort dennoch Cache-Erstellungs-Token melden, der Cache wird bei der nächsten Anfrage jedoch nicht gelesen. Prüfen Sie bei der Fehlersuche nach ausbleibenden Cache-Treffern auch, ob `stop_reason` den Wert `refusal` hat. ### Der Cache ist noch gültig Die Cache-Gültigkeitsdauer beträgt 5 Minuten oder 1 Stunde und wird ab dem letzten Zugriff berechnet. Ein Cache-Treffer erneuert die Gültigkeitsdauer. ## Abrechnungsnutzung Die Cache-bezogene Nutzung wird in drei Kategorien unterteilt: | Nutzung | Zeitpunkt | | -------------------- | ----------------------------------------------- | | Cache-Schreibvorgang | Bei der ersten Cache-Erstellung | | Cache-Lesevorgang | Wenn eine nachfolgende Anfrage den Cache trifft | | Gewöhnliche Eingabe | Eingabe außerhalb des Cache-Präfixes | Die drei Nutzungskategorien überschneiden sich nicht. Cache-Schreibvorgänge kosten in der Regel mehr als gewöhnliche Eingaben, während Cache-Lesevorgänge in der Regel weniger kosten. Context Cache eignet sich daher besonders für stabile Präfixe, die innerhalb der TTL wiederverwendet werden. ## Minimales reproduzierbares Beispiel Das folgende Skript erzeugt zunächst einen ausreichend langen stabilen Präfix und sendet anschließend dieselbe Anfrage zweimal. In der zweiten Antwort sollte `cache_read_input_tokens > 0` erscheinen. ```bash theme={null} python3 - <<'PY' > /tmp/claude-cache-request.json import json paragraph = ( "Prompt caching stores a prefix of the request so that later requests " "can reuse the same byte-identical prefix without processing it again. " ) system_text = ( "You are a documentation assistant. Reference material follows.\n\n" + paragraph * 40 ) print(json.dumps({ "model": "claude-sonnet-5", "max_tokens": 32, "system": [{ "type": "text", "text": system_text, "cache_control": {"type": "ephemeral"} }], "messages": [{ "role": "user", "content": "In one sentence, what must remain unchanged?" }] })) PY for request_number in 1 2; do echo "Anfrage ${request_number}" curl -s "https://api.apimart.ai/v1/messages" \ -H "x-api-key: $API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ --data @/tmp/claude-cache-request.json \ | python3 -c "import json, sys; print(json.load(sys.stdin)['usage'])" done ``` Erwartetes Ergebnis: ```text theme={null} Anfrage 1: cache_creation_input_tokens > 0, cache_read_input_tokens = 0 Anfrage 2: cache_creation_input_tokens = 0, cache_read_input_tokens > 0 ``` ## Checkliste zur Fehlerbehebung Wenn der Cache nicht getroffen wird, prüfen Sie die folgenden Punkte in dieser Reihenfolge: * Hat `stop_reason` den Wert `refusal`? * Erreicht der Cache-Präfix die für das Modell erforderliche Mindestanzahl an Token? * Sind die stabilen Präfixe der beiden Anfragen bytegenau identisch? * Ist `content` im OpenAI-kompatiblen Format ein Array? * Befindet sich `cache_control` in einem konkreten Inhaltsblock? * Sind für einen 1-Stunden-Cache sowohl `ttl: "1h"` als auch der entsprechende `anthropic-beta`-Header festgelegt? * Ist die TTL des Caches bereits abgelaufen? * Lesen Sie die Cache-Nutzungsfelder der verwendeten API aus?