Pattern Avanzati
In questa pagina
Aggiornato il 3 novembre 2026: Il sotto-flusso di lavoro restituiva precedentemente
execution.output, che manca nell’SDKmistralai3.7.0. Il risultato viene ora letto daresult, utilizzandowait_for_result=Trueper attendere il completamento.
Oltre i flussi di lavoro lineari
Finora abbiamo esaminato flussi di lavoro che eseguono le attività in sequenza. Nella pratica, i casi d’uso reali richiedono pattern più sofisticati: concatenare flussi di lavoro, eseguire attività in parallelo o prendere decisioni condizionali complesse. Questi quattro pattern—concatenamento, continuazione, parallelismo e fan-out/fan-in—coprono quasi tutte le architetture che dovrai costruire.
Concatenamento dei flussi di lavoro
Un flusso di lavoro può triggerarne un altro. Questa capacità serve due obiettivi distinti: scomporre la logica complessa in sotto-flussi di lavoro riutilizzabili e aggirare il limite di 51.200 eventi per esecuzione, poiché ogni flusso di lavoro figlio dispone del proprio budget. Il meccanismo si basa su un’attività, l’unico luogo in cui l’SDK può effettuare legittimamente una chiamata di rete.
import mistralai.workflows as workflows
from mistralai.client import Mistral
@workflows.activity()
async def launch_sub_workflow(workflow_name: str, input_data: dict) -> dict:
"""Avvia un flusso di lavoro figlio e attende il suo risultato."""
client = Mistral()
execution = await client.workflows.execute_workflow_async(
workflow_identifier=workflow_name,
input=input_data,
wait_for_result=True, # attende il risultato del flusso di lavoro figlio
)
return execution.result
@workflows.workflow.define(name="main_pipeline")
class MainPipeline:
@workflows.workflow.entrypoint
async def run(self, params: dict) -> dict:
# Passo 1: Raccolta dati (sotto-flusso di lavoro dedicato)
data = await launch_sub_workflow(
"data_collection",
{"sources": params["sources"]}
)
# Passo 2: Analisi (sotto-flusso di lavoro dedicato)
analysis = await launch_sub_workflow(
"content_analysis",
{"data": data}
)
# Passo 3: Generazione report (sotto-flusso di lavoro dedicato)
report = await launch_sub_workflow(
"report_generation",
{"analysis": analysis, "format": params["format"]}
)
return report
Il vantaggio va oltre la semplice leggibilità: data_collection diventa un flusso di lavoro autonomo, testabile in isolamento e riutilizzabile da altre pipeline, con i propri timeout e politiche di retry.
Lo stesso meccanismo, applicato a un flusso di lavoro che chiama se stesso, crea il pattern di continuazione. Invece di elaborare centomila elementi in una singola esecuzione—cosa vietata dal limite di eventi—il flusso di lavoro elabora un batch e delega il resto a una nuova istanza.
@workflows.workflow.define(name="batch_processing")
class BatchProcessing:
@workflows.workflow.entrypoint
async def run(self, params: dict) -> dict:
offset = params.get("offset", 0)
batch_size = 100
# Recupera il batch corrente
batch = await retrieve_batch(offset, batch_size)
if not batch["items"]:
# Tutti i batch elaborati
return {"status": "completed", "total_processed": offset}
# Elabora il batch corrente
await process_batch(batch["items"])
# Avvia il prossimo batch tramite un nuovo flusso di lavoro
next_batch = await launch_sub_workflow(
"batch_processing",
{"offset": offset + batch_size}
)
return next_batch
Ogni nuova esecuzione inizia con un journal pulito. Il numero di elementi elaborabili diventa illimitato, con la condizione di arresto rappresentata semplicemente da un batch vuoto.
Parallelizzazione con asyncio.gather
Quando più attività sono indipendenti l’una dall’altra, non c’è motivo di eseguirle in sequenza. asyncio.gather le invia alla piattaforma simultaneamente e il tempo totale si avvicina a quello dell’attività più lenta piuttosto che alla somma di tutte.
import asyncio
import mistralai.workflows as workflows
@workflows.activity()
async def analyze_source(url: str) -> dict:
"""Analizza una fonte di dati."""
async with httpx.AsyncClient() as client:
response = await client.get(url)
return {"url": url, "size": len(response.text)}
@workflows.workflow.define(name="parallel_analysis")
class ParallelAnalysis:
@workflows.workflow.entrypoint
async def run(self, urls: list) -> dict:
# Avvia tutte le analisi in parallelo
results = await asyncio.gather(
*[analyze_source(url) for url in urls]
)
return {
"source_count": len(results),
"results": list(results)
}
Tuttavia, vale una precisazione: di default, gather propaga la prima eccezione incontrata e interrompe l’intero set. Se stai analizzando quaranta fonti esterne, il fatto che una sola sia offline ti fa perdere le altre trentanove. Il parametro return_exceptions=True modifica questo comportamento: gli errori vengono restituiti come valori ordinari, lasciandoti il compito di smistarli.
@workflows.workflow.define(name="fault_tolerant_analysis")
class FaultTolerantAnalysis:
@workflows.workflow.entrypoint
async def run(self, urls: list) -> dict:
# return_exceptions=True impedisce a un errore di bloccare gli altri
results = await asyncio.gather(
*[analyze_source(url) for url in urls],
return_exceptions=True
)
successes = []
errors = []
for i, result in enumerate(results):
if isinstance(result, Exception):
errors.append({"url": urls[i], "error": str(result)})
else:
successes.append(result)
return {
"successes": successes,
"errors": errors,
"success_rate": len(successes) / len(urls)
}
Questo flusso di lavoro restituisce un risultato parziale accompagnato da un tasso di successo, permettendo ai processi a valle di decidere se la qualità è sufficiente o se è necessario un retry.
Prendere decisioni nel flusso di lavoro
Il branching complesso non è solo consentito, ma spesso costituisce il motivo principale per utilizzare i flussi di lavoro, a patto che le condizioni derivino dai risultati delle attività. Il caso della moderazione dei contenuti illustra bene questa logica a cascata: decisione automatica quando il modello è altamente confidente, secondo parere quando la confidenza è moderata ed escalation umana in caso di disaccordo o bassa confidenza.
@workflows.workflow.define(name="content_moderation")
class ContentModeration:
@workflows.workflow.entrypoint
async def run(self, content: dict) -> dict:
# Passo 1: Analisi automatica
analysis = await auto_analyze_content(content["text"])
if analysis["confidence_score"] > 0.95:
# Alta confidenza: decisione automatica
if analysis["category"] == "acceptable":
await publish_content(content["id"])
return {"decision": "published", "method": "automatic"}
else:
await reject_content(content["id"], analysis["reason"])
return {"decision": "rejected", "method": "automatic"}
elif analysis["confidence_score"] > 0.7:
# Confidenza moderata: seconda analisi con un modello diverso
second_analysis = await analyze_content_model_b(content["text"])
if analysis["category"] == second_analysis["category"]:
# Entrambi i modelli concordano
if analysis["category"] == "acceptable":
await publish_content(content["id"])
return {"decision": "published", "method": "ai_consensus"}
else:
await reject_content(content["id"], analysis["reason"])
return {"decision": "rejected", "method": "ai_consensus"}
else:
# Disaccordo: escalation umana
await escalate_moderation(content["id"], analysis, second_analysis)
return {"decision": "pending", "method": "human_escalation"}
else:
# Bassa confidenza: escalation diretta
await escalate_moderation(content["id"], analysis, None)
return {"decision": "pending", "method": "human_escalation"}
Nota il campo method restituito in ogni punto di uscita: ti permette di misurare retrospettivamente quale proporzione di contenuti è stata elaborata senza intervento umano e, di conseguenza, di regolare le soglie.
Fan-out / Fan-in
L’ultimo pattern combina i precedenti: distribuire il lavoro in parallelo, quindi aggregare i risultati in un unico punto. Qui, un documento viene tradotto simultaneamente in tre lingue, ogni traduzione viene analizzata in parallelo e tutto converge in un riepilogo.
@workflows.workflow.define(name="multi_language_analysis")
class MultiLanguageAnalysis:
@workflows.workflow.entrypoint
async def run(self, document: dict) -> dict:
# Fan-out: traduci in parallelo in 3 lingue
translations = await asyncio.gather(
translate(document["text"], "en"),
translate(document["text"], "de"),
translate(document["text"], "es")
)
# Fan-out: analizza ogni traduzione in parallelo
analyses = await asyncio.gather(
*[analyze_sentiment(trad["translated_text"]) for trad in translations]
)
# Fan-in: aggrega i risultati
summary = await aggregate_analyses(list(analyses))
return summary
Le due ondate di parallelismo sono successive perché la seconda dipende dai risultati della prima. In sequenza stretta, questo flusso di lavoro richiederebbe sette chiamate concatenate; qui, costa solo tre passaggi di orchestrazione.
In sintesi, scomponi i flussi di lavoro complessi in sotto-flussi riutilizzabili, parallelizza ogni volta che le attività sono indipendenti, abilita return_exceptions=True quando i fallimenti parziali sono tollerabili, tieni la continuazione di riserva per lavori di elaborazione molto lunghi e assicurati sempre che il tuo branching si basi sui risultati delle attività piuttosto che su valori non deterministici.
Punti chiave
- Un flusso di lavoro può triggerare altri flussi di lavoro tramite un’attività che chiama l’SDK
- Il pattern di continuazione permette di elaborare un numero illimitato di elementi in batch successivi
asyncio.gatherti permette di eseguire le attività in parallelo per ridurre il tempo totale- Il branching condizionale complesso è supportato purché dipenda dai risultati delle attività
- Il pattern fan-out / fan-in distribuisce il lavoro e poi aggrega i risultati