Qwen4-Prompt-Caching: Agentenkontext wiederverwenden und Cache-Misses prüfen

Cache-Haltepunkt setzen, zwei Anfragen vergleichen und Nutzungsdaten korrekt lesen. Mit lokalem Anfragegenerator und Prüfliste für ausbleibende Cache-Treffer.

Ein wiederverwendbarer Druckstock erzeugt gleichbleibende Abdrücke, während sich ein kleines orangefarbenes Detail verändert.

Wenn ein Agent wiederholt dasselbe Referenzmaterial liest, setzen Sie den unveränderten Kontext vor einen Cache-Haltepunkt und die wechselnde Frage dahinter. Prüfen Sie anschließend die gemeldeten Cache-Lesezugriffe. Ähnliche Prompts und eine schnellere Antwort beweisen noch kein funktionierendes Caching.

Diese Anleitung behandelt die direkte Qwen4-API von QwenCloud, geprüft am 16. November 2026. Sie ergänzt unseren Qwen4-Max-Leitfaden zu Zugang und Migration. Der folgende Anfragegenerator läuft lokal ohne Schlüssel. Wir haben für diesen Artikel keine kostenpflichtigen Cache-Anfragen ausgeführt. Die Beispiele beschreiben daher einen reproduzierbaren Versuch, keine gemessene Ersparnis oder Latenz.

Festlegen, was unverändert bleiben soll

Ein Agent für Supportanalysen erhält beispielsweise immer dasselbe Produkthandbuch, aber in jeder Runde eine andere Kundenfrage. Das Handbuch eignet sich zur Wiederverwendung. Ein Zeitstempel, eine Zufallskennung oder eine wechselnde Frage vor dem Handbuch kann dagegen den Anfrageanfang verändern.

Teilen Sie die Eingabe ausdrücklich in zwei Bereiche:

Unveränderter KontextWechselnde Aufgabe
Freigegebene HandbuchversionAktuelle Kundenfrage
Feste WerkzeugdefinitionenWerkzeugergebnisse der aktuellen Aufgabe
Gleichbleibende Reihenfolge der AnweisungenGewünschte Ausgabe dieser Runde
Festgelegte Serialisierung des DokumentsNeue Belege, die die Analyse verändern

Halten Sie falsche Informationen nicht unverändert, nur um die Trefferquote zu verbessern. Wird das Handbuch aktualisiert, ist ein neuer Präfix sinnvoll. Notieren Sie Dokumentversion und Hash, damit sich ein beabsichtigtes Update von einer versehentlichen Formatänderung unterscheiden lässt.

Der offizielle Qwen4-Cache-Leitfaden nennt mindestens 1.024 Tokens im zwischengespeicherten Präfix, exakte Präfixübereinstimmung innerhalb desselben Benutzerbereichs sowie Unterstützung für Chat Completions, Responses und Anthropic Messages. DashScope unterstützt dieses explizite Qwen4-Caching nicht. Wort- und Zeichenzahlen sind keine exakten Tokenzahlen.

Zwei Anfragen lokal erzeugen

Verwenden Sie ein synthetisches oder nicht sensibles Referenzdokument, das Sie an den gewählten Anbieter senden dürfen. Speichern Sie es als reference.txt und ändern Sie den Inhalt zwischen erster und zweiter Anfrage nicht.

Speichern Sie den folgenden Code als build_cache_requests.py:

import hashlib
import json
from pathlib import Path

reference = Path("reference.txt").read_text(encoding="utf-8")
if not reference.strip():
    raise SystemExit("reference.txt is empty")

questions = [
    "List the three main responsibilities described in the reference.",
    "Which responsibilities in the reference require an explicit approval?"
]
for number, question in enumerate(questions, 1):
    payload = {
        "model": "qwen4-max",
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": reference,
                    "prompt_cache_breakpoint": {"mode": "explicit"}
                },
                {"type": "text", "text": question}
            ]
        }],
        "enable_thinking": False,
        "max_completion_tokens": 1024
    }
    Path(f"request-{number}.json").write_text(
        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
    )
print("Reference SHA256:", hashlib.sha256(reference.encode()).hexdigest())
print("Created two request files; no network requests were sent.")

Führen Sie python3 build_cache_requests.py aus. Prüfen Sie das erzeugte JSON: Erster Inhaltsblock und Haltepunkt müssen exakt gleich sein; nur die Frage im zweiten Block darf sich unterscheiden. Das Skript zählt keine Tokens. Prüfen Sie die Mindestlänge vor einer kostenpflichtigen Anfrage mit der Tokenzählung des Anbieters oder einem etablierten modellspezifischen Tokenizer.

