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

Oħloq Attività

Lezzjoni 4 / 14 Aġġornat 2 ta’ Novembru 2026 Avvanzat
F'din il-paġna
  1. X’inhi Attività?
  2. Anatomija ta’ Attività
  3. Eżempji Konkreti ta’ Attivitajiet
  4. Karatteristiċi Ewlenin
  5. Tisimja ta’ Attività
  6. Restrizzjonijiet tad-Daqs
  7. Punti Ewlenin

X’inhi Attività?

Attività hija l-unità operattiva bażika f’workflow. Hawnhekk iseħħ ix-xogħol reali: sejħiet għal API esterni, mistoqsijiet tad-database, tibgħat emails, ipproċessar ta’ fajls, u sejħiet għal mudelli tal-AI. Id-diviżjoni tax-xogħol hija sempliċi u se sservi bħala l-kumpass tiegħek matul dan il-kors: kwalunkwe operazzjoni li tinvolvi input/output (I/O) jew effetti sekondarji trid tiġi inkapsulata f’attività.

Filwaqt li l-workflow jorganizza, l-attività teżegwixxi. Din hija d-distinzjoni fundamentali, u għandha konsegwenza diretta: peress li x-xogħol riskjuż huwa iżolat ġewwa l-attivitajiet, l-engine jista’ jipprova mill-ġdid, ikejjel, u jerġa’ jdoqq mingħajr qatt ma jidduppja l-effetti sekondarji.

Anatomija ta’ Attività

Attività hija funzjoni Python async imżejna b’@workflows.activity():

import mistralai.workflows as workflows

@workflows.activity()
async def get_user_profile(user_id: str) -> dict:
    """Retrieves a user profile from the API."""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        response.raise_for_status()
        return response.json()

Erba’ elementi f’dawn il-ftit linji jistħoqqilhom l-attenzjoni tiegħek. Id-dekoratur @workflows.activity() jirreġistra l-funzjoni bħala attività mal-engine, u jagħmilha sejħibbli minn workflow. L-async def huwa obbligatorju: l-attivitajiet kollha għandhom ikunu asinkroni, mingħajr eċċezzjoni. Il-parametri għandhom ikunu JSON-serializzabbli, jiġifieri tipi sempliċi—str, int, float, bool, list, dict—jew mudelli Pydantic; li tgħaddi oġġett ta’ konnessjoni jew handle ta’ fajl bħala argument se jfalli s-serializzazzjoni. L-istess regola tapplika għall-valur tar-ritorn, li jivvjaġġa fin-netwerk qabel ma jiġi miktub fil-log tal-avvenimenti.

Eżempji Konkreti ta’ Attivitajiet

L-ewwel każ, probabbilment l-aktar komuni f’dan il-kors, jinkapsula sejħa għal mudell Mistral. Innota li l-attività tirritorna wkoll il-konsum tat-tokens: darba fil-log, dan it-tip ta’ metadata jħallik tirrikostruwixxi l-ispiża ta’ eżekuzzjoni wara l-fatt.

import mistralai.workflows as workflows
from mistralai.client import Mistral

@workflows.activity()
async def generate_summary(text: str) -> dict:
    """Generates a summary of the provided text via Mistral."""
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "You are an assistant specialized in text summarization."},
            {"role": "user", "content": f"Summarize this text in 3 sentences:\n\n{text}"}
        ]
    )
    return {
        "summary": response.choices[0].message.content,
        "tokens_used": response.usage.total_tokens
    }

It-tieni każ juri aċċess għad-database. Il-blokka try/finally mhix dekorattiva: jekk l-attività tfalli u tiġi ppruvata mill-ġdid, li tħalli konnessjoni miftuħa f’kull tentattiv se jeżawrixxi malajr il-pool ta’ PostgreSQL.

import mistralai.workflows as workflows
import asyncpg

@workflows.activity()
async def save_report(report: dict) -> dict:
    """Saves a report to PostgreSQL."""
    conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
    try:
        row = await conn.fetchrow(
            "INSERT INTO reports (title, content, created_at) VALUES ($1, $2, NOW()) RETURNING id",
            report["title"],
            report["content"]
        )
        return {"id": row["id"], "status": "saved"}
    finally:
        await conn.close()

It-tielet każ, li tibgħat email, huwa fejn l-effetti sekondarji huma l-aktar viżibbli: darba li l-messaġġ jintbagħat, l-ebda prova mill-ġdid ma tista’ taqbdu.

import mistralai.workflows as workflows
import aiosmtplib

