Ponawianie, wykładnicze opóźnianie i wzorzec circuit breaker
Na tej stronie
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
tenacitydo 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)