Ausweichstrategie für KI-APIs: Fehlermatrix für Anbieter

Phasenbasierte Richtlinie für Wiederholungen, Ausweichrouten mit gleichem Vertrag, Abbruch, Abgleich von Nebenwirkungen und Routenuntersuchung.

Ausweichstrategie für KI-APIs: Fehlermatrix für Anbieter

Ein Wiederholungsversuch für eine KI-API, ein Routenwechsel und ein Modellaustausch sind drei verschiedene Aktionen. Der Wiederholungsversuch startet unter demselben Vertrag erneut. Beim Routenwechsel werden angefordertes Modell und Protokoll über einen anderen geeigneten Pfad gesendet. Ein Modellaustausch ändert das Modell und damit möglicherweise Qualität, Preis, Latenz, Werkzeugverhalten, Kontextgrenzen und Ausgabeformat.

Eine belastbare Richtlinie entscheidet bereits vor einem Vorfall, welche Aktion erlaubt ist. Maßgeblich sind Fehlerklasse, Antwortphase, Idempotenz der gesamten Operation und die Zahl der Versuche, die noch in die Frist des Nutzers passen.

Wiederholungsversuch, Routenwechsel und Modellaustausch trennen

Verwenden Sie in Konfiguration, Protokollen und Betriebshandbüchern eindeutige Begriffe.

Aktion Was sich ändert Geeigneter Zweck Hauptrisiko
Wiederholung auf derselben Route Zeitpunkt und Versuchsnummer Kurzen vorübergehenden Fehler derselben Route überbrücken Zusätzliche Last auf einer gestörten Abhängigkeit
Alternativroute mit gleichem Vertrag Anbieterkanal, Konto oder geordnete Gruppe Modell und Protokoll trotz ausgefallenem Pfad erhalten Verdeckte Unterschiede angeblich gleichwertiger Routen
Modellaustausch Modell-ID oder benannte Modellrichtlinie Produktseitig genehmigter Kompromiss bei Qualität, Kosten oder Verfügbarkeit Stille Änderung von Verhalten und Abrechnung

Bezeichnen Sie nicht alle drei Aktionen als „Wiederholung“. Der Betrieb muss erkennen, ob eine Anfrage wiederholt, auf eine andere Route verschoben oder von einem anderen Modell beantwortet wurde. Für Nutzer muss ein Modellaustausch ein ausdrücklicher Produktvertrag sein, kein unsichtbarer Notbehelf.

Manche Gateways unterstützen geordnete Anbieter- oder Modellschritte. Die Cloudflare-Dokumentation zu Alternativrouten weist etwa den erfolgreichen Schritt aus. Entscheidend ist nicht die konkrete Anbieterrichtlinie, sondern ein Nachweis für jeden Versuch bei jedem Routenwechsel.

Vor einer Wiederholung vier Voraussetzungen prüfen

Ein Statuscode allein ist keine Richtlinie für Wiederholungen. Prüfen Sie:

  1. Fehlerklasse: Ist der Fehler vorübergehend, dauerhaft, vom Aufrufer verursacht oder im Ergebnis mehrdeutig?
  2. Antwortphase: Trat er vor den Headern, vor einer wirksamen Ausgabe oder nach ausgeliefertem Inhalt auf?
  3. Idempotenz: Kann die vollständige Operation ohne doppelte Nebenwirkung wiederholt werden?
  4. Versuchsbudget: Bleiben genügend reale Zeit und ein freier Versuch?

Die Wiederholungsstrategie von Google Cloud trifft dieselben Grundunterscheidungen für allgemeine APIs: Die Antwort zeigt, ob ein weiterer Versuch sinnvoll sein kann; die Idempotenz entscheidet, ob er sicher ist. 408, 429, 5xx, Socket-Zeitüberschreitungen und Verbindungsabbrüche sind häufig vorübergehend, für nicht idempotente Operationen gelten jedoch strengere Bedingungen.

In einem KI-Arbeitsablauf endet die Idempotenz nicht bei der HTTP-Anfrage an das Modell. Eine wiederholte Anweisung kann dieselbe E-Mail, Erstattung, Bereitstellung oder Datenbankänderung erneut vorschlagen. Jede Werkzeugausführung benötigt deshalb einen stabilen Idempotenzschlüssel und ein dauerhaft gespeichertes Ergebnis, selbst wenn die Inferenz nur lesend arbeitet.

Mit einer Fehlermatrix beginnen

Die folgende Matrix ist eine konservative Richtlinie für die Anwendung. Da das Gateway vor dem Endergebnis bereits intern auf einen anderen Kanal mit gleichem Vertrag wechseln kann, müssen beide Ebenen koordiniert werden.