@workflows.activity()
async def send_notification(recipient: str, subject: str, body: str) -> dict:
    """Sends a notification email."""
    message = f"Subject: {subject}\nTo: {recipient}\n\n{body}"
    await aiosmtplib.send(
        message,
        hostname="smtp.example.com",
        port=587,
        username="[email protected]",
        password="secret",
        use_tls=True
    )
    return {"status": "sent", "recipient": recipient}

Karatteristiċi Ewlenin

L-ewwel, libertà li tilqa’ b’merħba: kuntrarjament għall-workflows, l-attivitajiet m’għandhom l-ebda restrizzjoni ta’ determiniżmu. Tista’ tuża liberament datetime.now(), uuid.uuid4(), random.random(), jew kwalunkwe sejħa oħra mhux deterministika ġewwa attività. Dan huwa preċiżament għal xiex huma maħsuba l-attivitajiet—li jassorbu kollox li l-workflow mhuwiex permess jagħmel.

Il-pjattaforma mbagħad tittratta kull sejħa ta’ attività bħala unità atomika: jew tirnexxi kompletament jew tfalli kompletament, mingħajr l-ebda stat intermedjarju viżibbli għall-workflow. Jekk l-attività tiegħek tagħmel tliet affarijiet u t-tieni waħda taqbeż, il-workflow jara biss falliment, mhux suċċess parzjali. Għalhekk għandek tevita li tgħaqqad ħames operazzjonijiet distinti f’funzjoni waħda.

Ladarba attività tirnexxi, ir-riżultat tagħha jiġi rreġistrat b’mod permanenti fil-log tal-avvenimenti tal-workflow. Matul replay, l-attività qatt ma tiġi eżegwita mill-ġdid: jintuża biss ir-riżultat irreġistrat. Min-naħa l-oħra, peress li attività tista’ tiġi ppruvata mill-ġdid fuq falliment—time-out tan-netwerk, żball tranżitorju—trid tkun idempotenti: eżegwita diversi drabi bl-istess parametri, trid tipproduċi l-istess riżultat. Li tibdel minn POST għal PUT fuq identifikatur stabbil spiss ikun biżżejjed biex tikseb din il-proprjetà, bħal hawn fejn l-email isservi bħala ċ-ċavetta:

@workflows.activity()
async def create_or_update_client(email: str, name: str) -> dict:
    """Idempotent: uses an upsert instead of an insert."""
    async with httpx.AsyncClient() as client:
        response = await client.put(
            f"https://api.crm.com/clients/{email}",
            json={"name": name, "email": email}
        )
        return response.json()

Tisimja ta’ Attività

Id-dekoratur jaċċetta isem espliċitu, li jtejjeb b’mod sinifikanti l-qari tat-traċċar meta funzjoni teknika jkollha isem bl-Ingliż li ħadd ħliefek fit-tim ma jorbot mad-dominju tan-negozju:

@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
    # ...
    pass

Dan l-isem jidher fit-traċċi ta’ OpenTelemetry u jiffaċilita d-debugging. Agħmilha drawwa li tissettjah mill-bidu: il-jum li tkun qed tfittex għaliex eżekuzzjoni ħadet erbgħin minuta, se taqra tikketti sinifikanti minflok lista ta’ ismijiet ta’ funzjonijiet.

Restrizzjonijiet tad-Daqs

Żewġ limiti jirregolaw l-iskambji: massimu ta’ 2 MB għall-parametri tal-input u massimu ta’ 2 MB għall-valur tar-ritorn. Dawn ġejjin direttament mis-sors tal-avvenimenti (event sourcing), peress li dawn il-valuri huma serializzati u maħżuna fil-log.

Il-konsegwenza prattika hija ċara. Jekk għandek bżonn tipproċessa fajls kbar—PDF skennjat ta’ 40 MB, arkivju ta’ esportazzjoni—tgħaddihomx minn attività għal oħra. Aħżinhom f’servizz estern (S3, GCS) u ċirkola biss l-URL jew l-identifikatur: l-attività tnizzel il-fajl, tipproċessah, tikteb ir-riżultat lura fil-ħażna, u tirritorna referenza ta’ ftit mijiet ta’ bytes.

Punti Ewlenin

  • Attività hija funzjoni async imżejna b’@workflows.activity() li twettaq ix-xogħol reali (I/O, API, DB)
  • Il-parametri u l-valuri tar-ritorn għandhom ikunu JSON-serializzabbli
  • L-attivitajiet m’għandhom l-ebda restrizzjoni ta’ determiniżmu
  • Attività ta’ suċċess qatt ma tiġi eżegwita mill-ġdid matul replay
  • L-attivitajiet għandhom ikunu idempotenti (l-istess riżultat jekk eżegwiti diversi drabi)
  • Limitu ta’ 2 MB fuq l-input u l-output għal kull attività