Règle de déterminisme
Pe această pagină
Pourquoi le déterminisme est obligatoire
Le déterminisme constitue la contrainte la plus critique dans les workflows Mistral. Cette exigence découle directement du mécanisme de rejeu que vous avez étudié précédemment. Lorsqu’un worker reprend un workflow interrompu, il réexécute le code du workflow depuis le début et compare, opération par opération, ce que le code produit avec ce qui a été enregistré dans le journal d’historique. Tant que les deux séquences correspondent, la reprise est invisible. Dès qu’elles divergent, la plateforme ne peut plus savoir où elle s’est arrêtée : elle détecte l’incohérence et échoue le workflow avec une erreur de non-déterminisme.
En pratique, un workflow déterministe produit exactement la même séquence d’opérations à chaque exécution pour des entrées identiques. Notez la nuance : les résultats des activités peuvent varier entre les exécutions puisqu’ils proviennent du journal. C’est l’ordre des appels qui doit rester identique.
À quoi cela ressemble-t-il dans le code ?
Considérons un workflow qui envoie un rapport à un utilisateur en fonction de son statut d’abonnement.
@workflows.workflow.define(name="deterministic_workflow")
class DeterministicWorkflow:
@workflows.workflow.entrypoint
async def run(self, user_id: str) -> dict:
# Toujours la même séquence d'appels pour la même entrée
profile = await get_profile(user_id)
if profile["premium"]:
report = await generate_full_report(user_id)
else:
report = await generate_basic_report(user_id)
await send_email(profile["email"], report)
return {"status": "completed"}
Ce workflow est déterministe bien qu’il contienne une branche. La raison réside dans la source de la condition : profile["premium"] provient du résultat d’une activité, donc du journal. Lors du rejeu, get_profile renvoie exactement la même valeur que lors de la première exécution, et le même chemin est emprunté.
Comparez maintenant avec cette version, qui semble inoffensive mais qui brise tout.
import datetime
import random
@workflows.workflow.define(name="non_deterministic_workflow")
class NonDeterministicWorkflow:
@workflows.workflow.entrypoint
async def run(self, user_id: str) -> dict:
# INTERDIT : datetime.now() change à chaque exécution
if datetime.datetime.now().hour < 12:
await send_morning_email(user_id)
else:
await send_afternoon_email(user_id)
# INTERDIT : random.random() produit un résultat différent à chaque fois
if random.random() > 0.5:
await send_notification(user_id)
return {"status": "completed"}
Imaginez que le worker plante à 11h58 et redémarre à 12h03. Lors du rejeu, datetime.now() renvoie une heure de l’après-midi alors que l’historique contient un appel à send_morning_email. Le workflow échoue. random.random() produit le même effet, mais est plus difficile à diagnostiquer.
Remplacements fournis par le SDK
Le SDK ne se contente pas d’interdire ces appels ; il fournit des équivalents déterministes pour les trois opérations les plus courantes.
from mistralai.workflows import workflow
# Obtenir l'heure actuelle (déterministe lors du rejeu)
current_time = workflow.now() # Au lieu de datetime.now()
# Générer un ID unique (déterministe lors du rejeu)
request_id = workflow.uuid4() # Au lieu de uuid.uuid4()
# Obtenir un nombre aléatoire (déterministe lors du rejeu)
rand_value = workflow.random() # Au lieu de random.random()
Le principe est le même que pour les activités : la valeur est calculée et enregistrée dans le journal lors de la première exécution, puis simplement rejouée par la suite. L’exemple précédent devient alors parfaitement sûr.
import mistralai.workflows as workflows
from mistralai.workflows import workflow
@workflows.workflow.define(name="fixed_workflow")
class FixedWorkflow:
@workflows.workflow.entrypoint
async def run(self, user_id: str) -> dict:
# CORRECT : workflow.now() est déterministe lors du rejeu
current_hour = workflow.now()
if current_hour.hour < 12:
await send_morning_email(user_id)
else:
await send_afternoon_email(user_id)
# CORRECT : workflow.random() est déterministe lors du rejeu
if workflow.random() > 0.5:
await send_notification(user_id)
# CORRECT : workflow.uuid4() est déterministe lors du rejeu
trace_id = workflow.uuid4()
await log_trace(str(trace_id), user_id)
return {"status": "completed", "trace_id": str(trace_id)}
La frontière à retenir
Les éléments suivants sont interdits dans le code du workflow : datetime.now(), datetime.utcnow() et time.time() ; uuid.uuid4() et uuid.uuid1() ; random.random(), random.randint() et random.choice() ; tout appel réseau direct (httpx, aiohttp, requests) ; toute lecture ou écriture de fichier (open(), aiofiles) ; tout accès à la base de données ; os.environ, car les variables d’environnement peuvent changer entre les rejeux ; et enfin threading et multiprocessing, puisque la plateforme gère le parallélisme interne.
Tout ce qui est reproductible reste autorisé : appeler des activités via await, utiliser workflow.now(), workflow.uuid4() et workflow.random(), écrire une logique conditionnelle ou des boucles dont les conditions dépendent des résultats d’activités, manipuler des données en mémoire (calculs, chaînes de caractères) et journaliser — la journalisation est considérée comme un effet de bord acceptable.
Diagnostiquer une erreur de non-déterminisme
Lorsque l’erreur survient, quatre vérifications suffisent généralement à la localiser.
- Présence d’appels non déterministes — Recherchez
datetime.now,uuid.uuid4,random.randomdans le code du workflow. - E/S directes — Tout appel réseau ou fichier doit résider dans une activité.
- Variables d’environnement — Si vous utilisez
os.environpour une branche, déplacez la lecture dans une activité. - Bibliothèques tierces — Certaines bibliothèques effectuent des appels réseau ou utilisent l’aléatoire en interne.
Ce dernier point est le plus insidieux : une bibliothèque de sérialisation qui trie par un ID généré aléatoirement, ou un client HTTP instancié au chargement du module, peut faire échouer un rejeu sans qu’une seule ligne suspecte n’apparaisse dans votre workflow.
La défense la plus efficace consiste à garder le workflow aussi léger que possible et à pousser toute la logique complexe dans des activités. Un workflow qui se contente d’enchaîner trois appels n’a mécaniquement aucune opportunité d’être non déterministe.
# MEILLEURE PRATIQUE : workflow simple, logique dans les activités
@workflows.workflow.define(name="simple_pipeline")
class SimplePipeline:
@workflows.workflow.entrypoint
async def run(self, params: dict) -> dict:
step1 = await prepare_data(params)
step2 = await process_data(step1)
step3 = await finalize(step2)
return step3
Puncte cheie
- Le code du workflow doit être déterministe : mêmes entrées = même séquence d’opérations.
- Utilisez
workflow.now(),workflow.uuid4(),workflow.random()au lieu des équivalents Python standards. - Toutes les opérations d’E/S (réseau, fichier, base de données) doivent résider dans une activité, jamais dans le workflow.
- Les branches conditionnelles sont autorisées si elles dépendent des résultats d’activités.
- Une violation du déterminisme entraîne l’échec du workflow lors du rejeu.
- En cas de doute, déplacez la logique dans une activité.