Fehler oder Phase Wiederholung auf derselben Route Alternativroute mit gleichem Vertrag Stoppen oder untersuchen Begründung
Fehlerhafte Eingabe, nicht unterstütztes Feld oder ungültig aufgebaute Anfrage Nein Nein Anfrage korrigieren Derselbe ungültige Vertrag kann nicht erfolgreich werden
Authentifizierungs-, Berechtigungs-, Kontingent- oder Richtlinienfehler des Gateways Nein Nein Konto oder Richtlinie korrigieren Eine Anbieterroute darf die Gateway-Entscheidung nicht umgehen
Fehler bei Anbieterzugangsdaten oder -konto vor der Ausgabe Nicht auf der fehlerhaften Route Ja, mit geprüftem Kanal Kanal isolieren und untersuchen Beim Entfernen fehlerhafter Zugangsdaten bleibt der Nutzervertrag gleich
Netzwerkfehler oder 408 vor der Ausgabe Höchstens ein begrenzter Versuch bei Idempotenz Ja An der Frist stoppen Der Fehler kann vorübergehend sein, nach einem Verbindungsabbruch bleibt der Abschluss aber möglicherweise unklar
429 vor der Ausgabe Verzögert und unter Beachtung von Retry-After Ja, wenn eine gleichwertige Route Kapazität hat Bei ausgeschöpftem Budget stoppen Sofortige Wiederholung verstärkt die Ratenbegrenzung
500, 502, 503 oder 504 vor der Ausgabe Begrenzt mit wachsender Wartezeit Ja Wiederholte Routenfehler untersuchen Meist vorübergehend, aber kein Beweis für die Sicherheit jeder anderen Route
Anbieterantwort verletzt vor der Ausgabe an den Empfänger das Schema Meist nein Nur zu einer für dasselbe Schema geprüften Route Kompatibilität untersuchen Eine inkompatible Implementierung wird durch Wiederholung selten korrekt
Modellverweigerung oder richtlinienkonforme Antwort Nein Nein Ergebnis zurückgeben Eine gültige Verweigerung ist kein Infrastrukturfehler
Abbruch durch den Aufrufer oder 499 beim Empfänger Nein Nein Sofort stoppen Der Aufrufer benötigt die Arbeit nicht mehr
Teilweiser Datenstrom nach sichtbarem Inhalt oder Werkzeugargumenten Keine transparente Wiederholung Kein transparenter Routenwechsel Als teilweise abgeschlossen markieren; Anwendung entscheidet Ein neuer Datenstrom kann bereits gelieferte Ausgabe duplizieren oder ihr widersprechen
Werkzeugnebenwirkung mit unbekanntem Abschluss Erst nach Abgleich Erst nach Abgleich Idempotenzdatensatz oder Zielsystem abfragen Eine erneute Inferenz kann dieselbe Nebenwirkung erneut auslösen

Ein 503 vor jeder Ausgabe ist nicht dasselbe wie ein Verbindungsabbruch nach 400 sichtbaren Tokens.

Den Beginn des Datenstroms als Festschreibungsgrenze behandeln

Vor der Ausgabe an den Empfänger kann ein Gateway den fehlgeschlagenen Versuch verwerfen und eine andere Route wählen, ohne zwei Antworten auszuliefern. Nach dem ersten inhaltlich relevanten Byte ist eine transparente Wiederholung unsicher.

Ein neu gestarteter Datenstrom kann:

  • den Anfang wiederholen;
  • eine andere Fortsetzung erzeugen;
  • einen doppelten Funktionsaufruf mit neuer Aufruf-ID senden;
  • Nutzung und Kosten ohne klare Grenze verändern;
  • Ereignisse für den Client unzuordenbar machen.

Bricht der Datenstrom nach Beginn der Ausgabe ab, geben Sie einen endgültigen Teil- oder Transportfehler mit der ursprünglichen Anfrage-ID zurück. Die Anwendung kann einen ausdrücklichen neuen Versuch anbieten, an einem sicheren Kontrollpunkt fortsetzen oder die Teilausgabe verwerfen. Sie sollte keinen neuen Modelldatenstrom unsichtbar an den alten anhängen.

Für Funktionsaufrufe gilt eine noch strengere Grenze: Akzeptierte Aufruf-IDs und Ergebnisse ihrer Nebenwirkungen müssen dauerhaft gespeichert sein, bevor ein Wiederholungsversuch sie neu erzeugen kann. Der Vergleich der Funktionsaufrufformate verbindet Aufruf-IDs mit der Idempotenz der Anwendung.

