Async u L-Aħjar Prattiki
F'din il-paġna
Async I/O: Rekwiżit Tekniku
L-attivitajiet kollha f’Mistral Workflows iridu jużaw operazzjonijiet ta’ input/output asinkroni. Din mhix sempliċiment rakkomandazzjoni ta’ stil; hija kostrenzjoni teknika. Sejħa sinkrona li timblokka bħal requests.post() tissakkar il-ħaddiem (worker) u tipprevjeni kwalunkwe attività oħra milli titħaddem.
Dan ir-rekwiżit ġej mill-arkitettura tal-ħaddiem, li tesegwixxi l-attivitajiet fi ħdan ċ-ċiklu ta’ avvenimenti (event loop) ta’ asyncio. Meta coroutine tistenna (await) tweġiba tan-netwerk b’mod asinkronu, tirritorna l-kontroll lura liċ-ċiklu, u b’hekk tippermetti lil attivitajiet oħra jipproċedu. Sejħa sinkrona, min-naħa l-oħra, ma tirritorna xejn.
import requests
# MHUX KORRETT: Jibblokka l-ħaddiem kollu kemm hu
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# requests.post() hija sinkrona — tibblokka ċ-ċiklu tal-avvenimenti
response = requests.post(url, json={"query": "test"})
return response.json()
Is-sintomu fil-produzzjoni jista’ jkun konfuż: tniedi għaxar attivitajiet paralleli b’asyncio.gather, iżda fil-fatt jesegwixxu waħda wara l-oħra. Jekk kull waħda tistenna żewġ sekondi għal API remot, tkejjel għoxrin sekonda minflok iż-żewġ mistennija, mingħajr l-ebda żball imqajjem.
Agħżel Libreriji Nattivament Asinkroni
Is-soluzzjoni hija li tibdel kull librerija li timblokka bl-ekwivalenti asinkronu tagħha. Għas-sejħiet HTTP, httpx huwa l-għażla standard.
import httpx
# KORRETT: Mhux imblukkar
@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 isservi l-istess skop b’API ftit differenti bbażata fuq is-sessjonijiet.
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()
Għad-databases, asyncpg jieħu post psycopg2 għal PostgreSQL. Innota l-blokk try/finally: il-konnessjoni trid tingħalaq anke jekk il-mistoqsija tqajjem eċċezzjoni. Inkella, tentattivi suċċessivi ta’ retry se jexawru l-pool tal-konnessjonijiet.
import asyncpg
# KORRETT: Driver asinkronu għal 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()
L-aċċess għall-fajls isegwi l-istess loġika b’aiofiles, anke għal fajls żgħar fejn tista’ tkun ittentat li tkompli tuża open().
import aiofiles
# KORRETT: Qari asinkronu ta' fajls
@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)}
L-SDK ta’ Mistral innifsu mhuwiex eċċezzjoni: kull metodu għandu varjant bi suffiss _async, u dik hija l-waħda li trid isejjaħ minn attività.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Uża complete_async, MHUX complete
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Żomm din it-tabella ta’ korrispondenza ħdejk waqt ir-reviżjonijiet tal-kodiċi: kwalunkwe linja mill-kolonna tax-xellug li tinstab f’attività hija bug potenzjali tal-prestazzjoni.
| Operazzjoni | Mhux Korrett (jibblokka) | Korrett (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() |
| Fajls | open() | aiofiles.open() |
| Sleep | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Meta Ma Jeżistix Verżjoni Async
Xi libreriji tan-negozju, bħal SDK proprjetarju jew klijent antik, sempliċiment ma joffrux varjant asinkronu. F’dawn il-każijiet, asyncio.to_thread() jippermettilek tħaddem il-kodiċi li jibblokka f’thread separat mingħajr ma tissakkar iċ-ċiklu tal-avvenimenti.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Jgħatti sejħa li timblokka f'thread."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Dan huwa kompromess, mhux soluzzjoni ekwivalenti: kull sejħa tikkonsma thread mill-pool, li għandu daqs finit. Għal attività msejħa massivament b’mod parallel, inti sempliċiment iċċaqlaq il-collof ta’ bottlanek (bottleneck) minflok ma tneħħih. Dejjem ippreferi librerija nattivamente asinkrona meta tkun teżisti waħda.
Iddisinja Attivitajiet Nodfa
Lil hinn mill-asinkronija, erba’ drawwiet jiddistingwu attività robusta minn waħda li se tiswielek sigħat sħaħ ta’ debug.
L-ewwel huwa l-ambitu (scope). Attività għandha jkollha responsabbiltà waħda u waħda biss, għax hija wkoll l-unità ta’ retry u persistenza: attività “catch-all” li tfalli waqt li tibgħat email se terġa’ tgħaddi mill-estrazzjoni u l-analiżi mill-bidu nett.
# TJIEB: Kull attività għandha responsabbiltà ċara
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# ĦŻIEN: Attività catch-all
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # estrazzjoni
sentiment = ... # analiżi
# ibgħat email
# iffranka fid-DB
pass
It-tieni jikkonċerna r-riżorsi. Il-ġestur tal-kuntest async with jiggarantixxi li l-klijent jingħalaq anke jekk iseħħ eċċezzjoni, xi ħaġa li s-sejħiet manwali inevitabbilment jinsu qabel jew wara.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Uża async with biex tiggarantixxi l-għeluq
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# Il-klijent jingħalaq awtomatikament hawnhekk
return response.json()
It-tielet hija aktar sottili: mhux l-iżbalji kollha jistħoqqilhom retry. Timeout, 429, jew 500 huma tranżitorji u għandhom jitilgħu ‘l fuq (bubble up) biex jattivaw retry. Żball 4xx, madankollu, jindika talba invalida li t-tliet tentattivi ta’ retry mhux se jsolvu. Minflok, irritorna riżultat espliċitu u ħalli l-workflow jiddeċiedi.
@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 # Se jiġi rritentat mill-pjattaforma
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Rata limitata — se jiġi rritentat
elif e.response.status_code >= 500:
raise # Żball tas-server — se jiġi rritentat
else:
# Żball tal-klijent (4xx) — tirritentax
return {"status": "error", "code": e.response.status_code}
Fl-aħħar nett, ir-raba’ drawja ġejja mil-limitu ta’ 2 MB għal kull sejħa: irritorna biss dak li l-workflow verament jeħtieġ biex jiddeċiedi l-pass li jmiss. Għadd, kampjun, u l-URL għar-riżultat sħiħ huma kważi dejjem biżżejjed.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Irritorna biss dak li l-workflow jeħtieġ
return {
"item_count": len(data),
"summary": data[:10], # L-ewwel 10 biss
"full_url": await upload_results(data)
}
Punti Ewlenin
- Async I/O huwa obbligatorju: uża
httpx,asyncpg,aiofilesminflok l-ekwivalenti sinkroni tagħhom - Sejħiet li jibblukkaw (
requests,psycopg2,open) jissakkar lill-ħaddiem kollu kemm hu - Uża
asyncio.to_thread()bħala aħħar riżorsa għal libreriji mingħajr verżjoni async - Kull attività trid ikollha responsabbiltà waħda ċara
- Dejjem agħlaq il-konnessjonijiet b’
async with - Immaniġġja l-iżbalji b’mod espliċitu: uħud għandhom jiġu rritentati, oħrajn le
- Illimita d-daqs tar-ritorni biex tibqa’ taħt il-limitu ta’ 2 MB