Workers-AI-Inference über AI Gateway routen

Einführung

Im Workers-AI-Kurs hat eine Anwendung eine Eingabe direkt an ein von Cloudflare gehostetes Modell gesendet. Das funktioniert, aber eine wachsende Anwendung benötigt außerdem eine zentrale Stelle, an der sich Modellzugriffe beobachten und steuern lassen. Cloudflare AI Gateway übernimmt diese Aufgabe: Der Aufrufer sendet eine Anfrage an ein benanntes Gateway, und das Gateway leitet die Anfrage an einen Upstream-Modellanbieter wie Workers AI weiter.

In diesem Lab bleiben die drei Rollen sichtbar:

der Aufrufer ist curl in Ihrer LabEx-VM;
das Gateway prüft, ob der Aufrufer zugreifen darf, und protokolliert die Anfrage;
der Upstream-Anbieter ist Workers AI. Dort wird geprüft, ob die Anfrage das Modell ausführen darf.

Für die beiden letzten Prüfungen werden getrennte Zugangsdaten verwendet. cf-aig-authorization authentifiziert den Aufrufer gegenüber AI Gateway. Der normale Authorization-Header authentifiziert die Gateway-Anfrage gegenüber Workers AI. Ein gültiges Gateway-Token ist nicht automatisch eine Workers-AI-Zugangsdaten, und eine Workers-AI-Zugangsdaten umgeht kein authentifiziertes Gateway.

Sie erstellen im Cloudflare Dashboard ein kurzlebiges authentifiziertes Gateway, legen ein eng begrenztes AI-Gateway-Token an, senden eine kurze Anfrage an das von Cloudflare gehostete Modell Llama 3.3 und untersuchen das daraus entstehende Protokoll. Danach ersetzen Sie nur die Gateway-Zugangsdaten durch einen ungültigen Wert, um zu zeigen, welche Grenze die Anfrage ablehnt. Zum Schluss löschen Sie das Gateway, löschen dessen Token, sodass es keine Anfragen mehr autorisieren kann, und melden Wrangler ab.

Wenn Sie diesen Kurs direkt aufgerufen haben, absolvieren Sie zuerst LabEx mit Ihrem Cloudflare-Konto verbinden. Dort lernen Sie das Terminal der LabEx-VM, die Geräteautorisierung mit Wrangler, die Kontobestätigung und die explizite Angabe von Konto-IDs kennen. Das Lab zur Workers-AI-Inference ist ebenfalls eine sinnvolle Voraussetzung.

AI Gateway ist im Free-Tarif verfügbar, und die grundlegende Protokollierung ist innerhalb der Kontolimits kostenlos. Das ausgewählte Modell @cf/meta/llama-3.3-70b-instruct-fp8-fast kann mit der gemeinsamen kostenlosen Workers-AI-Zuteilung und der Abrechnungsoption Standard verwendet werden. Workers Paid und Unified Billing sind nicht erforderlich. Beenden Sie den Versuch, statt wiederholt neue Anfragen zu senden, wenn die tägliche Workers-AI-Zuteilung des Kontos nicht verfügbar ist.

Die Einrichtung installiert Node.js 22.22.0 und Wrangler 4.132.0 als projektspezifische Version in /home/labex/project/ai-gateway-route. Sie stellt unabhängige Prüfungen mit Lesezugriff bereit, autorisiert Wrangler jedoch nicht, erstellt kein Token oder Gateway, sendet keine Inference und ändert Ihr Cloudflare-Konto nicht. LabEx speichert diese temporäre VM nach dem Lab nicht. Sie löschen das Cloud-Token und dessen Kopie in der VM dennoch ausdrücklich, damit die Bereinigung abgeschlossen ist, bevor die VM zerstört wird.

VM autorisieren und eigene Namen speichern

In diesem Schritt verbinden Sie die neue VM mit Ihrem Lernkonto und speichern Namen, die die Ressourcen dieses Labs eindeutig machen.

Die Geräteanmeldung mit Wrangler autorisiert Workers AI, erstellt aber nicht die separate AI-Gateway-Zugangsdaten für den Aufrufer, die Sie später verwenden. Wenn Sie diese Zugangsdaten getrennt halten, wird die Vertrauensgrenze leichter erkennbar.

Wechseln Sie in das vorbereitete Projekt und bestätigen Sie die festgelegte CLI-Version:

cd /home/labex/project/ai-gateway-route
npx wrangler --version