Wartezeiten nach Versuchen und Gesamtzeit begrenzen

Exponentiell wachsende Wartezeiten verteilen die Versuche; eine zufällige Streuung verhindert synchrone Wiederholungen vieler Clients nach einem gemeinsamen Ausfall.

delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)

Ein gültiges Retry-After sollte beachtet werden, sofern es in die Nutzerfrist passt. Eine Wartezeit erteilt noch keine Wiederholungserlaubnis: Fehler- und Idempotenzvoraussetzungen müssen zuerst erfüllt sein.

Definieren Sie ein Gesamtbudget statt nur eines Zählers:

  • maximale Versuche pro Nutzeraktion;
  • maximale verstrichene Zeit einschließlich Warteschlange und Wartezeit;
  • Versuche vor und nach der Auswahl einer Alternativgruppe;
  • Restzeit, die für eine nützliche Antwort erforderlich ist;
  • Weitergabe eines Abbruchs durch den Aufrufer an jeden aktiven Versuch.

Bei einer interaktiven Frist von 15 Sekunden sind drei Versuche mit je 10 Sekunden keine ausführbare Richtlinie. Stapelaufträge dürfen länger laufen, benötigen aber ebenfalls eine endgültige Frist und eine dauerhafte Auftrags-ID.

Verstärkung von Wiederholungen über mehrere Ebenen verhindern

Wenn das SDK dreimal versucht, das Gateway pro Client-Versuch drei Routen nutzt und ein vorgeschalteter Proxy jede Route zweimal aufruft, gilt:

3 Client-Versuche × 3 Gateway-Versuche × 2 Upstream-Versuche = 18 Anbieteraufrufe

Eine Nutzeraktion erzeugt 18 Anbieteraufrufe. Während eines Ausfalls steigen Warteschlangen, Ratenbegrenzungen, Kosten und Wiederherstellungszeit.

Verteilen Sie die Verantwortung für Wiederholungen bewusst:

  • Das Gateway übernimmt den unmittelbaren Wechsel auf einen anderen Kanal mit gleichem Vertrag.
  • Die Anwendung entscheidet über die Wiederholung der vollständigen Nutzeraktion.
  • Automatische SDK-Wiederholungen werden deaktiviert oder begrenzt, wenn das Gateway bereits erneut versucht.
  • Asynchrone Aufträge nutzen eine dauerhafte Auftrags-ID und ein Versuchsprotokoll.
  • Nach einem Abbruch durch den Aufrufer startet keine Ebene einen neuen Versuch.

Protokollieren Sie die Versuchsnummer dieser Ebene und eine stabile Anfrage-ID über die gesamte Verarbeitungskette. Andernfalls sieht jede Komponente nur zwei oder drei Versuche, während die gesamte Verstärkung verborgen bleibt.

Vertragstreue einer Alternativroute nachweisen

Ein identischer öffentlicher Modellname beweist kein identisches Verhalten. Vor der Aufnahme in eine transparente Gruppe von Alternativrouten sind folgende Nachweise nötig:

Vertragsbereich Erforderliche Evidenz
Modellidentität Das angeforderte Modell ist ohne stille Zuordnung zu einem anderen Modell verfügbar
Endpunkt Konfigurierte Anfragen an Responses oder Chat Completions werden akzeptiert
Streaming Ereignistypen, Abschluss, Nutzung und Abbruch funktionieren
Strukturierte Ausgabe Der benötigte Teilumfang von JSON Schema und der strikte Modus funktionieren
Funktionsaufrufe Werkzeuge, Aufruf-IDs, gestreamte Argumente und Ergebnisse funktionieren in beide Richtungen
Grenzen Kontext, Ausgabe, Rate und Parallelität passen zur Arbeitslast
Fehler Status und Fehlertexte sind klassifizierbar, ohne Geheimnisse offenzulegen
Nutzung und Kosten Tokens, Cache-Felder, Dienststufe und Preisrichtlinie sind geklärt
Sicherheit und Region Richtlinie, Datenpfad und Anforderungen an den Speicherort bleiben konform

Scheitert eine Route in einem Pflichtbereich, ist sie für diese Arbeitslast keine transparente Alternative. Unter einer separaten ausdrücklichen Produktrichtlinie kann sie dennoch verwendet werden.

Ein anderes Modell ist immer eine Produktentscheidung. Definieren Sie erlaubte Modelle, Mindestqualität, Preisobergrenze, Werkzeugvertrag und den sichtbaren Hinweis an Nutzer. Ein Routenfehler rechtfertigt keinen stillen Wechsel auf ein billigeres oder schwächeres Modell.

