Salt la conținutul principal
Română— Alege o limbă
Meniu

Règle de déterminisme

Lecția 8 din 14 Actualizată 2 noiembrie 2026 Avansat
Pe această pagină
  1. Pourquoi le déterminisme est obligatoire
  2. À quoi cela ressemble-t-il dans le code ?
  3. Remplacements fournis par le SDK
  4. La frontière à retenir
  5. Diagnostiquer une erreur de non-déterminisme
  6. Puncte cheie

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.

  1. Présence d’appels non déterministes — Recherchez datetime.now, uuid.uuid4, random.random dans le code du workflow.
  2. E/S directes — Tout appel réseau ou fichier doit résider dans une activité.
  3. Variables d’environnement — Si vous utilisez os.environ pour une branche, déplacez la lecture dans une activité.
  4. 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é.