Strategia di ripetizione

Le librerie client dell'SDK Google Gen AI includono una logica di ripetizione 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 carico di lavoro specifico.

Determinare quando riprovare

Prima di implementare una strategia di ripetizione personalizzata, valuta in che modo la selezione degli 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 indirizza 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.

Modificare in base al modello di pagamento

  • Standard pay-as-you-go: utilizza risorse condivise. Utilizza il backoff esponenziale per gestire gli errori temporanei di limite di frequenza (429) causati da picchi di traffico.
  • Flex pay-as-you-go: progettato per l'elaborazione più lenta e a bassa priorità. 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à.
  • Priorità con pagamento a consumo: progettato per workload sensibili alla latenza e ad alta affidabilità senza l'impegno iniziale del throughput di cui è stato eseguito il provisioning. Se ricevi un errore 429 in questo livello, riprova con un backoff esponenziale, ma assicurati di non superare la quota.
  • Throughput riservato: utilizza la capacità dedicata. Gli errori frequenti di solito indicano che hai superato la capacità acquistata, quindi l'aggiunta di tentativi non risolve il problema di fondo.

Definisci la tolleranza alla latenza

  • In tempo reale (ad esempio, chat): fail fast. Limita il numero di tentativi di ripetizione in modo che gli utenti non debbano attendere una risposta a tempo indeterminato.
  • Inferenza batch: non riprovare con i singoli elementi. Il servizio Batch gestisce automaticamente i nuovi tentativi per le singole richieste all'interno del job per ottenere un tasso di completamento elevato. La tua unica responsabilità è inviare correttamente la richiesta una sola volta. Per saperne di più, consulta Previsione batch.

Identificare gli errori non irreversibili

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 generalmente riproducibili. tra cui:

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

Per saperne di più, consulta 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 idempotenti: operazioni di elenco (non modificano le risorse), richieste di recupero, richieste di conteggio dei token e richieste di incorporamento.
  • Mai idempotenti: operazioni che creano risorse uniche ogni volta che vengono eseguite correttamente, ad esempio la creazione di un nuovo modello ottimizzato.
  • Sfumatura 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.

Configurazione dei tentativi

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

Parametri chiave

  • initial_delay: il ritardo iniziale in secondi prima del primo nuovo tentativo (valore predefinito: 1.0).
  • attempts: il numero massimo di tentativi di ripetizione (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 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,
        )
    )
)

Flex Pay-as-you-go

Per Flex Pay as you go, il timeout predefinito è di 10 minuti a causa dell'elaborazione più lenta e del nuovo tentativo trasparente. Gli utenti possono aumentare questo valore 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

Che tu stia utilizzando i meccanismi di ripetizione predefiniti, li stia personalizzando o stia implementando una logica di ripetizione personalizzata, segui queste best practice ed evita i modelli negativi 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 un "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 tentativi: definisci un numero massimo di tentativi per evitare loop infiniti.
  • Monitoraggio e logging: registra i dettagli relativi ai tentativi di ripetizione, ai tipi di errore e ai tempi di risposta per eseguire il debug della strategia.

Anti-pattern per i nuovi tentativi

  • Ripetizione dei tentativi senza backoff: la ripetizione immediata dei tentativi può causare errori a cascata e sovraccaricare il servizio.
  • Ripetizione degli errori non ripetibili: non ripetere gli errori del client (4xx diversi da 429/408) in quanto indicano problemi come chiavi API non valide o sintassi errata.
  • Ripetizione incondizionata di operazioni non idempotenti: l'esecuzione ripetuta di operazioni non idempotenti può portare a effetti collaterali, ad esempio risorse duplicate.
  • Ignorare i limiti di ripetizione dei tentativi: ripetere i tentativi all'infinito può causare l'esaurimento delle risorse. Imposta sempre un numero massimo di tentativi.

Passaggi successivi