Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Async u L-Aħjar Prattiki

Lezzjoni 13 / 14 Aġġornat 2 ta’ Novembru 2026 Avvanzat
F'din il-paġna
  1. Async I/O: Rekwiżit Tekniku
  2. Agħżel Libreriji Nattivament Asinkroni
  3. Meta Ma Jeżistix Verżjoni Async
  4. Iddisinja Attivitajiet Nodfa
  5. Punti Ewlenin

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.

OperazzjoniMhux Korrett (jibblokka)Korrett (async)
HTTPrequests.get()httpx.AsyncClient().get()
HTTPurllib.request.urlopen()aiohttp.ClientSession().get()
PostgreSQLpsycopg2.connect()asyncpg.connect()
MySQLmysql.connector.connect()aiomysql.connect()
Redisredis.Redis()redis.asyncio.Redis()
Fajlsopen()aiofiles.open()
Sleeptime.sleep()asyncio.sleep()
Mistralclient.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, aiofiles minflok 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