Workers-AI-Anfragen mit einem Modell-Fallback wiederherstellen

Einführung

Ein KI-Modell kann vorübergehend nicht verfügbar oder überlastet sein oder Eingaben erhalten, die es nicht versteht. Ein Fallback stellt einer Anwendung eine geplante Alternative bereit, anstatt sofort einen Fehler zurückzugeben. Ein sinnvoller Fallback ist begrenzt: Er besitzt eine kurze, geordnete Liste und einen eindeutigen Endpunkt. Er darf nicht unbegrenzt wiederholen oder nach dem ersten Erfolg jedes weitere Modell aufrufen.

Sie stellen einen kleinen Cloudflare Worker mit zwei Pfaden bereit. Der Fallback-Pfad sendet absichtlich eine Chat-Eingabe an ein Embedding-Modell, fängt diese vorhersehbare Inkompatibilität ab und ruft anschließend ein Chat-Modell auf. Der funktionierende Pfad ruft ein kompatibles primäres Chat-Modell auf und beendet den Ablauf. Jeder Versuch läuft über dasselbe AI Gateway. Die Protokolle zeigen daher, welches Modell fehlgeschlagen ist und welches Modell die Anfrage abgeschlossen hat.

Wenn Sie diesen Kurs direkt geöffnet haben, absolvieren Sie zuerst LabEx mit Ihrem Cloudflare-Konto verbinden. Dort lernen Sie das LabEx-Terminal, die Wrangler-Geräteautorisierung, die Kontenauswahl und die Konto-ID kennen. Absolvieren Sie außerdem zuerst Route Inference Through a Gateway, da dieses Lab auf dessen Gateway- und Workers-AI-Konzepten aufbaut.

Das Lab verwendet von Cloudflare gehostete Workers-AI-Modelle und das Workers-AI-Binding. Workers Paid, ein Schlüssel für einen externen Anbieter und der veraltete Universal Endpoint sind nicht erforderlich. Der kontrollierte fehlgeschlagene Versuch wird vor der Inferenz abgelehnt, und jeder erfolgreiche Pfad erzeugt nur eine kurze Antwort. Wenn das gemeinsam genutzte tägliche Workers-AI-Kontingent nicht verfügbar ist, beenden Sie den Versuch, anstatt wiederholt Anfragen zu senden.

Das Setup installiert Node.js 22.22.0 und Wrangler 4.132.0 als lokale Projektabhängigkeit unter /home/labex/project/ai-gateway-fallback. Es bereitet unabhängige Prüfungen vor, autorisiert Wrangler jedoch nicht, erstellt keine Cloud-Ressourcen, stellt keinen Worker bereit und sendet keinen Modellverkehr. LabEx zerstört die VM nach dem Lab. Sie müssen den Remote-Worker, das Gateway und das API-Token trotzdem löschen, da durch das Zerstören einer VM keine Cloud-Ressourcen entfernt werden.

Die VM autorisieren und den Wiederherstellungspfad benennen

Jedes Lab startet in einer neuen VM. In diesem Schritt autorisieren Sie Wrangler für Ihr Lernkonto und speichern eindeutige Namen für ein Gateway, einen Worker und ein temporäres Token.

cd /home/labex/project/ai-gateway-fallback
npx wrangler --version
npx wrangler login --device --browser=false

Öffnen Sie den angezeigten Link, geben Sie den Code ein und autorisieren Sie das vorgesehene Lernkonto. Wrangler fordert die später in diesem Lab benötigten Berechtigungen für die Worker-Bereitstellung und Workers AI an. Prüfen Sie vor der Bestätigung das angezeigte Konto. Untersuchen Sie anschließend die strukturierten Identitätsdaten:

npx wrangler whoami --json

Erwarten Sie Wrangler 4.132.0 und loggedIn: true. Ersetzen Sie YOUR_ACCOUNT_ID durch die tatsächliche 32-stellige ID, die für das vorgesehene Konto angezeigt wird:

GATEWAY_ID="labex-c09-g05-$(openssl rand -hex 6)"
WORKER_NAME="${GATEWAY_ID/g05/g05-worker}"
TOKEN_NAME="$GATEWAY_ID-token"
cat > .labex/state.json <<JSON
{
  "accountId": "YOUR_ACCOUNT_ID",
  "gatewayId": "$GATEWAY_ID",
  "workerName": "$WORKER_NAME",
  "tokenName": "$TOKEN_NAME"
}
JSON
cat .labex/state.json

Diese Bezeichner sind keine Geheimnisse. Durch das Speichern können Sie bei späteren Prüfungen und beim Aufräumen gezielt nur die Ressourcen dieses Labs ansprechen.

