Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Politika ta' Retrying

Lezzjoni 12 / 14 Aġġornat 29 ta’ Lulju 2026 Avvanzat
F'din il-paġna
  1. Għaliex ir-retrying huwa essenzjali
  2. Konfigurazzjoni ta’ politika ta’ retrying
  3. Qatt ma tħalli barra start_to_close_timeout
  4. Idempotenza: kundizzjoni mhux negozjabbli
  5. Tliet profili ta’ konfigurazzjoni
  6. Punti Ewlenin

Għaliex ir-retrying huwa essenzjali

F’sistema distribwita, l-iżbalji tranżitorji huma inevitabbli: time-outs tan-network, limiti ta’ rata (rate limits) maqbura, servizzi mhux disponibbli temporanjament. L-ebda waħda minn dawn il-fallimenti ma tindika bug fil-kodiċi tiegħek, madankollu kwalunkwe waħda minnhom tista’ tikkawża li proċess ifalli jekk xejn ma jassorbi x-xokk. Politika ta’ retrying (retry policy) tippermetti lill-attivitajiet tiegħek jissopravvivenzu dawn l-iżbalji mingħajr intervent manwali, billi l-pjattaforma terġa’ tniedihom awtomatikament skont il-konfigurazzjoni li tiddefinixxi għal kull attività.

Konfigurazzjoni ta’ politika ta’ retrying

Id-dekoratur @workflows.activity() jaċċetta parametri li jirregolaw dan l-imġiba. Hawnhekk hemm attività ta’ sejħa ta’ API esterna armata sew għar-reżiljenza.

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:
    """Issejjaħ API esterna b'retrying awtomatiku."""
    async with httpx.AsyncClient(timeout=60) as client:
        response = await client.post(url, json=data)
        response.raise_for_status()
        return response.json()

Tliet parametri, tliet rwoli komplementari.

  • start_to_close_timeout — It-tul massimu ta’ żmien għal tentattiv wieħed ta’ eżekuzzjoni. Jekk l-attività ma titlestix f’dan il-perjodu ta’ żmien, titqies bħala falluta u jinbeda tentattiv ġdid.

  • retry_policy_max_attempts — In-numru massimu ta’ tentattivi. Il-valur predefinit jiddependi mill-pjattaforma. Wara dan in-numru ta’ tentattivi, l-attività tfalli definittivament u l-workflow jirċievi żball.

  • retry_policy_backoff_coefficient — Il-multiplikatur għad-dewmien bejn it-tentattivi. B’koeffiċjent ta’ 2.0, id-dewmien jirdoppja ma’ kull tentattiv (1s, 2s, 4s, 8s…). Dan huwa “exponential backoff”.

Dan il-mekkaniżmu ta’ backoff jixraq attenzjoni għax l-għan tiegħu mhux biss li tistenna: jagħti lis-servizz li qed isofri ħin biex jirkupra minflok ma tħabbtu bla waqfien. Il-progressjoni ta’ sejħa li eventwalment tirnexxi turi dan b’mod ċar.

Tentattiv 1: eżekuzzjoni immedjata
  → Falliment (network timeout)
  → Stenna sekonda waħda

Tentattiv 2: eżekuzzjoni
  → Falliment (servizz mhux disponibbli)
  → Stenna 2 sekondi (1 × 2.0)

