Prompt-Caching & Kostenoptimierung

Experte

Wenn viele deiner Anfragen einen großen, unveränderlichen Block teilen — einen langen System-Prompt, ein großes Dokument, einen Tool-Katalog — ermöglicht Prompt-Caching der API, den bereits verarbeiteten Präfix wiederzuverwenden, statt ihn bei jedem Aufruf erneut einzulesen. Das senkt sowohl Kosten als auch Latenz beim gecachten Teil.

What you'll learn

Das mentale Modell: ein Cache-Breakpoint nach einem stabilen Präfix, über Aufrufe hinweg wiederverwendet
Wie man den Breakpoint in Python und TypeScript mit cache_control markiert
Die eine Invariante, an der es steht oder fällt — der Präfix muss Byte für Byte identisch sein
Wie man die usage-Felder liest, um zu bestätigen, dass man wirklich Cache-Treffer erzielt
Wo sich Caching am meisten lohnt und wie man es mit Batching und der richtigen Modelldimensionierung kombiniert

Wie es funktioniert (das mentale Modell)

Du markierst einen Cache-Breakpoint nach dem stabilen Präfix. Beim ersten Aufruf wird er verarbeitet und gecacht; nachfolgende Aufrufe, die den exakt gleichen Präfix teilen, treffen den Cache und zahlen dafür deutlich weniger.

Caching-Vokabular

Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.

1 / 4

Den Breakpoint setzen (zum Kopieren)

Füge cache_control zum letzten stabilen Block hinzu — hier ein großer System-Prompt. Der Turn des Nutzers kommt danach und variiert frei; alles bis einschließlich des markierten Blocks wird gecacht.

Guided walkthrough1 of 4

Finde den großen, unveränderlichen Block — einen langen System-Prompt, ein großes Dokument oder einen Tool-Katalog, der über viele Anfragen hinweg wiederverwendet wird.

Python
TypeScript

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LARGE_STABLE_PROMPT,  # long, unchanging — the cached prefix
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Summarize the key points."}],  # varies per call
)

print(message.usage.cache_read_input_tokens)  # > 0 means you got a hit

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: LARGE_STABLE_PROMPT, // long, unchanging — the cached prefix
      cache_control: { type: "ephemeral" },
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points." }], // varies per call
});

console.log(message.usage.cache_read_input_tokens); // > 0 means you got a hit

Der erste Aufruf zahlt einen kleinen Schreib-Aufschlag, um den Cache zu befüllen; jeder spätere Aufruf mit demselben Präfix liest ihn zu einem Bruchteil des Eingabepreises zurück. Der Präfix muss lang genug sein, um in Frage zu kommen — einige tausend Tokens, je nach Modell —, sonst wird er stillschweigend nicht gecacht.

Die Invariante, an der es steht oder fällt

:::warning Caching ist präfix-exakt Ein Cache-Treffer erfordert, dass der gecachte Präfix Byte für Byte identisch ist. Der häufigste Fehler: ein stiller Invalidator nahe dem Anfang des Prompts — ein Zeitstempel, ein wechselnder Benutzername, eine umsortierte Tool-Liste — der den Präfix ändert und deine Trefferquote stillschweigend auf null fallen lässt. :::

Setze alles Stabile zuerst, alles Variable zuletzt und halte den Präfix wirklich konstant.

Prüfen, ob es tatsächlich funktioniert

Verlasse dich nicht auf Annahmen — lies es aus dem usage der Antwort zurück:

cache_creation_input_tokens — Tokens, die bei diesem Aufruf in den Cache geschrieben wurden (die erste Anfrage).
cache_read_input_tokens — Tokens, die aus dem Cache bedient wurden (die Einsparung).
input_tokens — der nicht gecachte Rest, zum vollen Preis abgerechnet.

Wenn cache_read_input_tokens über wiederholte Anfragen hinweg, die einen Präfix teilen sollten, bei null bleibt, ist ein stiller Invalidator am Werk — vergleiche die gerenderten Prompt-Bytes zweier Aufrufe, um ihn zu finden.

Wo es sich am meisten lohnt

Lange System-Prompts, die über Nutzer hinweg wiederverwendet werden.
RAG / Dokument-Q&A, bei dem derselbe Quelltext wiederholt abgefragt wird.
Agenten mit einem festen Tool-Katalog und festen Anweisungen über viele Runden hinweg.

Kombiniere Caching mit Batching für Offline-Workloads und mit der richtigen Dimensionierung des Modells (Ein Modell auswählen) für die größten kombinierten Einsparungen — siehe Kosten & Latenz.

Überprüfe dich selbst

0/3

Was erfordert ein Cache-Treffer vom gecachten Präfix?
Welches usage-Feld sagt dir, dass Tokens aus dem Cache bedient wurden (deine Einsparung)?
Wohin sollte der variable Inhalt pro Aufruf relativ zum Cache-Breakpoint?

Key takeaways

Markiere einen Cache-Breakpoint nach dem stabilen Präfix; der erste Aufruf schreibt ihn, spätere Aufrufe lesen ihn günstig zurück.
Ein Cache-Treffer braucht einen Byte für Byte identischen Präfix — halte stabilen Inhalt zuerst, variablen Inhalt zuletzt.
Stille Invalidatoren nahe dem Anfang des Prompts (Zeitstempel, Namen, umsortierte Tools) lassen die Trefferquote stillschweigend auf null fallen.
Überprüfe es mit usage: cache_read_input_tokens > 0 bedeutet einen Treffer; null über wiederholte Anfragen hinweg bedeutet, dass ein Invalidator am Werk ist.
Caching lohnt sich am meisten für wiederverwendete System-Prompts, RAG und Agenten; kombiniere es mit Batching und der richtigen Modelldimensionierung.

Wie es funktioniert (das mentale Modell)​

Den Breakpoint setzen (zum Kopieren)​

Die Invariante, an der es steht oder fällt​

Prüfen, ob es tatsächlich funktioniert​

Wo es sich am meisten lohnt​