Ein beobachtbares AI Gateway erstellen

In diesem Schritt erstellen Sie den gemeinsamen Prüfpunkt, der beide Modellrouten protokolliert.

Ein AI Gateway ist ein benannter Prüfpunkt zwischen einer Anwendung und den Modellaufrufen. Es stellt für mehrere Versuche einen gemeinsamen Ort für Protokolle und Metadaten bereit, auch wenn die Anwendung das Modell wechselt.

Öffnen Sie das Cloudflare Dashboard und wählen Sie AI → AI Gateway → Create a custom gateway. Verwenden Sie die gespeicherte gatewayId. Lassen Sie Collect Logs und Authenticated Gateway aktiviert. Deaktivieren Sie Caching, Rate Limits, Retries und Spend Limits, und lassen Sie die Abrechnung für Workers AI auf Standard. Erstellen Sie anschließend das Gateway.

Das gespeicherte Gateway aktiviert Protokollierung und authentifizierten Zugriff

Öffnen Sie My Profile → API Tokens, wählen Sie Create Token → Create Custom Token und verwenden Sie den gespeicherten tokenName. Fügen Sie die Kontoberechtigungen AI Gateway — Edit und AI Gateway — Run hinzu und beschränken Sie sie auf das vorgesehene Lernkonto. Mit diesem temporären Token kann das Lab nur sein Gateway auslesen und später löschen. Das AI-Binding des bereitgestellten Workers enthält dieses Token nicht.

Kopieren Sie nach dem Erstellen des Tokens aus Cloudflares einmalig angezeigtem Prüfungsbefehl nur den Wert hinter Bearer und speichern Sie ihn mit einer verdeckten Eingabe:

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
'

Lesen Sie anschließend nur die wichtigen, nicht geheimen Einstellungen aus:

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" \
  > .labex/gateway.json
unset GATEWAY_TOKEN
node -e 'const g=require("./.labex/gateway.json").result; console.log({id:g.id,collect_logs:g.collect_logs,authentication:g.authentication})'

Erwarten Sie die gespeicherte Gateway-ID. Beide Werte müssen auf true gesetzt sein.

Einen Worker mit zwei Versuchen definieren

In diesem Schritt schreiben Sie die Wiederherstellungsrichtlinie in normalem Worker-Code. Die Richtlinie enthält zwei explizite Aufrufe statt einer Schleife. Dadurch sind maximale Kosten und Latenz leicht erkennbar.

Der erste Aufruf im Fallback-Pfad verwendet ein Embedding-Modell. Embedding-Modelle wandeln Text in Zahlenvektoren um; sie akzeptieren keine Chat-messages. Eine Eingabe in Chat-Form erzeugt vor der Inferenz einen sicheren, deterministischen Kompatibilitätsfehler. Der catch-Block protokolliert diesen Fehler und ruft anschließend ein kompatibles Chat-Modell auf.

GATEWAY_ID=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).gatewayId')
WORKER_NAME=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).workerName')
cat > wrangler.jsonc <<JSON
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-09-17",
  "ai": { "binding": "AI" }
}
JSON
cat > src/index.js <<JS
export default {
  async fetch(request, env) {
    const healthy = new URL(request.url).pathname === "/healthy";
    const attempts = [];
    const gateway = {
      gateway: {
        id: "$GATEWAY_ID",
        metadata: {
          lab: "g05-fallback",
          mode: healthy ? "healthy" : "fallback",
          synthetic: true
        }
      }
    };

    if (!healthy) {
      try {
        await env.AI.run(
          "@cf/baai/bge-small-en-v1.5",
          { messages: [{ role: "user", content: "Reply with ROUTE OK" }] },
          gateway
        );
        attempts.push({ model: "@cf/baai/bge-small-en-v1.5", status: "unexpected-success" });
      } catch (error) {
        attempts.push({
          model: "@cf/baai/bge-small-en-v1.5",
          status: "failed",
          reason: String(error).slice(0, 180)
        });
      }
    }

    const selectedModel = healthy
      ? "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
      : "@cf/meta/llama-3.2-3b-instruct";
    const result = await env.AI.run(
      selectedModel,
      { prompt: "Reply with exactly: ROUTE OK", max_tokens: 12 },
      gateway
    );
    attempts.push({ model: selectedModel, status: "succeeded" });

    return Response.json({
      mode: healthy ? "healthy-primary" : "fallback-recovery",
      usedFallback: !healthy,
      selectedModel,
      attempts,
      response: result.response
    });
  }
};
JS
npx wrangler deploy --dry-run