Der Haltepunkt gehört zu einem Inhaltsblock, deshalb ist content ein Array. Das Beispiel verwendet eine Markierung; kombinieren Sie diese nicht mit einer zweiten Cache-Markierungssyntax in derselben Anfrage. Der erste Aufruf soll wiederverwendbaren Kontext anlegen, der zweite ihn lesen. Ob das tatsächlich geschehen ist, entscheiden die Nutzungsdaten der Antwort.

Die Anfragen nacheinander an die richtige Route senden

Richten Sie anhand der offiziellen Schlüsselanleitung einen QwenCloud-Schlüssel für nutzungsabhängige Abrechnung in der gewählten Region ein. Der Befehl verwendet den Chat-Completions-Endpunkt in Singapur. Ofox- und Token-Plan-Schlüssel sind hier nicht beliebig austauschbar.

curl --silent --show-error --fail-with-body --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request-1.json -o response-1.json

Prüfen Sie HTTP-Ergebnis, Antwortinhalt und Nutzung, bevor Sie fortfahren. Sobald der erste Aufruf erfolgreich abgeschlossen ist, wiederholen Sie den Befehl mit request-2.json und response-2.json. Bleiben Sie innerhalb der dokumentierten Cache-Gültigkeit. Senden Sie beide Anfragen für diesen Versuch nicht gleichzeitig: Bei aufeinanderfolgenden Anfragen lassen sich Erstellung und Wiederverwendung leichter unterscheiden.

Ein Timeout beweist nicht, dass der Anbieter nichts verarbeitet hat. Prüfen Sie vor einer Wiederholung seine Anfrageprotokolle und legen Sie ein ausdrückliches Budget für den Versuch fest. Diese Anleitung führt die Befehle nicht für Sie aus.

Standardmäßig gilt der Cache fünf Minuten; dokumentiert ist auch eine Stunde. Lassen Sie beim ersten Versuch den Standard unverändert. Ändern sich Gültigkeit und Präfix gleichzeitig, wird die Diagnose schwieriger. Auch die Zeit zur Antwortgenerierung verbraucht einen Teil der Gültigkeitsdauer.

Nutzungsdaten des tatsächlich verwendeten Protokolls lesen

Prüfen Sie beim Chat-Completions-Versuch usage.prompt_tokens_details. Unterscheiden Sie Cache-Lesen, Cache-Schreiben und gewöhnliche Eingabe. Ein vorhandenes Cache-Feld beweist nicht, dass das gesamte Dokument wiederverwendet wurde.

import json
from pathlib import Path

for name in ["response-1.json", "response-2.json"]:
    response = json.loads(Path(name).read_text(encoding="utf-8"))
    usage = response.get("usage") or {}
    details = usage.get("prompt_tokens_details") or {}
    print(name, {
        "input_tokens": usage.get("prompt_tokens"),
        "cache_read_tokens": details.get("cached_tokens"),
        "cache_write_tokens": details.get("cache_write_tokens"),
        "output_tokens": usage.get("completion_tokens")
    })

Fehlende Werte bleiben None; das Skript ersetzt nicht gemeldete Nutzung nicht stillschweigend durch null. Speichern Sie beide Rohantworten privat. Liefert der Anbieter die Nutzungsstruktur eines anderen Protokolls, verwenden Sie dessen Dokumentation, statt Feldnamen so lange umzubenennen, bis das Skript scheinbar funktioniert.

Für Responses dokumentiert QwenCloud beispielsweise input_tokens_details; die Anthropic-kompatible API hat eigene Felder für Lesen und Erstellung. Manche Felder sind Aliase: Wer Alias und zugehörigen Zähler addiert, zählt doppelt. Siehe die protokollspezifischen Tabellen der Cache-Nutzungsreferenz.

Cache-Misses gezielt untersuchen

