Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Retry, eksponentiaalinen viive ja katkaisija

Oppitunti 14 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Retry, eksponentiaalinen viive ja katkaisija
  2. Eksponentiaalinen viive
  3. Tenacity-kirjaston käyttö
  4. Katkaisijamalli (Circuit Breaker)
  5. Kolmen mallin yhdistäminen
  6. Keskeiset asiat

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)