Vai al contenuto principale
Italiano— Scegli una lingua
Menu

La regola del determinismo

Lezione 8 di 14 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. Perché il determinismo è obbligatorio
  2. Come appare questo nel codice
  3. Sostituzioni nell’SDK
  4. Il confine da ricordare
  5. Diagnosticare un errore di non-determinismo
  6. Punti chiave

Perché il determinismo è obbligatorio

Il determinismo è il vincolo più critico nei workflow di Mistral e deriva direttamente dal meccanismo di replay che hai appreso in precedenza. Quando un worker riprende un workflow interrotto, riesegue il codice del workflow dall’inizio e confronta, operazione per operazione, ciò che il codice produce con quanto registrato nel log della cronologia. Finché le due sequenze coincidono, la ripresa è invisibile. Nel momento in cui divergono, la piattaforma non ha modo di sapere dove si era interrotta: rileva l’incongruenza e fa fallire il workflow con un errore di non-determinismo.

In pratica, un workflow deterministico produce esattamente la stessa sequenza di operazioni ogni volta che viene eseguito con gli stessi input. Nota la sfumatura: i risultati delle attività possono variare tra le esecuzioni poiché provengono dal journal. È l’ordine delle chiamate che deve rimanere identico.

Come appare questo nel codice

Considera un workflow che invia un report a un utente in base al suo stato di abbonamento.

@workflows.workflow.define(name="deterministic_workflow")
class DeterministicWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, user_id: str) -> dict:
        # Sempre la stessa sequenza di chiamate per lo stesso input
        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"}

Questo workflow è deterministico anche se contiene un ramo condizionale. La ragione risiede nella fonte della condizione: profile["premium"] proviene dal risultato di un’attività, quindi dal journal. Durante il replay, get_profile restituisce esattamente lo stesso valore della prima esecuzione e viene percorso lo stesso ramo.

Confrontalo ora con questa versione, che sembra innocua ma rompe tutto.

import datetime
import random

@workflows.workflow.define(name="non_deterministic_workflow")
class NonDeterministicWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, user_id: str) -> dict:
        # VIETATO: datetime.now() cambia a ogni esecuzione
        if datetime.datetime.now().hour < 12:
            await send_morning_email(user_id)
        else:
            await send_afternoon_email(user_id)
        
        # VIETATO: random.random() produce un risultato diverso ogni volta
        if random.random() > 0.5:
            await send_notification(user_id)
        
        return {"status": "completed"}

Immagina che il worker si blocchi alle 11:58 e si riavvii alle 12:03. Al replay, datetime.now() restituisce un orario pomeridiano mentre la cronologia contiene una chiamata a send_morning_email. Il workflow fallisce. random.random() produce lo stesso effetto, solo più difficile da diagnosticare.

Sostituzioni nell’SDK

L’SDK non si limita a vietare queste chiamate; fornisce equivalenti deterministici per le tre operazioni più comuni.

from mistralai.workflows import workflow

# Ottieni l'ora corrente (deterministico durante il replay)
current_time = workflow.now()          # Invece di datetime.now()

# Genera un ID univoco (deterministico durante il replay)
request_id = workflow.uuid4()          # Invece di uuid.uuid4()

# Ottieni un numero casuale (deterministico durante il replay)
rand_value = workflow.random()         # Invece di random.random()

Il principio è lo stesso delle attività: il valore viene calcolato e registrato nel journal alla prima esecuzione, per poi essere semplicemente riprodotto in seguito. L’esempio precedente diventa quindi perfettamente sicuro.

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:
        # CORRETTO: workflow.now() è deterministico durante il replay
        current_hour = workflow.now()
        if current_hour.hour < 12:
            await send_morning_email(user_id)
        else:
            await send_afternoon_email(user_id)
        
        # CORRETTO: workflow.random() è deterministico durante il replay
        if workflow.random() > 0.5:
            await send_notification(user_id)
        
        # CORRETTO: workflow.uuid4() è deterministico durante il replay
        trace_id = workflow.uuid4()
        await log_trace(str(trace_id), user_id)
        
        return {"status": "completed", "trace_id": str(trace_id)}

Il confine da ricordare

Nel codice del workflow sono vietati: datetime.now(), datetime.utcnow() e time.time(); uuid.uuid4() e uuid.uuid1(); random.random(), random.randint() e random.choice(); qualsiasi chiamata di rete diretta (httpx, aiohttp, requests); qualsiasi lettura o scrittura di file (open(), aiofiles); qualsiasi accesso al database; os.environ, poiché le variabili d’ambiente possono cambiare tra i replay; e infine threading e multiprocessing, dato che la piattaforma gestisce il parallelismo interno.

Tutto ciò che è riproducibile rimane consentito: chiamare attività tramite await, usare workflow.now(), workflow.uuid4() e workflow.random(), scrivere logica condizionale o loop le cui condizioni dipendono dai risultati delle attività, manipolare dati in memoria (calcoli, stringhe) e fare logging: il logging è considerato un effetto collaterale accettabile.

Diagnosticare un errore di non-determinismo

Quando si verifica l’errore, quattro controlli sono solitamente sufficienti per individuarlo.

  1. Presenza di chiamate non deterministiche — Cerca datetime.now, uuid.uuid4, random.random nel codice del workflow
  2. I/O diretto — Qualsiasi chiamata di rete o file deve risiedere in un’attività
  3. Variabili d’ambiente — Se usi os.environ per diramazioni logiche, sposta la lettura in un’attività
  4. Librerie di terze parti — Alcune librerie effettuano chiamate di rete o usano casualità internamente

Quest’ultimo punto è il più insidioso: una libreria di serializzazione che ordina per un ID generato casualmente, o un client HTTP istanziato al caricamento del modulo, può far fallire un replay senza che appaia una singola linea sospetta nel tuo workflow.

La difesa più efficace consiste nel mantenere il workflow il più snello possibile e spostare tutta la logica complessa nelle attività. Un workflow che si limita a concatenare tre chiamate non ha meccanicamente alcuna possibilità di essere non deterministico.

# BEST PRACTICE: workflow semplice, logica nelle attività
@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

Punti chiave

  • Il codice del workflow deve essere deterministico: stessi input = stessa sequenza di operazioni
  • Usa workflow.now(), workflow.uuid4(), workflow.random() invece degli equivalenti Python standard
  • Tutte le operazioni di I/O (rete, file, DB) devono risiedere in un’attività, mai nel workflow
  • I rami condizionali sono consentiti se dipendono dai risultati delle attività
  • Una violazione del determinismo causa il fallimento del workflow durante il replay
  • In caso di dubbio, sposta la logica in un’attività