Aszinkron műveletek és bevált gyakorlatok
Ezen az oldalon
Aszinkron I/O: Technikai követelmény
A Mistral Workflows összes tevékenységének aszinkron bemeneti/kimeneti műveleteket kell használnia. Ez nem stílusjavaslat, hanem technikai kényszer. Egy blokkoló szinkron hívás, mint például a requests.post(), lefagyasztja a munkást (worker), és megakadályozza bármely más tevékenység futását.
Ez a követelmény a munkás architektúrájából ered, amely egy asyncio eseményhurokban hajtja végre a tevékenységeket. Amikor egy korutin aszinkron módon vár egy hálózati válaszra, visszaadja a vezérlést a huroknak, lehetővé téve más tevékenységek folytatását. Ezzel szemben egy szinkron hívás semmit nem ad vissza.
import requests
# HELYTELEN: Blokkolja az egész munkást
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# A requests.post() szinkron — blokkolja az eseményhurkot
response = requests.post(url, json={"query": "test"})
return response.json()
A tünet éles környezetben zavaró lehet: tíz tevékenységet indítasz párhuzamosan az asyncio.gather segítségével, de azok valójában egymás után hajtódnak végre. Ha mindegyik két másodpercet vár egy távoli API-ra, akkor húsz másodpercet mérsz a várt két másodperc helyett, hibajelzés nélkül.
Válassz natívan aszinkron könyvtárakat
A megoldás az, hogy minden blokkoló könyvtárat lecserélsz annak aszinkron megfelelőjére. HTTP-hívások esetén az httpx az alapértelmezett választás.
import httpx
# HELYES: Nem blokkoló
@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()
Az aiohttp ugyanerre a célra szolgál, kissé eltérő, munkameneteken alapuló API-val.
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()
Adatbázisok esetén az asyncpg váltja le a psycopg2-t PostgreSQL-hez. Figyeld meg a try/finally blokkot: a kapcsolatnak le kell záródnia akkor is, ha a lekérdezés kivételt dob. Ellenkező esetben az ismétlődő újrapróbálkozások kimerítik a kapcsolatkészletet.
import asyncpg
# HELYES: Aszinkron PostgreSQL illesztőprogram
@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()
A fájlhozzáférés ugyanígy működik az aiofiles segítségével, még kis fájlok esetén is, amikor esetleg kísértésbe esnél, hogy továbbra is az open()-t használd.
import aiofiles
# HELYES: Aszinkron fájlolvasás
@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)}
Maga a Mistral SDK sem kivétel: minden metódusnak létezik egy _async utótaggal ellátott változata, és ezt kell meghívnod egy tevékenységből.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Használd a complete_async metódust, NE a complete-et
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Tartsd kéznél ezt az összehasonlító táblázatot kódreviewk során: a bal oszlopból származó bármely sor, amelyet egy tevékenységben találsz, potenciális teljesítményhiba.
| Művelet | Helytelen (blokkoló) | Helyes (aszinkron) |
|---|---|---|
| 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() |
| Fájlok | open() | aiofiles.open() |
| Alvás | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Ha nem létezik aszinkron verzió
Egyes üzleti könyvtárak, mint például egy tulajdonosi SDK vagy egy elavult kliens, egyszerűen nem kínálnak aszinkron változatot. Ilyen esetekben az asyncio.to_thread() lehetővé teszi, hogy a blokkoló kódot egy külön szálban futtasd anélkül, hogy lefagyasztanád az eseményhurkot.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Becsomagol egy blokkoló hívást egy szálba."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Ez egy kompromisszum, nem egyenértékű megoldás: minden hívás fogyaszt egy szálat a készletből, amelynek véges a mérete. Ha egy tevékenységet masszívan párhuzamosítva hívsz meg, csupán áthelyezed a szűk keresztmetszetet, nem pedig megszünteted azt. Mindig részesítsd előnyben a natívan aszinkron könyvtárat, ha létezik ilyen.
Tiszta tevékenységek tervezése
Az aszinkronitás mellett négy szokás különbözteti meg a robusztus tevékenységet attól, amely óráknyi hibakeresésbe fog kerülni.
Az első a hatáskör. Egy tevékenységnek pontosan egy felelőssége legyen, mivel ez egyszerre az újrapróbálkozás és a perzisztencia egysége is: egy mindent magába foglaló tevékenység, amely e-mail küldése közben elbukik, újra lefuttatja a kinyerést és az elemzést is a legelejétől.
# JÓ: Minden tevékenységnek világos felelőssége van
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# ROSSZ: Mindent egyben tevékenység
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # kinyerés
sentiment = ... # elemzés
# e-mail küldés
# mentés az adatbázisba
pass
A második az erőforrásokra vonatkozik. Az async with kontextuskezelő garantálja, hogy a kliens lezáródik még kivétel esetén is, amit a manuális hívások előbb-utóbb elfelejtenek.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Használd az async with blokkot a lezárás garantálásához
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# A kliens itt automatikusan lezáródik
return response.json()
A harmadik finomabb: nem minden hiba érdemel újrapróbálkozást. Egy időtúllépés, egy 429-es vagy egy 500-as hiba átmeneti jellegű, és fel kell emelkednie (bubble up), hogy újrapróbálkozást váltson ki. Ezzel szemben egy 4xx-es hiba érvénytelen kérést jelez, amit három újrapróbálkozás sem fog megoldani. Ehelyett adj vissza egy explicit eredményt, és hagyd, hogy a munkafolyamat döntsön.
@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 # A platform újrapróbálja
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Sebességkorlátozás — újrapróbálásra kerül
elif e.response.status_code >= 500:
raise # Szerverhiba — újrapróbálásra kerül
else:
# Klienshiba (4xx) — ne próbáld újra
return {"status": "error", "code": e.response.status_code}
Végül, a negyedik szokás a hívásonkénti 2 MB-os limitből ered: csak azt add vissza, amire a munkafolyamatnak ténylegesen szüksége van a következő lépés eldöntéséhez. Egy darabszám, egy minta és a teljes eredmény URL-címe szinte mindig elegendő.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Csak azt add vissza, amire a munkafolyamatnak szüksége van
return {
"item_count": len(data),
"summary": data[:10], # Csak az első 10 elem
"full_url": await upload_results(data)
}
Főbb megállapítások
- Az aszinkron I/O kötelező: használd az
httpx,asyncpg,aiofileskönyvtárakat szinkron megfelelőik helyett - A blokkoló hívások (
requests,psycopg2,open) lefagyasztják az egész munkást - Használd az
asyncio.to_thread()funkciót végső megoldásként olyan könyvtárakhoz, amelyeknek nincs aszinkron verziójuk - Minden tevékenységnek egyértelmű felelősséggel kell rendelkeznie
- Mindig zárd le a kapcsolatokat az
async withhasználatával - Kezeld explicit módon a hibákat: egyeseket újra kell próbálni, másokat nem
- Korlátozd a visszatérési adatok méretét, hogy a 2 MB-os limit alatt maradj