Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Retry, Backoff Esponenzjali, u Circuit Breaker

Lezzjoni 14 / 22 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Retry, Backoff Esponenzjali, u Circuit Breaker
  2. Backoff Esponenzjali
  3. L-Użu tal-Librerija Tenacity
  4. Il-Mudell ta’ Circuit Breaker
  5. Il-Kombinazzjoni tat-Tliet Mudelli
  6. Punti Ewlenin

Retry, Backoff Esponenzjali, u Circuit Breaker

L-iżbalji tranżitorji huma normali fil-produzzjoni. L-SDK ta’ OpenAI jimmaniġġja awtomatikament żewġ tentattivi mill-ġdid (retries), iżda għal reżiljenza massima, għandek timplimenta l-istrateġiji tiegħek stess. Il-lezzjoni preċedenti għallmetek tirrikonoxxi l-iżbalji li jistgħu jiġu ttrattati mill-ġdid; din tgħallmek kif terġa’ tipprova b’mod intelliġenti—mingħajr ma tagħmel is-sitwazzjoni li qed tipprova ssolvi agħar.

Backoff Esponenzjali

Il-prinċipju huwa sempliċi: kull tentattiv mill-ġdid jistenna aktar minn ta’ qablu. Dan jipprevjeni t-tagħbija żejda fuq l-API meta tkun taħt pressjoni. Il-”jitter” (varjazzjoni każwali) jixraqlu attenzjoni speċjali għax in-nuqqas tiegħu jikkawża modalità ta’ ħsara klassika: ħamsin istanza tas-servizz tiegħek jirċievu żball 429 fl-istess sekonda, kollha jistennew eżattament sekonda waħda, imbagħad kollha jerġgħu jibdew flimkien u jiġu miċħuda mill-ġdid bħala grupp. Billi żżid dewmien każwali, tferrex dan ir-ristart—dik hija r-rimedju għall-”thundering herd” (merħla li tiġri flimkien).

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)

Innota t-tentattiv finali: aħna npropagaw l-iżball oriġinali minflok ma niblgħuh. Għalhekk, min sejjaħ il-funzjoni jirċievi d-dijanjożi reali—429 jew 500—u jista’ jiddeċiedi x’għandu jagħmel biha.

L-Użu tal-Librerija Tenacity

Il-kitba ta’ dan iċ-ċiklu bl-idejn malajr issir ripetittiva ladarba jkollok ħames funzjonijiet biex tipproteġi. Għal ġestjoni aktar avvanzata tar-retries, tenacity hija l-għodda preferuta: id-dekoratur jiddikjara l-politika, u l-korp tal-funzjoni fih biss is-sejħa tal-loġika tan-negozju. Tikseb l-istess ingredjenti, iżda msemmija u konfigurabbli—il-lista ta’ eċċezzjonijiet li għalihom għandek terġa’ tipprova, stennija esponenzjali limitata għal sittin sekonda, waqfien wara ħames tentattivi, u reġistrazzjoni (logging) awtomatika qabel kull pausa.

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

Il-Mudell ta’ Circuit Breaker

Ir-retry isolvi inċidenti li jdumu ftit sekondi. Isir ta’ ħsara meta l-interruzzjoni ddum aktar: kull talba tal-utent imbagħad tikkonsma ħames tentattivi u tletin sekonda ta’ stennija qabel ma tfalli, il-threads tiegħek jakkumulaw, u huwa s-servizz tiegħek stess li jaqa’. Iċ-”circuit breaker” jipprevjeni l-applikazzjoni tiegħek milli tkompli ssejjaħ API li qed tfalli.

Jaħdem bħal fusibbli elettriku, b’tliet stati. Magħluq (Closed), kollox jaħdem normalment u s-sejħiet jgħaddu. Miftuħ (Open), l-API titqies bħala ‘l isfel u s-sejħiet jiġu mblukkati immedjatament, mingħajr anke ma tipprova n-netwerk—l-utent jirċievi żball f’millisekondi minflok wara timeout. Nofs Miftuħ (Half-open), ladarba jgħaddi l-perjodu ta’ mistrieħ, tintbagħat sejħa ta’ test biex tiċċekkja jekk l-API terġax lura: jekk tirnexxi, iċ-ċirkwit jingħalaq; jekk tfalli, jerġa’ jiftaħ għal ċiklu ġdid.

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

Il-kontatur tal-iżbalji jiġi rriżettjat għal żero malli sejħa tirnexxi: huma l-fallimenti konsekuttivi li jiftħu ċ-ċirkwit, mhux għadd kumulattiv storiku. L-integrazzjoni fuq in-naħa tal-klijent imbagħad tinżel għal tliet passi—itlob permess, issinna suċċess, issinna falliment.

# 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}")

Il-Kombinazzjoni tat-Tliet Mudelli

Fil-produzzjoni, għaqqad il-backoff, iċ-circuit breaker, u t-timeout. Innota l-kostruttur: il-klijent jinħoloq b’max_retries=0, li jiddiżattiva r-retries interni tal-SDK. Mingħajr dan, it-tliet tentattivi tiegħek jiġu mmultiplikati b’żewġ tal-SDK, u tistenna ħafna aktar milli mistenni. It-timeout ta’ tletin sekonda jillimita kull sejħa individwali, iċ-ċiklu jimmaniġġja r-retries, u ċ-circuit breaker jissorvelja s-saħħa ġenerali tas-servizz.

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

Qabel ma tkompli, ittestja dan il-klijent billi tissimula interruzzjoni: aqta’ n-netwerk, nedja dożina ta’ sejħiet, u vverifika li tal-aħħar ifallu immedjatament minflok ma jistennew. Jekk dan ma jiġrix, il-limitu (threshold) tiegħek huwa għoli wisq għall-volum li qed jiġi pproċessat.

Punti Ewlenin

  • L-SDK jimmaniġġja 2 retries b’mod default — aġġusta b’max_retries
  • Il-backoff esponenzjali bil-jitter jevita l-”thundering herd”
  • Iċ-circuit breaker jipproteġi l-applikazzjoni tiegħek minn interruzzjonijiet fit-tul
  • Uża tenacity għal ġestjoni dikjarattiva tar-retries fil-produzzjoni
  • Għaqqad it-tliet mudelli kollha għal reżiljenza massima
  • Qatt ma terġa’ tipprova żbalji 400/401/403 (iżbalji tal-klijent)