Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Pravilnik o poskusih ponovnega izvajanja

Lekcija 12 od 14 Posodobljeno 29. julij 2026 Napredni
Na tej strani
  1. Zakaj so poskusi ponovnega izvajanja nujni
  2. Konfiguracija pravilnika o poskusih ponovnega izvajanja
  3. Nikoli ne izpusti start_to_close_timeout
  4. Idempotentnost: nepogrešljiv pogoj
  5. Trije profili konfiguracije
  6. Ključne ugotovitve

Zakaj so poskusi ponovnega izvajanja nujni

V porazdeljenem sistemu so prehodne napake neizogibne: časovne omejitve omrežja, presežene omejitve hitrosti, začasno nedostopne storitve. Nobena od teh napak ne kaže na hrošča v tvoji kodi, vendar lahko katera koli od njih povzroči okvaro procesa, če ničesar ne ublaži udarca. Pravilnik o poskusih ponovnega izvajanja omogoča, da tvoje dejavnosti preživijo te napake brez ročnega posega, saj platforma samodejno ponovno zažene dejavnosti v skladu s konfiguracijo, ki jo določiš za vsako dejavnost posebej.

Konfiguracija pravilnika o poskusih ponovnega izvajanja

Dekorater @workflows.activity() sprejme parametre, ki urejajo to vedenje. Tukaj je primer dejavnosti za klic zunanjega API-ja, pravilno opremljene za odpornost.

from datetime import timedelta
import mistralai.workflows as workflows

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5),
    retry_policy_max_attempts=3,
    retry_policy_backoff_coefficient=2.0,
)
async def call_external_api(url: str, data: dict) -> dict:
    """Calls an external API with automatic retry."""
    async with httpx.AsyncClient(timeout=60) as client:
        response = await client.post(url, json=data)
        response.raise_for_status()
        return response.json()

Trije parametri, tri komplementarne vloge.

  • start_to_close_timeout — Najdaljše trajanje enega samega poskusa izvajanja. Če se dejavnost ne zaključi v tem časovnem okviru, se šteje za neuspešno in sproži se nov poskus.

  • retry_policy_max_attempts — Največje število poskusov. Privzeta vrednost je odvisna od platforme. Po tem številu poskusov dejavnost dokončno odpove in delovni tok prejme napako.

  • retry_policy_backoff_coefficient — Množitelj za zamik med poskusi. S koeficientom 2,0 se zamiki z vsakim poskusom podvojijo (1 s, 2 s, 4 s, 8 s …). To je eksponentno odlašanje.

Ta mehanizem odlašanja si zasluži pozornost, saj njegov namen ni le čakanje: storitvi, ki ima težave, da čas za obnovitev, namesto da bi jo neprestano obremenjeval. Napredek klica, ki se na koncu uspešno izvede, to jasno prikazuje.

Attempt 1: immediate execution
  → Failure (network timeout)
  → Wait 1 second

Attempt 2: execution
  → Failure (service unavailable)
  → Wait 2 seconds (1 × 2.0)

Attempt 3: execution
  → Failure (rate limit)
  → Wait 4 seconds (2 × 2.0)

Attempt 4: execution
  → Success!

Ob odzivu „429 Too Many Requests” je ta mehanizem še posebej učinkovit: pravilnik, ki bi takoj ponovno poskusil, bi le vzdrževal zasičenost, medtem ko povečevanje razmikov sčasoma pade pod prag ponudnika.

Nikoli ne izpusti start_to_close_timeout

Ta časovna omejitev je ključna in mora biti prisotna pri vsaki dejavnosti, brez izjeme. Brez nje dejavnost, ki se zatakne (slepi ulični blok, viseča povezava, storitev, ki sprejme zahtevo, a nikoli ne odgovori), čaka v nedogled in zamrzne celoten delovni tok. Še huje: ne sproži ponovnega poskusa, saj z njenega vidika še ni odpovedala.

# BAD PRACTICE: no timeout
@workflows.activity()
async def dangerous_activity(params: dict) -> dict:
    # If the service never responds, the activity waits indefinitely
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.lente.example.com/data")
    return response.json()

# GOOD PRACTICE: explicit timeout
@workflows.activity(
    start_to_close_timeout=timedelta(minutes=2)
)
async def safe_activity(params: dict) -> dict:
    async with httpx.AsyncClient(timeout=90) as client:
        response = await client.get("https://api.lente.example.com/data")
    return response.json()

