Strategie für Wiederholungen

Die Clientbibliotheken des Google Gen AI SDK enthalten eine automatische Wiederholungslogik mit exponentiellem Backoff zur Behandlung vorübergehender Fehler wie Zeitüberschreitungen, Netzwerkprobleme und Ratenbeschränkungen (HTTP-Statuscodes 429 und 5xx). Das Python SDK wiederholt beispielsweise vorübergehende Fehler automatisch bis zu viermal mit einer anfänglichen Verzögerung von etwa 1 Sekunde und einer maximalen Verzögerung von 60 Sekunden. Das SDK übernimmt dies standardmäßig, Sie können das Verhalten aber so konfigurieren, dass es besser zu Ihrer jeweiligen Arbeitslast passt.

Wann sollte ein erneuter Versuch erfolgen?

Bevor Sie eine benutzerdefinierte Wiederholungsstrategie implementieren, sollten Sie berücksichtigen, wie sich die Endpunktauswahl, das Zahlungsmodell und die Arbeitslast auf Ihre Anforderungen auswirken.

Den richtigen Endpunkt auswählen

  • Globaler Endpunkt: Empfohlen für die Verfügbarkeit. Der globale Endpunkt leitet den Traffic dynamisch weiter, wodurch die Notwendigkeit von clientseitigen Wiederholungsversuchen aufgrund von regionalen Kapazitätsproblemen reduziert werden kann.
  • Regionale Endpunkte: Auf einen bestimmten Standort beschränkt. Wenn eine Region überlastet ist, können sofortige Wiederholungsversuche fehlschlagen. Erwägen Sie stattdessen Failover-Strategien.

An das Zahlungsmodell anpassen

  • Standard-Pay-as-you-go: Hier werden freigegebene Ressourcen verwendet. Verwenden Sie exponentiellen Backoff, um vorübergehende Ratenbegrenzungsfehler (429) zu beheben, die durch Trafficspitzen verursacht werden.
  • Flex „Pay as you go“: Für Verarbeitung mit niedrigerer Priorität und langsamerer Verarbeitung. Führen Sie keine aggressiven Wiederholungsversuche durch. Erhöhen Sie stattdessen das Zeitlimit für Anfragen (z. B. auf 30 Minuten), damit das System genügend Zeit hat, die Aufgabe abzuschließen.
  • Pay-as-you-go mit Priorität: Entwickelt für latenzempfindliche Arbeitslasten mit hoher Zuverlässigkeit ohne die Vorabverpflichtung von bereitgestelltem Durchsatz. Wenn Sie in dieser Stufe einen 429-Fehler erhalten, versuchen Sie es mit exponentiellem Backoff noch einmal. Achten Sie aber darauf, dass Sie Ihr Kontingent nicht überschreiten.
  • Bereitgestellter Durchsatz: Hier wird dedizierte Kapazität verwendet. Häufige Fehler deuten in der Regel darauf hin, dass Sie die gekaufte Kapazität überschritten haben. Das Hinzufügen von Wiederholungsversuchen löst das zugrunde liegende Problem möglicherweise nicht.

Latenztoleranz definieren

  • Echtzeit (z. B. Chat): Schnell scheitern. Begrenzen Sie die Anzahl der Wiederholungsversuche, damit Nutzer nicht unbegrenzt auf eine Antwort warten müssen.
  • Batchinferenz: Einzelne Elemente nicht noch einmal versuchen. Der Batch-Dienst verarbeitet automatisch Wiederholungsversuche für einzelne Anfragen innerhalb des Jobs, um eine hohe Abschlussrate zu erzielen. Ihre einzige Aufgabe besteht darin, den Job einmal erfolgreich einzureichen. Weitere Informationen finden Sie unter Batchvorhersage.

Wiederholbare Fehler erkennen

Es gibt zwei primäre Faktoren, die bestimmen, ob eine Anfrage sicher wiederholt werden kann:

Antwort

Der empfangene Fehlercode oder die empfangene Antwort gibt an, ob es sich um ein vorübergehendes oder dauerhaftes Problem handelt. Antworten auf vorübergehende Probleme sind in der Regel wiederholbar. Dazu gehören:

  • HTTP-Codes: 408 (Request Timeout), 429 (Too Many Requests) und 5xx (Server Errors).
  • Netzwerkprobleme: Socket-Zeitlimits und getrennte TCP-Verbindungen

Weitere Informationen finden Sie unter API-Fehler.

Idempotenz

Idempotente Anfragen können wiederholt ausgeführt werden, ohne den Endzustand der Ressource zu ändern. Berücksichtigen Sie bei der Bestimmung der Idempotenz Folgendes:

  • Immer idempotent: List-Vorgänge (sie ändern keine Ressourcen), get-Anfragen, Anfragen zur Tokenanzahl und Anfragen zu Einbettungen.
  • Nie idempotent: Vorgänge, bei denen jedes Mal, wenn sie erfolgreich sind, eindeutige Ressourcen erstellt werden, z. B. beim Erstellen eines neuen angepassten Modells.
  • Nuancen der generativen KI: Obwohl generateContent aufgrund der stochastischen Natur generativer Modelle nicht streng idempotent ist, kann bei vorübergehenden Fehlern in der Regel ein erneuter Versuch unternommen werden, da der serverseitige Status nicht geändert wird.

