Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Retry Policy

Oppitunti 12 / 14 Päivitetty 29. heinäkuuta 2026 Edistynyt
Tällä sivulla
  1. Miksi uudelleenyritykset ovat välttämättömiä
  2. Uudelleenyrityskäytännön määrittäminen
  3. Älä koskaan unohda start_to_close_timeout-aikakatkaisua
  4. Idempotenssi: ehdoton vaatimus
  5. Kolme konfiguraatioprofiilia
  6. Keskeiset asiat

Miksi uudelleenyritykset ovat välttämättömiä

Hajautetuissa järjestelmissä ohimenevät virheet ovat väistämättömiä: verkkokatkokset, ylitetyt nopeusrajoitukset tai väliaikaisesti tavoittamattomat palvelut. Mikään näistä vioista ei kerro koodissasi olevasta bugista, mutta yksikin niistä voi kaataa prosessin, ellei järjestelmä pysty absorboimaan iskua. Uudelleenyrityskäytäntö (retry policy) mahdollistaa sen, että aktiviteettisi selviävät näistä virheistä ilman manuaalista puuttumista: alusta käynnistää ne uudelleen automaattisesti määrittämäsi konfiguraation mukaisesti.

Uudelleenyrityskäytännön määrittäminen

@workflows.activity()-dekoraattori hyväksyy parametreja, jotka ohjaavat tätä käyttäytymistä. Tässä on ulkoista API-kutsua tekevä aktiviteetti, joka on varustettu kestävyyttä varten.

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

Kolme parametria, kolme täydentävää roolia.

  • start_to_close_timeout — Yhden suoritusyrityksen enimmäiskesto. Jos aktiviteetti ei valmistu tässä ajassa, se katsotaan epäonnistuneeksi ja uusi yritys käynnistetään.

  • retry_policy_max_attempts — Yritysten enimmäismäärä. Oletusarvo riippuu alustasta. Tämän määrän jälkeen aktiviteetti epäonnistuu lopullisesti ja workflow vastaanottaa virheen.

  • retry_policy_backoff_coefficient — Viiveen kerroin yritysten välillä. Kertoimella 2.0 viiveet kaksinkertaistuvat jokaisella yrityksellä (1 s, 2 s, 4 s, 8 s…). Tätä kutsutaan eksponentiaaliseksi viiveeksi (exponential backoff).

Tämä viivemekanismi ansaitsee huomiota, sillä sen tarkoitus ei ole vain odottaa: se antaa hädässä olevalle palvelulle aikaa toipua sen sijaan, että sitä pommitettaisiin pyynnöillä. Lopulta onnistuvan kutsun eteneminen havainnollistaa tätä selkeästi.

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!

Kohdatessasi vastauksen “429 Too Many Requests”, tämä mekanismi on erityisen tehokas: käytäntö, joka yrittäisi heti uudelleen, vain ylläpitäisi ruuhkaa, kun taas viiveen kasvattaminen pudottaa pyyntötiheyden lopulta tarjoajan kynnyksen alapuolelle.

Älä koskaan unohda start_to_close_timeout-aikakatkaisua

Tämä aikakatkaisu on kriittinen, ja sen tulee esiintyä jokaisessa aktiviteetissa ilman poikkeuksia. Ilman sitä aktiviteetti, joka jumittuu (deadlock, roikkuva yhteys tai palvelu, joka hyväksyy pyynnön mutta ei koskaan vastaa), odottaa loputtomiin ja jäädyttää koko workflow’n. Pahempaa vielä: se ei laukaise uudelleenyritystä, sillä alustan näkökulmasta aktiviteetti ei ole vielä epäonnistunut.

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

Asettaaksesi arvon, mittaa ensin aktiviteetin normaali suoritusaika ja lisää siihen kahden tai kolmen kertaisen marginaali hitaiden tapausten varalle. Varmista lopuksi, että sisäisen HTTP-asiakkaan aikakatkaisu on pienempi kuin start_to_close_timeout – yllä olevassa esimerkissä 90 sekuntia versus 2 minuuttia – jotta virhe etenee siististi koodistasi sen sijaan, että alusta katkaisisi sen.

Idempotenssi: ehdoton vaatimus

Koska aktiviteetti voidaan toistaa useita kertoja samoilla parametreilla, sen on tuotettava sama vaikutus suorituskerroista riippumatta. Tätä ominaisuutta kutsutaan idempotenssiksi, ja sen puuttuminen muuttaa uudelleenyrityskäytännön incidenttigeneraattoriksi.

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

Pelätty skenaario on yleinen: laskutus-API käsittelee pyynnön oikein, mutta vastaus katoaa verkossa. Aktiviteetti päättelee epäonnistumisen, alusta yrittää uudelleen, ja asiakas saa hyvityksen kahdesti. Idempotenssiavain poistaa ongelman antamalla etäpalvelulle tavan tunnistaa jo käsitelty pyyntö.

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

Generoi avain workflowssa käyttämällä workflow.uuid4():tä, mikä takaa sen pysyvän identtisenä toistosta toiseen – klassinen uuid.uuid4() tuottaisi uuden arvon jokaisella yrityksellä ja kumoaisi kaiken suojan. Kun etäpalvelu ei tarjoa tätä mekanismia, on olemassa kaksi muuta reittiä: upsert-tietokantaan käyttämällä INSERT ... ON CONFLICT UPDATE pelkän INSERT:n sijaan, tai tilan ennakkotarkistus, joka tarkoittaa tilan kysymistä ennen toimintaa.

Kolme konfiguraatioprofiilia

Arvot kalibroidaan operaation luonteen mukaan. Maksun tai ilmoituksen on onnistuttava nopeasti tai epäonnistuttava nopeasti: lyhyt aikakatkaisu, kolme yritystä, kohtuullinen viivekerroin.

@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

Pitkäkestoinen käsittely, kuten raportin generointi tai raskas inferenssi, kääntää logiikan päälaelleen: jokainen yritys maksaa merkittävästi laskenta-aikaa, joten hyväksyt vähemmän yrityksiä suuremmilla viiveillä.

@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

Epävakaan, nopeusrajoitetun kolmannen osapuolen API:n edessä omaksut viimeisenä keinona sitkeyden: viisi yritystä, vaikka se venyisi useiden minuuttien mittaiseksi.

@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

Keskeiset asiat

  • Määritä aina start_to_close_timeout välttääksesi aktiviteettien jumittumisen
  • Eksponentiaalinen viive (retry_policy_backoff_coefficient) kasvattaa yritysten välistä odotusaikaa
  • retry_policy_max_attempts määrittää yritysten enimmäismäärän ennen lopullista epäonnistumista
  • Uudelleenyrityksiä käyttävien aktiviteettien on oltava idempotentteja – sama tulos vaikka suoritettaisiin useita kertoja
  • Käytä idempotenssiavaimia tai upserteja idempotenssin takaamiseksi
  • Sovita aikakatkaisut ja yritysmäärät operaatiotyypin mukaan (nopea vs. pitkä, vakaa vs. epävakaa)