Politica di ritentativo
In questa pagina
Perché i ritentativi sono essenziali
In un sistema distribuito, gli errori transitori sono inevitabili: timeout di rete, limiti di frequenza superati, servizi temporaneamente non disponibili. Nessuno di questi guasti indica un bug nel tuo codice, eppure ciascuno di essi può far fallire un processo se nulla ne assorbe l’impatto. Una politica di ritentativo permette alle tue attività di sopravvivere a questi errori senza intervento manuale, con la piattaforma che le rilancia automaticamente secondo la configurazione che definisci per ciascuna attività.
Configurare una politica di ritentativo
Il decoratore @workflows.activity() accetta parametri che governano questo comportamento. Ecco un’attività di chiamata API esterna correttamente attrezzata per la resilienza.
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()
Tre parametri, tre ruoli complementari.
-
start_to_close_timeout— Durata massima per un singolo tentativo di esecuzione. Se l’attività non si completa entro questo lasso di tempo, viene considerata fallita e ne viene lanciato un nuovo tentativo. -
retry_policy_max_attempts— Numero massimo di tentativi. Il valore predefinito dipende dalla piattaforma. Dopo questo numero di tentativi, l’attività fallisce definitivamente e il workflow riceve un errore. -
retry_policy_backoff_coefficient— Moltiplicatore per il ritardo tra i tentativi. Con un coefficiente di 2.0, i ritardi raddoppiano a ogni tentativo (1s, 2s, 4s, 8s…). Questo è il backoff esponenziale.
Questo meccanismo di backoff merita attenzione perché il suo scopo non è solo aspettare: dà tempo al servizio in difficoltà di recuperare invece di martellarlo. La progressione di una chiamata che alla fine ha successo lo illustra chiaramente.
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!
Di fronte a una risposta “429 Too Many Requests”, questo meccanismo è particolarmente efficace: una politica che ritentasse immediatamente non farebbe che sostenere la saturazione, mentre aumentare lo spaziamento permette infine di scendere sotto la soglia del provider.
Non omettere mai start_to_close_timeout
Questo timeout è critico e deve apparire su ogni attività, senza eccezioni. Senza di esso, un’attività che si blocca—deadlock, connessione pendente, servizio che accetta la richiesta ma non risponde mai—attende indefinitamente e congela l’intero workflow. Peggio ancora: non attiva alcun ritentativo, poiché dal suo punto di vista non è ancora fallita.
# 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()
Per impostare il valore, misura prima il tempo di esecuzione normale dell’attività, quindi aggiungi un margine di due o tre volte per coprire i casi lenti. Infine, assicurati che il timeout del client HTTP interno rimanga inferiore al start_to_close_timeout—nell’esempio sopra, 90 secondi contro 2 minuti—affinché l’errore si propaghi pulitamente dal tuo codice invece di essere troncato dalla piattaforma.
Idempotenza: una condizione non negoziabile
Poiché un’attività può essere rieseguita più volte con gli stessi parametri, deve produrre lo stesso effetto indipendentemente dal numero di esecuzioni. Questa proprietà si chiama idempotenza e la sua assenza trasforma una politica di ritentativo in un generatore di incidenti.
@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()
Lo scenario temuto è comune: l’API di fatturazione elabora correttamente la richiesta, ma la risposta si perde sulla rete. L’attività conclude con un fallimento, la piattaforma ritenta e il cliente viene accreditato due volte. Una chiave di idempotenza elimina il problema fornendo al servizio remoto un modo per riconoscere una richiesta già elaborata.
@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 la chiave nel workflow usando workflow.uuid4(), che garantisce che rimanga identica da una riesecuzione all’altra—un classico uuid.uuid4() produrrebbe un nuovo valore a ogni tentativo e annullerebbe tutta la protezione. Quando il servizio remoto non offre questo meccanismo, esistono altre due strade: l’upsert nel database, usando INSERT ... ON CONFLICT UPDATE invece del solo INSERT, oppure la verifica preventiva, che consiste nel interrogare lo stato prima di agire.
Tre profili di configurazione
I valori si calibrano in base alla natura dell’operazione. Un pagamento o una notifica devono riuscire rapidamente o fallire rapidamente: timeout breve, tre tentativi, backoff moderato.
@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
L’elaborazione di lunga durata, come la generazione di report o inferenze pesanti, inverte la logica: ogni tentativo costa un tempo di calcolo significativo, quindi autorizzi meno tentativi con uno spaziamento più ampio.
@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
Di fronte a un’API di terze parti instabile soggetta a limitazione di frequenza, assumi infine la persistenza: cinque tentativi, anche se si estendono per 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 chiave
- Configura sempre
start_to_close_timeoutper evitare attività bloccate - Il backoff esponenziale (
retry_policy_backoff_coefficient) aumenta il ritardo tra i tentativi retry_policy_max_attemptsdefinisce il numero massimo di tentativi prima del fallimento definitivo- Le attività con ritentativo devono essere idempotenti—stesso risultato se eseguite più volte
- Usa chiavi di idempotenza o upsert per garantire l’idempotenza
- Adatta timeout e conteggio dei ritentativi al tipo di operazione (veloce vs lunga, stabile vs instabile)