Strategia di ripetizione dei tentativi

Le librerie client dell'SDK Google Gen AI includono una logica di nuovi tentativi automatica con backoff esponenziale per la gestione di errori temporanei come timeout, problemi di rete e limiti di frequenza (codici di stato HTTP 429 e 5xx). Ad esempio, l'SDK Python ritenta automaticamente gli errori temporanei fino a quattro volte con un ritardo iniziale di circa 1 secondo e un ritardo massimo di 60 secondi. Anche se l'SDK gestisce questa operazione per impostazione predefinita, puoi configurare questo comportamento in modo che si adatti meglio al tuo workload specifico.

Determinare quando riprovare

Prima di implementare una strategia di nuovi tentativi personalizzata, valuta in che modo la selezione dell'endpoint, il modello di pagamento e il workload influiscono sulle tue esigenze.

Scegliere l'endpoint giusto

  • Endpoint globale: consigliato per la disponibilità. L'endpoint globale instrada il traffico in modo dinamico, il che può ridurre la necessità di nuovi tentativi lato client causati da problemi di capacità regionali.
  • Endpoint regionali: limitati a una località specifica. Se una regione è sovraccarica, i nuovi tentativi immediati potrebbero non riuscire; valuta invece le strategie di failover.

Regolare il modello di pagamento

  • **Pagamento a consumo standard**: utilizza risorse condivise. Utilizza il backoff esponenziale per gestire gli errori temporanei di limite di frequenza (429) causati da picchi di traffico.
  • **Pagamento a consumo flessibile**: progettato per l'elaborazione più lenta e a priorità inferiore. Non riprovare in modo aggressivo; aumenta invece il timeout della richiesta (ad esempio, a 30 minuti) per dare al sistema il tempo di completare l'attività.
  • **Pagamento a consumo con priorità**: progettato per workload sensibili alla latenza e ad alta affidabilità senza l'impegno iniziale del Throughput riservato. Se ricevi un errore 429 in questo livello, riprova con il backoff esponenziale, ma assicurati di non superare la quota.
  • Throughput riservato: utilizza la capacità riservata. Gli errori frequenti in genere indicano che hai superato la capacità acquistata, quindi l'aggiunta di nuovi tentativi potrebbe non risolvere il problema sottostante.

Definire la tolleranza alla latenza

  • In tempo reale (ad es. chat): fail fast. Limita il numero di tentativi di nuovi tentativi in modo che gli utenti non debbano attendere indefinitamente una risposta.
  • Inferenza batch: non riprovare i singoli elementi. Il servizio Batch gestisce automaticamente i nuovi tentativi per le singole richieste all'interno del job per ottenere una percentuale di completamento elevata. La tua unica responsabilità è di inviare correttamente il job una sola volta. Per ulteriori informazioni, consulta la sezione Previsioni in batch.

Identificare gli errori che possono essere riprovati

Esistono due fattori principali che determinano se è sicuro riprovare una richiesta:

Risposta

Il codice di errore o la risposta ricevuta indica se il problema è temporaneo o permanente. Le risposte relative a problemi temporanei sono in genere riprovabili. Questi includono:

  • Codici HTTP: 408 (Request Timeout), 429 (Too Many Requests) e 5xx (Server Errors).
  • Problemi di rete: timeout dei socket e disconnessioni TCP.

Per ulteriori informazioni, consulta la sezione Errori API.

Idempotenza

Le richieste idempotenti possono essere eseguite ripetutamente senza modificare lo stato finale della risorsa. Quando determini l'idempotenza, tieni presente quanto segue:

  • Sempre idempotente: operazioni di elenco (non modificano le risorse), richieste di recupero, richieste di conteggio dei token e richieste di incorporamento.
  • Mai idempotente: operazioni che creano risorse univoche ogni volta che hanno esito positivo, ad esempio la creazione di un nuovo modello ottimizzato.
  • Sfida dell'AI generativa: anche se generateContent non è strettamente idempotente a causa della natura stocastica dei modelli generativi, in genere è sicuro riprovare in caso di errori temporanei, in quanto non modifica lo stato lato server.

Configurare i nuovi tentativi

L'SDK Google Gen AI ti consente di configurare il comportamento dei nuovi tentativi tramite i parametri client o HttpRetryOptions.

Parametri principali

  • initial_delay: il ritardo iniziale in secondi prima del primo nuovo tentativo (valore predefinito: 1.0).
  • attempts: il numero massimo di tentativi di nuovi tentativi (valore predefinito: 5).
  • exp_base: la base per il calcolo del backoff esponenziale (valore predefinito: 2).
  • max_delay: il ritardo massimo in secondi tra i nuovi tentativi (valore predefinito: 60).
  • jitter: un fattore per aggiungere un ritardo casuale al backoff (valore predefinito: 1).
  • http_status_codes: un elenco di codici di stato che attivano un nuovo tentativo.

Esempi

Configurazione a livello di client

Puoi impostare le opzioni a livello globale durante l'inizializzazione del client.

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();

Configurazione a livello di richiesta

Puoi anche eseguire l'override delle impostazioni per una singola richiesta utilizzando il parametro config.

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,
        )
    )
)

Pagamento a consumo flessibile

Per il pagamento a consumo flessibile, il timeout predefinito è di 10 minuti a causa dell'elaborazione più lenta e del nuovo tentativo trasparente. Gli utenti possono aumentarlo a 30 minuti per una percentuale di successo migliore.

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 practice e anti-pattern

Se utilizzi i meccanismi di nuovi tentativi predefiniti, li personalizzi o implementi la tua logica di nuovi tentativi, segui queste best practice ed evita gli anti-pattern comuni.

Best practice

  • Utilizza il backoff esponenziale: attendi un breve periodo di tempo prima del primo nuovo tentativo (ad esempio, 1 secondo), quindi aumenta il ritardo in modo esponenziale (ad esempio, 2 secondi, 4 secondi, 8 secondi).
  • Aggiungi jitter: l'aggiunta di "jitter" casuale al ritardo impedisce a tutti i client di riprovare esattamente nello stesso momento.
  • Riprova in caso di errori specifici: riprova solo in caso di errori temporanei (429, 408, 5xx).
  • Imposta il numero massimo di nuovi tentativi: definisci un numero massimo di tentativi di nuovi tentativi per evitare loop infiniti.
  • Monitora e registra: registra i dettagli relativi ai tentativi di nuovi tentativi, ai tipi di errori e ai tempi di risposta per eseguire il debug della strategia.

Anti-pattern di nuovi tentativi

  • Riprovare senza backoff: riprovare immediatamente può causare errori a cascata e sovraccaricare il servizio.
  • Riprovare in caso di errori non riprovabili: non riprovare in caso di errori del client (4xx diversi da 429/408), in quanto indicano problemi come chiavi API non valide o sintassi errata.
  • Riprovare in modo incondizionato le operazioni non idempotenti: l'esecuzione ripetuta di operazioni non idempotenti può causare effetti collaterali, ad esempio risorse duplicate.
  • Ignorare i limiti di nuovi tentativi: riprovare indefinitamente può causare l'esaurimento delle risorse; imposta sempre un numero massimo di tentativi.

Passaggi successivi