Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Diagnose für das Prompt-Caching

Vergleiche Antworten, um herauszufinden, warum ein Prompt-Präfix nicht wiederverwendet wurde.

Mit der Diagnose für das Prompt-Caching kannst du herausfinden, warum bei einer Anfrage weniger Token als erwartet wiederverwendet wurden. Vergleiche die Anfrage mit einer früheren Antwort, um festzustellen, welche Änderungen am Modell, an den Tools, an den Einstellungen oder an der Eingabe die Wiederverwendung verhindert haben.

Die Diagnose ist in der Responses API für GPT-5.6 und neuere unterstützte Modelle verfügbar. Untersuche damit einzelne Anfragen. Im Dashboard für Prompt-Caching kannst du die Cache-Leistung für deine gesamte Anwendung überwachen.

So funktioniert der Vergleich

Die Diagnose für das Prompt-Caching vergleicht deine aktuelle Anfrage mit einer früheren Antwort. So kannst du nachvollziehen, warum ein Prompt-Präfix entgegen deiner Erwartung nicht wiederverwendet wurde. Ein Präfix ist der Inhalt am Anfang eines Prompts. Damit es wiederverwendet werden kann, muss es exakt übereinstimmen. Auch die Einstellungen der Anfragen müssen kompatibel sein, etwa das Modell, die Servicestufe und die Tools.

  1. Wähle eine Referenzantwort aus. Verwende eine kürzlich abgeschlossene Antwort aus derselben Organisation. Wähle eine Antwort, deren Präfix die aktuelle Anfrage voraussichtlich wiederverwendet, etwa die Antwort aus der vorherigen Gesprächsrunde.
  2. Fordere einen Vergleich an. Setze prompt_cache_options.comparison_response_id auf die id der Referenzantwort.
  3. Prüfe das Ergebnis. Lies prompt_cache_diagnostics in der aktuellen Antwort aus. Erkennt die Diagnose einen Cache-Miss, enthält das Ergebnis einen Grund, dem du nachgehen kannst. Mit usage.input_tokens_details.cached_tokens misst du, wie viele Token tatsächlich wiederverwendet wurden.

Mit comparison_response_id forderst du lediglich die Diagnose an. Dadurch wird weder die frühere Unterhaltung geladen noch das Caching-Verhalten geändert. Für die aktuelle Anfrage können weiterhin passende Cache-Einträge aus anderen Anfragen wiederverwendet werden.

Anwendungsbeispiel

Das folgende Beispiel sendet zwei Anfragen mit demselben Modell, denselben Anweisungen und derselben Eingabe. Der Name eines Funktionstools ändert sich dabei von get_time zu get_date. Die zweite Anfrage nutzt die erste als Referenz, um die Wiederverwendung von Token aus dem Cache zu prüfen.

Speichere deine eigenen Richtlinien in support-policy.txt. Das wiederverwendbare Präfix muss die Mindestlänge für das Caching des Modells erreichen. Bei GPT-5.6 und neueren Modellen sind das 1.024 Token.

Wiederverwendung von Token beim Prompt-Caching zwischen Antworten vergleichen
from pathlib import Path

from openai import OpenAI

client = OpenAI()
policy = Path("support-policy.txt").read_text()  # At least 1,024 tokens.

first = client.responses.create(
    model="gpt-6-astra",
    instructions=policy,
    input="Reply with exactly OK.",
    tools=[{"type": "function", "name": "get_time"}],
)

second = client.responses.create(
    model="gpt-6-astra",
    instructions=policy,
    input="Reply with exactly OK.",
    tools=[{"type": "function", "name": "get_date"}],
    prompt_cache_options={"comparison_response_id": first.id},
)

diagnostics = second.prompt_cache_diagnostics
if diagnostics is not None and diagnostics.type == "cache_miss":
    print(diagnostics.reason)
    print(diagnostics.comparison_reusable_tokens)
    print(diagnostics.cache_missed_tokens)

Wenn der geänderte Toolname einen Cache-Miss verursacht, kann das Ergebnis wie folgt aussehen. Die Anzahl der Token hängt von der Eingabe ab.

{
  "prompt_cache_diagnostics": {
    "type": "cache_miss",
    "reason": "tools_changed",
    "comparison_reusable_tokens": 5629,
    "cache_missed_tokens": 5629
  }
}

Damit das Präfix wiederverwendet werden kann, behalte die Tooldefinitionen und ihre Reihenfolge bei allen Anfragen bei. Siehe Tools verwalten, indem du neue Tools nur am Ende hinzufügst.

Unterhaltungen mit mehreren Gesprächsrunden

Um aufeinanderfolgende Gesprächsrunden zu vergleichen, speichere die id jeder abgeschlossenen Antwort. Übergib sie bei der nächsten Anfrage als comparison_response_id in prompt_cache_options. Lass die Vergleichs-ID in der ersten Runde weg.

Wenn du eine Korrektur testest, verwende weiterhin die ID der Referenzantwort für den Vergleich.

