Salt la conținutul principal
Română— Alege o limbă
Meniu

Retry, Exponential Backoff și Circuit Breaker

Lecția 14 din 22 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Retry, Exponential Backoff și Circuit Breaker
  2. Exponential Backoff
  3. Utilizarea bibliotecii Tenacity
  4. Modelul Circuit Breaker
  5. Combinarea celor trei modele
  6. Puncte cheie

Retry, Exponential Backoff și Circuit Breaker

Erorile tranzitorii sunt normale în producție. SDK-ul OpenAI gestionează automat două reîncercări, dar pentru o reziliență maximă, ar trebui să implementați propriile strategii. Lecția anterioară v-a învățat să recunoașteți erorile care pot fi reîncercate; aceasta vă învață să reîncercați inteligent—fără a agrava situația pe care încercați să o remediați.

Exponential Backoff

Principiul este simplu: fiecare reîncercare așteaptă mai mult decât cea precedentă. Acest lucru previne supraîncărcarea API-ului atunci când este sub presiune. Jitter-ul merită o atenție specială, deoarece absența sa provoacă un mod clasic de eșec: cincizeci de instanțe ale serviciului dumneavoastră primesc un 429 în aceeași secundă, toate așteaptă exact o secundă, apoi toate repornesc simultan și sunt respinse din nou ca grup. Prin adăugarea unei întârzieri aleatorii, distribuiți această repornire—acesta este remediul pentru „thundering herd“.

import time
import random
from openai import OpenAI, RateLimitError, InternalServerError, APIConnectionError

client = OpenAI()

def call_with_backoff(prompt: str, max_retries: int = 5) -> str:
    """API call with exponential backoff and jitter."""

    for attempt in range(max_retries):
        try:
            response = client.responses.create(
                model="gpt-5.6-terra",
                input=prompt
            )
            return response.output_text

        except (RateLimitError, InternalServerError, APIConnectionError) as e:
            if attempt == max_retries - 1:
                raise  # Last attempt, propagate the error

            # Exponential backoff: 1s, 2s, 4s, 8s, 16s
            base_delay = 2 ** attempt

            # Random jitter to avoid thundering herd
            jitter = random.uniform(0, base_delay * 0.5)
            delay = base_delay + jitter

            print(f"Attempt {attempt + 1}/{max_retries} failed. "
                  f"Retrying in {delay:.1f}s...")
            time.sleep(delay)

    raise RuntimeError("Should never reach here")

# Usage
result = call_with_backoff("Explain exponential backoff.")
print(result)

Observați încercarea finală: propagăm eroarea originală în loc să o înghițim. Astfel, apelantul primește diagnosticul real—429 sau 500—și poate decide ce să facă cu acesta.

Utilizarea bibliotecii Tenacity

Scrierea manuală a acestei bucle devine rapid repetitivă odată ce aveți cinci funcții de protejat. Pentru o gestionare mai avansată a reîncercărilor, tenacity este instrumentul de referință: decoratorul declară politica, iar corpul funcției conține doar apelul logicii de afaceri. Obțineți aceleași ingrediente, dar numite și configurabile—lista de excepții pentru reîncercare, așteptarea exponențială limitată la șaizeci de secunde, oprirea după cinci încercări și jurnalizarea automată înainte de fiecare pauză.

# pip install tenacity
from tenacity import (
    retry,
    stop_after_attempt,
    wait_exponential,
    retry_if_exception_type,
    before_sleep_log,
)
from openai import RateLimitError, InternalServerError, APIConnectionError
import logging

logger = logging.getLogger(__name__)

@retry(
    retry=retry_if_exception_type(
        (RateLimitError, InternalServerError, APIConnectionError)
    ),
    wait=wait_exponential(multiplier=1, min=1, max=60),
    stop=stop_after_attempt(5),
    before_sleep=before_sleep_log(logger, logging.WARNING),
)
def resilient_call(prompt: str, model: str = "gpt-5.6-terra") -> str:
    """API call with automatic retry via tenacity."""
    response = client.responses.create(
        model=model,
        input=prompt
    )
    return response.output_text

# Usage — retries are transparent
result = resilient_call("Hello!")
print(result)

Modelul Circuit Breaker

Retry rezolvă incidente care durează câteva secunde. Devine dăunător când întreruperea durează mai mult: fiecare cerere a utilizatorului consumă atunci cinci încercări și treizeci de secunde de așteptare înainte de a eșua, thread-urile dumneavoastră se acumulează, iar propriul serviciu este cel care cade. Circuit breaker previne ca aplicația dumneavoastră să continue să apeleze un API defect.

