Asynchrónne operácie a osvedčené postupy
Na tejto strane
Asynchrónny I/O: Technická požiadavka
Všetky aktivity v Mistral Workflows musia používať asynchrónne operácie vstupu/výstupu. Nie je to len odporúčanie štýlu; je to technické obmedzenie. Blokujúci synchronný volanie, ako je requests.post(), zmrazí worker a zabráni spusteniu akejkoľvek inej aktivity.
Táto požiadavka vyplýva z architektúry workeru, ktorý vykonáva aktivity v rámci slučky udalostí asyncio. Keď korutína asynchrónne čaká na odpoveď zo siete, vráti riadenie späť do slučky a umožní pokračovanie iným aktivitám. Synchronné volanie naopak nič neuvolní.
import requests
# NESPRÁVNE: Blokuje celého workera
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# requests.post() je synchronné — blokuje slučku udalostí
response = requests.post(url, json={"query": "test"})
return response.json()
Príznak v produkcii môže byť mätúci: spustíš desať aktivít paralelne pomocou asyncio.gather, no v skutočnosti sa vykonajú jedna po druhej. Ak každá čaká dve sekundy na vzdialené API, nameriaš dvadsať sekúnd namiesto očakávaných dvoch, pričom sa nevyhodí žiadna chyba.
Vyberaj natívne asynchrónne knižnice
Riešením je nahradiť každú blokujúcu knižnicu jej asynchrónnym ekvivalentom. Pre HTTP volania je štandardnou voľbou httpx.
import httpx
# SPRÁVNE: Neblokujúce
@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 slúži na rovnaký účel s mierne odlišným API založeným na reláciách.
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()
Pre databázy nahrádza asyncpg knižnicu psycopg2 pre PostgreSQL. Všimni si blok try/finally: pripojenie sa musí uzavrieť aj v prípade, že dotaz vyhodí výnimku. Inak successive retry vyčerpajú pool pripojení.
import asyncpg
# SPRÁVNE: Asynchrónny ovládač pre PostgreSQL
@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()
Prístup k súborom funguje na rovnakom princípe s aiofiles, dokonca aj pre malé súbory, kde by ťa mohlo lákať pokračovať v používaní open().
import aiofiles
# SPRÁVNE: Asynchrónne čítanie súboru
@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)}
Ani samotné Mistral SDK nie je výnimkou: každá metóda má variantu s príponou _async a práve tú musíš volať z aktivity.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Použi complete_async, NIE complete
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Maj túto mapovaciu tabuľku poruke počas kódových revízií: akýkoľvek riadok z ľavého stĺpca nájdený v aktivite je potenciálnou chybou výkonu.
| Operácia | Nesprávne (blokujúce) | Správne (asynchrónne) |
|---|---|---|
| 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() |
| Súbory | open() | aiofiles.open() |
| Čakanie | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Keď neexistuje asynchrónna verzia
Niektoré business knižnice, ako proprietárne SDK alebo starší klient, jednoducho nenabízajú asynchrónnu variantu. V týchto prípadoch ti asyncio.to_thread() umožní spustiť blokujúci kód v samostatnom vlákne bez zmrazenia slučky udalostí.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Zabalí blokujúce volanie do vlákna."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Je to kompromis, nie rovnocenné riešenie: každé volanie spotrebuje vlákno z poolu, ktorý má konečnú veľkosť. Pre aktivitu volanú masívne paralelne len presunieš úzke hrdlo, namiesto toho, aby si ho odstránil. Vždy uprednostni natívne asynchrónnu knižnicu, ak existuje.
Navrhovanie čistých aktivít
Okrem asynchrónnosti štyri návyky odlišujú robustnú aktivitu od tej, ktorá ťa bude stáť hodiny ladenia.
Prvým je rozsah. Aktivita by mala mať jednu a len jednu zodpovednosť, pretože je tiež jednotkou opakovania a perzistencie: catch-all aktivita, ktorá zlyhá pri odosielaní e-mailu, zopakuje extrakciu a analýzu od začiatku.
# DOBRÉ: Každá aktivita má jasnú zodpovednosť
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# ZLÉ: Catch-all aktivita
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # extrakcia
sentiment = ... # analýza
# odoslať e-mail
# uložiť do DB
pass
Druhý sa týka zdrojov. Kontextový manažér async with garantuje uzavretie klienta aj v prípade výnimky, čo manuálne volania skôr či neskôr nevyhnutne zabudnú urobiť.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Použi async with na garantovanie uzavretia
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# Klient sa tu automaticky uzavrie
return response.json()
Tretí je jemnejší: nie všetky chyby si zaslúžia opakovanie. Časový limit, 429 alebo 500 sú prechodné a mali by sa preniesť vyššie, aby sa spustil retry. Chyba 4xx však indikuje neplatnú požiadavku, ktorú tri opakovania neopravia. Namiesto toho vráť explicitný výsledok a nechaj workflow rozhodnúť.
@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 to zopakuje
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Obmedzená rýchlosť — zopakuje sa
elif e.response.status_code >= 500:
raise # Chyba servera — zopakuje sa
else:
# Chyba klienta (4xx) — neopakovať
return {"status": "error", "code": e.response.status_code}
Nakoniec, štvrtý návyk vyplýva z limitu 2 MB na jedno vyvolanie: vráť len to, čo workflow skutočne potrebuje na rozhodnutie o ďalšom kroku. Počet, vzorka a URL k úplnému výsledku sú takmer vždy dostatočné.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Vráť len to, čo workflow potrebuje
return {
"item_count": len(data),
"summary": data[:10], # Len prvých 10
"full_url": await upload_results(data)
}
Kľúčové poznatky
- Asynchrónny I/O je povinný: používaj
httpx,asyncpg,aiofilesnamiesto ich synchronných ekvivalentov - Blokujúce volania (
requests,psycopg2,open) zmrazia celého workera - Použi
asyncio.to_thread()ako poslednú možnosť pre knižnice bez asynchrónnej verzie - Každá aktivita musí mať jednu jasnú zodpovednosť
- Vždy uzatváraj pripojenia pomocou
async with - Spracúvaj chyby explicitne: niektoré sa majú opakovať, iné nie
- Obmedz veľkosť návratových hodnôt, aby si zostal pod limitom 2 MB