Streaming

Wenn stream=True gesetzt ist, lies prompt_cache_diagnostics aus event.response im Ereignis response.completed aus.

Die Antwort auswerten

Lies prompt_cache_diagnostics.type aus, um das Ergebnis des Vergleichs zu ermitteln.

Typ Bedeutung Nächster Schritt
cache_hit Beim Vergleich wurde kein Cache-Miss erkannt. Prüfe usage.input_tokens_details.cached_tokens, um die tatsächliche Anzahl wiederverwendeter Token zu ermitteln.
cache_miss Ein Unterschied hat die Wiederverwendung des erwarteten Präfixes verhindert. Das Ergebnis enthält reason und cache_missed_tokens. Es kann auch comparison_reusable_tokens enthalten. Die Ursache und einen Lösungsvorschlag findest du im Abschnitt Cache-Misses beheben.
comparison_response_not_found Für die Referenzantwort ist kein nutzbarer Diagnosedatensatz verfügbar. Möglicherweise fehlt er oder ist abgelaufen. Wähle eine andere kürzlich abgeschlossene Antwort aus derselben Organisation.
unavailable Der Vergleich hat kein eindeutiges Ergebnis geliefert oder das Modell unterstützt die Diagnose nicht. Prüfe, ob das Modell die Diagnose unterstützt, und versuche es mit einer anderen aktuellen Referenzantwort. Du kannst die Antwort weiterhin wie gewohnt verwenden.

Tokenzahlen interpretieren

cache_hit bedeutet, dass beim Vergleich kein Cache-Miss erkannt wurde. Neue Eingaben müssen gegebenenfalls trotzdem verarbeitet werden. Beispielsweise kann eine Anfrage mit 2.500 Eingabetoken cache_hit melden, wenn das Präfix der Referenzantwort mit 2.000 Token wiederverwendet wird und 500 neue Token verarbeitet werden.

Bei einem cache_miss gilt:

  • comparison_reusable_tokens gibt, sofern vorhanden, die unbereinigte Anzahl der Token im wiederverwendbaren Präfix der Referenzantwort an.
  • cache_missed_tokens gibt an, wie viele dieser Token schätzungsweise nicht wiederverwendet wurden.

Diese Diagnosewerte können von den Nutzungswerten abweichen. Verwende die Nutzungsfelder der aktuellen Antwort, um die gemeldete Cache-Nutzung und die abgerechnete Nutzung zu ermitteln.

Cache-Misses beheben

Schlage den Wert von prompt_cache_diagnostics.reason in der folgenden Tabelle nach. Dort findest du die Ursache des Cache-Misses und einen Lösungsvorschlag.

Manche Änderungen sind beabsichtigt, etwa ein Modellwechsel oder die Kontextverdichtung in einer Unterhaltung. Du kannst sie beibehalten, auch wenn dadurch weniger Token wiederverwendet werden.