Wiederholungsversuche konfigurieren

Mit dem Google Gen AI SDK können Sie das Wiederholungsverhalten über Clientparameter oder HttpRetryOptions konfigurieren.

Wichtige Parameter

  • initial_delay: Die anfängliche Verzögerung in Sekunden vor dem ersten Wiederholungsversuch (Standard: 1.0).
  • attempts: Die maximale Anzahl von Wiederholungsversuchen (Standard: 5).
  • exp_base: Die Basis für die Berechnung des exponentiellen Backoff (Standard: 2).
  • max_delay: Die maximale Verzögerung zwischen Wiederholungsversuchen in Sekunden (Standard: 60).
  • jitter: Ein Faktor, mit dem der Backoff eine zufällige Verzögerung erhält (Standard: 1).
  • http_status_codes: Eine Liste von Statuscodes, die einen Wiederholungsversuch auslösen.

Beispiele

Konfiguration auf Clientebene

Sie können Optionen global festlegen, wenn Sie den Client initialisieren.

Python

from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=PROJECT_ID,
    location="global",
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(
            initial_delay=1.0,
            attempts=5,
            http_status_codes=[408, 429, 500, 502, 503, 504],
        ),
        timeout=120 * 1000,
    ),
)

Java

import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.HttpRetryOptions;

HttpOptions httpOptions = HttpOptions.builder()
  .retryOptions(
      HttpRetryOptions.builder()
          .attempts(5)
          .httpStatusCodes(408, 429, 500, 502, 503, 504).build())
  .build();

Client client = Client.builder()
  .project(PROJECT_ID)
  .location("global")
  .vertexAI(true)
  .httpOptions(httpOptions)
  .build();

Konfiguration auf Anfrageebene

Sie können Einstellungen für eine einzelne Anfrage auch mit dem Parameter config überschreiben.

Python

from google import genai
from google.genai import types

client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Tell me a joke about a rabbit.",
    config=types.GenerateContentConfig(
        http_options=types.HttpOptions(
            retry_options=types.HttpRetryOptions(
                initial_delay=1.0,
                attempts=10,
                http_status_codes=[408, 429, 500, 502, 503, 504],
            ),
            timeout=120 * 1000,
        )
    )
)

Flex Pay as you go

Bei Flex Pay-as-you-go beträgt das Standardzeitlimit 10 Minuten, da die Verarbeitung langsamer ist und Wiederholungsversuche transparent erfolgen. Nutzer können diesen Wert auf 30 Minuten erhöhen, um die Erfolgsrate zu verbessern.

Python

from google import genai
from google.genai import types

client = genai.Client(
  vertexai=True, project=PROJECT_ID, location='global',
  http_options=types.HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "flex" # Use Flex PayGo
      },
      timeout = 30 * 60 * 1000 # Increase to 30 minutes
  )
)

Best Practices und Antipatterns

Unabhängig davon, ob Sie die standardmäßigen Wiederholungsmechanismen verwenden, sie anpassen oder eine eigene Wiederholungslogik implementieren, sollten Sie diese Best Practices befolgen und häufige Antimuster vermeiden.

Best Practices

  • Exponentiellen Backoff verwenden: Warten Sie vor dem ersten Wiederholungsversuch kurz (z. B. 1 Sekunde) und erhöhen Sie dann die Verzögerung exponentiell (z. B. 2 Sekunden, 4 Sekunden, 8 Sekunden).
  • Jitter hinzufügen: Durch das Hinzufügen von zufälligem „Jitter“ zur Verzögerung wird verhindert, dass alle Clients genau zur selben Zeit einen Wiederholungsversuch starten.
  • Bei bestimmten Fehlern noch einmal versuchen: Versuchen Sie es nur bei vorübergehenden Fehlern (429, 408, 5xx) noch einmal.
  • Maximale Anzahl an Wiederholungsversuchen festlegen: Definieren Sie eine maximale Anzahl an Wiederholungsversuchen, um Endlosschleifen zu vermeiden.
  • Überwachen und protokollieren: Protokollieren Sie Details zu Wiederholungsversuchen, Fehlertypen und Antwortzeiten, um Ihre Strategie zu debuggen.

Antimuster für Wiederholungsversuche

  • Wiederholung ohne Backoff: Wenn Sie Anfragen sofort wiederholen, kann dies zu kaskadierenden Fehlern führen und den Dienst überlasten.
  • Nicht wiederholbare Fehler wiederholen: Wiederholen Sie keine Clientfehler (4xx außer 429/408), da sie auf Probleme wie ungültige API-Schlüssel oder eine fehlerhafte Syntax hinweisen.
  • Nicht idempotente Vorgänge bedingungslos wiederholen: Wenn Sie Vorgänge, die nicht idempotent sind, wiederholt ausführen, kann dies zu Nebeneffekten führen, z. B. zu doppelten Ressourcen.
  • Wiederholungslimits ignorieren: Unbegrenzte Wiederholungen können zu Ressourcenerschöpfung führen. Legen Sie immer eine maximale Anzahl von Versuchen fest.

Nächste Schritte