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 do 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 processe isso por padrão, é possível configurar esse comportamento para atender melhor à sua carga de trabalho específica.

Determinar quando repetir

Antes de implementar uma estratégia de repetição 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 repetições 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 repetições imediatas poderão falhar. Considere estratégias de failover.

Ajustar para o modelo de pagamento

  • **Pagamento por uso padrão**: usa recursos compartilhados. Use a espera exponencial para lidar com erros temporários de limite de taxa (429s) causados por picos de tráfego.
  • Flex pagamento por uso: projetado para processamento mais lento e de menor prioridade. Não repita 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.
  • **Pagamento por utilização 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 nessa camada, repita com espera exponencial, mas verifique se não está excedendo sua cota.
  • Capacidade de processamento provisionada: usa capacidade reservada. Erros frequentes geralmente indicam que você excedeu a capacidade comprada. Portanto, adicionar repetições pode não resolver o problema subjacente.

Definir a tolerância de latência

  • Em tempo real (por exemplo, chat): falha rápida. Limite o número de tentativas de repetição para que os usuários não fiquem esperando indefinidamente por uma resposta.
  • Inferência em lote: não repita itens individuais. O serviço em lote processa automaticamente as repetições 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 Previsão em lote.

Identificar erros que permitem uma nova tentativa

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

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 elas:

  • Códigos HTTP: 408 (tempo limite da solicitação), 429 (muitas solicitações) 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 alterar o estado final do recurso. Considere o seguinte ao determinar a idempotência:

  • Sempre idempotente: operações de listagem (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 bem-sucedidas, como a criação de um novo modelo ajustado.
  • Nuance de IA generativa: embora generateContent não seja estritamente idempotente devido à natureza estocástica dos modelos generativos, geralmente é seguro repetir erros temporários, já que não modifica o estado do lado do servidor.

Configurar novas tentativas

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

Parâmetros-chave

  • initial_delay: o atraso inicial em segundos antes da primeira repetição (padrão: 1.0).
  • attempts: o número máximo de tentativas de repetiçã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 as repetições (padrão: 60).
  • jitter: um fator para adicionar um atraso aleatório à espera (padrão: 1).
  • http_status_codes: uma lista de códigos de status que acionam uma repetição.

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 pagamento por uso

Para o Flex pagamento por uso, o tempo limite padrão é de 10 minutos devido ao processamento mais lento e à repetição transparente. Os usuários podem aumentar esse valor para 30 minutos para 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 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

  • Usar a espera exponencial: aguarde um curto período antes da primeira repetição (por exemplo, 1 segundo) e aumente o atraso exponencialmente (por exemplo, 2s, 4s, 8s).
  • Adicionar jitter: adicionar "jitter" aleatório ao atraso ajuda a evitar que todos os clientes repitam ao mesmo tempo.
  • Repetir em erros específicos: repita apenas erros temporários (429, 408, 5xx).
  • Definir o número máximo de repetições: defina um número máximo de tentativas de repetição 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

  • Repetir sem espera: repetir imediatamente pode levar a falhas em cascata e sobrecarregar o serviço.
  • Repetir erros que não permitem uma nova tentativa: não repita erros do cliente (4xx diferentes de 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 repetição: repetir indefinidamente pode levar ao esgotamento de recursos. Sempre defina um número máximo de tentativas.

A seguir