BeobachtungPrüfenNächster kontrollierter Versuch
Erste Anfrage meldet keinen wiederverwendbaren PräfixMindestlänge, Platzierung der Markierung, unterstütztes ProtokollRoute beibehalten und serialisierte Anfrage ansehen
Zweite Anfrage meldet keine Cache-LesezugriffeExakter Präfix, Benutzerbereich und verstrichene ZeitErste Inhaltsblöcke Byte für Byte vergleichen
Nur ein Teil der Eingabe wurde gecachtEnde des Haltepunkts und geänderte InhalteStabiles Dokument von der aktuellen Frage trennen
Eine zuvor funktionierende Folge trifft nicht mehrDokumentversion, Werkzeugdefinitionen und ClientserialisierungGespeicherte Anfragen mit dem letzten funktionierenden Paar vergleichen
Nutzungsfelder fehlenProtokoll, Antwortformat und StreamingZunächst eine vollständige Antwort ohne Streaming verwenden
ParameterfehlerUnterstützung der Route und JSON-StrukturAuf das dokumentierte Beispiel mit einer Markierung reduzieren

Lange Agentengespräche haben eine weitere Grenze: Laut offizieller Anleitung schaut jeder Haltepunkt bis zu 20 Inhaltsblöcke zurück; nur die letzten vier wirksamen Haltepunkte bleiben erhalten, gegebenenfalls einschließlich eines automatischen. Wächst der Verlauf so weit, dass der nutzbare Präfix außerhalb dieses Fensters liegt, prüfen Sie die Blockstruktur und setzen Sie bewusst einen Haltepunkt an der stabilen Grenze. Löschen Sie keine benötigten Werkzeugergebnisse oder Reasoning-Verläufe, nur um einen Treffer zu erzwingen. Speichern Sie Vorher-/Nachher-Anfragen und prüfen Sie die daraus resultierende Nutzung.

Nicht jeder Cache-Miss bedeutet einen Modellrückschritt. Die Agentenumgebung kann Werkzeuge umsortieren, dynamischen Systemtext voranstellen oder die Dokumentformatierung ändern. Protokollieren Sie eine bereinigte Darstellung des stabilen Präfixes und seinen Hash, bevor Sie den Anbieter als Ursache ansehen.

Bei Kennungs- oder Endpunktfehlern hilft unser Leitfaden zu „model not found“ (Englisch). Funktioniert der Cache, aber ein Agent verliert Werkzeugergebnisse, liegt ein separates Verlaufsproblem vor; siehe Erhalt mehrstufiger Werkzeugaufrufe (Englisch).

Ersparnis anhand vollständig abgenommener Aufgaben berechnen

Cache-Schreiben kann anders kosten als Lesen oder gewöhnliche Eingabe. Vergleichen Sie die gesamte Folge einschließlich anfänglichem Schreibvorgang und jeder erzeugten Antwort mit derselben Folge ohne Cache. Nutzen Sie aktuelle regionale Tarife aus der QwenCloud-Preisübersicht, keinen Tarif einer anderen Region oder einer Preview-Aktion.

Erfassen Sie je Aufruf Dokumentversion, Eingabetokens, gelesene und geschriebene Cache-Tokens, gewöhnliche Eingabe, Ausgabetokens, Laufzeit und Abnahmeergebnis. Zählen Sie Aliase nicht doppelt. Ein Rabatt auf gecachte Eingabe entspricht nicht demselben prozentualen Rabatt auf die gesamte Agentenaufgabe: Ausgabe und externe Werkzeuge können einen großen Teil der Kosten ausmachen.

Prüfen Sie neben der Rechnung auch die Antwort. Kontrollieren Sie im Zwei-Fragen-Beispiel unabhängig, ob die genannten Zuständigkeiten und Genehmigungspflichten im Referenzdokument stehen. Eine billigere, unbelegte Antwort ist kein abgenommenes Ergebnis.

Dies ist ein direkter QwenCloud-Ablauf. Unser Ofox-Katalogcheck vom 16. November enthielt Qwen4 nicht. Prüfen Sie bei bestehenden Ofox-Routen den genauen Modelleintrag, verwenden Sie die Ofox-Authentifizierung und folgen Sie der Ofox-Fehlerbehandlung. Diese Dokumente belegen nicht, dass QwenClouds neue Cache-Parameter bei Ofox verfügbar sind.

Häufig gestellte Fragen

Beweist ein wiederholter Prompt, dass Qwen4 den Cache genutzt hat?
Nein. Prüfen Sie die vom Anbieter zurückgegebenen Cache-Lesezähler. Eine schnellere Antwort oder wiederholter Text allein belegt keinen Cache-Treffer.
Kann ich diese Cache-Parameter bei Ofox verwenden?
Der Artikel beschreibt die direkte Qwen4-API von QwenCloud. Der Ofox-Katalog enthielt bei der Prüfung am 16. November kein Qwen4. Gehen Sie nicht davon aus, dass Modell und Cache-Verhalten auch bei Ofox verfügbar sind.