Grund Was hat sich geändert? So verbesserst du die Wiederverwendung
model_changed Ein anderes Modell hat die Anfrage verarbeitet, etwa aufgrund des Routings, eines A/B-Tests oder eines Fallbacks. Prüfe, ob die Modellauswahl zu unbeabsichtigten Wechseln führt. Verwende dasselbe Modell für Anfragen, die ein gemeinsames Präfix aus dem Cache nutzen sollen. Siehe Einstellungen, die das Präfix im Cache beeinflussen.
prompt_cache_key_changed Der angegebene Schlüssel hat sich zwischen den Anfragen geändert. In den Nutzungsdaten der Antwort (usage) kann dies als Cache-Miss erscheinen, auch wenn im Cache selbst kein Miss aufgetreten ist. Lass prompt_cache_key weg, sofern deine Anwendung die Cache-Nutzung nicht für einzelne Kunden- oder Nutzerkonten getrennt erfassen muss. Wenn du Schlüssel verwendest, behalte innerhalb jeder Gruppe denselben Schlüssel bei. Siehe Cache-Nutzung mit Schlüsseln getrennt erfassen.
service_tier_changed Für die Verarbeitung der Anfrage wurde eine andere Servicestufe verwendet. Verwende für Anfragen, die ein gemeinsames Präfix nutzen sollen, dieselbe Servicestufe. Prüfe den zurückgegebenen Wert von service_tier. Er kann vom angeforderten Wert abweichen. Die unterstützten Werte und ihre Auswirkungen findest du in der Referenz zu service_tier.
tools_changed Tools wurden hinzugefügt, entfernt oder umsortiert. Auch Änderungen an ihren Beschreibungen, Schemas oder Einstellungen können die Ursache sein. Behalte die Tooldefinitionen und ihre Reihenfolge bei. Mit tool_choice: "none" deaktivierst du die Tools. Mit allowed_tools legst du fest, welche Tools ausgeführt werden dürfen, ohne die übergebene Toolliste zu ändern. Siehe Tools verwalten, indem du neue Tools nur am Ende hinzufügst.
text_format_changed Das Ausgabeformat oder das zugehörige Schema hat sich geändert. Behalte bei unterstützten Modellen ab GPT-6 den Wert von text.format auf der obersten Ebene bei. Wenn du ein anderes Schema brauchst, hänge eine Formataktualisierung an.
reasoning_effort_changed Der Reasoning-Aufwand hat sich geändert. Bei unterstützten Modellen ab GPT-6 kannst du ein Eingabeelement vom Typ configuration_update anhängen, um den Reasoning-Aufwand während einer Unterhaltung zu ändern. Das bisherige Präfix bleibt dabei im Cache erhalten.
Verwende bei älteren Modellen denselben Wert für reasoning.effort, wenn Anfragen ein gemeinsames Präfix nutzen sollen.
verbosity_changed Der Detailgrad der Antwort hat sich geändert. Verwende denselben Wert für text.verbosity bei Anfragen, die ein gemeinsames Präfix nutzen sollen. Siehe Einstellungen, die das Präfix im Cache beeinflussen.
context_compacted Die Kontextverdichtung hat frühere Inhalte der Unterhaltung ersetzt. Behalte gleichbleibende Anweisungen bei und nutze den verdichteten Kontext als Grundlage für die nächsten Gesprächsrunden. Vergleiche die Gesamtkosten der Eingabe. Weniger Eingabetoken können die Kosten senken, selbst wenn weniger Token aus dem Cache wiederverwendet werden. Siehe Kontextverdichtung.
input_changed Frühere Eingaben haben sich geändert, etwa weil die Anweisungen einen Zeitstempel oder eine Anfrage-ID enthalten oder weil frühere Nachrichten bearbeitet, umsortiert oder entfernt wurden. Platziere veränderliche Inhalte hinter dem wiederverwendbaren Präfix und seinem Cache-Breakpoint. Behalte frühere Nachrichten und Toolergebnisse bei und hänge neue Gesprächsrunden an. Siehe Gesprächsverlauf beibehalten.

Die Verbesserung überprüfen

Gehe nach einer Änderung wie folgt vor:

  1. Sende eine weitere repräsentative Anfrage und vergleiche sie mit der vorgesehenen Referenzantwort.
  2. Prüfe im Diagnoseergebnis, ob noch ein Unterschied vorliegt.
  3. Vergleiche cached_tokens, cache_write_tokens und die Gesamtkosten über mehrere Anfragen hinweg.

Nutzungsmetriken und Kostenberechnungen findest du im Abschnitt Cache-Leistung überwachen.

Preise und Ratenlimits

Für die Diagnose beim Prompt-Caching fallen keine zusätzlichen Kosten an. Sie wird auch nicht gesondert auf die Ratenlimits angerechnet. Zusätzliche Anfragen an die Responses API, mit denen du eine Referenzantwort erzeugst oder einen Versuch wiederholst, werden wie üblich abgerechnet und auf die Ratenlimits angerechnet.

Keine Datenaufbewahrung

Die Diagnose für das Prompt-Caching ist mit der Einstellung „Keine Datenaufbewahrung“ kompatibel. OpenAI speichert für diese Funktion weder Prompts im Rohformat noch Modellergebnisse. Diagnosedatensätze enthalten Metadaten zur Konfiguration, Schätzwerte für die Tokenanzahl und Hashwerte zum Vergleich von Inhalten, die für das Caching relevant sind. Diese Datensätze sind auf die jeweilige Organisation beschränkt, laufen nach kurzer Zeit ab und dienen ausschließlich dazu, Cache-Treffer oder Cache-Misses beim Prompt-Caching zu erklären.

Wenn du comparison_response_id setzt, wird der Inhalt der früheren Antwort weder abgerufen noch dauerhaft gespeichert. Informationen zu den Einstellungen für den Umgang mit Daten bei OpenAI findest du im Abschnitt Deine Daten.

Einschränkungen

  • Die Diagnose ist in der Responses API für GPT-5.6 und neuere unterstützte Modelle verfügbar.
  • Diagnosedatensätze laufen nach kurzer Zeit ab. Ist ein Datensatz abgelaufen, liefert der Vergleich comparison_response_not_found, selbst wenn die Antwort weiterhin über die API abrufbar ist.
  • Die Diagnose meldet die erste Ursache, die sie zuordnen kann. Behebe diese Ursache und wiederhole den Vergleich, um weitere Ursachen zu erkennen.
  • Die Diagnose versucht, Cache-Misses zu klassifizieren, kann aber nicht jeden Fall zuordnen. Das Ergebnis unavailable gibt weder einen Treffer noch einen Cache-Miss an. Du erhältst es auch, wenn der Vergleich noch nicht bereit ist.
  • Die Diagnose blockiert deine Anfrage nie, lässt sie nicht fehlschlagen und hat keinen Einfluss darauf, wie das Modell seine Ausgabe generiert.