Politica de reîncercare
Pe această pagină
De ce sunt esențiale reîncercările
Într-un sistem distribuit, erorile tranzitorii sunt inevitabile: timeout-uri de rețea, depășirea limitelor de rată (rate limits), servicii indisponibile temporar. Niciuna dintre aceste defecțiuni nu indică o eroare în codul dumneavoastră, totuși oricare dintre ele poate duce la eșecul unui proces dacă nimic nu absoarbe șocul. O politică de reîncercare permite activităților dumneavoastră să supraviețuiască acestor erori fără intervenție manuală, platforma relansându-le automat conform configurației definite pentru fiecare activitate.
Configurarea unei politici de reîncercare
Decoratorul @workflows.activity() acceptă parametri care guvernează acest comportament. Iată o activitate de apel API extern configurată corect pentru reziliență.
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()
Trei parametri, trei roluri complementare.
-
start_to_close_timeout— Durata maximă pentru o singură încercare de execuție. Dacă activitatea nu se finalizează în acest interval de timp, este considerată eșuată și se lansează o nouă încercare. -
retry_policy_max_attempts— Numărul maxim de încercări. Valoarea implicită depinde de platformă. După acest număr de încercări, activitatea eșuează definitiv, iar fluxul de lucru (workflow) primește o eroare. -
retry_policy_backoff_coefficient— Multiplicatorul pentru întârzierea dintre încercări. Cu un coeficient de 2.0, întârzierile se dublează la fiecare încercare (1s, 2s, 4s, 8s…). Aceasta este o strategie de backoff exponențial.
Acest mecanism de backoff merită atenție deoarece scopul său nu este doar așteptarea: oferă serviciului aflat în dificultate timp să își revină, în loc să fie bombardat cu cereri. Evoluția unui apel care reușește în final ilustrează acest lucru clar.
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!
În fața unui răspuns „429 Too Many Requests“, acest mecanism este deosebit de eficient: o politică ce ar reîncerca imediat nu ar face decât să mențină saturația, în timp ce creșterea spațierii permite eventual scăderea sub pragul furnizorului.
Nu omiteți niciodată start_to_close_timeout
Acest timeout este critic și trebuie să apară la fiecare activitate, fără excepție. Fără el, o activitate care se blochează—deadlock, conexiune suspendată, serviciu care acceptă cererea dar nu răspunde niciodată—așteaptă la infinit și îngheață întregul flux de lucru. Mai grav: nu declanșează nicio reîncercare, deoarece din perspectiva sa nu a eșuat încă.
# 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()
Pentru a stabili valoarea, măsurați mai întâi timpul normal de execuție al activității, apoi adăugați o marjă de două până la trei ori pentru a acoperi cazurile lente. În final, asigurați-vă că timeout-ul clientului HTTP intern rămâne mai mic decât start_to_close_timeout—în exemplul de mai sus, 90 de secunde față de 2 minute—astfel încât eroarea să se propage corect din codul dumneavoastră, în loc să fie întreruptă brusc de platformă.
Idempotența: o condiție non-negociabilă
Deoarece o activitate poate fi rejucată de mai multe ori cu aceiași parametri, aceasta trebuie să producă același efect indiferent de numărul de execuții. Această proprietate se numește idempotență, iar absența ei transformă o politică de reîncercare într-un generator de incidente.
@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()
Scenariul temut este comun: API-ul de facturare procesează cererea corect, dar răspunsul se pierde în rețea. Activitatea concluzionează eșecul, platforma reîncearcă, iar clientul este creditat de două ori. O cheie de idempotență elimină problema, oferind serviciului remote un mod de a recunoaște o cerere deja procesată.
@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()
Generați cheia în fluxul de lucru folosind workflow.uuid4(), ceea ce garantează că aceasta rămâne identică de la o rejucare la alta—un uuid.uuid4() clasic ar produce o valoare nouă la fiecare încercare și ar anula orice protecție. Când serviciul remote nu oferă acest mecanism, există alte două căi: upsert în baza de date, folosind INSERT ... ON CONFLICT UPDATE în loc de simplu INSERT, sau verificare prealabilă, care implică interogarea stării înainte de a acționa.
Trei profile de configurare
Valorile se calibrează în funcție de natura operațiunii. O plată sau o notificare trebuie să reușească rapid sau să eșueze rapid: timeout scurt, trei încercări, 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
Procesările de lungă durată, cum ar fi generarea de rapoarte sau inferența complexă, inversează logica: fiecare încercare costă timp semnificativ de calcul, așa că autorizați mai puține încercări cu o spațiere mai largă.
@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
În fața unui API terț instabil, supus limitării ratei, adoptați în final persistența: cinci încercări, chiar dacă aceasta se întinde pe câteva minute.
@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
Puncte cheie
- Configurați întotdeauna
start_to_close_timeoutpentru a evita blocarea activităților - Backoff-ul exponențial (
retry_policy_backoff_coefficient) mărește întârzierea dintre încercări retry_policy_max_attemptsdefinește numărul maxim de încercări înainte de eșecul definitiv- Activitățile cu reîncercare trebuie să fie idempotente—același rezultat dacă sunt executate de mai multe ori
- Folosiți chei de idempotență sau upserts pentru a garanta idempotența
- Adaptați timeout-urile și numărul de reîncercări la tipul de operațiune (rapid vs. lung, stabil vs. instabil)