Repetir estratégia

As bibliotecas de cliente do SDK de IA generativa do Google incluem lógica de repetição automática com espera exponencial para lidar com erros temporários, como tempos limite, problemas de rede e limites de taxa (códigos de status HTTP 429 e 5xx). Por exemplo, o SDK para Python repete automaticamente erros temporários até quatro vezes com um atraso inicial de aproximadamente 1 segundo e um atraso máximo de 60 segundos. Embora o SDK faça isso por padrão, é possível configurar esse comportamento para se adequar melhor à sua carga de trabalho específica.

Como determinar quando tentar novamente

Antes de implementar uma estratégia de nova tentativa personalizada, considere como a seleção de endpoint, o modelo de pagamento e a carga de trabalho afetam suas necessidades.

Escolher o endpoint certo

  • Endpoint global: recomendado para disponibilidade. O endpoint global encaminha o tráfego de forma dinâmica, o que pode reduzir a necessidade de novas tentativas do lado do cliente causadas por problemas de capacidade regional.
  • Endpoints regionais: restritos a um local específico. Se uma região estiver sobrecarregada, as novas tentativas imediatas poderão falhar. Em vez disso, considere estratégias de failover.

Ajustar para seu modelo de pagamento

  • Pagamento por uso padrão: usa recursos compartilhados. Use a espera exponencial para lidar com erros temporários de limitação de taxa (429) causados por picos de tráfego.
  • Pagamento por uso flexível: projetado para processamento mais lento e de menor prioridade. Não tente novamente de forma agressiva. Em vez disso, aumente o tempo limite da solicitação (por exemplo, para 30 minutos) para dar ao sistema tempo para concluir a tarefa.
  • Pagamento por uso prioritário: projetado para cargas de trabalho sensíveis à latência e de alta confiabilidade, sem o compromisso inicial da Capacidade de Processamento Provisionada. Se você receber um erro 429 nesse nível, tente novamente com espera exponencial, mas verifique se não está excedendo sua cota.
  • Capacidade de processamento provisionada: usa a capacidade reservada. Erros frequentes geralmente indicam que você excedeu a capacidade adquirida. Portanto, adicionar novas tentativas pode não resolver o problema.

Definir a tolerância de latência

  • Em tempo real (por exemplo, chat): falha rápida. Limite o número de tentativas para que os usuários não fiquem esperando indefinidamente por uma resposta.
  • Inferência em lote: não tente novamente itens individuais. O serviço Batch lida automaticamente com novas tentativas de solicitações individuais no job para buscar uma alta taxa de conclusão. Sua única responsabilidade é enviar o job uma vez. Para mais informações, consulte Predição em lote.

Identificar erros que podem ser repetidos

Há dois fatores principais que determinam se uma solicitação é segura para repetição:

Resposta

O código do erro ou a resposta recebida indica se o problema é temporário ou permanente. As respostas relacionadas a problemas temporários geralmente podem ser repetidas. São eles:

  • Códigos HTTP: 408 (tempo limite da solicitação), 429 (muitas solicitações) e 5xx (erros de servidor).
  • Problemas de rede: tempos limite de soquete e desconexões de TCP.

Para mais informações, consulte Erros de API.

Idempotência

As solicitações idempotentes podem ser executadas repetidamente sem alterar o estado final do recurso. Considere o seguinte ao determinar a idempotência:

  • Sempre idempotentes: operações de lista (não modificam recursos), solicitações GET, solicitações de contagem de tokens e solicitações de embeddings.
  • Nunca idempotentes: operações que criam recursos exclusivos sempre que são bem-sucedidas, como a criação de um novo modelo ajustado.
  • Nuance da IA generativa: embora generateContent não seja estritamente idempotente devido à natureza estocástica dos modelos generativos, geralmente é seguro tentar novamente em caso de erros temporários, já que ele não modifica o estado do lado do servidor.

Como configurar novas tentativas

O SDK de IA generativa do Google permite configurar o comportamento de repetição usando parâmetros do cliente ou HttpRetryOptions.

Principais parâmetros

  • initial_delay: o atraso inicial em segundos antes da primeira nova tentativa (padrão: 1.0).
  • attempts: o número máximo de novas tentativas (padrão: 5).
  • exp_base: a base para o cálculo da espera exponencial (padrão: 2).
  • max_delay: o atraso máximo em segundos entre as novas tentativas (padrão: 60).
  • jitter: um fator para adicionar um atraso aleatório ao backoff (padrão: 1).
  • http_status_codes: uma lista de códigos de status que acionam uma nova tentativa.

Exemplos

Configuração no nível do cliente

É possível definir opções globalmente ao inicializar o cliente.

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

Configuração no nível da solicitação

Também é possível substituir as configurações de uma única solicitação usando o parâmetro 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 PayGo

Para o Flex PayGo, o tempo limite padrão é de 10 minutos devido ao processamento mais lento e à nova tentativa transparente. Os usuários podem aumentar esse tempo para 30 minutos para melhorar a taxa de sucesso.

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

Práticas recomendadas e antipadrões

Seja usando os mecanismos de repetição padrão, personalizando-os ou implementando sua própria lógica de repetição, siga estas práticas recomendadas e evite antipadrões comuns.

Práticas recomendadas

  • Use a espera exponencial: aguarde um curto período antes da primeira nova tentativa (por exemplo, 1 segundo) e aumente o atraso exponencialmente (por exemplo, 2s, 4s, 8s).
  • Adicionar instabilidade: adicionar uma "instabilidade" aleatória ao atraso ajuda a evitar que todos os clientes tentem novamente ao mesmo tempo.
  • Tentar novamente em erros específicos: tente novamente apenas em erros temporários (429, 408, 5xx).
  • Defina o número máximo de novas tentativas: defina um número máximo de novas tentativas para evitar loops infinitos.
  • Monitorar e registrar: registre detalhes sobre tentativas de repetição, tipos de erro e tempos de resposta para depurar sua estratégia.

Antipadrões de repetição

  • Tentar novamente sem espera: tentar novamente de imediato pode levar a falhas em cascata e sobrecarregar o serviço.
  • Tentar novamente erros que não podem ser repetidos: não tente novamente erros do cliente (4xx que não sejam 429/408), porque eles indicam problemas como chaves de API inválidas ou sintaxe incorreta.
  • Repetir operações não idempotentes sem condições: executar repetidamente operações que não são idempotentes pode levar a efeitos colaterais, como recursos duplicados.
  • Ignorar limites de novas tentativas: tentar novamente indefinidamente pode levar ao esgotamento de recursos. Sempre defina um número máximo de tentativas.

A seguir