재시도 전략

Google 생성형 AI SDK 클라이언트 라이브러리에는 시간 초과, 네트워크 문제, 비율 제한 (HTTP 429 및 5xx 상태 코드)과 같은 일시적인 오류를 처리하기 위한 지수 백오프를 사용한 자동 재시도 로직이 포함되어 있습니다. 예를 들어 Python SDK는 초기 지연 시간 약 1초, 최대 지연 시간 60초로 일시적인 오류를 최대 4회 자동으로 재시도합니다. SDK는 기본적으로 이를 처리하지만 특정 워크로드에 맞게 이 동작을 구성할 수 있습니다.

언제 재시도할지 결정

맞춤 재시도 전략을 구현하기 전에 엔드포인트 선택, 결제 모델, 워크로드가 요구사항에 미치는 영향을 고려하세요.

올바른 엔드포인트 선택

  • 전역 엔드포인트: 가용성에 권장됩니다. 전역 엔드포인트는 트래픽을 동적으로 라우팅하므로 리전 용량 문제로 인한 클라이언트 측 재시도의 필요성을 줄일 수 있습니다.
  • 리전 엔드포인트: 특정 위치로 제한됩니다. 리전이 과부하된 경우 즉시 재시도하면 실패할 수 있습니다. 대신 장애 조치 전략을 고려하세요.

지급 모델 조정

  • 표준 사용한 만큼만 지불: 공유 리소스를 사용합니다. 트래픽 급증으로 인해 발생하는 일시적인 비율 제한 오류 (429)를 처리하려면 지수 백오프를 사용하세요.
  • 유연한 종량제: 우선순위가 낮고 처리 속도가 느린 워크로드에 적합합니다. 공격적으로 재시도하지 말고 시스템이 작업을 완료할 수 있도록 요청 시간 제한을 늘리세요 (예: 30분).
  • 우선순위 사용한 만큼만 지불: 프로비저닝된 처리량의 선불 약정 없이 지연 시간에 민감하고 신뢰성이 높은 워크로드를 위해 설계되었습니다. 이 등급에서 429 오류가 발생하면 지수 백오프로 다시 시도하되 할당량을 초과하지 않도록 하세요.
  • 프로비저닝된 처리량: 전용 용량을 사용합니다. 오류가 자주 발생하면 구매한 용량을 초과했음을 나타내므로 재시도를 추가해도 근본적인 문제가 해결되지 않을 수 있습니다.

지연 시간 허용 범위 정의

  • 실시간 (예: 채팅): 빠르게 실패합니다. 사용자가 응답을 무기한 기다리지 않도록 재시도 횟수를 제한합니다.
  • 일괄 추론: 개별 항목을 재시도하지 마세요. Batch 서비스는 높은 완료율을 달성하기 위해 작업 내 개별 요청의 재시도를 자동으로 처리합니다. 한 번만 작업을 성공적으로 제출하면 됩니다. 자세한 내용은 일괄 예측을 참고하세요.

재시도 가능한 오류 식별

요청을 재시도해도 안전한지 여부를 결정하는 두 가지 주요 요소는 다음과 같습니다.

응답

수신된 오류 코드 또는 응답은 문제가 일시적인지 영구적인지 나타냅니다. 일시적인 문제와 관련된 응답은 일반적으로 재시도 가능합니다. 예를 들면 다음과 같습니다.

  • HTTP 코드: 408 (요청 시간 초과), 429 (요청이 너무 많음), 5xx (서버 오류)
  • 네트워크 문제: 소켓 시간 초과 및 TCP 연결 해제

자세한 내용은 API 오류를 참고하세요.

멱등성

멱등성 요청은 리소스의 최종 상태를 변경하지 않고 반복적으로 실행할 수 있습니다. 멱등성을 결정할 때는 다음 사항을 고려하세요.

  • 항상 멱등성: 목록 작업 (리소스를 수정하지 않음), 가져오기 요청, 토큰 수 요청, 임베딩 요청
  • 멱등원이 아님: 성공할 때마다 고유한 리소스를 만드는 작업(예: 새로운 조정 모델 만들기)
  • 생성형 AI 미묘한 차이: 생성형 모델의 확률적 특성으로 인해 generateContent가 엄격하게 멱등은 아니지만 서버 측 상태를 수정하지 않으므로 일시적인 오류에 대해 다시 시도해도 일반적으로 안전합니다.

재시도 구성

Google 생성형 AI SDK를 사용하면 클라이언트 매개변수 또는 HttpRetryOptions를 통해 재시도 동작을 구성할 수 있습니다.

주요 매개변수

  • initial_delay: 첫 번째 재시도 전의 초기 지연 시간(초)(기본값: 1.0)
  • attempts: 최대 재시도 횟수입니다 (기본값: 5).
  • exp_base: 지수 백오프 계산의 기준입니다 (기본값: 2).
  • max_delay: 재시도 간 최대 지연 시간(초)(기본값: 60)입니다.
  • jitter: 지연에 무작위 지연을 추가하는 요소입니다 (기본값: 1).
  • http_status_codes: 재시도를 트리거하는 상태 코드 목록입니다.

예시

클라이언트 수준 구성

클라이언트를 초기화할 때 전역으로 옵션을 설정할 수 있습니다.

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

자바

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

요청 수준 구성

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 종량제

Flex 종량제의 경우 처리 속도가 느리고 투명한 재시도로 인해 기본 제한 시간은 10분입니다. 성공률을 높이려면 이 시간을 30분으로 늘리면 됩니다.

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

권장사항 및 안티 패턴

기본 재시도 메커니즘을 사용하든, 맞춤설정하든, 자체 재시도 로직을 구현하든 다음 권장사항을 따르고 일반적인 안티패턴을 피하세요.

권장사항

  • 지수 백오프 사용: 첫 번째 재시도 전에 잠시 기다린 후 (예: 1초) 지연 시간을 지수적으로 늘립니다 (예: 2초, 4초, 8초).
  • 지터 추가: 지연에 무작위 '지터'를 추가하면 모든 클라이언트가 정확히 동시에 재시도하는 것을 방지할 수 있습니다.
  • 특정 오류 시 재시도: 일시적 오류 (429, 408, 5xx)에 대해서만 재시도합니다.
  • 최대 재시도 횟수 설정: 무한 루프를 방지하기 위해 최대 재시도 횟수를 정의합니다.
  • 모니터링 및 로깅: 재시도 횟수, 오류 유형, 응답 시간에 관한 세부정보를 로깅하여 전략을 디버그합니다.

재시도 안티패턴

  • 백오프 없이 재시도: 즉시 재시도하면 연쇄 장애가 발생하고 서비스가 과부하될 수 있습니다.
  • 재시도할 수 없는 오류 재시도: 잘못된 API 키 또는 잘못된 구문과 같은 문제를 나타내는 클라이언트 오류 (429/408 이외의 4xx)는 재시도하지 마세요.
  • 멱등성이 없는 작업을 무조건 재시도: 멱등성이 없는 작업을 반복적으로 실행하면 중복 리소스와 같은 부작용이 발생할 수 있습니다.
  • 재시도 제한 무시: 무한정 재시도하면 리소스가 소진될 수 있으므로 항상 최대 시도 횟수를 설정하세요.

다음 단계