Ismétlési házirend
Ezen az oldalon
Miért elengedhetetlenek az ismétlések?
Elosztott rendszerekben az átmeneti hibák elkerülhetetlenek: hálózati időtúllépések, túlléptetett sebességkorlátok, ideiglenesen elérhetetlen szolgáltatások. Egyik hiba sem utal kódhibára, mégis bármelyikük meghiúsíthat egy folyamatot, ha nincs ami elnyelje a lökést. Az ismétlési házirend lehetővé teszi, hogy tevékenységeid túléljék ezeket a hibákat emberi beavatkozás nélkül: a platform automatikusan újraindítja őket az egyes tevékenységekhez definiált konfiguráció szerint.
Ismétlési házirend konfigurálása
A @workflows.activity() dekorátor olyan paramétereket fogad el, amelyek ezt a viselkedést szabályozzák. Íme egy külső API-hívást végző tevékenység, amelyet megfelelően felkészítettünk a hibatűrésre.
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()
Három paraméter, három kiegészítő szerep.
-
start_to_close_timeout— Egyetlen végrehajtási kísérlet maximális időtartama. Ha a tevékenység nem fejeződik be ezen időkereten belül, sikertelennek minősül, és a rendszer elindít egy újabb kísérletet. -
retry_policy_max_attempts— Kísérletek maximális száma. Az alapértelmezett érték a platformtól függ. Ennyi kísérlet után a tevékenység véglegesen meghiúsul, és a munkafolyamat hibát kap. -
retry_policy_backoff_coefficient— A kísérletek közötti várakozási idő szorzója. 2,0-s együttható esetén a várakozási idők minden kísérlettel megduplázódnak (1 mp, 2 mp, 4 mp, 8 mp…). Ezt nevezzük exponenciális visszalépésnek (exponential backoff).
Ez a visszalépési mechanizmus figyelmet érdemel, mert célja nem csupán a várakozás: időt ad a küzdő szolgáltatásnak a felépülésre, ahelyett, hogy folyamatosan terhelnéd. Egy végül sikerrel záruló hívás menete ezt világosan illusztrálja.
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!
„429 Too Many Requests“ válasz esetén ez a mechanizmus különösen hatékony: egy azonnal ismétlő házirend csak fenntartaná a telítettséget, míg a növekvő időközökkel végül a szolgáltató küszöbértéke alá csökkented a kérések sűrűségét.
Soha ne hagyd ki a start_to_close_timeout értéket
Ez az időkorlát kritikus fontosságú, és kivétel nélkül minden tevékenységnél meg kell adni. Enélkül egy beragadt tevékenység – holtpont, lógó kapcsolat, olyan szolgáltatás, amely fogadja a kérést, de sosem válaszol – végtelenül várakozik, és befagyasztja az egész munkafolyamatot. Ami még rosszabb: nem indít el ismétlést, hiszen a platform szemszögéből a tevékenység még nem hibázott meg.
# 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()
Az érték beállításához először mérd meg a tevékenység normál végrehajtási idejét, majd adj hozzá két-háromszoros tartalékot a lassú esetek lefedésére. Végül győződj meg róla, hogy a belső HTTP-kliens időkorlátja alacsonyabb, mint a start_to_close_timeout – a fenti példában 90 másodperc szemben 2 perccel –, így a hiba tisztán propagálódik a kódodból, ahelyett, hogy a platform vágná el.
Idempotencia: nem tárgyalható feltétel
Mivel egy tevékenység többször is lejátszódhat ugyanazon paraméterekkel, ugyanazt a hatást kell produireálnia a végrehajtások számától függetlenül. Ezt a tulajdonságot idempotenciának nevezzük, és annak hiánya incidensgenerátorrá változtatja az ismétlési házirendet.
@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()
A rettegett forgatókönyv gyakori: a számlázási API helyesen feldolgozza a kérést, de a válasz elveszik a hálózaton. A tevékenység sikertelennek minősül, a platform újrapróbálkozik, és az ügyfél kétszer kap jóváírást. Egy idempotencia-kulcs megszünteti a problémát, mivel lehetőséget ad a távoli szolgáltatásnak, hogy felismerje a már feldolgozott kérést.
@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()
A kulcsot a munkafolyamatban a workflow.uuid4() függvénnyel generáld, ami garantálja, hogy az érték minden újrajátszásnál ugyanaz marad – egy klasszikus uuid.uuid4() minden próbálkozásnál új értéket hozna létre, és megszüntetné a védelmet. Ha a távoli szolgáltatás nem kínálja ezt a mechanizmust, két másik út létezik: upsert művelet az adatbázisban (az INSERT helyett INSERT ... ON CONFLICT UPDATE használata), vagy előzetes ellenőrzés, ami az állapot lekérdezését jelenti a művelet végrehajtása előtt.
Három konfigurációs profil
Az értékeket a művelet jellege szerint kalibrálod. Egy fizetésnek vagy értesítésnek gyorsan sikerülnie kell, vagy gyorsan meg kell hiúsulnia: rövid időkorlát, három próbálkozás, mérsékelt visszalépés.
@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
A hosszú futású feldolgozás, mint például a jelentésgenerálás vagy a nehéz inferencia, megfordítja a logikát: mivel minden kísérlet jelentős számítási időbe kerül, kevesebb próbálkozást engedélyez szélesebb időközökkel.
@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
Instabil, sebességkorlátozás alá eső harmadik féltől származó API esetén végül a kitartást választod: öt próbálkozás, még akkor is, ha ez több percet vesz igénybe.
@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
Főbb megállapítások
- Mindig állítsd be a
start_to_close_timeoutértéket a tevékenységek blokkolódásának elkerülése érdekében - Az exponenciális visszalépés (
retry_policy_backoff_coefficient) növeli a kísérletek közötti várakozási időt - A
retry_policy_max_attemptshatározza meg a végleges meghibásodás előtti maximális próbálkozások számát - Az ismétléssel rendelkező tevékenységeknek idempotensnek kell lenniük – ugyanazt az eredményt adják többszöri végrehajtás esetén is
- Használj idempotencia-kulcsokat vagy upsert műveleteket az idempotencia garantálásához
- Igazítsd az időkorlátokat és az ismétlések számát a művelet típusához (gyors vs. hosszú, stabil vs. instabil)