Repetir estratégia

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

Determinar quando tentar de novo

Antes de implementar uma estratégia personalizada de novas tentativas, considere como a seleção de endpoints, 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. Considere estratégias de failover.

Ajustar o modelo de pagamento

  • Pagamento por utilização padrão: usa recursos compartilhados. Use a espera exponencial para lidar com erros transitórios de limitação de taxa (429) causados por picos de tráfego.
  • Pagamento por utilização flexível: projetado para processamento mais lento e de baixa prioridade. Não tente de novo agressivamente. Em vez disso, aumente o tempo limite da solicitação (por exemplo, para 30 minutos) para dar ao sistema tempo para concluir a tarefa.
  • Priority pay-as-you-go: projetado para cargas de trabalho sensíveis à latência e de alta confiabilidade sem o compromisso antecipado da capacidade de processamento provisionada. Se você receber um erro 429 nesse nível, tente de novo com espera exponencial, mas verifique se não está excedendo sua cota.
  • Capacidade de processamento provisionada: usa capacidade dedicada. Erros frequentes geralmente indicam que você excedeu a capacidade comprada. Portanto, adicionar novas tentativas pode não resolver o problema.

Definir a tolerância à latência

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

Identificar erros que permitem uma nova tentativa

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

Resposta

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

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

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

Idempotência

As solicitações idempotentes podem ser executadas repetidamente sem mudar 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 de recebimento, solicitações de contagem de tokens e solicitações de incorporações.
  • Nunca idempotente: operações que criam recursos exclusivos sempre que são concluídas, 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.

Configurar novas tentativas

Com o SDK de IA generativa do Google, é possível configurar o comportamento de novas tentativas usando parâmetros do cliente ou HttpRetryOptions.

Parâmetros principais

  • initial_delay: o atraso inicial em segundos antes da primeira nova tentativa. Padrão: 1.0.
  • attempts: o número máximo de tentativas de nova execução (padrão: 5).
  • exp_base: a base para o cálculo de espera exponencial (padrão: 2).
  • max_delay: o atraso máximo em segundos entre 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 Pay-as-you-go

Para o pagamento flexível conforme o uso, 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 e ter uma taxa de sucesso melhor.

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

Se você estiver usando os mecanismos de nova tentativa padrão, personalizando-os ou implementando sua própria lógica de nova tentativa, siga estas práticas recomendadas e evite antipadrões comuns.

Práticas recomendadas

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

Antipadrões de nova tentativa

  • Nova tentativa sem espera: tentar de novo imediatamente pode causar falhas em cascata e sobrecarregar o serviço.
  • Repetir erros que não podem ser repetidos: não repita erros do cliente (4xx que não sejam 429/408), porque eles indicam problemas como chaves de API inválidas ou sintaxe incorreta.
  • Repetir incondicionalmente operações não idempotentes: 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