Przejdź do głównej treści
Polski— Wybierz język
Menu

Ponawianie, wykładnicze opóźnianie i wzorzec circuit breaker

Lekcja 14 z 22 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Ponawianie, wykładnicze opóźnianie i wzorzec circuit breaker
  2. Wykładnicze opóźnianie (Exponential Backoff)
  3. Korzystanie z biblioteki Tenacity
  4. Wzorzec Circuit Breaker
  5. Łączenie trzech wzorców
  6. Kluczowe wnioski

Ponawianie, wykładnicze opóźnianie i wzorzec circuit breaker

Błędy przemijające są normą w środowisku produkcyjnym. SDK OpenAI automatycznie obsługuje dwie próby ponowienia, ale aby osiągnąć maksymalną odporność, powinieneś wdrożyć własne strategie. Poprzednia lekcja nauczyła Cię rozpoznawać błędy nadające się do ponowienia; ta nauczy Cię, jak ponawiać inteligentnie – nie pogarszając sytuacji, którą próbujesz naprawić.

Wykładnicze opóźnianie (Exponential Backoff)

Zasada jest prosta: każda kolejna próba czeka dłużej niż poprzednia. Zapobiega to przeciążeniu API, gdy znajduje się ono pod presją. Na szczególną uwagę zasługuje jitter (losowe opóźnienie), ponieważ jego brak prowadzi do klasycznego trybu awarii: pięćdziesiąt instancji Twojej usługi otrzymuje kod 429 w tej samej sekundzie, wszystkie czekają dokładnie jedną sekundę, następnie wszystkie restartują się jednocześnie i ponownie zostają odrzucone jako grupa. Dodając losowe opóźnienie, rozkładasz ten restart w czasie – to właśnie jest lekarstwo na efekt „tłumu“ (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:
    """Wywołanie API z wykładniczym opóźnianiem i jitterem."""

    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  # Ostatnia próba, propaguj błąd

            # Wykładnicze opóźnianie: 1s, 2s, 4s, 8s, 16s
            base_delay = 2 ** attempt

            # Losowy jitter, aby uniknąć efektu tłumu
            jitter = random.uniform(0, base_delay * 0.5)
            delay = base_delay + jitter

            print(f"Próba {attempt + 1}/{max_retries} nieudana. "
                  f"Ponawianie za {delay:.1f}s...")
            time.sleep(delay)

    raise RuntimeError("Ten kod nigdy nie powinien zostać osiągnięty")

# Użycie
result = call_with_backoff("Wyjaśnij wykładnicze opóźnianie.")
print(result)

Zwróć uwagę na ostatnią próbę: propagujemy oryginalny błąd zamiast go połykać. Dzięki temu wywołujący otrzymuje rzeczywistą diagnozę – 429 lub 500 – i może zdecydować, co z nią zrobić.

Korzystanie z biblioteki Tenacity

Ręczne pisanie tej pętli szybko staje się powtarzalne, gdy masz do zabezpieczenia pięć funkcji. Do bardziej zaawansowanego zarządzania ponawianiem narzędziem pierwszego wyboru jest tenacity: dekorator deklaruje politykę, a ciało funkcji zawiera wyłącznie wywołanie logiki biznesowej. Otrzymujesz te same składniki, ale nazwane i konfigurowalne – listę wyjątków do ponowienia, wykładnicze oczekiwanie ograniczone do sześćdziesięciu sekund, zatrzymanie po pięciu próbach oraz automatyczne logowanie przed każdą przerwą.

# 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:
    """Wywołanie API z automatycznym ponawianiem przez tenacity."""
    response = client.responses.create(
        model=model,
        input=prompt
    )
    return response.output_text

# Użycie — ponawianie jest przezroczyste
result = resilient_call("Cześć!")
print(result)

Wzorzec Circuit Breaker

Ponawianie rozwiązuje problemy trwające kilka sekund. Staje się szkodliwe, gdy awaria trwa dłużej: każde żądanie użytkownika zużywa wtedy pięć prób i trzydzieści sekund oczekiwania przed niepowodzeniem, wątki się piętrzą i to Twoja własna usługa ulega awarii. Circuit breaker (wyłącznik nadprądowy) zapobiega sytuacji, w której Twoja aplikacja nadal wywołuje niedziałające API.

Działa jak elektryczny wyłącznik nadprądowy i posiada trzy stany. Zamknięty (Closed): wszystko działa normalnie, a wywołania są przepuszczane. Otwarty (Open): API jest uznawane za niedostępne, a wywołania są natychmiast blokowane, bez nawet podejmowania próby połączenia sieciowego – użytkownik otrzymuje błąd w milisekundach, a nie po upływie czasu oczekiwania. Półotwarty (Half-open): gdy okres odpoczynku minie, wysyłane jest próbne wywołanie, aby sprawdzić, czy API działa ponownie: jeśli się powiedzie, obwód się zamyka; jeśli nie, otwiera się ponownie na nowy cykl.

import time
from enum import Enum

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

class CircuitBreaker:
    """Circuit breaker dla wywołań API."""

    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:
        """Sprawdza, czy wywołanie jest dozwolone."""
        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  # Jedno wywołanie testowe
            return False

        # Half-open: dozwolone tylko jedno wywołanie
        return True

    def record_success(self):
        """Rejestruje udane wywołanie."""
        self.consecutive_errors = 0
        self.state = CircuitState.CLOSED

    def record_error(self):
        """Rejestruje niepowodzenie."""
        self.consecutive_errors += 1
        self.last_error_time = time.monotonic()

        if self.consecutive_errors >= self.threshold:
            self.state = CircuitState.OPEN
            print(f"Circuit OPEN po {self.threshold} kolejnych błędach")

Licznik błędów resetuje się do zera, gdy tylko wywołanie się powiedzie: to kolejne niepowodzenia otwierają obwód, a nie historyczna suma skumulowana. Integracja po stronie klienta sprowadza się następnie do trzech kroków: poproś o pozwolenie, zgłoś sukces, zgłoś niepowodzenie.

# Integracja z klientem OpenAI
circuit = CircuitBreaker(error_threshold=3, reset_timeout=30.0)

def call_with_circuit_breaker(prompt: str) -> str:
    """Wywołanie API chronione przez circuit breaker."""
    if not circuit.can_call():
        raise RuntimeError(
            f"Circuit open — API niedostępne. "
            f"Spróbuj ponownie za {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

# Użycie
try:
    result = call_with_circuit_breaker("Cześć!")
    print(result)
except RuntimeError as e:
    print(f"Błąd: {e}")

Łączenie trzech wzorców

W środowisku produkcyjnym połącz opóźnianie, circuit breaker i limit czasu (timeout). Zwróć uwagę na konstruktor: klient jest tworzony z parametrem max_retries=0, co wyłącza wewnętrzne ponawianie SDK. Bez tego Twoje trzy próby pomnożyłyby się przez dwie próby SDK i czekałbyś znacznie dłużej, niż oczekiwano. Trzydziestosekundowy limit czasu ogranicza każde pojedyncze wywołanie, pętla obsługuje ponawianie, a circuit breaker monitoruje ogólny stan usługi.

class APIClient:
    """Odporny klient API łączący wszystkie wzorce."""

    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("Usługa tymczasowo niedostępna")

        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("Niepowodzenie po wszystkich próbach")

# Użycie
api = APIClient()
print(api.call("Wyjaśnij odporność w inżynierii oprogramowania."))

Zanim przejdziesz dalej, przetestuj tego klienta, symulując awarię: odłącz sieć, uruchom tuzin wywołań i sprawdź, czy ostatnie z nich kończą się niepowodzeniem natychmiast, zamiast czekać. Jeśli tak nie jest, Twój próg jest zbyt wysoki w stosunku do przetwarzanej liczby żądań.

Kluczowe wnioski

  • SDK domyślnie obsługuje 2 ponowienia – dostosuj to za pomocą max_retries
  • Wykładnicze opóźnianie z jitterem zapobiega efektowi tłumu
  • Circuit breaker chroni Twoją aplikację przed długotrwałymi awariami
  • Użyj tenacity do deklaratywnego zarządzania ponawianiem w produkcji
  • Połącz wszystkie trzy wzorce, aby osiągnąć maksymalną odporność
  • Nigdy nie ponawiaj błędów 400/401/403 (błędy klienta)