Das AI-Binding ermöglicht dem Worker den direkten Zugriff auf Workers AI. Die Option gateway leitet jeden Aufruf über das gespeicherte Gateway und fügt ausschließlich synthetische Metadaten hinzu – niemals einen Prompt, ein Anmeldedatum oder eine Personenkennung.

Den Worker bereitstellen und den Fallback-Pfad ausführen

In diesem Schritt stellen Sie den Worker bereit und lösen den kontrollierten Wiederherstellungsfall einmal aus.

Stellen Sie den Worker bereit und speichern Sie Wranglers Ausgabe, damit der Test genau die URL verwendet, die Ihrem Konto zugewiesen wurde:

npx wrangler deploy 2>&1 | tee .labex/deploy-output.txt
WORKER_URL=$(grep -Eo 'https://[^ ]+\.workers\.dev' .labex/deploy-output.txt | tail -1)
printf '%s\n' "$WORKER_URL" | tee .labex/worker-url.txt

Die workers.dev-Route kann nach einer erfolgreichen Bereitstellung einige Sekunden benötigen, bis sie verfügbar ist. Prüfen Sie die URL, ohne zusätzlichen Modellverkehr zu erzeugen: Ein 404 bedeutet lediglich, dass die Edge-Route noch nicht bereit ist. Die Schleife endet bei der ersten 200-Antwort.

WORKER_URL=$(cat .labex/worker-url.txt)
for attempt in $(seq 1 12); do
  STATUS=$(curl --http1.1 -sS -o .labex/fallback-response.json -w '%{http_code}' "$WORKER_URL/fallback")
  printf 'attempt %s: HTTP %s\n' "$attempt" "$STATUS"
  [ "$STATUS" = 200 ] && break
  [ "$attempt" -eq 12 ] && exit 1
  sleep 5
done
python3 -m json.tool < .labex/fallback-response.json

Erwarten Sie usedFallback: true, zwei Versuche, das als failed markierte Embedding-Modell und @cf/meta/llama-3.2-3b-instruct mit dem Status succeeded. Der genaue Wortlaut der generierten Antwort wird nicht bewertet; entscheidend ist die Routenentscheidung.

Nachweisen, dass ein funktionierendes primäres Modell früh beendet

In diesem Schritt zeigen Sie, dass ein erfolgreiches primäres Modell einen unnötigen Fallback-Aufruf verhindert.

Ein Fallback ist nur dann korrekt, wenn er bei einem funktionierenden primären Pfad nicht eingreift. Der Pfad /healthy startet mit einem kompatiblen Chat-Modell. Daher sollte er genau einen Versuch ausführen und anschließend stoppen.

WORKER_URL=$(cat .labex/worker-url.txt)
curl --http1.1 -fsS "$WORKER_URL/healthy" \
  | tee .labex/healthy-response.json \
  | python3 -m json.tool

Erwarten Sie usedFallback: false, @cf/meta/llama-3.3-70b-instruct-fp8-fast als selectedModel und genau einen erfolgreichen Versuch. Dieses Verhalten wird als short-circuit bezeichnet: Ein Erfolg beendet die Route sofort.

Die Route aus den Gateway-Protokollen ablesen

In diesem Schritt verknüpfen Sie die JSON-Ergebnisse des Workers mit unabhängigen Nachweisen aus dem AI Gateway.

Die Worker-Antwort beschreibt das Verhalten der Anwendung. Die AI-Gateway-Protokolle liefern unabhängige Nachweise auf Anbieterseite. Es kann einige Sekunden dauern, bis die Protokolle erscheinen. Warten Sie daher kurz und geben Sie nur die für das Routing relevanten Felder aus:

sleep 8
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 rows=require('./.labex/logs.json').result||[];
const meta=row=>{try{return typeof row.metadata==='string'?JSON.parse(row.metadata):(row.metadata||{})}catch{return {}}};
console.table(rows.filter(row=>meta(row).lab==='g05-fallback').map(row=>({
  mode:meta(row).mode, model:row.model, success:row.success, status:row.status_code
})));
NODE

Öffnen Sie im Dashboard die Seite Logs des Gateways. Die Fallback-Gruppe sollte eine fehlgeschlagene Zeile für das Embedding-Modell und eine erfolgreiche Zeile für das Fallback-Modell enthalten. Die gesunde Gruppe sollte nur das erfolgreiche primäre Chat-Modell enthalten.

Gateway-Protokolle zeigen den fehlgeschlagenen primären Versuch, gefolgt vom erfolgreichen Fallback

Die gesunde Anfrage enthält ein erfolgreiches Protokoll für genau ein primäres Modell

