Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Politika opakovania

Lekcia 12 z 14 Aktualizované 29. júla 2026 Pokročilý
Na tejto strane
  1. Prečo sú opakovania nevyhnutné
  2. Konfigurácia politiky opakovania
  3. Nikdy nevynechávaj start_to_close_timeout
  4. Idempotencia: nepostrádateľná podmienka
  5. Tri konfiguračné profily
  6. Kľúčové poznatky

Prečo sú opakovania nevyhnutné

V distribuovanom systéme sú prechodné chyby nevyhnutné: časové limity siete, prekročené limity rýchlosti alebo dočasne nedostupné služby. Žiadna z týchto chýb neznamená chybu vo tvojom kóde, no ktorákoľvek z nich môže spôsobiť zlyhanie procesu, ak nič neabsorbuje náraz. Politika opakovania umožňuje tvojim aktivitám prežiť tieto chyby bez manuálneho zásahu, pričom platforma ich automaticky spustí znova podľa konfigurácie, ktorú definuješ pre každú aktivitu.

Konfigurácia politiky opakovania

Dekorátor @workflows.activity() prijíma parametre, ktoré riadia toto správanie. Tu je aktivita volajúca externé API, správne vybavená pre odolnosť.

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 parametre, tri doplnkové role.

  • start_to_close_timeout — Maximálna dĺžka trvania jedného pokusu o vykonanie. Ak sa aktivita neukončí v tomto časovom rámci, považuje sa za zlyhanú a spustí sa nový pokus.

  • retry_policy_max_attempts — Maximálny počet pokusov. Predvolená hodnota závisí od platformy. Po tomto počte pokusov aktivita definitívne zlyhá a workflow dostane chybu.

  • retry_policy_backoff_coefficient — Násobiteľ oneskorenia medzi pokusmi. Pri koeficiente 2,0 sa oneskorenia s každým pokusom zdvojnásobia (1 s, 2 s, 4 s, 8 s…). Toto je exponenciálne oneskorovanie (exponential backoff).

Tento mechanizmus oneskorovania si zaslúži pozornosť, pretože jeho účelom nie je len čakať: dáva trpiacej službe čas na zotavenie namiesto toho, aby si ju bombardoval požiadavkami. Priebeh volania, ktoré nakoniec uspeje, to jasne ilustruje.

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!

Pri odpovedi „429 Too Many Requests“ je tento mechanizmus obzvlášť účinný: politika, ktorá by opakovala okamžite, by len udržiavala saturáciu, zatiaľ čo zväčšovanie rozostupov časom klesne pod prah poskytovateľa.

Nikdy nevynechávaj start_to_close_timeout

Tento časový limit je kritický a musí sa objaviť pri každej aktivite, bez výnimky. Bez neho aktivita, ktorá sa zasekne (deadlock, visiaci spoj, služba, ktorá prijme požiadavku, ale nikdy neodpovie), čaká donekonečna a zmrazí celé workflow. Ešte horšie: nespustí sa žiadne opakovanie, keďže z jej pohľadu ešte nezlyhala.

# 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()

Na nastavenie hodnoty najprv zmeraj bežný čas vykonania aktivity, potom pridaj rezervu dvojnásobnú až trojnásobnú na pokrytie pomalších prípadov. Nakoniec sa uisti, že vnútorný časový limit HTTP klienta zostane nižší ako start_to_close_timeout – v príklade vyššie 90 sekúnd oproti 2 minútam – aby sa chyba správne preniesla z tvojho kódu, namiesto toho, aby ju platforma prerušila.

Idempotencia: nepostrádateľná podmienka

Keďže aktivita sa môže viackrát prehrať s rovnakými parametrami, musí produkovať rovnaký efekt bez ohľadu na počet vykonaní. Táto vlastnosť sa nazýva idempotencia a jej absencia mení politiku opakovania na generátor 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()

Obávaný scenár je bežný: fakturačné API spracuje požiadavku správne, ale odpoveď sa stratí v sieti. Aktivita vyhodnotí zlyhanie, platforma to skúsi znova a zákazník dostane kredit dvakrát. Kľúč idempotencie tento problém eliminuje tým, že vzdialenej službe poskytne spôsob, ako rozpoznať už spracovanú požiadavku.

@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()

Kľúč vygeneruj vo workflow pomocou workflow.uuid4(), čo zaručí, že zostane identický od jedného prehratia k druhému – klasické uuid.uuid4() by vyprodukovalo novú hodnotu pri každom pokuse a zrušilo by všetku ochranu. Keď vzdialená služba tento mechanizmus neponúka, existujú dve ďalšie cesty: upsert v databáze (použitie INSERT ... ON CONFLICT UPDATE namiesto samotného INSERT) alebo overenie pred kontrolou, čo zahŕňa dotazovanie sa na stav pred konaním.

Tri konfiguračné profily

Hodnoty sa kalibrujú podľa povahy operácie. Platba alebo oznámenie musia rýchlo uspieť alebo rýchlo zlyhať: krátky časový limit, tri pokusy, mierne oneskorenie.

@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

Dlhodobé spracovanie, ako je generovanie reportov alebo ťažká inferencia, obracia logiku: každý pokus stojí významný výpočtový čas, preto povoľuješ menej pokusov s väčšími rozostupmi.

@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

Tvárou v tvár nestabilnému API tretej strany podliehajúcemu obmedzeniu rýchlosti nakoniec predpokladáš vytrvalosť: päť pokusov, aj keď to potrvá niekoľko minút.

@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

Kľúčové poznatky

  • Vždy konfiguruj start_to_close_timeout, aby si predišiel blokovaniu aktivít
  • Exponenciálne oneskorovanie (retry_policy_backoff_coefficient) zvyšuje oneskorenie medzi pokusmi
  • retry_policy_max_attempts definuje maximálny počet pokusov pred definitívnym zlyhaním
  • Aktivity s opakovaním musia byť idempotentné – rovnaký výsledok pri viacnásobnom vykonaní
  • Na zaručenie idempotencie používaj kľúče idempotencie alebo upserty
  • Prispôsob časové limity a počty opakovaní typu operácie (rýchla vs. dlhá, stabilná vs. nestabilná)