Politika ponovnih pokušaja
Na ovoj stranici
Zašto su ponovni pokušaji ključni
U distribuiranom sustavu prolazne greške su neizbježne: istek vremena mreže, premašena ograničenja brzine (rate limits) ili privremeno nedostupne usluge. Nijedan od ovih kvarova ne ukazuje na bug u tvom kodu, no svaki od njih može uzrokovati pad procesa ako ništa ne ublaži udarac. Politika ponovnih pokušaja omogućuje tvojim aktivnostima da prežive ove greške bez ručne intervencije, pri čemu platforma automatski ponovno pokreće aktivnosti prema konfiguraciji koju definiraš za svaku od njih.
Konfiguriranje politike ponovnih pokušaja
Dekorator @workflows.activity() prihvaća parametre koji upravljaju ovim ponašanjem. Evo primjera aktivnosti koja poziva vanjski API i ispravno je opremljena za otpornost.
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()
Tri parametra, tri komplementarne uloge.
-
start_to_close_timeout— Maksimalno trajanje jednog pokušaja izvršenja. Ako se aktivnost ne završi unutar tog vremenskog okvira, smatra se neuspjelom i pokreće se novi pokušaj. -
retry_policy_max_attempts— Maksimalan broj pokušaja. Zadana vrijednost ovisi o platformi. Nakon tog broja pokušaja, aktivnost konačno ne uspijeva i radni tijek (workflow) prima grešku. -
retry_policy_backoff_coefficient— Množitelj za kašnjenje između pokušaja. S koeficijentom od 2.0, kašnjenja se udvostručuju sa svakim pokušajem (1s, 2s, 4s, 8s…). To je eksponencijalno povlačenje (exponential backoff).
Ovaj mehanizam povlačenja zaslužuje pažnju jer mu svrha nije samo čekanje: on daje usluzi koja posrće vrijeme da se oporavi umjesto da je zasipaš zahtjevima. Napredak poziva koji na kraju uspijeva to jasno ilustrira.
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!
Suočen s odgovorom „429 Too Many Requests“, ovaj je mehanizam posebno učinkovit: politika koja bi odmah ponovila pokušaj samo bi održala zasićenje, dok povećavanje razmaka na kraju spušta promet ispod praga pružatelja usluge.
Nikada ne izostavljaj start_to_close_timeout
Ovo vremensko ograničenje je kritično i mora se pojaviti na svakoj aktivnosti, bez iznimke. Bez njega, aktivnost koja se zaglavi—deadlock, viseća veza ili usluga koja prihvati zahtjev, ali nikada ne odgovori—čeka beskonačno i zamrzava cijeli radni tijek. Još gore: to ne pokreće ponovni pokušaj jer s njezine perspektive još nije došlo do neuspjeha.
# 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 postavljanje vrijednosti prvo izmjeri normalno vrijeme izvršenja aktivnosti, zatim dodaj marginu od dva do tri puta kako bi pokrio spore slučajeve. Konačno, osiguraj da interno vremensko ograničenje HTTP klijenta ostane niže od start_to_close_timeout—u gornjem primjeru 90 sekundi naspram 2 minute—kako bi se greška čisto propagirala iz tvog koda, a ne da je platforma naglo prekine.
Idempotentnost: neupitan uvjet
Budući da se aktivnost može višestruko ponoviti s istim parametrima, ona mora proizvesti isti učinak bez obzira na broj izvršenja. Ovo se svojstvo naziva idempotentnost, a njezin izostanak pretvara politiku ponovnih pokušaja u generator incidenata.
@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()
Strahoviti scenarij je čest: API za naplatu ispravno obradi zahtjev, ali se odgovor izgubi na mreži. Aktivnost zaključi da je neuspjela, platforma ponovi pokušaj i kupac dobije kredit dva puta. Ključ idempotentnosti eliminira problem dajući udaljenoj usluzi način da prepozna već obrađen zahtjev.
@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()
Generiraj ključ unutar radnog tijeka koristeći workflow.uuid4(), što jamči da ostaje identičan od jednog ponavljanja do drugog—klasični uuid.uuid4() proizveo bi novu vrijednost pri svakom pokušaju i poništio svu zaštitu. Kada udaljena usluga ne nudi ovaj mehanizam, postoje dva druga puta: upsert u bazi podataka, koristeći INSERT ... ON CONFLICT UPDATE umjesto samog INSERT, ili provjera prethodnog stanja, što uključuje upitivanje stanja prije djelovanja.
Tri profila konfiguracije
Vrijednosti se kalibriraju prema prirodi operacije. Plaćanje ili obavijest moraju uspjeti brzo ili brzo ne uspjeti: kratko vremensko ograničenje, tri pokušaja, umjereno povlačenje.
@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
Dugotrajna obrada, poput generiranja izvješća ili teške inferencije, invertira logiku: svaki pokušaj košta značajno računalno vrijeme, pa odobravaš manje pokušaja s većim razmacima.
@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
Suočen s nestabilnim API-jem treće strane podložnim ograničenjima brzine, naposljetku preuzimaš ustrajnost: pet pokušaja, čak i ako to traje nekoliko minuta.
@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 točke
- Uvijek konfiguriraj
start_to_close_timeoutkako bi izbjegao blokiranje aktivnosti - Eksponencijalno povlačenje (
retry_policy_backoff_coefficient) povećava kašnjenje između pokušaja retry_policy_max_attemptsdefinira maksimalan broj pokušaja prije konačnog neuspjeha- Aktivnosti s ponovnim pokušajem moraju biti idempotentne—isti rezultat ako se izvrše više puta
- Koristi ključeve idempotentnosti ili upserte za jamčenje idempotentnosti
- Prilagodi vremenska ograničenja i broj ponovnih pokušaja vrsti operacije (brzo naspram dugog, stabilno naspram nestabilnog)