Kordamispoliitika
Sellel lehel
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_attemptsmää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)