Einführung
Ein KI-Modell erzeugt normalerweise jedes Mal eine neue Antwort, wenn eine Anwendung es aufruft. Das kostet Zeit und Modellnutzung, selbst wenn die Anfrage exakt einer gerade beantworteten Anfrage entspricht. Ein Cache speichert eine wiederverwendbare Antwort für eine begrenzte Zeit. Dadurch kann eine identische Anfrage beantwortet werden, ohne das Modell erneut aufzurufen.
Caching ist nur sinnvoll, wenn die Wiederverwendung sicher ist. Eine öffentliche, unveränderliche FAQ-Frage ist dafür geeignet, weil alle Aufrufer dieselbe Antwort erhalten können. Eine personalisierte Supportanfrage ist dafür nicht geeignet: Zwei Kunden dürfen niemals nur zur Verbesserung der Geschwindigkeit unter einem gemeinsamen Cache-Schlüssel zusammengefasst werden. Der standardmäßige Cache-Schlüssel von AI Gateway schützt dieses Lab, indem er den Anbieter, den Endpunkt, das Modell, die Anbieteranmeldedaten und den vollständigen Anfrage-Body enthält. Jede Änderung am Body erzeugt einen anderen Eintrag.
Sie erstellen ein einziges kurzlebiges authentifiziertes Gateway mit einer Cache-Lebensdauer von fünf Minuten. Sie senden eine kleine öffentliche Workers-AI-Frage und beobachten einen Cache-MISS, wiederholen exakt dieselbe Anfrage und weisen einen HIT nach. Anschließend ändern Sie die Frage und sehen einen weiteren MISS. Zum Schluss umgehen Sie die vorhandene zwischengespeicherte Antwort, wenn Aktualität wichtig ist, und bestätigen anhand der Gateway-Protokolle, dass die Anfrage das Modell erreicht hat.
Wenn Sie diesen Kurs direkt geöffnet haben, bearbeiten Sie zuerst LabEx mit Ihrem Cloudflare-Konto verbinden. Dort lernen Sie das LabEx-VM-Terminal, die Wrangler-Geräteautorisierung, die Bestätigung des Lernkontos und die explizite Angabe von Konto-IDs kennen. Bearbeiten Sie außerdem zuerst Inference über ein Gateway routen, da dieses Lab dessen separates Gateway und die getrennten Berechtigungsgrenzen für das Upstream wiederverwendet.
Das Lab verwendet das von Cloudflare gehostete Modell @cf/meta/llama-3.3-70b-instruct-fp8-fast mit der Standardabrechnung von Workers AI. Workers Paid, Unified Billing und ein externes Anbieter-Konto sind nicht erforderlich. Nur drei Anfragen sollten das Modell erreichen; die exakt wiederholte Anfrage sollte aus dem Cache beantwortet werden. Brechen Sie ab, anstatt wiederholt erneut zu versuchen, wenn die gemeinsame tägliche Workers-AI-Zuteilung nicht verfügbar ist.
Das Setup installiert Node.js 22.22.0 und Wrangler 4.132.0 als lokale Projektabhängigkeit in /home/labex/project/ai-gateway-cache. Es bereitet unabhängige Prüfungen mit Leseberechtigung vor, autorisiert Wrangler jedoch nicht, erstellt keine Cloud-Ressourcen und sendet keinen Modell-Traffic. LabEx zerstört die temporäre VM am Ende des Labs. Sie müssen das Gateway und das Token trotzdem vor dem Abmelden löschen, da die Zerstörung der VM Cloud-Ressourcen nicht entfernen kann.
Die VM autorisieren und das Cache-Experiment benennen
In diesem Schritt verbinden Sie die neue VM mit Ihrem Lernkonto und erzeugen Namen für ein kurzlebiges Gateway und ein Token.
Ein Cache ist gemeinsam genutzte Infrastruktur. Deshalb muss sein Gültigkeitsbereich bewusst festgelegt werden. Dieses Lab verwendet ein eindeutig benanntes Gateway und ausschließlich synthetische öffentliche Fragen. Das zufällige Suffix verhindert, dass sich Ihr Experiment mit einem anderen Gateway im selben Lernkonto überschneidet.
Wechseln Sie in das vorbereitete Projekt, prüfen Sie die festgelegte CLI-Version und autorisieren Sie diese VM:
cd /home/labex/project/ai-gateway-cache
npx wrangler --version
npx wrangler login --device --browser=false --scopes account:read user:read ai:write
Öffnen Sie den angezeigten Link, geben Sie den Code ein und autorisieren Sie das vorgesehene Lernkonto. Prüfen Sie anschließend die strukturierte Identität:
npx wrangler whoami --json
Erwartet werden Wrangler 4.132.0 und loggedIn: true. Ersetzen Sie YOUR_ACCOUNT_ID unten durch die tatsächliche 32-stellige ID, die für das vorgesehene Konto angezeigt wird:
GATEWAY_ID="labex-c09-g03-$(openssl rand -hex 6)"
TOKEN_NAME="$GATEWAY_ID-token"
cat > .labex/state.json <<JSON
{
"accountId": "YOUR_ACCOUNT_ID",
"gatewayId": "$GATEWAY_ID",
"tokenName": "$TOKEN_NAME"
}
JSON
cat .labex/state.json
Diese nicht geheimen Bezeichner bleiben in einem lokalen Inventar gespeichert. Dadurch richten sich alle späteren Lese-, Prüf- und Bereinigungsschritte ausschließlich an die Ressourcen dieses Labs.
Ein authentifiziertes Gateway mit kurzem Cache erstellen
In diesem Schritt erstellen Sie das Gateway und geben zwischengespeicherten Antworten eine Time to Live von fünf Minuten, kurz TTL. Eine TTL ist die maximale Zeit, während der ein Eintrag wiederverwendet werden darf, bevor er veraltet und vom Modell aktualisiert werden muss.
Öffnen Sie das Cloudflare-Dashboard und wählen Sie AI → AI Gateway → Create gateway → Custom gateway. Verwenden Sie die gespeicherte gatewayId als Namen des Gateways. Lassen Sie die Anfrageprotokollierung und die Gateway-Authentifizierung aktiviert, aktivieren Sie Cache responses und setzen Sie die TTL exakt auf 300 Sekunden. Lassen Sie Rate-Limits, Ausgabenlimits und Wiederholungsversuche deaktiviert. Lassen Sie die Workers-AI-Abrechnung auf Standard eingestellt.
Prüfen Sie nach der Erstellung die eindeutige Gateway-ID in der Breadcrumb-Navigation. Die kurze TTL ist lang genug, um dieses Experiment zu wiederholen, verhindert aber, dass die Beispielantwort unnötig lange bestehen bleibt.
Wählen Sie Create an AI Gateway authentication token. Verwenden Sie den gespeicherten tokenName, beziehen Sie nur das vorgesehene Lernkonto ein und legen Sie genau diese Berechtigungen fest:
- AI Gateway — Run, um das authentifizierte Gateway aufzurufen;
- AI Gateway — Edit, um Cache-Nachweise zu lesen und dieses kurzlebige Gateway zu löschen.
Fügen Sie keine Workers-AI-Berechtigung hinzu. Wrangler stellt die separate, kurzlebige Upstream-Anmeldedaten bereit. Erstellen Sie das Token nach der Prüfung des Kontos und der Berechtigungen. Speichern Sie anschließend seinen nur einmal angezeigten Wert, ohne ihn auszugeben:
bash -c '
while :; do
read -ersp "Paste the AI Gateway token: " GATEWAY_TOKEN
printf "\n"
[ -n "$GATEWAY_TOKEN" ] && break
printf "Token cannot be empty; paste it again.\n" >&2
done
umask 077
printf "%s" "$GATEWAY_TOKEN" > .labex/gateway-token
unset GATEWAY_TOKEN
chmod 600 .labex/gateway-token
'
Prüfen Sie die exakte Cache-Konfiguration über die authentifizierte Management-API:
ACCOUNT_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).accountId')
GATEWAY_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).gatewayId')
GATEWAY_TOKEN=$(cat .labex/gateway-token)
curl --http1.1 -fsS \
-H "Authorization: Bearer $GATEWAY_TOKEN" \
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways/$GATEWAY_ID" \
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const b=JSON.parse(s),g=b.result||{};console.log(JSON.stringify({success:b.success,id:g.id,collect_logs:g.collect_logs,authentication:g.authentication,cache_ttl:g.cache_ttl},null,2))})'
unset GATEWAY_TOKEN
Erwartet werden die gespeicherte ID, collect_logs: true, authentication: true und cache_ttl: 300.
Die erste öffentliche FAQ-Anfrage senden
In diesem Schritt senden Sie eine kleine öffentliche Frage, die für alle Lernenden zur Wiederverwendung geeignet ist. Für die erste passende Anfrage kann unter diesem neuen Gateway noch kein Eintrag existieren. Daher sollte sie einen Cache-MISS erzeugen. Bei einem Miss leitet AI Gateway die Anfrage an Workers AI weiter und speichert anschließend die erfolgreiche Antwort.
Der standardmäßige Cache-Schlüssel enthält die Anmeldedaten des Upstream-Anbieters. Speichern Sie die aktuellen Wrangler-Anmeldedaten dieser VM geschützt, damit alle vier Anfragen denselben kontrollierten Schlüssel verwenden. Dies ist eine kurzlebige Lab-Datei und kein Muster für Produktionsgeheimnisse:
umask 077
npx wrangler auth token --json \
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(JSON.parse(s).token))' \
> .labex/upstream-token
chmod 600 .labex/upstream-token
Senden Sie die erste Anfrage und speichern Sie Antwort-Header, Body und HTTP-Status, ohne eine der beiden Anmeldedaten auszugeben:
ACCOUNT_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).accountId')
GATEWAY_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).gatewayId')
MODEL='@cf/meta/llama-3.3-70b-instruct-fp8-fast'
METADATA='{"lab":"g03-cache","case":"public-faq","synthetic":true}'
GATEWAY_TOKEN=$(cat .labex/gateway-token)
UPSTREAM_TOKEN=$(cat .labex/upstream-token)
STATUS=$(curl --http1.1 -sS -D .labex/first-headers.txt \
-o .labex/first-response.json -w '%{http_code}' \
-H "cf-aig-authorization: Bearer $GATEWAY_TOKEN" \
-H "Authorization: Bearer $UPSTREAM_TOKEN" \
-H "cf-aig-metadata: $METADATA" \
-H 'Content-Type: application/json' \
--data '{"prompt":"In one short sentence, what does an AI gateway do?","max_tokens":32}' \
"https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/workers-ai/$MODEL")
unset GATEWAY_TOKEN UPSTREAM_TOKEN METADATA
printf '%s\n' "$STATUS" | tee .labex/first-status.txt
awk 'BEGIN{IGNORECASE=1} /^cf-aig-cache-status:/ {gsub("\r","",$2); print toupper($2)}' .labex/first-headers.txt \
| tail -1 | tee .labex/first-cache-status.txt
node -e 'const b=require("./.labex/first-response.json"); console.log(b.result?.response ?? b.result)'
Erwartet werden HTTP 200, der Cache-Status MISS und eine kurze generierte Antwort. Der Anfrage-Body enthält keine Kundendaten. Daher ist es sicher, diese Antwort vorübergehend wiederzuverwenden.
Die exakte Anfrage wiederholen und einen Cache-Treffer nachweisen
In diesem Schritt senden Sie exakt denselben Anbieter, Endpunkt, dasselbe Modell, dieselben Anmeldedaten und denselben Anfrage-Body. AI Gateway kann daher den im vorherigen Schritt erstellten Eintrag wiederverwenden. Ein Cache-HIT bedeutet, dass die Antwort aus dem Gateway-Cache stammt und keine neue Modellgenerierung erfolgte.
Das Speichern im Cache erfolgt asynchron. Warten Sie deshalb nach der erfolgreichen ersten Antwort einige Sekunden, bevor Sie die Anfrage wiederholen:
sleep 5
GATEWAY_TOKEN=$(cat .labex/gateway-token)
UPSTREAM_TOKEN=$(cat .labex/upstream-token)
METADATA='{"lab":"g03-cache","case":"public-faq","synthetic":true}'
STATUS=$(curl --http1.1 -sS -D .labex/repeat-headers.txt \
-o .labex/repeat-response.json -w '%{http_code}' \
-H "cf-aig-authorization: Bearer $GATEWAY_TOKEN" \
-H "Authorization: Bearer $UPSTREAM_TOKEN" \
-H "cf-aig-metadata: $METADATA" \
-H 'Content-Type: application/json' \
--data '{"prompt":"In one short sentence, what does an AI gateway do?","max_tokens":32}' \
"https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/workers-ai/$MODEL")
unset GATEWAY_TOKEN UPSTREAM_TOKEN METADATA
printf '%s\n' "$STATUS" | tee .labex/repeat-status.txt
awk 'BEGIN{IGNORECASE=1} /^cf-aig-cache-status:/ {gsub("\r","",$2); print toupper($2)}' .labex/repeat-headers.txt \
| tail -1 | tee .labex/repeat-cache-status.txt
cmp -s .labex/first-response.json .labex/repeat-response.json \
&& echo 'response bytes match the cached source'
Erwartet werden HTTP 200 und HIT. Übereinstimmende Bytes sind eine hilfreiche zusätzliche Beobachtung. Maßgeblich sind jedoch der HIT-Antwort-Header und der entsprechende Eintrag im Dashboard-Protokoll. Das Speichern im AI-Gateway-Cache erfolgt asynchron und ist flüchtig. Senden Sie die beiden Anfragen daher nicht gleichzeitig. Falls die sequenzielle Wiederholung weiterhin einen Miss ergibt, warten Sie einige Sekunden und führen Sie diesen exakten Block einmal erneut aus.
Öffnen Sie im Dashboard die Ansicht Logs des Gateways. Suchen Sie die beiden public-faq-Anfragen und vergleichen Sie deren Cache-Indikatoren, Laufzeiten und Token-Nutzung. Eine Zeile sollte den modellgestützten Miss zeigen, die andere den zwischengespeicherten Hit.
Die Frage ändern und einen neuen Miss beobachten
In diesem Schritt ändern Sie nur den Prompt. Der vollständige Anfrage-Body ist Bestandteil des standardmäßigen Cache-Schlüssels. Daher darf die neue Frage nicht die vorherige Antwort erhalten.
GATEWAY_TOKEN=$(cat .labex/gateway-token)
UPSTREAM_TOKEN=$(cat .labex/upstream-token)
METADATA='{"lab":"g03-cache","case":"changed-question","synthetic":true}'
STATUS=$(curl --http1.1 -sS -D .labex/changed-headers.txt \
-o .labex/changed-response.json -w '%{http_code}' \
-H "cf-aig-authorization: Bearer $GATEWAY_TOKEN" \
-H "Authorization: Bearer $UPSTREAM_TOKEN" \
-H "cf-aig-metadata: $METADATA" \
-H 'Content-Type: application/json' \
--data '{"prompt":"In one short sentence, name one benefit of an AI gateway.","max_tokens":32}' \
"https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/workers-ai/$MODEL")
unset GATEWAY_TOKEN UPSTREAM_TOKEN METADATA
printf '%s\n' "$STATUS" | tee .labex/changed-status.txt
awk 'BEGIN{IGNORECASE=1} /^cf-aig-cache-status:/ {gsub("\r","",$2); print toupper($2)}' .labex/changed-headers.txt \
| tail -1 | tee .labex/changed-cache-status.txt
node -e 'const b=require("./.labex/changed-response.json"); console.log(b.result?.response ?? b.result)'
Erwartet werden HTTP 200 und MISS. Dieses Verhalten bei exakter Übereinstimmung ist bewusst enger als semantische Ähnlichkeit: Zwei Fragen, die ähnlich klingen, haben trotzdem unterschiedliche Bodies und unterschiedliche Cache-Einträge.
Ersetzen Sie den standardmäßigen Schlüssel bei personalisierten Prompts nicht durch einen gemeinsamen Schlüssel wie support-answer. Ein benutzerdefinierter Schlüssel ist nur dann sicher, wenn jede unter diesem Schlüssel zusammengefasste Anfrage berechtigt ist, dieselbe Antwort zu erhalten.
Den Cache umgehen, wenn Aktualität wichtig ist
In diesem Schritt kehren Sie zur ursprünglichen Frage zurück, umgehen deren zwischengespeicherte Antwort jedoch ausdrücklich. Bypass bedeutet: „Fragen Sie den Anbieter jetzt“, selbst wenn ein gültiger Cache-Eintrag vorhanden ist. Das ist nützlich, wenn eine Anwendung für eine bestimmte Anfrage eine aktuelle Ausgabe benötigt.
Der Header cf-aig-skip-cache: true steuert nur diese Anfrage. Der Cache des Gateways wird dadurch für andere Aufrufer nicht deaktiviert:
GATEWAY_TOKEN=$(cat .labex/gateway-token)
UPSTREAM_TOKEN=$(cat .labex/upstream-token)
METADATA='{"lab":"g03-cache","case":"fresh-bypass","synthetic":true}'
STATUS=$(curl --http1.1 -sS -D .labex/bypass-headers.txt \
-o .labex/bypass-response.json -w '%{http_code}' \
-H "cf-aig-authorization: Bearer $GATEWAY_TOKEN" \
-H "Authorization: Bearer $UPSTREAM_TOKEN" \
-H "cf-aig-metadata: $METADATA" \
-H 'cf-aig-skip-cache: true' \
-H 'Content-Type: application/json' \
--data '{"prompt":"In one short sentence, what does an AI gateway do?","max_tokens":32}' \
"https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/workers-ai/$MODEL")
unset GATEWAY_TOKEN UPSTREAM_TOKEN METADATA
printf '%s\n' "$STATUS" | tee .labex/bypass-status.txt
awk 'BEGIN{IGNORECASE=1} /^cf-aig-cache-status:/ {gsub("\r","",$2); print toupper($2)}' .labex/bypass-headers.txt \
| tail -1 | tee .labex/bypass-cache-status.txt
node -e 'const b=require("./.labex/bypass-response.json"); console.log(b.result?.response ?? b.result)'
Erwartet werden HTTP 200 und kein HIT. Je nach aktueller Gateway-Antwort kann der Header einen Bypass beschreiben oder einfach ein Status ungleich Hit bleiben. Maßgeblich ist der Gateway-Protokolleintrag: Für fresh-bypass muss dort cached: false angezeigt werden.
Kehren Sie im Dashboard zu Logs zurück und öffnen Sie die Anfrage fresh-bypass. Vergleichen Sie sie mit dem zwischengespeicherten Eintrag public-faq. Die gleiche Frage hat Workers AI erreicht, weil der anfragebezogene Bypass die Standardeinstellung des Gateways überschrieben hat.
Das kurzlebige Gateway löschen
In diesem Schritt entfernen Sie das Gateway, solange die Management-Anmeldedaten seine Abwesenheit noch nachweisen können. Das Löschen dieses von Ihnen erstellten Gateways entfernt auch seinen kurzlebigen Cache-Namensraum und seine Protokolle.
ACCOUNT_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).accountId')
GATEWAY_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).gatewayId')
GATEWAY_TOKEN=$(cat .labex/gateway-token)
curl --http1.1 -fsS -X DELETE \
-H "Authorization: Bearer $GATEWAY_TOKEN" \
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways/$GATEWAY_ID" \
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const b=JSON.parse(s);if(!b.success)process.exit(1);console.log("gateway deletion accepted")})'
unset GATEWAY_TOKEN
GATEWAY_TOKEN=$(cat .labex/gateway-token)
curl --http1.1 -fsS \
-H "Authorization: Bearer $GATEWAY_TOKEN" \
"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/gateways" \
> .labex/gateways-after-delete.json
unset GATEWAY_TOKEN
node -e 'const b=require("./.labex/gateways-after-delete.json"),id=process.argv[1],found=(b.result||[]).some(g=>g.id===id);console.log("gateway absent:",!found);if(found)process.exit(1)' "$GATEWAY_ID"
Erwartet wird gateway absent: true. Dieses authentifizierte Inventar unterscheidet eine tatsächliche Löschung von einer fehlenden Seite, die durch eine Abmeldung oder einen Netzwerkfehler verursacht wurde.
Das Token löschen und abmelden
In diesem Schritt widerrufen Sie die verbleibenden Cloud-Anmeldedaten, löschen beide temporären Token-Kopien und trennen die VM.
Öffnen Sie im Cloudflare-Dashboard My Profile → API Tokens. Suchen Sie den exakt gespeicherten tokenName, öffnen Sie Actions, wählen Sie Delete, prüfen Sie die Bestätigung und löschen Sie nur dieses Token. Der Widerruf ist jetzt sicher, weil die Löschung des Gateways bereits nachgewiesen wurde.
Löschen Sie die Gateway- und Upstream-Token-Dateien und beenden Sie anschließend die separate Wrangler-Autorisierung:
shred -u .labex/gateway-token .labex/upstream-token
npx wrangler logout
npx wrangler whoami --json || true
test ! -e .labex/gateway-token -a ! -e .labex/upstream-token \
&& echo "local token files removed"
Erwartet werden loggedIn: false und local token files removed. Die Dashboard-Sitzung ist davon getrennt und bleibt angemeldet. Wenn das Lab endet, zerstört LabEx diese temporäre VM, anstatt sie zu speichern.
Zusammenfassung
Sie haben einen kurzen Antwort-Cache von AI Gateway für eine sichere öffentliche Frage konfiguriert. Die erste Anfrage erzeugte einen MISS, die exakt wiederholte Anfrage wurde zu einem HIT, und eine geänderte Eingabe erzeugte einen separaten Eintrag. Anschließend verwendeten Sie einen anfragebezogenen Bypass, als Aktualität wichtig war, und bestätigten anhand der Protokolle, dass das Modell – nicht die zwischengespeicherte Kopie – die Anfrage verarbeitet hat.
Das nächste Lab fügt Traffic-Steuerungen hinzu. Sie lernen den Unterschied zwischen der Begrenzung der Anfragerate und der Begrenzung der Modellnutzung, die ein Gateway ausgeben darf, während Testvolumen und Kosten bewusst gering bleiben.
