Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Polasaí Athiarrachta

Ceacht 12 as 14 Nuashonraithe 29 Iúil 2026 Ardleibhéal
Ar an leathanach seo
  1. Cén fáth a bhfuil athiarrachtaí riachtanach
  2. Polasaí athiarrachta a chumrú
  3. Ná fág start_to_close_timeout ar lár riamh
  4. Idempotence: coinníoll nach féidir a sheachaint
  5. Trí phróifíl chumraíochta
  6. Príomhphointí

Cén fáth a bhfuil athiarrachtaí riachtanach

I gcóras dáilte, tá earráidí sealadacha dosheachanta: amanna teasta na líonra, teorainneacha ráta sáraithe, seirbhísí nach bhfuil ar fáil go sealadach. Ní léiríonn aon cheann de na teipeanna seo bug i do chód, ach is féidir le haon cheann acu próiseas a theip mura ndéanann rud éigin an turraing a mhaolú. Ligeann polasaí athiarrachta do do ghníomhaíochtaí teacht slán ó na hearráidí seo gan idirghabháil láimhe, agus athsheolann an t-ardán iad go huathoibríoch de réir an chumraíochta a shainíonn tú do gach gníomhaíocht.

Polasaí athiarrachta a chumrú

Glacann an maisiúchán @workflows.activity() le paraiméadair a rialaíonn an iompar seo. Seo gníomhaíocht glaonna API seachtracha atá armtha go cuí d’fhulaingt.

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

Trí pharaiméadar, trí ról comhlántach.

  • start_to_close_timeout — An fad uasta d’aon iarracht feidhmithe amháin. Mura gcríochnaíonn an ghníomhaíocht laistigh den amchlár seo, meastar go dteip air agus seoltar iarracht nua.

  • retry_policy_max_attempts — An líon uasta iarrachtaí. Braitheann an luach réamhshocraithe ar an ardán. Tar éis an líon sin iarrachtaí, teipeann ar an ngníomhaíocht go cinntitheach agus faigheann an sruth oibre earráid.

  • retry_policy_backoff_coefficient — Iolraitheoir don mhoill idir iarrachtaí. Le comhéifeacht 2.0, dúbailtear na moilleanna le gach iarracht (1s, 2s, 4s, 8s…). Is é seo cúlú easpónantúil.

Tuillfidh an mheicníocht chúlaithe seo aird, toisc nach fanacht amháin atá i gceist léi: tugann sí am don tseirbhís atá i dtrioblóid teacht chuici féin in ionad í a bhuailt gan stad. Léiríonn dul chun cinn glaonna a éiríonn leis sa deireadh é seo go soiléir.

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!

Agus tú ag tabhairt aghaidh ar fhreagra “429 Too Many Requests”, tá an mheicníocht seo thar a bheith éifeachtach: bheadh polasaí a dhéanfadh athiarracht láithreach ag cothú na sáithithe ach amháin, cé go dtiteann spásáil mhéadaithe faoi bhun tairsí an tsoláthraí sa deireadh.

Ná fág start_to_close_timeout ar lár riamh

Tá an t-am-teorainn seo ríthábhachtach agus ba chóir go mbeadh sé ar gach gníomhaíocht, gan eisceacht. Gan é, fanann gníomhaíocht a ghlasálann—marbhghlas, nasc crochta, seirbhís a ghlacann an t-iarratas ach nach bhfreagraíonn riamh—go deo agus reoíonn sí an sruth oibre ar fad. Is measa fós: ní spreagann sé aon athiarracht, ós rud é nach dteip air óna pheirspictíocht féin fós.

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

Chun an luach a shocrú, tomhais ar dtús an t-am feidhmithe gnáth don ghníomhaíocht, ansin cuir corrlach de dhá go trí huaire leis chun cásanna mall a chlúdach. Ar deireadh, déan cinnte go bhfanann am-teorainn an chliaint HTTP inmheánaigh níos ísle ná an start_to_close_timeout—san sampla thuas, 90 soicind i gcoinne 2 nóiméad—ionas go scaipeann an earráid go glan ó do chód seachas a bheith gearrtha ag an ardán.

Idempotence: coinníoll nach féidir a sheachaint

Ós rud é gur féidir gníomhaíocht a athsheinm uaireanta iomadúla leis na paraiméadair chéanna, caithfidh sí an éifeacht chéanna a tháirgeadh beag beann ar líon na bhfeidhmithe. Tugtar idempotence ar an airí seo, agus casann a easnamh polasaí athiarrachta ina ghineadóir teagmhas.

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

Is coitianta an cás uafásach: próiseálann an API billeála an t-iarratas i gceart, ach cailleadh an freagra ar an líonra. Conclúideann an ghníomhaíocht go dteip air, déanann an t-ardán athiarracht, agus faigheann an custaiméir creidiúint faoi dhó. Cuireann eochair idempotachta deireadh leis an bhfadhb trí bhealach a thabhairt don tseirbhís i gcéin aitheantas a thabhairt d’iarratas a próiseáladh cheana.

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

Gin an eochair sa sruth oibre ag baint úsáide as workflow.uuid4(), a ráthaíonn go bhfanann sé mar an gcéanna ó athsheinm go chéile—chruthódh uuid.uuid4() clasaiceach luach nua ar gach iarracht agus chuirfeadh sé ar ceal gach cosaint. Nuair nach dtairgeann an tseirbhís i gcéin an mheicníocht seo, tá dhá bhealach eile ann: upsert sa bhunachar sonraí, ag baint úsáide as INSERT ... ON CONFLICT UPDATE in ionad INSERT amháin, nó fíorú réamh-sheiceála, a bhaineann le staid a fhiosrú sula ndéantar gníomh.

Trí phróifíl chumraíochta

Déantar luachanna a chalabrú de réir nádúr na hoibríochta. Caithfidh íocaíocht nó fógra éirí leis go tapa nó teip go tapa: am-teorainn gairid, trí iarracht, cúlú measartha.

@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

Próiseáil fhada, mar shampla giniúint tuarascála nó infheicneacht throm, a mhalartaíonn an loighic: costáil gach iarracht am ríomhaireachta suntasach, mar sin údaróidh tú níos lú iarrachtaí le spásáil níos leithne.

@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

Agus tú ag tabhairt aghaidh ar API tríú páirtí éagobhsaí atá faoi réir teorannú ráta, glacann tú le buanseasmhacht ar deireadh: cúig iarracht, fiú má shíneann sé thar roinnt nóiméad.

@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

Príomhphointí

  • Cumraigh start_to_close_timeout i gcónaí chun gníomhaíochtaí a bhlocáil a sheachaint
  • Méadaíonn cúlú easpónantúil (retry_policy_backoff_coefficient) an mhoill idir iarrachtaí
  • Sainíonn retry_policy_max_attempts an líon uasta iarrachtaí sula dteipeann go cinntitheach
  • Caithfidh gníomhaíochtaí le hathiarracht a bheith idempotach—an toradh céanna má fheidhmítear iad uaireanta iomadúla
  • Úsáid eochracha idempotachta nó upserts chun idempotence a ráthú
  • Oiriúnaigh amanna-teorainn agus líonta athiarrachta don chineál oibríochta (tapa vs. fada, cobhsaí vs. éagobhsaí)