Erwarten Sie 4.132.0. Starten Sie die Geräteautorisierung mit Kontoidentität und Zugriff auf Workers AI:

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

Bestätigen Sie loggedIn: true. Erstellen Sie eine eindeutige Gateway-ID und den zugehörigen Token-Namen. Ersetzen Sie YOUR_ACCOUNT_ID durch die tatsächliche ID mit 32 Zeichen, die für das vorgesehene Konto angezeigt wird:

GATEWAY_ID="labex-c09-g01-$(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

Das zufällige Suffix verhindert Kollisionen. Die Zustandsdatei enthält Ressourcenkennungen, aber keine Zugangsdaten. Dadurch kann jeder spätere Befehl genau die Ressource ansprechen, die zu diesem Lab gehört.

Authentifiziertes Gateway und Token für den Aufrufer erstellen

In diesem Schritt erstellen Sie die Kontrollstelle und eine Zugangsdaten, mit der Sie sie aufrufen und untersuchen können.

Öffnen Sie das Cloudflare Dashboard und wählen Sie AI → AI Gateway → Create gateway → Custom gateway. Verwenden Sie den gatewayId aus .labex/state.json als Gateway-Namen. Behalten Sie diese Einstellungen bei:

Anfragen protokollieren: aktiviert;
Gateway-Authentifizierung: aktiviert;
Cache, Ratenlimits, Ausgabenlimits und Wiederholungsversuche: deaktiviert;
Workers-AI-Abrechnung: Standard.

Die Abrechnungsoption Standard verwendet die normale Workers-AI-Zuteilung. Unified Billing ist ein anderer Zahlungsweg und gehört nicht zu diesem Einsteiger-Lab.

Nachdem Cloudflare die neue Ressource geöffnet hat, prüfen Sie anhand der Breadcrumb-Navigation und des ausgewählten Tabs Overview, dass Sie sich im exakt vorgesehenen temporären Gateway befinden und nicht in der kontoweiten Gateway-Liste.

Die Übersicht des neuen Gateways mit seiner eindeutigen ID und leeren Metriken für die erste Anfrage

Öffnen Sie nach der Erstellung Settings. Bestätigen Sie, dass die angezeigte Gateway-ID exakt mit Ihrer gespeicherten ID übereinstimmt und dass Protokollierung und Authentifizierung aktiviert sind.

Wählen Sie nun Create an AI Gateway authentication token. Verwenden Sie den gespeicherten tokenName als Namen, wählen Sie nur das vorgesehene Lernkonto aus und fügen Sie diese Berechtigungen hinzu:

AI Gateway — Run ermöglicht dem Aufrufer den Zugriff auf ein authentifiziertes Gateway;
AI Gateway — Edit ermöglicht es dem Lab, AI-Gateway-Ressourcen über die Management-API zu lesen und zu löschen.

Fügen Sie diesem Token keine Workers-AI-Berechtigung hinzu. Workers AI bleibt durch Wranglers separate, kurzlebige Zugangsdaten autorisiert.

Das Formular für Tokenberechtigungen, begrenzt auf AI Gateway Run und Edit

Erstellen Sie das Token erst, nachdem Sie Konto und Berechtigungen überprüft haben. Cloudflare zeigt den Wert nur einmal an. Speichern Sie ihn privat, ohne ihn auszugeben:

bash -c '
while :; do
  read -rsp "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
'

Das vorbereitete Terminal verwendet interaktiv zsh. Deshalb startet dieser Block einen kurzen Bash-Unterprozess für die verdeckte read-Eingabeaufforderung von Bash. Eine leere Eingabe wird abgelehnt, bevor der Befehl zur Shell zurückkehrt. Das Token bleibt nur im Unterprozess und in der privaten Datei gespeichert.

Das Token wird bewusst nicht in der Konfiguration oder in der Befehlsausgabe gespeichert. Überprüfen Sie das tatsächliche Gateway ü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},null,2))})'
unset GATEWAY_TOKEN

Erwarten Sie die eigene ID mit collect_logs: true und authentication: true. Es wird kein Geheimnis ausgegeben.

Die Ansicht „Gateway Settings“ mit Authentifizierung, Protokollen und Standardabrechnung

Eine Workers-AI-Anfrage über das Gateway routen

In diesem Schritt senden Sie eine kleine Anfrage über das Gateway statt direkt an Workers AI.

Die provider-spezifische Gateway-URL enthält Konto, Gateway, Anbieter und Modell. Die beiden Autorisierungs-Header bleiben bewusst getrennt:

caller → cf-aig-authorization → AI Gateway → Authorization → Workers AI model

Rufen Sie Wranglers aktuelle kurzlebige Workers-AI-Zugangsdaten als strukturierte Daten ab und stellen Sie anschließend die Anfrage. Der Befehl schreibt ausschließlich die JSON-Antwort in eine Datei. Keine der beiden Zugangsdaten wird ausgegeben:

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'
GATEWAY_TOKEN=$(cat .labex/gateway-token)
UPSTREAM_TOKEN=$(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))')
curl --http1.1 -fsS \
  -H "cf-aig-authorization: Bearer $GATEWAY_TOKEN" \
  -H "Authorization: Bearer $UPSTREAM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"prompt":"In one sentence, explain why an AI gateway is useful.","max_tokens":64}' \
  "https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/workers-ai/$MODEL" \
  > .labex/valid-response.json
unset GATEWAY_TOKEN UPSTREAM_TOKEN
node -e 'const b=require("./.labex/valid-response.json"); console.log(b.result?.response ?? b.result)'

Der genaue Wortlaut kann abweichen, weil die Generierung nicht deterministisch ist. Die Prüfung kontrolliert nur, dass der Anbieter über das eigene Gateway ein erfolgreiches, nicht leeres Ergebnis zurückgegeben hat.

Grenze der Gateway-Authentifizierung isolieren

In diesem Schritt behalten Sie die gültigen Workers-AI-Zugangsdaten bei und ersetzen nur die Gateway-Zugangsdaten.