Die Metadaten mode verknüpfen die Zeilen, ohne einen Prompt oder ein Geheimnis einzuschließen. Modell, Erfolg und Status erklären die Route; Der erzeugte Text allein kann das nicht.

Den Vertrag für die begrenzte Wiederherstellung prüfen

In diesem Schritt vergleichen Sie beide Pfade und bestimmen die maximale Anzahl der Modellversuche.

Sie verfügen jetzt über drei übereinstimmende Beweisformen:

Der Quelltext enthält zwei explizite Aufrufe von env.AI.run() und keine Wiederholungsschleife.
/fallback meldet einen Fehler, gefolgt von einem Erfolg.
/healthy meldet einen Erfolg und beendet den Ablauf.

Geben Sie aus den gespeicherten Antworten einen kompakten Vergleich aus:

node - <<'NODE'
for (const name of ['fallback','healthy']) {
  const body=require(`./.labex/${name}-response.json`);
  console.log(name, {
    usedFallback: body.usedFallback,
    selectedModel: body.selectedModel,
    attemptCount: body.attempts.length,
    statuses: body.attempts.map(item=>item.status)
  });
}
NODE

Das Maximum beträgt zwei Versuche. Wenn auch der Fallback fehlschlägt, gibt der Worker einen Fehler zurück, anstatt die Route neu zu starten. In einer Produktionsanwendung könnten Sie ein Timeout, einen Circuit Breaker oder einen benutzerfreundlichen Fehler ergänzen. Jeder zusätzliche Wiederherstellungsmechanismus sollte jedoch weiterhin unabhängig begrenzt und beobachtbar sein.

Die temporären Ressourcen entfernen

In diesem Schritt löschen Sie jede von diesem Lab erstellte Remote-Ressource und entfernen die lokale Autorisierung.

Löschen Sie zuerst den Worker, damit er keinen weiteren Gateway-Verkehr erzeugen kann. Löschen Sie anschließend nur das in state.json gespeicherte Gateway:

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')
WORKER_NAME=$(node -p 'JSON.parse(require("fs").readFileSync(".labex/state.json")).workerName')
GATEWAY_TOKEN=$(cat .labex/gateway-token)
npx wrangler delete --name "$WORKER_NAME" --force
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" \
  > .labex/delete-gateway.json
unset GATEWAY_TOKEN
node -p 'require("./.labex/delete-gateway.json").success'

Erwarten Sie true. Solange beide temporären Autorisierungen in dieser VM noch existieren, speichern Sie unabhängige Nachweise für das Fehlen des Workers und des Gateways:

set +e
npx wrangler deployments list --name "$WORKER_NAME" --json \
  > .labex/worker-after-delete.json 2> .labex/worker-absent.err
printf '%s\n' "$?" > .labex/worker-absent-status.txt
set -e
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
GATEWAY_ID="$GATEWAY_ID" node - <<'NODE'
const rows=require('./.labex/gateways-after-delete.json').result||[];
console.log('gateway absent:', !rows.some(row=>row.id===process.env.GATEWAY_ID));
NODE
grep -Ei '10090|10007|script_not_found|does not exist' .labex/worker-absent.err

Erwarten Sie gateway absent: true und eine Antwort, die das Fehlen des Workers bestätigt, beispielsweise script_not_found, den Code 10090, den Code 10007 oder does not exist. Wrangler kann für dasselbe fehlende Script unterschiedliche Fehlerformate verwenden. Netzwerk- und Authentifizierungsfehler sind kein Nachweis für eine erfolgreiche Löschung.

Öffnen Sie nun My Profile → API Tokens und löschen Sie den exakt gespeicherten tokenName. Entfernen Sie anschließend die VM-Kopie des Tokens und melden Sie sich ab:

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

Erwarten Sie loggedIn: false. Das spätere Löschen der VM entfernt zwar lokale Dateien, aber nur diese Befehle entfernen die Remote-Ressourcen und widerrufen die Autorisierung.

Zusammenfassung

Sie haben einen begrenzten Wiederherstellungspfad mit zwei von Cloudflare gehosteten Modellen erstellt. Ein kontrollierter, inkompatibler primärer Versuch ist fehlgeschlagen, ein Fallback-Modell hat die Anfrage erfolgreich verarbeitet, und ein funktionierendes primäres Modell hat nach einem einzigen Aufruf beendet. Die AI-Gateway-Protokolle haben die Entscheidungen der Anwendung mit modell- und statusbezogenen Nachweisen auf Anbieterseite verknüpft. Außerdem haben Sie gelernt, warum explizite Versuchslimits, sichere Metadaten und überprüftes Aufräumen zu einem zuverlässigen Fallback-Design gehören.

Mit einem Modell-Fallback wiederherstellen