Asinkroni I/O i najbolje prakse
Na ovoj stranici
Asinkroni I/O: Tehnički zahtjev
Sve aktivnosti u Mistral Workflows moraju koristiti asinkrone operacije ulaza/izlaza. To nije preporuka za stil kodiranja; radi se o tehničkom ograničenju. Blokirajući sinkroni poziv poput requests.post() zamrzava radnika (worker) i sprječava izvršavanje bilo koje druge aktivnosti.
Ovaj zahtjev proizlazi iz arhitekture radnika, koja izvršava aktivnosti unutar asyncio petlje događaja. Kada korutina asinkrono čeka mrežni odgovor, vraća kontrolu petlji, omogućujući drugim aktivnostima da nastave. Suprotno tome, sinkroni poziv ne vraća ništa.
import requests
# NETOČNO: Blokira cijelog radnika
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# requests.post() je sinkron — blokira petlju događaja
response = requests.post(url, json={"query": "test"})
return response.json()
Simptom u produkciji može biti zbunjujuć: pokreneš deset aktivnosti paralelno s asyncio.gather, ali one se zapravo izvršavaju jedna za drugom. Ako svaka čeka dvije sekunde na udaljeni API, izmjerit ćeš dvadeset sekundi umjesto očekivane dvije, bez ikakvih podignutih grešaka.
Odaberi izvorno asinkrone biblioteke
Rješenje je zamijeniti svaku blokirajuću biblioteku njezinim asinkronim ekvivalentom. Za HTTP pozive, httpx je zadani izbor.
import httpx
# TOČNO: Ne-blokirajuće
@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 služi istoj svrsi s nešto drugačijim API-jem temeljenim na sesijama.
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()
Za baze podataka, asyncpg zamjenjuje psycopg2 za PostgreSQL. Obrati pažnju na blok try/finally: veza se mora zatvoriti čak i ako upit podigne iznimku. Inače će uzastovni ponovni pokušaji iscrpsti pool veza.
import asyncpg
# TOČNO: Asinkroni PostgreSQL driver
@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()
Pristup datotekama slijedi istu logiku s aiofiles, čak i za male datoteke gdje bi te moglo privući da nastaviš koristiti open().
import aiofiles
# TOČNO: Asinkrono čitanje datoteke
@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)}
Ni Mistral SDK nije iznimka: svaka metoda ima varijantu s sufiksom _async i to je ona koju moraš pozvati iz aktivnosti.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Koristi complete_async, NE complete
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Drži ovu tablicu mapiranja pri ruci tijekom pregleda koda: svaki redak iz lijevog stupca uočen u aktivnosti potencijalni je bug performansi.
| Operacija | Netočno (blokirajuće) | Točno (asinkrono) |
|---|---|---|
| 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() |
| Datoteke | open() | aiofiles.open() |
| Pauza | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Kada ne postoji asinkrona verzija
Neke poslovne biblioteke, poput vlasničkog SDK-a ili legacy klijenta, jednostavno ne nude asinkronu varijantu. U tim slučajevima, asyncio.to_thread() omogućuje ti pokretanje blokirajućeg koda u zasebnoj niti bez zamrzavanja petlje događaja.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Omata blokirajući poziv u nit."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Ovo je kompromis, a ne ekvivalentno rješenje: svaki poziv troši nit iz poola, koji ima konačnu veličinu. Za aktivnost koja se masovno poziva paralelno, samo pomičeš usko grlo umjesto da ga ukloniš. Uvijek daj prednost izvorno asinkronoj biblioteci kada ona postoji.
Dizajniranje čistih aktivnosti
Osim asinkronosti, četiri navike razlikuju robustnu aktivnost od one koja će te koštati sati debugiranja.
Prva je opseg. Aktivnost treba imati jednu i samo jednu odgovornost, jer je ona također jedinica ponovnog pokušaja i perzistencije: aktivnost „uhvati sve“ koja zakaže tijekom slanja e-pošte ponovno će pokrenuti ekstrakciju i analizu od početka.
# DOBRO: Svaka aktivnost ima jasnu odgovornost
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# LOŠE: Aktivnost „uhvati sve“
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # ekstrakcija
sentiment = ... # analiza
# pošalji e-poštu
# spremi u bazu
pass
Druga se tiče resursa. Upravitelj konteksta async with jamči da se klijent zatvara čak i ako dođe do iznimke, nešto što ručni pozivi neizbježno prije ili kasnije zaborave.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Koristi async with za jamstvo zatvaranja
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# Klijent je ovdje automatski zatvoren
return response.json()
Treća je suptilnija: ne zaslužuju sve greške ponovni pokušaj. Istek vremena (timeout), 429 ili 500 su prolazni i trebali bi se propagirati kako bi se pokrenuo ponovni pokušaj. Greška 4xx, međutim, ukazuje na neispravan zahtjev koji ponavljanje tri puta neće popraviti. Umjesto toga, vrati eksplicitan rezultat i pusti workflow da odluči.
@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 # Platforma će ponoviti pokušaj
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Ograničenje stope — ponovit će se
elif e.response.status_code >= 500:
raise # Greška poslužitelja — ponovit će se
else:
# Greška klijenta (4xx) — ne ponavljaj
return {"status": "error", "code": e.response.status_code}
Konačno, četvrta navika proizlazi iz ograničenja od 2 MB po pozivu: vrati samo ono što workflowu zapravo treba za donošenje odluke o sljedećem koraku. Brojka, uzorak i URL do punog rezultata gotovo su uvijek dovoljni.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Vrati samo ono što workflow treba
return {
"item_count": len(data),
"summary": data[:10], # Samo prvih 10
"full_url": await upload_results(data)
}
Ključne točke
- Asinkroni I/O je obavezan: koristi
httpx,asyncpg,aiofilesumjesto njihovih sinkronih ekvivalenata - Blokirajući pozivi (
requests,psycopg2,open) zamrzavaju cijelog radnika - Koristi
asyncio.to_thread()kao posljednje sredstvo za biblioteke bez asinkrone verzije - Svaka aktivnost mora imati jednu jasnu odgovornost
- Uvijek zatvori veze s
async with - Rukuj greškama eksplicitno: neke treba ponoviti, druge ne
- Ograniči veličinu povratnih podataka kako bi ostao unutar limita od 2 MB