Politique de nouvelle tentative
Šiame puslapyje
Pourquoi les nouvelles tentatives sont essentielles
Dans un système distribué, les erreurs transitoires sont inévitables : délais d’attente réseau dépassés, limites de débit atteintes, services temporairement indisponibles. Aucune de ces pannes n’indique un bug dans ton code, pourtant l’une d’entre elles suffit à faire échouer un processus si rien n’amortit le choc. Une politique de nouvelle tentative permet à tes activités de survivre à ces erreurs sans intervention manuelle, la plateforme les relançant automatiquement selon la configuration que tu définis pour chacune d’elles.
Configurer une politique de nouvelle tentative
Le décorateur @workflows.activity() accepte des paramètres qui régissent ce comportement. Voici une activité d’appel d’API externe correctement armée pour la résilience.
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()
Trois paramètres, trois rôles complémentaires.
-
start_to_close_timeout— Durée maximale pour une seule tentative d’exécution. Si l’activité ne se termine pas dans ce délai, elle est considérée comme échouée et une nouvelle tentative est lancée. -
retry_policy_max_attempts— Nombre maximal de tentatives. La valeur par défaut dépend de la plateforme. Après ce nombre de tentatives, l’activité échoue définitivement et le workflow reçoit une erreur. -
retry_policy_backoff_coefficient— Multiplicateur pour le délai entre les tentatives. Avec un coefficient de 2,0, les délais doublent à chaque tentative (1 s, 2 s, 4 s, 8 s…). C’est ce qu’on appelle un backoff exponentiel.
Ce mécanisme de backoff mérite attention car son but n’est pas seulement d’attendre : il donne au service en difficulté le temps de récupérer au lieu de le marteler. La progression d’un appel qui finit par réussir l’illustre clairement.
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!
Face à une réponse „429 Too Many Requests“, ce mécanisme est particulièrement efficace : une politique qui retenterait immédiatement ne ferait qu’entretenir la saturation, tandis qu’un espacement croissant finit par passer sous le seuil du fournisseur.
Ne jamais omettre start_to_close_timeout
Ce délai d’attente est critique et doit apparaître sur chaque activité, sans exception. Sans lui, une activité qui se bloque — interblocage, connexion pendante, service qui accepte la requête mais ne répond jamais — attend indéfiniment et gèle l’intégralité du workflow. Pire : cela ne déclenche aucune nouvelle tentative, car de son point de vue, elle n’a pas encore échoué.
# 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()
Pour définir la valeur, mesure d’abord le temps d’exécution normal de l’activité, puis ajoute une marge de deux à trois fois pour couvrir les cas lents. Enfin, assure-toi que le délai d’attente interne du client HTTP reste inférieur au start_to_close_timeout — dans l’exemple ci-dessus, 90 secondes contre 2 minutes — afin que l’erreur se propage proprement depuis ton code plutôt que d’être coupée par la plateforme.
Idempotence : une condition non négociable
Puisqu’une activité peut être rejouée plusieurs fois avec les mêmes paramètres, elle doit produire le même effet quel que soit le nombre d’exécutions. Cette propriété s’appelle l’idempotence, et son absence transforme une politique de nouvelle tentative en générateur d’incidents.
@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()
Le scénario redouté est courant : l’API de facturation traite correctement la requête, mais la réponse se perd sur le réseau. L’activité conclut à un échec, la plateforme retente, et le client est crédité deux fois. Une clé d’idempotence élimine le problème en donnant au service distant un moyen de reconnaître une requête déjà traitée.
@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()
Génère la clé dans le workflow en utilisant workflow.uuid4(), ce qui garantit qu’elle reste identique d’une rejouée à l’autre — un uuid.uuid4() classique produirait une nouvelle valeur à chaque tentative et annulerait toute protection. Lorsque le service distant n’offre pas ce mécanisme, deux autres voies existent : l’upsert en base de données, en utilisant INSERT ... ON CONFLICT UPDATE au lieu de INSERT seul, ou la vérification préalable, qui consiste à interroger l’état avant d’agir.
Trois profils de configuration
Les valeurs se calibrent selon la nature de l’opération. Un paiement ou une notification doit réussir vite ou échouer vite : délai court, trois tentatives, backoff modéré.
@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
Un traitement de longue durée, comme la génération de rapports ou une inférence lourde, inverse la logique : chaque tentative coûte un temps de calcul significatif, tu autorises donc moins de tentatives avec un espacement plus large.
@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
Face à une API tierce instable soumise à une limitation de débit, tu mises enfin sur la persistance : cinq tentatives, même si cela s’étale sur plusieurs minutes.
@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
Svarbiausi punktai
- Configure toujours
start_to_close_timeoutpour éviter de bloquer les activités - Le backoff exponentiel (
retry_policy_backoff_coefficient) augmente le délai entre les tentatives retry_policy_max_attemptsdéfinit le nombre maximal de tentatives avant l’échec définitif- Les activités avec nouvelle tentative doivent être idempotentes — même résultat si exécutées plusieurs fois
- Utilise des clés d’idempotence ou des upserts pour garantir l’idempotence
- Adapte les délais d’attente et le nombre de tentatives au type d’opération (rapide vs long, stable vs instable)