Async e migliori pratiche
In questa pagina
I/O asincrono: un requisito tecnico
Tutte le attività in Mistral Workflows devono utilizzare operazioni di input/output asincrone. Non si tratta di una raccomandazione di stile, ma di un vincolo tecnico. Una chiamata sincrona bloccante come requests.post() congela il worker e impedisce l’esecuzione di qualsiasi altra attività.
Questo requisito deriva dall’architettura del worker, che esegue le attività all’interno di un event loop asyncio. Quando una coroutine attende asincronamente una risposta di rete, cede il controllo al loop, permettendo ad altre attività di procedere. Al contrario, una chiamata sincrona non cede nulla.
import requests
# ERRATO: Blocca l'intero worker
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# requests.post() è sincrono — blocca l'event loop
response = requests.post(url, json={"query": "test"})
return response.json()
Il sintomo in produzione può essere confuso: lanci dieci attività in parallelo con asyncio.gather, ma queste vengono eseguite effettivamente una dopo l’altra. Se ciascuna attende due secondi per un’API remota, misuri venti secondi invece dei due previsti, senza che venga sollevato alcun errore.
Scegli librerie nativamente asincrone
La soluzione consiste nel sostituire ogni libreria bloccante con la sua equivalente asincrona. Per le chiamate HTTP, httpx è la scelta predefinita.
import httpx
# CORRETTO: Non bloccante
@workflows.activity()
async def async_activity(url: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.post(url, json={"query": "test"})
return response.json()
aiohttp svolge la stessa funzione con un’API leggermente diversa basata sulle sessioni.
import aiohttp
@workflows.activity()
async def aiohttp_activity(url: str) -> dict:
async with aiohttp.ClientSession() as session:
async with session.post(url, json={"query": "test"}) as response:
return await response.json()
Per i database, asyncpg sostituisce psycopg2 per PostgreSQL. Nota il blocco try/finally: la connessione deve essere chiusa anche se la query solleva un’eccezione. Altrimenti, i tentativi successivi esauriranno il pool di connessioni.
import asyncpg
# CORRETTO: Driver PostgreSQL asincrono
@workflows.activity()
async def async_db_query(user_id: str) -> dict:
conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
try:
row = await conn.fetchrow(
"SELECT * FROM users WHERE id = $1", user_id
)
return dict(row) if row else {"error": "user not found"}
finally:
await conn.close()
L’accesso ai file segue la stessa logica con aiofiles, anche per file piccoli dove potresti essere tentato di continuare a usare open().
import aiofiles
# CORRETTO: Lettura file asincrona
@workflows.activity()
async def read_file_async(path: str) -> dict:
async with aiofiles.open(path, mode="r") as f:
content = await f.read()
return {"content": content, "size": len(content)}
Nemmeno l’SDK Mistral fa eccezione: ogni metodo ha una variante con suffisso _async, ed è quella che devi chiamare da un’attività.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Usa complete_async, NON complete
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Tieni a portata di mano questa tabella di corrispondenza durante le revisioni del codice: qualsiasi riga della colonna di sinistra individuata in un’attività rappresenta un potenziale bug di prestazioni.
| Operazione | Errato (bloccante) | Corretto (async) |
|---|---|---|
| HTTP | requests.get() | httpx.AsyncClient().get() |
| HTTP | urllib.request.urlopen() | aiohttp.ClientSession().get() |
| PostgreSQL | psycopg2.connect() | asyncpg.connect() |
| MySQL | mysql.connector.connect() | aiomysql.connect() |
| Redis | redis.Redis() | redis.asyncio.Redis() |
| File | open() | aiofiles.open() |
| Sleep | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Quando non esiste una versione Async
Alcune librerie di business, come un SDK proprietario o un client legacy, semplicemente non offrono una variante asincrona. In questi casi, asyncio.to_thread() ti permette di eseguire il codice bloccante in un thread separato senza congelare l’event loop.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Avvolge una chiamata bloccante in un thread."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Questo è un compromesso, non una soluzione equivalente: ogni chiamata consuma un thread dal pool, che ha una dimensione finita. Per un’attività chiamata massicciamente in parallelo, sposti semplicemente il collo di bottiglia invece di rimuoverlo. Preferisci sempre una libreria nativamente asincrona quando ne esiste una.
Progettare attività pulite
Oltre all’asincronia, quattro abitudini distinguono un’attività robusta da una che ti costerà ore di debug.
La prima è l’ambito. Un’attività dovrebbe avere una e una sola responsabilità, poiché è anche l’unità di retry e persistenza: un’attività “tuttofare” che fallisce durante l’invio di un’email ripeterà dall’inizio l’estrazione e l’analisi.
# BUONO: Ogni attività ha una responsabilità chiara
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# CATTIVO: Attività tuttofare
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # estrazione
sentiment = ... # analisi
# invia email
# salva su DB
pass
La seconda riguarda le risorse. Il context manager async with garantisce che il client venga chiuso anche se si verifica un’eccezione, qualcosa che le chiamate manuali inevitabilmente dimenticano prima o poi.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Usa async with per garantire la chiusura
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# Il client viene chiuso automaticamente qui
return response.json()
La terza è più sottile: non tutti gli errori meritano un retry. Un timeout, un 429 o un 500 sono transitori e dovrebbero propagarsi per attivare un nuovo tentativo. Un errore 4xx, invece, indica una richiesta non valida che ripetere tre volte non risolverà. Invece, restituisci un risultato esplicito e lascia che il workflow decida.
@workflows.activity(
start_to_close_timeout=timedelta(minutes=2),
retry_policy_max_attempts=3,
)
async def robust_activity(params: dict) -> dict:
async with httpx.AsyncClient(timeout=60) as client:
try:
response = await client.post(params["url"], json=params["data"])
response.raise_for_status()
return {"status": "success", "data": response.json()}
except httpx.TimeoutException:
raise # Verrà ritentato dalla piattaforma
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Limite di frequenza raggiunto — verrà ritentato
elif e.response.status_code >= 500:
raise # Errore server — verrà ritentato
else:
# Errore client (4xx) — non ritentare
return {"status": "error", "code": e.response.status_code}
Infine, la quarta abitudine deriva dal limite di 2 MB per invocazione: restituisci solo ciò di cui il workflow ha effettivamente bisogno per decidere il passo successivo. Un conteggio, un campione e l’URL al risultato completo sono quasi sempre sufficienti.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Restituisci solo ciò di cui il workflow ha bisogno
return {
"item_count": len(data),
"summary": data[:10], # Solo i primi 10
"full_url": await upload_results(data)
}
Punti chiave
- I/O asincrono è obbligatorio: usa
httpx,asyncpg,aiofilesinvece delle loro controparti sincrone - Le chiamate bloccanti (
requests,psycopg2,open) congelano l’intero worker - Usa
asyncio.to_thread()come ultima risorsa per le librerie senza versione asincrona - Ogni attività deve avere una responsabilità chiara
- Chiudi sempre le connessioni con
async with - Gestisci gli errori in modo esplicito: alcuni vanno ritentati, altri no
- Limita le dimensioni dei dati restituiti per rimanere sotto il limite di 2 MB