Timeouts, Ratenbegrenzung und Wiederholungen

SDK-Timeouts und begrenzte Wiederholungen konfigurierbar machen, wiederholbare Fehler von Konfigurationsfehlern unterscheiden und doppelte Übermittlungen vermeiden.

Behebe zuerst Konfigurationsfehler, dann behandle temporäre Ausfälle. Begrenze Wiederholungsanzahl, Parallelität und Gesamtwartezeit gemeinsam, um zu vermeiden, dass dieselbe fehlgeschlagene Anfrage innerhalb kurzer Zeit mehrfach erneut gesendet wird.

Wann wiederholen

Situation	Empfehlung
400 / 401 / 403 / 404	Zuerst Anfrage, Berechtigungen oder Modell korrigieren; die Originalanfrage nicht automatisch wiederholen
429	Antwortmeldung prüfen; bei `Retry-After` die Wartezeit beachten und Parallelität reduzieren
500 / 502 / 503 / 504 / 529	Begrenzt wiederholen; bei anhaltendem Fehlschlag stoppen und die Anfrage-ID zurückmelden
Verbindungsfehler	DNS, Proxy und Netzwerk prüfen und innerhalb der für die Aufgabe zulässigen Zeit begrenzt wiederholen
Timeout oder abgebrochener Stream nach dem Senden der Anfrage	Ergebnis kann unklar sein; zuerst Protokolle prüfen; nicht annehmen, dass der Upstream die Anfrage noch nicht verarbeitet hat

Der Wiederholungsbereich der Clientbibliotheken stimmt nicht unbedingt vollständig mit der obigen Tabelle überein. Auf welcher Ebene wiederholt wird, dort die Strategie explizit festlegen.

Zuerst die eingebauten SDK-Wiederholungen nutzen

Python und Node.js verwenden unterschiedliche Timeout-Einheiten: Python verwendet Sekunden, Node.js verwendet Millisekunden. Das folgende Beispiel setzt ein Timeout von 120 Sekunden und bis zu 2 automatische Wiederholungen; beim ersten Einrichten und Debugging kann auf 0 geändert werden.

Python
Node.js

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEZHE_API_KEY"],
    base_url="https://1zheai.com/v1",
    timeout=120.0,
    max_retries=2,
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ONEZHE_API_KEY,
  baseURL: "https://1zheai.com/v1",
  timeout: 120_000,
  maxRetries: 2,
});

Die Timeout-Konfiguration ist keine Obergrenze für die Gesamtdauer der gesamten Geschäftsaufgabe: Wiederholungen und Wartezeiten erhöhen die Gesamtdauer. Wenn die äußere Ebene die Aufgabe erneut ausführt, sollte zusätzlich eine Gesamt-Deadline und ein Abbruchmechanismus eingerichtet werden.

Beim eigenen Wiederholungsmechanismus

Deaktiviere die automatischen SDK-Wiederholungen, um Überschneidungen zu vermeiden. Verwende schrittweise steigende Warteintervalle mit zufälligem Jitter; begrenze die Anzahl der Versuche, die maximale Wartezeit und die Parallelität der Warteschlange explizit. Beim Parsen von Retry-After beachten, dass der Wert sowohl Sekunden als auch ein HTTP-Datum sein kann.

Wenn dem Nutzer bereits ein Teil des Streaming-Ergebnisses angezeigt wurde, nicht automatisch von vorn abspielen und an den alten Text anhängen. Den Status „unvollständig“ beibehalten und dem Nutzer die Entscheidung über Neugenerierung oder Fortsetzung überlassen.

Bei Bildgenerierung, Tool-Ausführung und anderen Aufgaben, die externe Ergebnisse erzeugen können, besondere Aufmerksamkeit auf doppelte Übermittlungen richten. Es kann nicht davon ausgegangen werden, dass die Einstellung einer beliebigen Anfrage-ID eine automatische Deduplizierung auf Serverseite bewirkt.

Ausreichend Debugging-Informationen protokollieren

Zeitpunkt, Endpunkt, Modell, Statuscode, Dauer, Versuchsnummer und die vom Server zurückgegebene Anfrage-ID protokollieren. Authentifizierungs-Header und vollständige private Prompts nicht protokollieren. Diese Informationen mit den Aufrufprotokollen abgleichen.

SDK-Einstellungen siehe OpenAI Python SDK und Node SDK. Konkrete Fehler siehe Fehlercodes und Debugging.