Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Ismétlési házirend

12. lecke 14 közül Frissítve 2026. július 29. Haladó
Ezen az oldalon
  1. Miért elengedhetetlenek az ismétlések?
  2. Ismétlési házirend konfigurálása
  3. Soha ne hagyd ki a start_to_close_timeout értéket
  4. Idempotencia: nem tárgyalható feltétel
  5. Három konfigurációs profil
  6. Főbb megállapítások

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_attempts hatá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)