Bei einem kontrollierten Negativtest sollte jeweils nur eine Bedingung geändert werden. Wenn beide Zugangsdaten ungültig wären, würde ein HTTP-Fehler nicht zeigen, welches System die Anfrage abgelehnt hat. Diese Anfrage behält Wranglers gültiges Upstream-Token bei und sendet einen eindeutig ungültigen Wert für cf-aig-authorization:

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'
UPSTREAM_TOKEN=$(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))')
STATUS=$(curl --http1.1 -sS -o .labex/invalid-response.json -w '%{http_code}' \
  -H 'cf-aig-authorization: Bearer deliberately-invalid' \
  -H "Authorization: Bearer $UPSTREAM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"prompt":"This request must not reach the model.","max_tokens":8}' \
  "https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/workers-ai/$MODEL")
unset UPSTREAM_TOKEN
printf '%s\n' "$STATUS" | tee .labex/invalid-status.txt

Erwarten Sie 401 oder 403. Geben Sie den Antwort-Body nicht aus: Der Status ist ein ausreichender Nachweis, und eine begrenzte Fehlerausgabe verringert das Risiko, Anfragedetails offenzulegen.

Die Anfrage mit dem Gateway-Protokoll verknüpfen

In diesem Schritt verwenden Sie die Beobachtbarkeit, um das Laufzeitverhalten mit einem sichtbaren Gateway-Eintrag zu verknüpfen.

Beobachtbarkeit bedeutet, genügend Nachweise zu sammeln, um zu erklären, was ein System getan hat, nachdem eine Anfrage den Aufrufer verlassen hat. Ein Gateway-Protokoll kann Anbieter, Modell, Status, Latenz und Tokenverbrauch anzeigen, ohne das Modell erneut aufzurufen. Es kann kurze Zeit dauern, bis Protokolle erscheinen.

Lesen Sie die vorhandenen Protokolle über die authentifizierte Management-API. Dies ist eine schreibgeschützte Prüfung und sendet keine weitere Modellanfrage:

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/logs?per_page=50" \
  > .labex/logs.json
unset GATEWAY_TOKEN
node - <<'NODE'
const body = require('./.labex/logs.json')
const model = '@cf/meta/llama-3.3-70b-instruct-fp8-fast'
const matches = (body.result || []).filter(row =>
  row.provider === 'workers-ai' && row.model === model
)
console.log(matches.map(row => ({
  id: row.id,
  provider: row.provider,
  model: row.model,
  success: row.success,
  created_at: row.created_at
})))
if (!matches.some(row => row.success === true)) process.exit(2)
NODE

Erwarten Sie einen Eintrag mit provider: "workers-ai", dem vorgesehenen Modell und success: true. Wenn der Befehl ohne diesen Eintrag endet, warten Sie etwa 20 Sekunden und führen Sie denselben schreibgeschützten Block erneut aus, statt weitere Inference-Anfragen zu senden.

Öffnen Sie im Dashboard die Ansicht Logs des Gateways. Suchen Sie die erfolgreiche Workers-AI-Zeile für @cf/meta/llama-3.3-70b-instruct-fp8-fast. Bestätigen Sie Erfolg, Anbieter und Modell, bevor Sie den Detailbereich öffnen.

Die Gateway-Tabelle „Logs“ mit hervorgehobener erfolgreicher Workers-AI-Anfrage

Die genaue Dauer, Tokenanzahl und der generierte Text können abweichen. Diese Werte beschreiben die aktuelle Anfrage und sind nicht als exakt zu reproduzierende Zielwerte gedacht. Geben Sie niemals Zugangsdaten oder personenbezogene Informationen in einen Prompt ein, nur um ein Protokoll leichter zu finden.

Der fokussierte Detailbereich des Anfrageprotokolls mit Modell, Status, Latenz und Tokenverbrauch

Das temporäre Gateway löschen

In diesem Schritt entfernen Sie die Cloud-Ressource, solange die Management-Zugangsdaten noch verfügbar sind.

Die Bereinigung muss die exakt zugehörige ID verwenden und durch eine authentifizierte Inventarliste nachgewiesen werden. Eine fehlende Seite aufgrund einer Abmeldung oder eines Netzwerkfehlers beweist nicht, dass die Löschung erfolgreich war.

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"

Erwarten Sie gateway absent: true. Die zweite Anfrage listet die Gateways mit gültiger Autorisierung auf und schlägt fehl, wenn die eigene ID noch vorhanden ist. Andere Gateways in Ihrem Konto werden niemals geändert.

Token löschen und abmelden

In diesem Schritt entfernen Sie die beiden unabhängigen Zugangsdaten in umgekehrter Reihenfolge zu ihrer Verwendung.

Öffnen Sie im Cloudflare Dashboard My Profile → API Tokens. Suchen Sie den exakten Token-Namen aus .labex/state.json, öffnen Sie das Menü Actions, wählen Sie Delete, prüfen Sie die Bestätigung und löschen Sie nur dieses Token. Durch das Löschen wird sein Zugriff sofort widerrufen. Sie können es jetzt sicher entfernen, weil das Gateway bereits gelöscht wurde.

Entfernen Sie die lokale Kopie und beenden Sie anschließend Wranglers separate Autorisierung der VM:

shred -u .labex/gateway-token
npx wrangler logout
npx wrangler whoami --json || true

Erwarten Sie eine strukturierte Ausgabe mit loggedIn: false. Die Browsersitzung im Dashboard ist davon getrennt und bleibt angemeldet. Führen Sie die abschließende lokale Prüfung aus:

test ! -e .labex/gateway-token && echo "local gateway token removed"

Die Meldung bestätigt, dass die Kopie in der VM nicht mehr vorhanden ist. Die Schaltfläche Check von LabEx wiederholt unabhängig die Prüfungen der lokalen Datei und der Wrangler-Abmeldung. Das zugehörige Backend-Skript ist absichtlich nicht Bestandteil des Lernprojekts.

Sie haben nun das Gateway entfernt, das Aufrufer-/Management-Token gelöscht, die lokale Tokenkopie gelöscht und die neue VM getrennt. Wenn Sie das Lab beenden, zerstört LabEx diese temporäre VM, statt sie zu speichern. Die Bereinigung der Cloud-Ressourcen bleibt trotzdem wichtig, weil das alleinige Zerstören einer VM weder ein Cloudflare-Token widerrufen noch ein Gateway entfernen kann.

Zusammenfassung

Sie haben ein authentifiziertes Cloudflare AI Gateway erstellt und eine echte Workers-AI-Inference darüber geroutet. Sie haben die Gateway-Autorisierung von der Autorisierung des Upstream-Modells getrennt gehalten, nur eine Zugangsdaten geändert, um die ablehnende Grenze zu bestimmen, und die erfolgreiche Anfrage mit ihrem Gateway-Protokoll verknüpft. Schließlich haben Sie die authentifizierte Löschung der Ressource nachgewiesen, bevor Sie das Token gelöscht und die VM abgemeldet haben.

Das nächste Lab baut auf diesem beobachtbaren Anfragepfad auf. Sie fügen kleine nicht geheime Metadaten hinzu, verfolgen einen absichtlich ausgelösten Fehler und verwenden Nachweise aus dem Gateway, statt zu vermuten, an welcher Stelle eine Anfrage fehlgeschlagen ist.

Inference über ein Gateway routen