Retry, eksponentiaalinen viive ja katkaisija
Tällä sivulla
Retry, eksponentiaalinen viive ja katkaisija
Ohimenevät virheet ovat tuotantoympäristössä normaaleja. OpenAI SDK hoitaa automaattisesti kaksi uudelleenyritystä, mutta maksimaalisen kestävyyden saavuttamiseksi sinun tulee toteuttaa omat strategiasi. Edellisessä oppitunnissa opit tunnistamaan uudelleenyrityksen arvoiset virheet; tässä opit tekemään uudelleenyrityksiä älykkäästi – pahentamatta tilannetta, jota yrität korjata.
Eksponentiaalinen viive
Periaate on yksinkertainen: jokainen uudelleenyritys odottaa pidempään kuin edellinen. Tämä estää rajapinnan ylikuormittamisen sen ollessa paineen alla. Satunnaisvaihtelu (jitter) ansaitsee erityistä huomiota, sillä sen puuttuminen aiheuttaa klassisen vikatilan: viisikymmentä palvelusi instanssia saa 429-virheen samaan sekuntiin, kaikki odottavat tasan yhden sekunnin, käynnistyvät sitten yhdessä ja tulevat jälleen hylätyiksi ryhmänä. Lisäämällä satunnaisen viiveen hajautat tämän uudelleenkäynnistyksen – se on lääke “jyrisevään laumaan”.
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-kutsu eksponentiaalisella viiveellä ja satunnaisvaihtelulla."""
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 # Viimeinen yritys, levitä virhe eteenpäin
# Eksponentiaalinen viive: 1s, 2s, 4s, 8s, 16s
base_delay = 2 ** attempt
# Satunnaisvaihtelu jyrisevän lauman välttämiseksi
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")
# Käyttö
result = call_with_backoff("Explain exponential backoff.")
print(result)
Huomaa viimeinen yritys: levitämme alkuperäisen virheen eteenpäin sen nielemisen sijaan. Kutsuja saa näin todellisen diagnostiikan – 429 tai 500 – ja voi päättää, mitä sen kanssa tekee.
Tenacity-kirjaston käyttö
Tämän silmukan kirjoittaminen käsin muuttuu nopeasti toistuvaksi, kun suojattavia funktioita on viisi. Edistyneempään uudelleenyritysten hallintaan tenacity on ensisijainen työkalu: dekorattori määrittelee politiikan, ja funktion runko sisältää vain liiketoimintalogiikan kutsun. Saat samat ainesosat, mutta nimettyinä ja konfiguroitavina – uudelleen yritettävien poikkeusten luettelo, enintään kuuteenkymmeneen sekuntiin rajoitettu eksponentiaalinen odotus, pysähtyminen viiden yrityksen jälkeen ja automaattinen lokitus ennen jokaista taukoa.
# 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-kutsu automaattisella uudelleenyrityksellä tenacityn avulla."""
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
# Käyttö — uudelleenyritykset ovat läpinäkyviä
result = resilient_call("Hello!")
print(result)
Katkaisijamalli (Circuit Breaker)
Uudelleenyritys ratkaisee muutaman sekunnin kestävät häiriöt. Se muuttuu haitalliseksi, kun katkos kestää kauemmin: jokainen käyttäjäpyyntö kuluttaa tällöin viisi yritystä ja kolmekymmentä sekuntia odotusta ennen epäonnistumista, säikeesi kasautuvat ja oma palvelusi kaatuu. Katkaisija estää sovellustasi kutsumasta epäonnistuvaa rajapintaa jatkuvasti.
Se toimii kuin sähköinen katkaisija kolmessa tilassa. Closed (suljettu): kaikki toimii normaalisti ja kutsut kulkevat läpi. Open (avoin): rajapinnan katsotaan olevan alhaalla ja kutsut estetään välittömästi edes verkkoa yrittämättä – käyttäjä saa virheen millisekunneissa aikakatkaisun sijaan. Half-open (puoliavoin): kun lepoaika on kulunut umpeen, lähetetään testikutsu tarkistamaan, onko rajapinta palannut: jos se onnistuu, piiri sulkeutuu; jos se epäonnistuu, se avautuu uudelle kierrokselle.
import time
from enum import Enum
class CircuitState(Enum):
CLOSED = "closed"
OPEN = "open"
HALF_OPEN = "half_open"
class CircuitBreaker:
"""Katkaisija API-kutsuille."""
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:
"""Tarkistaa, onko kutsu sallittu."""
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 # Yksi testikutsu
return False
# Puoliavoin: vain yksi kutsu sallittu
return True
def record_success(self):
"""Kirjaa onnistuneen kutsun."""
self.consecutive_errors = 0
self.state = CircuitState.CLOSED
def record_error(self):
"""Kirjaa epäonnistumisen."""
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")
Virhelaskuri nollautuu nollaan heti, kun kutsu onnistuu: piirin avaa peräkkäiset epäonnistumiset, ei historiallinen kumulatiivinen määrä. Integrointi asiakaspuolella tiivistyy sitten kolmeen vaiheeseen – pyydä lupaa, ilmoita onnistuminen, ilmoita epäonnistuminen.
# Integrointi OpenAI-asiakkaan kanssa
circuit = CircuitBreaker(error_threshold=3, reset_timeout=30.0)
def call_with_circuit_breaker(prompt: str) -> str:
"""Katkaisijan suojaama API-kutsu."""
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
# Käyttö
try:
result = call_with_circuit_breaker("Hello!")
print(result)
except RuntimeError as e:
print(f"Error: {e}")
Kolmen mallin yhdistäminen
Tuotannossa yhdistä viive, katkaisija ja aikakatkaisu. Huomaa konstruktori: asiakas luodaan asetuksella max_retries=0, mikä poistaa SDK:n sisäiset uudelleenyritykset käytöstä. Ilman tätä kolme yritystäsi kertoituisivat SDK:n kahdella, ja odottaisit paljon odotettua kauemmin. Kolmenkymmenen sekunnin aikakatkaisu rajoittaa jokaista yksittäistä kutsua, silmukka hoitaa uudelleenyritykset ja katkaisija valvoo palvelun yleistä terveyttä.
class APIClient:
"""Kaikki mallit yhdistävä kestävä API-asiakas."""
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")
# Käyttö
api = APIClient()
print(api.call("Explain resilience in software engineering."))
Ennen kuin siirryt eteenpäin, testaa tätä asiakasta simuloimalla katkos: katkaise verkko, käynnistä tusina kutsuja ja varmista, että viimeiset epäonnistuvat välittömästi odottamisen sijaan. Jos näin ei käy, kynnysarvosi on liian korkea käsiteltävään volyymiin nähden.
Keskeiset asiat
- SDK hoitaa oletuksena 2 uudelleenyritystä – säädä asetuksella
max_retries - Eksponentiaalinen viive satunnaisvaihtelulla välttää jyrisevän lauman
- Katkaisija suojaa sovellustasi pitkittyneiltä katkoksilta
- Käytä
tenacity-kirjastoa deklaratiiviseen uudelleenyritysten hallintaan tuotannossa - Yhdistä kaikki kolme mallia maksimaalisen kestävyyden saavuttamiseksi
- Älä koskaan yritä uudelleen 400/401/403-virheitä (asiakasvirheet)