Tentattiv 3: eżekuzzjoni
  → Falliment (limitu ta' rata)
  → Stenna 4 sekondi (2 × 2.0)

Tentattiv 4: eżekuzzjoni
  → Suċċess!

Quddiem tweġiba “429 Too Many Requests”, dan il-mekkaniżmu huwa partikolarment effettiv: politika li tipprova mill-ġdid immedjatament biss iżżomm is-saturazzjoni, filwaqt li ż-żieda fl-ispazjar eventwalment tinżel taħt il-limitu tal-fornitur.

Qatt ma tħalli barra start_to_close_timeout

Dan it-timeout huwa kritiku u għandu jidher fuq kull attività, mingħajr eċċezzjoni. Mingħajru, attività li tispiċċa mblukkata—deadlock, konnessjoni mdendla, servizz li jaċċetta t-talba iżda qatt ma jwieġeb—tistenna għal żmien indefinit u tibblokka l-workflow kollu. Agħar minn hekk: ma jipprovoka l-ebda retry, peress li mill-perspettiva tiegħu għadu ma falliex.

 # PRATTIKA ĦŻIENA: l-ebda timeout
@workflows.activity()
async def dangerous_activity(params: dict) -> dict:
    # Jekk is-servizz qatt ma jwieġeb, l-attività tistenna għal żmien indefinit
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.lente.example.com/data")
    return response.json()

# PRATTIKA TAJBA: timeout espliċitu
@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()

Biex tissettja l-valur, l-ewwel kejjel il-ħin normali ta’ eżekuzzjoni tal-attività, imbagħad żid marġni ta’ żewġ sa tliet darbiet biex tkopri każijiet bil-mod. Fl-aħħar nett, żgura li t-timeout tal-klijent HTTP intern jibqa’ aktar baxx mill-start_to_close_timeout—fl-eżempju ta’ hawn fuq, 90 sekonda meta mqabbla ma’ 2 minuti—sabiex l-iżball jinxtered b’mod nadif mill-kodiċi tiegħek minflok ma jiġi maqtugħ mill-pjattaforma.

Idempotenza: kundizzjoni mhux negozjabbli

Peress li attività tista’ terġa’ tiġi riprodotta diversi drabi bl-istess parametri, trid tipproduċi l-istess effett irrispettivament min-numru ta’ eżekuzzjonijiet. Din il-proprjetà tissejjaħ idempotenza, u n-nuqqas tagħha jħawwel politika ta’ retrying f’ġeneratur ta’ inċidenti.

@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float) -> dict:
    """PERIKLUŻ: jekk jerġa' jsir, il-kreditu jiżdied diversi drabi!"""
    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()

L-ixraħ xenarju huwa komuni: l-API tal-fatturar tipproċessa t-talba korrettament, iżda t-tweġiba tintilef fin-network. L-attività tikkonkludi li falliet, il-pjattaforma tipprova mill-ġdid, u l-klijent jiġi akkreditat darbtejn. Ċavetta ta’ idempotenza (idempotency key) telimina l-problema billi tagħti lis-servizz remot mod biex jirrikonoxxi talba diġà pproċessata.

@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float, idempotency_key: str) -> dict:
    """KORRETT: iċ-ċavetta ta' idempotenza tevita d-duplikazzjoni."""
    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()

Iġġenera ċ-ċavetta fil-workflow bl-użu ta’ workflow.uuid4(), li jiggarantixxi li tibqa’ identika minn replay għal ieħor—uuid.uuid4() klassiku jipproduċi valur ġdid fuq kull tentattiv u jikkanċella l-protezzjoni kollha. Meta s-servizz remot ma joffrix dan il-mekkaniżmu, jeżistu żewġ triqat oħra: upsert fil-bażi tad-data, bl-użu ta’ INSERT ... ON CONFLICT UPDATE minflok INSERT biss, jew verifika ta’ pre-check, li tinvolvi l-ikkonsultar tal-istat qabel ma taġixxi.

Tliet profili ta’ konfigurazzjoni

Il-valuri jiġu kkwalibrati skont in-natura tal-operazzjoni. Pagament jew notifika trid tirnexxi malajr jew tfalli malajr: timeout qasir, tliet tentattivi, backoff moderat.

@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

Ipproċessar fit-tul, bħall-ġenerazzjoni ta’ rapporti jew inferenza tqila, jinverti l-loġika: kull tentattiv jispiċċa ħin ta’ komputazzjoni sinifikanti, għalhekk tawtorizza inqas tentattivi b’ispazjar usa’.

@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

Quddiem API ta’ parti terza instabbli soġġetta għal limitazzjoni ta’ rata (rate limiting), finalment tassumi l-persistenza: ħames tentattivi, anke jekk dan ifittex diversi minuti.

@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

Punti Ewlenin

  • Dejjem ikkonfigura start_to_close_timeout biex tevita attivitajiet imblukkati
  • Exponential backoff (retry_policy_backoff_coefficient) jiżdied id-dewmien bejn it-tentattivi
  • retry_policy_max_attempts jiddefinixxi n-numru massimu ta’ tentattivi qabel il-falliment definittiv
  • Attivitajiet b’retrying iridu jkunu idempotenti—l-istess riżultat jekk jiġu eżegwiti diversi drabi
  • Uża ċwievet ta’ idempotenza jew upserts biex tiggarantixxi l-idempotenza
  • Adatta t-timeouts u n-numru ta’ tentattivi għat-tip ta’ operazzjoni (mgħaġġla vs twila, stabbli vs instabbli)