Za nastavitev vrednosti najprej izmeri običajni čas izvajanja dejavnosti, nato dodaj varnostni rob dva- do trikratne vrednosti za pokrivanje počasnejših primerov. Nazadnje zagotovi, da ostane notranja časovna omejitev HTTP-odjemalca nižja od start_to_close_timeout—v zgornjem primeru 90 sekund nasproti 2 minutama—tako da se napaka čisto prenese iz tvoje kode, namesto da bi jo platforma prekinila.

Idempotentnost: nepogrešljiv pogoj

Ker se lahko dejavnost večkrat ponovi z istimi parametri, mora proizvesti enak učinek ne glede na število izvedb. Ta lastnost se imenuje idempotentnost in njena odsotnost spremeni pravilnik o poskusih ponovnega izvajanja v generator incidentov.

@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float) -> dict:
    """DANGEROUS: if retried, credit is added multiple times!"""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"https://api.billing.com/credits/add",
            json={"user_id": user_id, "amount": amount}
        )
    return response.json()

Grozeč scenarij je pogost: obračunski API pravilno obdela zahtevo, vendar se odgovor izgubi v omrežju. Dejavnost zaključi z napako, platforma ponovno poskusi in stranka dobi dobropis dvakrat. Ključ idempotentnosti odpravi težavo tako, da oddaljeni storitvi omogoči prepoznavanje že obdelane zahteve.

@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float, idempotency_key: str) -> dict:
    """CORRECT: idempotency key prevents duplication."""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"https://api.billing.com/credits/add",
            json={
                "user_id": user_id,
                "amount": amount,
                "idempotency_key": idempotency_key
            }
        )
    return response.json()

Ključ generiraj v delovnem toku z uporabo workflow.uuid4(), kar zagotavlja, da ostane identičen od ene ponovitve do druge—klasičen uuid.uuid4() bi proizvedel novo vrednost ob vsakem poskusu in razveljavil vso zaščito. Ko oddaljena storitev ne ponuja tega mehanizma, obstajata dve drugi poti: upsert v bazi podatkov z uporabo INSERT ... ON CONFLICT UPDATE namesto zgolj INSERT, ali preverjanje s predhodnim pregledom, kar vključuje poizvedbo stanja pred ukrepanjem.

Trije profili konfiguracije

Vrednosti se umerijo glede na naravo operacije. Plačilo ali obvestilo mora uspeti hitro ali hitro odpovedati: kratek časovni limit, trije poskusi, zmerno odlašanje.

@workflows.activity(
    start_to_close_timeout=timedelta(seconds=30),
    retry_policy_max_attempts=3,
    retry_policy_backoff_coefficient=2.0,
)
async def process_payment(params: dict) -> dict:
    # ...
    pass

Dolgotrajna obdelava, kot je generiranje poročil ali težko sklepanje, obrne logiko: vsak poskus stane znaten računalniški čas, zato dovoliš manj poskusov z večjimi razmiki.

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=15),
    retry_policy_max_attempts=2,
    retry_policy_backoff_coefficient=3.0,
)
async def generate_ml_report(params: dict) -> dict:
    # ...
    pass

Ob nestabilnem API-ju tretje strani, ki je podvržen omejevanju hitrosti, končno prevzameš vztrajnost: pet poskusov, tudi če to traja več minut.

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=2),
    retry_policy_max_attempts=5,
    retry_policy_backoff_coefficient=2.0,
)
async def call_third_party_api(params: dict) -> dict:
    # ...
    pass

Ključne ugotovitve

  • Vedno konfiguriraj start_to_close_timeout, da se izogneš blokiranju dejavnosti
  • Eksponentno odlašanje (retry_policy_backoff_coefficient) poveča zamik med poskusi
  • retry_policy_max_attempts določa največje število poskusov pred dokončno odpovedjo
  • Dejavnosti s poskusi ponovnega izvajanja morajo biti idempotentne—enak rezultat ob večkratni izvedbi
  • Uporabi ključe idempotentnosti ali upserte za zagotovitev idempotentnosti
  • Prilagodi časovne omejitve in število poskusov vrsti operacije (hitro proti dolgotrajno, stabilno proti nestabilno)