Funcționează ca un întrerupător de circuit electric, cu trei stări. Closed (închis), totul funcționează normal și apelurile trec. Open (deschis), API-ul este considerat indisponibil, iar apelurile sunt blocate imediat, fără a încerca măcar rețeaua—utilizatorul primește o eroare în milisecunde, nu după un timeout. Half-open (semi-deschis), odată ce perioada de repaus a expirat, se trimite un apel de test pentru a verifica dacă API-ul a revenit: dacă reușește, circuitul se închide; dacă eșuează, se redeschide pentru un nou ciclu.

import time
from enum import Enum

class CircuitState(Enum):
    CLOSED = "closed"
    OPEN = "open"
    HALF_OPEN = "half_open"

class CircuitBreaker:
    """Circuit breaker for API calls."""

    def __init__(self, error_threshold: int = 5, reset_timeout: float = 30.0):
        self.threshold = error_threshold
        self.reset_timeout = reset_timeout
        self.consecutive_errors = 0
        self.state = CircuitState.CLOSED
        self.last_error_time = 0.0

    def can_call(self) -> bool:
        """Checks if a call is allowed."""
        if self.state == CircuitState.CLOSED:
            return True

        if self.state == CircuitState.OPEN:
            if time.monotonic() - self.last_error_time > self.reset_timeout:
                self.state = CircuitState.HALF_OPEN
                return True  # One test call
            return False

        # Half-open: only one call allowed
        return True

    def record_success(self):
        """Records a successful call."""
        self.consecutive_errors = 0
        self.state = CircuitState.CLOSED

    def record_error(self):
        """Records a failure."""
        self.consecutive_errors += 1
        self.last_error_time = time.monotonic()

        if self.consecutive_errors >= self.threshold:
            self.state = CircuitState.OPEN
            print(f"Circuit OPEN after {self.threshold} consecutive errors")

Contorul de erori se resetează la zero imediat ce un apel reușește: eșecurile consecutive sunt cele care deschid circuitul, nu un cumul istoric. Integrarea latoarea client se reduce apoi la trei pași—cereți permisiunea, semnalizați succesul, semnalizați eșecul.

# Integration with the OpenAI client
circuit = CircuitBreaker(error_threshold=3, reset_timeout=30.0)

def call_with_circuit_breaker(prompt: str) -> str:
    """API call protected by a circuit breaker."""
    if not circuit.can_call():
        raise RuntimeError(
            f"Circuit open — API unavailable. "
            f"Retry in {circuit.reset_timeout}s"
        )

    try:
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt
        )
        circuit.record_success()
        return response.output_text

    except (RateLimitError, InternalServerError, APIConnectionError) as e:
        circuit.record_error()
        raise

# Usage
try:
    result = call_with_circuit_breaker("Hello!")
    print(result)
except RuntimeError as e:
    print(f"Error: {e}")

Combinarea celor trei modele

În producție, combinați backoff, circuit breaker și timeout. Observați constructorul: clientul este creat cu max_retries=0, ceea ce dezactivează reîncercările interne ale SDK-ului. Fără aceasta, cele trei încercări ale dumneavoastră s-ar înmulți cu cele două ale SDK-ului și ați aștepta mult mai mult decât era de așteptat. Timeout-ul de treizeci de secunde limitează fiecare apel individual, bucla gestionează reîncercările, iar circuit breaker monitorizează starea generală de sănătate a serviciului.

class APIClient:
    """Resilient API client combining all patterns."""

    def __init__(self):
        self.client = OpenAI(timeout=30.0, max_retries=0)
        self.circuit = CircuitBreaker(error_threshold=5, reset_timeout=60.0)

    def call(self, prompt: str, max_retries: int = 3) -> str:
        if not self.circuit.can_call():
            raise RuntimeError("Service temporarily unavailable")

        for attempt in range(max_retries):
            try:
                response = self.client.responses.create(
                    model="gpt-5.6-terra",
                    input=prompt
                )
                self.circuit.record_success()
                return response.output_text

            except (RateLimitError, InternalServerError) as e:
                self.circuit.record_error()

                if attempt < max_retries - 1:
                    delay = (2 ** attempt) + random.uniform(0, 1)
                    time.sleep(delay)
                else:
                    raise

        raise RuntimeError("Failed after all attempts")

# Usage
api = APIClient()
print(api.call("Explain resilience in software engineering."))

Înainte de a continua, testați acest client simulând o întrerupere: deconectați rețeaua, lansați o duzină de apeluri și verificați dacă ultimele eșuează instantaneu în loc să aștepte. Dacă nu este cazul, pragul dumneavoastră este prea ridicat pentru volumul procesat.

Puncte cheie

  • SDK-ul gestionează implicit 2 reîncercări — ajustați cu max_retries
  • Exponential backoff cu jitter evită „thundering herd“
  • Circuit breaker protejează aplicația dumneavoastră de întreruperi prelungite
  • Utilizați tenacity pentru gestionarea declarativă a reîncercărilor în producție
  • Combinați toate cele trei modele pentru o reziliență maximă
  • Nu reîncercați niciodată erorile 400/401/403 (erori client)