Die aktuelle Routenwechsel-Logik von Modelflare verstehen

Modelflare sucht geeignete Pfade für das vom API-Client angeforderte Modell. Ein normaler API-Schlüssel hat eine Hauptgruppe und optional geordnete Alternativgruppen. Ein intelligenter API-Schlüssel bewertet verfügbare Gruppen anhand seiner Routingstrategie. Beide Mechanismen dürfen das angeforderte Modell nicht still ersetzen.

Die RPM-Zulassung auf Gruppenebene erfolgt vor Abrechnung und Anbieteranfrage. Ist die Gruppe ausgelastet, kann eine geordnete Alternativgruppe oder ein Kandidat der intelligenten Routenwahl geprüft werden; ohne geeignete Gruppe folgt 429.

Innerhalb einer Gruppe legt die Kanalpriorität die Reihenfolge des Kontowechsels fest. Nach einem Anbieterfehler wird der fehlerhafte Kanal ausgeschlossen und die Auswahl fortgesetzt. Der aktuelle Kanalwechsel ist unabhängig von RetryTimes und AutomaticRetryStatusCodes; er stoppt bei Erfolg, erschöpften Routen, Abbruch durch den Aufrufer oder begonnener Ausgabe an den Empfänger.

Das sind interne Pfadentscheidungen für dasselbe Modell und keine Erlaubnis für eine unbegrenzte Client-Schleife. Zuverlässiges Routing für KI-APIs behandelt Gruppen- und Kanaldesign; Fehlerbehebung bei KI-APIs trennt Gateway-Richtlinienfehler von Anbieterfehlern.

Nachweise für jeden Versuch erhalten

Ein finales 200 beweist nicht, dass die erste Route erfolgreich war. Eine finale Kanal-ID beschreibt fehlgeschlagene Versuche nicht. Speichern Sie mindestens:

  • stabile Anfrage-ID und für den Aufrufer sichtbare Korrelations-ID;
  • Versuchsfolge und Gruppen-/Kanalreferenz;
  • Modell und Endpunktvertrag je Versuch;
  • Fehlerstatus, Fehlerklasse und Datenstromphase;
  • ob die Ausgabe an den Empfänger begonnen hatte;
  • Zeitmarken und Abbruchstatus;
  • verfügbare Nutzung für Eingabe, Ausgabe und zwischengespeicherte Tokens;
  • Kostenzuordnung je abgeschlossenem oder abrechenbarem Versuch;
  • Endgrund: Erfolg, Routen erschöpft, abgebrochen, teilweise abgeschlossen oder durch Richtlinie gestoppt.

Speichern Sie nicht allein für die Diagnose von Routenwechseln API-Schlüssel, unbearbeitete Anweisungen, rohe Antworten oder Anbieterzugangsdaten. Bereinigte Fehlerklassen und Zeitmetadaten reichen meist aus; eingeschränkte kurzlebige Anfragearchive gehören nur in ausdrücklich aktivierte Untersuchungen.

Die Richtlinie vor dem Produktivverkehr erproben

Führen Sie an den echten Protokollgrenzen und mit sicheren deterministischen Eingaben eine Übung in der Vorproduktionsumgebung durch:

  1. Hauptkanal vor den Headern deaktivieren und die nächste Route für dasselbe Modell prüfen;
  2. eine Ratenbegrenzung zurückgeben und Versuchsgrenzen sowie Retry-After prüfen;
  3. den Aufrufer abbrechen lassen und nachweisen, dass kein späterer Versuch beginnt;
  4. Datenstrom nach der Ausgabe unterbrechen und eine transparente Wiederholung ausschließen;
  5. eine ungültige Anfrage senden und prüfen, dass der Routenwechsel sie nicht verdeckt;
  6. den Werkzeugablauf wiederholen und genau eine Nebenwirkung nachweisen;
  7. alle Routen erschöpfen und einen eindeutigen Endfehler prüfen;
  8. Versuchsprotokoll prüfen und Nutzung sowie Kosten abgleichen.

Führen Sie die Richtlinie zuerst für eine kleine Arbeitslast ein. Beobachten Sie Anzahl der Versuche, Erfolg nach einem Routenwechsel und ungefilterte Erfolgsrate getrennt und halten Sie einen schnellen Weg bereit, gestörte Routen zu entfernen. Das Ziel sind nicht möglichst viele Routenwechsel, sondern eine sichere Wiederherstellung innerhalb einer begrenzten Frist bei unverändertem Modellvertrag und vollständigem Nachweis jedes Versuchs.