Oħloq Attività
F'din il-paġna
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
asyncimż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à