Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Kordamispoliitika

Õppetund 12 / 14 Värskendatud 29. juuli 2026 Edasijõudnutele
Sellel lehel
  1. Miks on kordamised hädavajalikud
  2. Kordamispoliitika seadistamine
  3. Ära jäta kunagi start_to_close_timeout määramata
  4. Idempotentsus: tingimus, millest ei saa mööda vaadata
  5. Kolm konfiguratsiooniprofiili
  6. Peamised punktid

Miks on kordamised hädavajalikud

Hajussüsteemides on mööduvad vead paratamatud: võrgu aegumised, ületatud kiirusepiirangud, ajutiselt kättesaamatud teenused. Ükski neist tõrgetest ei viita veale sinu koodis, ometi võib igaüks neist põhjustada protsessi ebaõnnestumise, kui midagi lööki ei neela. Kordamispoliitika võimaldab sinu tegevustel nendest vigadest üle saada ilma käsisekkumiseta, käivitades platvorm need automaatselt uuesti vastavalt iga tegevuse jaoks määratletud seadistusele.

Kordamispoliitika seadistamine

Dekoraator @workflows.activity() aktsepteerib parameetreid, mis seda käitumist juhivad. Siin on välist API väljakutset tegev tegevus, mis on vastupidavuse jaoks korralikult relvastatud.

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

Kolm parameetrit, kolm täiendavat rolli.

  • start_to_close_timeout — Ühe täitmiskatse maksimaalne kestus. Kui tegevus selle aja jooksul ei lõpe, loetakse see ebaõnnestunuks ja käivitatakse uus katse.

  • retry_policy_max_attempts — Katsete maksimaalne arv. Vaikimisi väärtus sõltub platvormist. Pärast seda arvu katseid ebaõnnestub tegevus lõplikult ja töövoog saab veateate.

  • retry_policy_backoff_coefficient — Kordaja katsetevahelise viite jaoks. Koefitsiendiga 2.0 viited kahekordistuvad iga katsega (1 s, 2 s, 4 s, 8 s…). See on eksponentsiaalne taganemine.

See taganemismehhanism väärib tähelepanu, sest selle eesmärk pole lihtsalt ootamine: see annab raskustes teenusele aega taastuda, selle asemel et seda pommitada. Lõpuks õnnestunud kõne kulgu illustreerib seda selgelt.

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!

Vastu tulles vastusele „429 Too Many Requests“, on see mehhanism eriti tõhus: poliitika, mis prooviks kohe uuesti, ainult süvendaks ummistust, samas kui vahede suurendamine langetab lõpuks taotluste mahu alla teenusepakkuja läve.

Ära jäta kunagi start_to_close_timeout määramata

See aegumine on kriitiline ja peab ilmuma igal tegevusel, ilma erandita. Ilma selleta ootab tegevus, mis jääb seisma (surnud lukk, rippuv ühendus, teenus, mis võtab päringu vastu, kuid ei vasta kunagi), määramata aja ja külmutab kogu töövoogu. Halvemgi: see ei käivita kordamist, kuna platvormi seisukohalt pole see veel ebaõnnestunud.

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

Väärtuse määramiseks mõõda esmalt tegevuse normaalne täitmisaeg ja lisa seejärel marginaal, mis on kaks kuni kolm korda suurem, et katta aeglased juhtumid. Lõpuks veendu, et sisemise HTTP-kliendi aegumine jääks väiksemaks kui start_to_close_timeout – ülaltoodud näites 90 sekundit versus 2 minutit –, et viga leviks puhtalt sinu koodist, selle asemel et platvorm selle katkestaks.

Idempotentsus: tingimus, millest ei saa mööda vaadata

Kuna tegevust saab sama parameetritega mitu korda uuesti esitada, peab see tootma sama tulemuse sõltumata täitmiste arvust. Seda omadust nimetatakse idempotentsuseks ja selle puudumine muudab kordamispoliitika intsidentide generaatoriks.

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

Kardetud stsenaarium on levinud: arveldus-API töötleb päringu õigesti, kuid vastus kaob võrgus. Tegevus järeldab ebaõnnestumise, platvorm proovib uuesti ja klient saab krediiti kaks korda. Idempotentsusvõti kõrvaldab probleemi, andes kaugteenusele võimaluse tuvastada juba töödeldud päringut.

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

Genereeri võti töövoos kasutades workflow.uuid4(), mis garanteerib, et see jääb ühest uuestiesitusest teiseni identseks – klassikaline uuid.uuid4() toodaks iga katsega uue väärtuse ja tühistaks kogu kaitse. Kui kaugteenus seda mehhanismi ei paku, on olemas kaks muud teed: upsert andmebaasis, kasutades INSERT ... ON CONFLICT UPDATE asemel pelgalt INSERT, või eelkontroll, mis hõlmab oleku pärimist enne tegutsemist.

Kolm konfiguratsiooniprofiili

Väärtused kalibreeritakse vastavalt operatsiooni olemusele. Makse või teavituse puhul peab õnnestumine või ebaõnnestumine toimuma kiiresti: lühike aegumine, kolm katset, mõõdukas taganemine.

@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

Pikaajaline töötlemine, nagu aruannete genereerimine või mahukas järeldamine, pöörab loogika ümber: iga katse maksab olulist arvutusaja ressursse, seega lubad vähem katseid laiemate vahedega.

@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

Silmitsi ebastabiilse kolmanda osapoole API-ga, mis allub kiirusepiirangutele, eeldad lõpuks püsivust: viis katset, isegi kui see venib mitmele minutile.

@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

Peamised punktid

  • Alati seadista start_to_close_timeout, et vältida tegevuste blokeerumist
  • Eksponentsiaalne taganemine (retry_policy_backoff_coefficient) suurendab katsetevahelist viidet
  • retry_policy_max_attempts määratleb maksimaalse katsete arvu enne lõplikku ebaõnnestumist
  • Kordamisega tegevused peavad olema idempotentsed – sama tulemus ka mitmekordsel täitmisel
  • Kasuta idempotentsuse garanteerimiseks idempotentsusvõtmeid või upserte
  • Kohanda aegumisi ja kordamiste arvu operatsiooni tüübile (kiire vs pikk, stabiilne vs ebastabiilne)