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.
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 Kontext | Wechselnde Aufgabe |
|---|---|
| Freigegebene Handbuchversion | Aktuelle Kundenfrage |
| Feste Werkzeugdefinitionen | Werkzeugergebnisse der aktuellen Aufgabe |
| Gleichbleibende Reihenfolge der Anweisungen | Gewünschte Ausgabe dieser Runde |
| Festgelegte Serialisierung des Dokuments | Neue 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
| Beobachtung | Prüfen | Nächster kontrollierter Versuch |
|---|---|---|
| Erste Anfrage meldet keinen wiederverwendbaren Präfix | Mindestlänge, Platzierung der Markierung, unterstütztes Protokoll | Route beibehalten und serialisierte Anfrage ansehen |
| Zweite Anfrage meldet keine Cache-Lesezugriffe | Exakter Präfix, Benutzerbereich und verstrichene Zeit | Erste Inhaltsblöcke Byte für Byte vergleichen |
| Nur ein Teil der Eingabe wurde gecacht | Ende des Haltepunkts und geänderte Inhalte | Stabiles Dokument von der aktuellen Frage trennen |
| Eine zuvor funktionierende Folge trifft nicht mehr | Dokumentversion, Werkzeugdefinitionen und Clientserialisierung | Gespeicherte Anfragen mit dem letzten funktionierenden Paar vergleichen |
| Nutzungsfelder fehlen | Protokoll, Antwortformat und Streaming | Zunächst eine vollständige Antwort ohne Streaming verwenden |
| Parameterfehler | Unterstützung der Route und JSON-Struktur | Auf 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.


