Anmerkung des Autors: Wenn die Trefferquote des Claude-Caches für Eingabeaufforderungen (Prompt-Caching) plötzlich auf 0 fällt oder die Rechnung einfach nicht sinken will, können Sie mit drei diagnostics-Schritten die Stelle finden, an der das Präfix auseinanderläuft, und anhand von usage beurteilen, ob der Cache wirklich getroffen wurde. Dieser Artikel erklärt außerdem, wie Sie bei Nutzung des API-Proxy-Dienstes von APIYI selbst nachprüfen können. (Wenn Sie dieses Problem haben, können Sie diesen Artikel nach dem Lesen an Ihren Agenten weiterleiten und ihn die Ursache untersuchen lassen.)
Ein Cache-Miss ist keine Hexerei: Die API sagt Ihnen, an welchem Segment das Präfix auseinanderläuft. Sie müssen nur die ID der Antwort aus der vorherigen Runde mitschicken, und schon sehen Sie, ob die erste Abweichung in model, system, tools oder messages liegt.
Dies ist kein Beitrag zu einem Feature-Release. Dieser Artikel richtet sich an Entwickler, die das Caching von Eingabeaufforderungen in Claude bereits nutzen, deren Trefferquote aber plötzlich auf null gefallen ist oder deren Rechnung dauerhaft hoch bleibt. Alle Diagnoseschritte sind so beschrieben, dass klar ist, was Sie bei jedem Schritt sehen werden.
Kernnutzen: Nach dem Lesen dieses Artikels können Sie die Ursache für den Cache-Ausfall innerhalb von drei Anfragen eingrenzen. Sie können außerdem unterscheiden, was diagnostics und usage jeweils aussagen, und wissen, welche zwei Felder Sie bei Nutzung eines Proxy-Dienstes miteinander vergleichen müssen.
Kernpunkte der Claude-Cache-Diagnose diagnostics
Kurz in einem Satz: Du übergibst die ID der vorherigen Antwort, die API vergleicht beide Requests und zeigt dir, an welcher Stelle die Wege zum ersten Mal auseinanderlaufen – bei model, system, tools oder messages. Bisher hast du, wenn der Cache still und leise nicht mehr griff, nur gesehen, dass usage.cache_read_input_tokens auf 0 fällt – ohne zu wissen, welcher Abschnitt sich verändert hat.
| Kernpunkt | Erklärung | Dein Nutzen |
|---|---|---|
| Aktivierung | Nur wenn im Request-Body auf oberster Ebene ein diagnostics-Objekt steht, wird ein Fingerabdruck gespeichert |
Keine Änderung an der Geschäftslogik nötig, ein Feld genügt |
| Vergleichsmechanik | previous_message_id bekommt die ID der vorherigen Antwort |
Zeigt direkt den ersten abweichenden Abschnitt |
| Ergebnisfeld | cache_miss_reason liefert einen von sechs Typen |
Jeder Typ zeigt genau, wo du ansetzen musst |
| Zusammenspiel mit Metriken | Muss zusammen mit usage.cache_read_input_tokens gelesen werden |
Damit du „keine Abweichung“ nicht mit „hat nicht gewirkt“ verwechselst |
| Verfügbarkeit | Gibt es nur bei der offiziellen Claude API | Über andere Zugangswege musst du die Selbstprüfung per usage machen |
Die Timeline der Claude-Cache-Diagnose
Das Feature ging im Mai 2026 als Beta an den Start; damals musste der Header anthropic-beta: cache-diagnosis-2026-04-07 mitgeschickt werden. Im Laufe des Septembers wurden die Regeln einmal verschärft: Nur Requests, die explizit ein diagnostics-Objekt enthalten, bekommen einen Fingerabdruck gespeichert – Requests, die lediglich den Header tragen, werden nicht erfasst.
Am 23. September wurde daraus die stabile Version: cache-diagnosis-2026-04-07 ist nicht mehr nötig, und Requests mit dem alten Header funktionieren weiterhin. Inzwischen taucht das Feld diagnostics in jeder Antwort von POST /v1/messages auf; ist die Diagnose nicht aktiviert, steht dort null. Ein null an dieser Stelle heißt also nicht, dass mit dem Endpoint etwas nicht stimmt.
Im Fingerabdruck werden nur Hashes und eine Schätzung der Token-Anzahl gespeichert, nicht der ursprüngliche Inhalt der Eingabeaufforderung. Er ist über die Response-ID indexiert, gilt nur innerhalb der eigenen Organisation und des eigenen Workspace und wird nur kurz aufbewahrt.
In 3 Schritten die Claude-Cache-Trefferquote mit diagnostics analysieren
Die folgenden drei Schritte orientieren sich an der offiziellen Feldbeschreibung. Wenn Sie über APIYI aufrufen, tragen Sie bei der nativen Messages-Schnittstelle als base_url https://api.apiyi.com/v1 ein, der Anfragepfad ist /v1/messages. Beachten Sie jedoch: Der Praxisteil weiter unten zeigt, wie diagnostics im Proxy-Szenario tatsächlich zurückgegeben wird.
Schritt 1: Das diagnostics-Objekt auf oberster Ebene der Anfrage hinzufügen
diagnostics ist der einzige Schalter. Anfragen ohne dieses Feld speichern keinen Fingerabdruck, und später gibt es dann nichts zum Vergleichen. In der ersten Runde existiert noch kein Vergleichsobjekt, daher übergeben Sie für previous_message_id den Wert null – das bedeutet „ab dieser Runde mit der Aufzeichnung beginnen“.
- Im Request-Header die übliche Versionsnummer beibehalten:
anthropic-version: 2023-06-01 - Nach der finalen Version nicht mehr nötig:
anthropic-beta: cache-diagnosis-2026-04-07 - Auf oberster Ebene des Request-Bodys ergänzen:
"diagnostics": {"previous_message_id": null} - Beim system-Block, der gecacht werden soll, wie gewohnt den Breakpoint setzen:
"cache_control": {"type": "ephemeral"} - Was Sie sehen werden: In der Antwort ist
diagnosticsgleichnull,cache_read_input_tokensist in der Regel 0 undcache_creation_input_tokensist größer als 0
Ein null in der ersten Runde bedeutet nicht, dass etwas schiefgelaufen ist. In dieser Runde wird der Cache geschrieben, es gibt also von vornherein keine vorherige Runde zum Vergleichen – hier müssen Sie nichts debuggen.
Schritt 2: Ab der zweiten Runde immer die ID der vorherigen Antwort mitschicken
Ab der zweiten Runde trägst du die id der vorherigen Antwort in previous_message_id ein. Der häufigste Fehler: diagnostics nur in der ersten Runde mitzuschicken und danach zu vergessen. Die Anfrage, auf die die nächste Runde verweist, wurde dann nicht aufgezeichnet, und du bekommst previous_message_not_found zurück.
- Request-Body der zweiten Runde:
"diagnostics": {"previous_message_id": "<id der Antwort aus Runde 1>"} - Request-Body der dritten Runde:
"diagnostics": {"previous_message_id": "<id der Antwort aus Runde 2>"} - Das Muster für die Schleife über mehrere Runden: Runde 1 bekommt
null, Runde 2r1.id, Runde 3r2.idund so weiter - Bei Streaming-Aufrufen erscheint das Ergebnis im
message_start-Event; die ID wird genauso von Runde zu Runde weitergereicht - Was du sehen wirst: Wenn zwei aufeinanderfolgende Runden kurz genug auseinanderliegen und im selben Workspace stattfinden, tauchen in der Antwort erste Vergleichsergebnisse auf
Schritt 3: cache_miss_reason lesen und gezielt beheben
diagnostics hat drei mögliche Ausprägungen – unterscheide sie, bevor du sie liest:
null: Die Anfrage enthielt keindiagnostics; oderprevious_message_idistnull; oder der Vergleich ist abgeschlossen und es wurde keine Abweichung gefunden{"cache_miss_reason": null}: Der Vergleich läuft noch, weil die Antwort zu schnell begonnen hat – in dieser Runde gibt es noch kein Fazit, schau auf die nächstecache_miss_reasonist ein Objekt: Es gibt bereits ein Ergebnis, mit Divergenztyp und Details- Was du sehen wirst: Sobald du den Typ hast, korrigierst du nach der Tabelle im nächsten Abschnitt – und zwar zuerst die früheste Divergenz. Es wird nämlich nur der erste Abweichungspunkt gemeldet; spätere Probleme können dahinter verborgen bleiben
🚀 Schnellstart: Wenn du zuerst prüfen willst, ob sich dein Cache-Prefix überhaupt schreiben und treffen lässt, kannst du bei APIYI apiyi.com mit demselben Key zwischen verschiedenen Claude-Modellen wechseln und zwei Runden vergleichen. Achte vor allem darauf, ob die beiden Zahlen für Cache-Schreiben und Cache-Lesen in
usagezusammenpassen.
Die sechs Typen von cache_miss_reason und wo du sie behebst
Sobald du cache_miss_reason erhalten hast, kannst du anhand der folgenden Tabelle sehen, an welcher Stelle du ansetzen musst:
| Typ | Bedeutung | Wo du ansetzt |
|---|---|---|
model_changed |
Das Modell unterscheidet sich von der vorherigen Runde, zum Beispiel weil Routing, A/B-Tests oder ein Fallback das Modell gewechselt haben. Der Cache ist pro Modell isoliert. | Das Modell innerhalb derselben Cache-Konversation konstant halten |
system_changed |
Der System-Prompt hat sich geändert. Am häufigsten werden Zeitstempel, Request-IDs oder andere Werte eingefügt, die sich bei jedem Aufruf unterscheiden. | Den System-Prompt zu einer byte-stabilen Konstante machen und dynamische Daten in die erste user-Nachricht nach dem Breakpoint verschieben |
tools_changed |
Tools wurden hinzugefügt, entfernt oder in ihrer Reihenfolge geändert, oder die Serialisierung von input_schema ist nicht stabil. |
In jeder Runde dieselbe Tool-Liste senden, die Reihenfolge festhalten und bei der Serialisierung nach Schlüsseln sortieren |
messages_changed |
Frühere Nachrichten wurden geändert, neu angeordnet oder gelöscht, statt am Ende anzuhängen. | Die Historie nur anhängen und Assistant-Inhalte sowie Tool-Ergebnisse unverändert zurücksenden |
previous_message_not_found |
Der passende Fingerabdruck wurde nicht gefunden. Das bedeutet nicht, dass sich die Anfrage geändert hat. | In jeder Runde diagnostics mitgeben, nicht workspace-übergreifend arbeiten und die Abstände nicht zu groß werden lassen |
unavailable |
In dieser Runde sind keine Diagnoseergebnisse verfügbar, zum Beispiel weil tool_choice, thinking, context_management, output_config, output_format oder die Menge der Beta-Header nicht übereinstimmen. Auch eine zu lange Konversation kann die Ursache sein. |
Diese Parameter über den gesamten Lebenszyklus einer Cache-Konversation unverändert lassen |
Die vier *_changed-Typen enthalten zusätzlich cache_missed_input_tokens. Dieser Wert gibt an, wie viele cachefähige Eingabe-Tokens nach dem Abzweigpunkt ungefähr verloren gegangen sind. Der Wert wird anhand der Byte-Länge umgerechnet, dient nur zur Einschätzung der Größenordnung und ist keine Abrechnungszahl. Gelegentlich kann er sogar größer als usage.input_tokens sein.
Nur diagnostics reicht nicht: Claude-Cache-Treffer mit usage richtig beurteilen
diagnostics beantwortet die Frage „Hat sich meine Anfrage geändert?“, usage.cache_read_input_tokens beantwortet „Gab es einen Cache-Treffer?“. Das sind zwei verschiedene Fragen – betrachtet man nur eine davon, kommt man leicht zu einem falschen Schluss.
| diagnostics-Ergebnis | Cache-Lese-Tokens | Schlussfolgerung | Vorgehen |
|---|---|---|---|
null |
hoch | Präfix stabil, Cache-Treffer | nichts tun |
null |
niedrig oder 0 | Anfrage unverändert, aber Cache abgelaufen | Anfrageintervall verkürzen oder auf TTL von 1 Stunde umstellen |
*_changed |
niedrig | Anfrage geändert, daher kein Treffer | nach der Vergleichstabelle im vorherigen Abschnitt beheben |
*_changed |
hoch | Änderung liegt weiter hinten, frühere Breakpoints treffen weiterhin | Behebung lohnt sich, die Auswirkung ist aber geringer |
Noch einmal betont: null bedeutet nicht, dass es nicht wirkt – es kann sogar das beste Ergebnis sein. Es gibt außerdem einige Fälle, in denen diese Tabelle nicht gilt: der erste Durchlauf, cache_miss_reason ist null (der Vergleich läuft noch), sowie previous_message_not_found und unavailable. In diesen Fällen kommt gar kein gültiger Vergleich zustande.
Wenn Sie noch nicht sicher sind, welche Runde in welche Zelle gehört, können Sie dieselbe Anfrage bei APIYI auf apiyi.com zweimal hintereinander senden, die Cache-Lese- und Cache-Schreibwerte für jede Runde notieren und dann Punkt für Punkt mit der obigen Matrix abgleichen.
Häufige Gründe für niedrige Cache-Trefferquoten bei Claude: drei harte Bedingungen
Oft liegt eine niedrige Trefferquote nicht daran, dass sich die Anfrage geändert hat, sondern daran, dass der Cache von Anfang an nicht geschrieben wurde. Fehlt eine der folgenden drei Bedingungen, wird der Cache nicht wirksam:
cache_controlmuss explizit gesetzt werden: Entweder auf einem konkreten Inhaltsblock als expliziter Breakpoint oder auf der obersten Ebene der Anfrage, wobei das System den Breakpoint automatisch auf den letzten cachefähigen Block setzt. Wenncontentein reiner String ist und es keinen Inhaltsblock gibt, an dem die Markierung hängen kann, wird nie gecacht.- Die Länge muss die minimale cachefähige Länge erreichen: Bei der Claude API sind das sowohl für Sonnet 5.5 als auch für Opus 5.5 512 Tokens. Ist das Präfix zu kurz, wird der Cache stillschweigend ignoriert, ohne Fehlermeldung.
- Das Präfix muss bytegenau identisch sein: Die Historie wird nur angehängt,
systemundtoolsbleiben stabil. Sobald sich Leerzeichen, die Reihenfolge der JSON-Felder oder ein Zeitstempel ändern, gilt das als neues Präfix.
Die Cache-Dokumentation von APIYI nennt außerdem zwei harte Limits: Maximal 4 cache_control-Breakpoints pro Anfrage, und jeder Breakpoint greift nur auf die letzten 20 Content-Blöcke zurück. Bei langen mehrstufigen Dialogen deckt eine Markierung nur am letzten Eintrag nicht die gesamte Historie ab.
Auch die TTL wird oft übersehen. Standard sind 5 Minuten, und jeder Treffer verlängert sie. Die Zeitmessung beginnt jedoch mit der Anfrage, die schreibt oder liest, nicht mit dem Ende der Antwort. Wenn eine Streaming-Antwort 4 Minuten lang läuft, muss die nächste Anfrage innerhalb von etwa 1 Minute gesendet werden. Wird ein längeres Zeitfenster benötigt, kann in cache_control "ttl": "1h" angegeben werden.
Was es kostet, wenn die Claude-Cache-Trefferquote auf 0 fällt
Zuerst die Preise, in US-Dollar pro Million Tokens. Preisstand: 25.10.2026. Maßgeblich sind die Live-Preise in der Konsole:
| Modell | Eingabe | Ausgabe | Cache-Lesen | Cache-Schreiben (5 Min.) | Cache-Schreiben (1 Std.) |
|---|---|---|---|---|---|
| Claude Sonnet 5.5 | $2 | $10 | $0,10 | $2,50 | $4 |
| Claude Opus 5.5 | $4 | $20 | $0,20 | $5 | $8 |
| Claude Haiku 5.5 (bis 100.000 Tokens) | $0,10 | $0,50 | $0,01 | $0,125 | $0,20 |
| Claude Haiku 5.5 (über 100.000 Tokens) | $0,50 | $2,50 | $0,05 | $0,625 | $1 |
Die Faktoren müssen getrennt betrachtet werden. Der Cache-Leitfaden von APIYI nennt als allgemeine Faustregel: 0,1× bei Treffern, 1,25× beim Schreiben mit 5-Minuten-TTL und 2× beim Schreiben mit 1-Stunden-TTL. Bei Sonnet 5.5 wurde am 7. Oktober im Zuge der offiziellen Preisanpassung der Cache-Lesepreis von $0,20 auf $0,10 gesenkt; er liegt damit beim 0,05-Fachen des Basis-Eingabepreises. Der Schreibpreis blieb unverändert.
Diese Anpassung ist keine flächendeckende Preissenkung: Bei Sonnet 5 kostet das Cache-Lesen weiterhin $0,20. Rechnen Sie bei Sonnet 5.5 also nicht mit 0,1×; maßgeblich sind das jeweilige Modell und der Preis in der Modellliste der Plattform.
Der Break-even-Punkt berechnet sich nach der allgemeinen 0,1×-Faustregel der Plattform: Bei 5-Minuten-TTL reichen zwei Nutzungen, um die Kosten wieder hereinzuholen (1,25 + 0,1 = 1,35, weniger als 2,0 ohne Cache). Bei 1-Stunden-TTL sind drei Nutzungen nötig (2 + 0,2 = 2,2, weniger als 3,0).
Ein Rechenbeispiel: Sonnet 5.5, festes Präfix von 30.000 Tokens, 200 Anfragen pro Tag, alle innerhalb der 5-Minuten-TTL:
- Alle Treffer: 200 × 30.000 × $0,10/Million = $0,60, plus ein Schreibvorgang für $0,075, zusammen etwa $0,675/Tag
- Keine Treffer: 200 × 30.000 × $2/Million = $12/Tag
Die Tagesabrechnung unterscheidet sich um den Faktor 17,8. Das liegt nicht am Preis pro Token. Der Preis pro Token liegt bei $2 gegenüber $0,10 – ein Faktor von 20. Mit 1-Stunden-TTL kostet ein Schreibvorgang $0,12; der Trefferpreis bleibt gleich. Wenn zwischen den Anfragen häufig mehr als 5 Minuten liegen, lohnt sich der Vergleich: Sind die zusätzlichen Schreibkosten niedriger als die Kosten für den wiederholten Neuaufbau des Präfixes?
So prüfen Sie die Claude-Cache-Trefferrate bei APIYI
Zuerst die Messergebnisse. Am 26.10.2026 haben wir auf APIYI mit Claude Sonnet 5.5 zwei Runden getestet: In der ersten Runde gab es Cache-Write 2523 und Cache-Read 0; nachdem wir die zweite Runde unverändert zurückgeschickt hatten, gab es Cache-Read 2523 und Cache-Write 0 – die Token-Zahlen stimmten exakt überein. Auch Claude Opus 5.5 konnte mit einem langen Präfix Cache-Writes erzeugen und Cache-Hits erzielen.
In der Antwort fehlt jedoch das Feld diagnostics. Weder bei nicht gestreamten Aufrufen noch im message_start gestreamter Aufrufe ist es vorhanden. Wir haben die Anfrage noch einmal mit einem Beta-Header gesendet und außerdem absichtlich das system geändert, um einen echten Cache-Miss zu erzeugen (Read 0, Write 2526). Das Feld war weiterhin nicht in der Antwort enthalten. Alle Anfragen gaben 200 zurück, ohne Fehler. Der Upstream-Kanal der Proxy-Ebene ist nicht zwingend die offizielle Claude-API. Daher vergleicht man im Proxy-Szenario vor allem die beiden Felder in usage miteinander.
| Selbstprüfungs-Symptom | Erklärung |
|---|---|
cache_read_input_tokens dieser Runde entspricht exakt cache_creation_input_tokens der vorherigen Runde |
Das Präfix wurde vollständig getroffen |
| Cache-Read dieser Runde ist deutlich kleiner als Cache-Write der vorherigen Runde | Nur ein weiter vorne liegender Abschnitt wurde getroffen; dazwischen hat sich etwas geändert |
| Cache-Write bleibt durchgehend 0 | Keine Markierung gesetzt, Länge reicht nicht aus oder OpenAI-kompatibles Format verwendet |
| In der zweiten Runde wird erneut geschrieben, während Cache-Read 0 ist | Das Präfix hat sich geändert; Zeitstempel, UUID und Serialisierungsreihenfolge prüfen |
Außerdem besonders beachten: Der Cache greift nur bei nativem /v1/messages. Ruft man Claude über das OpenAI-kompatible Format /v1/chat/completions auf, erhält man unabhängig von den übergebenen Parametern keine Cache-Abrechnung.
💡 Tipp zur Fehlersuche: APIYI apiyi.com leitet
cache_controlunverändert an das Upstream weiter und gibt auch die beiden Cache-Felder in der Antwort unverändert zurück. Der Code muss für die Proxy-Ebene nicht zusätzlich angepasst werden. Wenn man „Cache-Read dieser Runde = Cache-Write der vorherigen Runde“ als Log-Alarm einrichtet, lassen sich die meisten manuellen Prüfungen ersetzen.
Grenzen der Claude-Cache-Diagnose diagnostics
diagnostics löst nicht jedes Problem – wer es einsetzt, sollte die Grenzen kennen:
- Es gibt die Funktion nur bei der offiziellen Claude-API; bei Claude über Amazon Bedrock und Google Cloud fehlt sie komplett.
- Fingerabdrücke werden nur kurzzeitig gespeichert. Die Requests müssen also über mehrere Runden hinweg in kurzen Abständen gesendet werden.
- Beide Requests müssen zur selben Organisation und zum selben Workspace gehören – prüfen lässt sich das über den Response-Header
anthropic-workspace-id. - In langen Konversationen kann die Antwort nur
unavailablelauten, wenn die Änderung tief in der Nachrichtenliste verborgen liegt. - Der Mechanismus arbeitet nach dem Best-Effort-Prinzip: Bleibt ein Ergebnis aus, wird der Request weder blockiert noch als fehlgeschlagen gewertet.
Häufige Fragen (FAQ)
F1: Warum ist diagnostics immer null?
Dafür gibt es drei Fälle: Das `diagnostics`-Objekt wurde nicht mitgeschickt; es handelt sich um die erste Runde und `previous_message_id` ist `null`; oder der Vergleich ist abgeschlossen und es gab keine Abweichung. Entscheidend ist der Blick auf die Cache-Werte: Ein hoher Wert bedeutet, dass alles normal läuft, ein Wert von 0 deutet meist auf einen abgelaufenen Cache hin. Läuft der Request über einen Proxy, werden die Felder möglicherweise gar nicht zurückgegeben – dann hilft die Selbstprüfung über `usage`.
F2: Bedeutet previous_message_not_found, dass sich der Request geändert hat?
Nein. Es heißt nur, dass der passende Fingerabdruck nicht gefunden wurde. Drei Ursachen sind typisch: In der vorherigen Runde fehlte `diagnostics`, die vorherige Runde kam aus einem anderen Workspace, oder der Abstand war zu groß. Lösung: In jeder Runde `diagnostics` mitschicken und die Abstände verkürzen.
F3: Kostet die Diagnose extra?
Die offizielle Dokumentation führt keine separate Position „Diagnosekosten“ auf – die Diagnose wird zusammen mit den normalen Messages-Requests abgerechnet. Dass kein Aufpreis erhoben wird, steht dort allerdings auch nicht ausdrücklich. Maßgeblich sind daher Rechnung und Konsole.
F4: Lässt sich diese Diagnose auch über einen Proxy nutzen?
In unseren Tests bei APIYI haben wir das Feld `diagnostics` nicht erhalten, aber die Cache-Schreibvorgänge und -Treffer funktionierten einwandfrei. Man kann also prüfen, ob die gelesenen Tokens dieser Runde exakt den geschriebenen Tokens der vorherigen Runde entsprechen. Wie die Anbindung funktioniert, steht in der Dokumentation zur Cache-Abrechnung von APIYI unter apiyi.com.
F5: Warum wurde trotz cache_control kein einziges Mal in den Cache geschrieben?
Prüfen Sie zuerst drei Punkte: Ist `content` ein reiner String? Erreicht das Präfix 512 Tokens (Sonnet 5.5 und Opus 5.5)? Läuft der Request im OpenAI-kompatiblen Format? Ist einer dieser Punkte nicht erfüllt, wird der Cache stillschweigend übersprungen.
F6: Wenn mehrere Probleme gleichzeitig auftreten – welches sollte zuerst behoben werden?
Zuerst das, was `cache_miss_reason` meldet. Es zeigt nur die früheste Abzweigung an. Ist sie behoben, folgt eine weitere Runde – erst dann werden die Probleme sichtbar, die bisher verdeckt waren. Wer denselben Request bei APIYI unter apiyi.com wiederholt durchspielt, kann die Ursachen relativ schnell der Reihe nach ausschließen.
Claude-Cache-Diagnose: Die wichtigsten Punkte (Key Takeaways)
- Was ist
diagnostics? Übergibst du die ID der vorherigen Antwort, lokalisiert es das erste abzweigende Segment des Präfixes. - Wie aktiviert man es? Auf oberster Ebene
diagnosticsmitgeben, in der ersten Rundenull, danach in jeder Runde. - Was bedeutet
null? In der ersten Runde oder wenn es keine Abweichung gibt, ist es ebenfallsnull– das allein ist noch kein Fehlersignal. - Wie beurteilt man es?
diagnosticsimmer zusammen mitcache_read_input_tokensbetrachten, erst dann lässt sich eine Schlussfolgerung ziehen. - Harte Bedingungen: Explizit markieren, 512 Tokens erreichen, Präfix byte-identisch halten.
- Kostenunterschied: Bei einem 30.000-Token-Präfix und 200 Aufrufen pro Tag unterscheidet sich die Tagesabrechnung um etwa das 17,8-Fache.
- Selbsttest beim Proxy: Bei APIYI apiyi.com prüfen, ob „diese Runde gelesen = letzte Runde geschrieben“ gilt.
Zusammenfassung
Die Fehlersuche bei der Claude-Cache-Trefferrate lässt sich auf drei Dinge reduzieren:
- Abzweigung lokalisieren: In jeder Runde
diagnosticsmitgeben,cache_miss_reasonlesen und zuerst die am frühesten gemeldete Stelle beheben. - Gegenseitig beurteilen:
diagnosticsundusagegemeinsam betrachten –nullheißt nicht, dass es nicht wirkt. - Harte Bedingungen einhalten: Sauber markieren, Länge erreichen, Historie nur anhängen,
systemundtoolsstabil halten.
Wenn deine Aufrufkette keine diagnostics liefert, baue mit den beiden Feldern in usage eine Selbstprüfung auf. Empfohlen: Teste zuerst bei APIYI apiyi.com mit zwei Anfragen die Cache-Lese- und Schreibzahlen, bevor du in die Produktion gehst.
📚 Referenzen
- Offizielle Claude-Dokumentation: Cache-Diagnose: Diagnosefelder, sechs Typen und Entscheidungsmatrix
- Link:
platform.claude.com -
Beschreibung: Die Felder, die Zeitlinie und die Einschränkungen der Diagnostics in diesem Artikel orientieren sich an dieser Dokumentation
-
Offizielle Claude-Dokumentation: Prompt-Caching: Cache-Regeln, TTL, Mindestlänge und Preise
- Link:
platform.claude.com -
Beschreibung: Quelle für die minimal cachebare Länge und die offizielle Preistabelle
-
APIYI-Modellliste: Eingabe-, Ausgabe- und Cache-Lesepreise der einzelnen Claude-Modelle
- Link:
docs.apiyi.com/models -
Beschreibung: Preisdaten aktualisiert am 25.10.2026
-
APIYI-Leitfaden zur Abrechnung von Claude Prompt Caching: Multiplikatoren, Break-even-Punkt und Kriterien zur Selbstprüfung
- Link:
docs.apiyi.com/api-capabilities/claude-prompt-caching - Beschreibung: Grundlage für die Fehlersuche im API-Proxy-Szenario
Autor: APIYI-Technikteam
Technischer Austausch: Kontaktieren Sie uns gerne über die Startseite der APIYI-Website – weitere Materialien finden Sie im Dokumentationszentrum unter docs.apiyi.com
