Tevékenység létrehozása
Ezen az oldalon
Mi az a tevékenység?
A tevékenység a munkafolyamat alapvető működési egysége. Itt történik meg a valódi munka: külső API-hívások, adatbázis-lekérdezések, e-mailek küldése, fájlok feldolgozása és AI-modellek meghívása. A munkamegosztás egyszerű, és ez lesz az iránytűd a tanfolyam során: minden olyan műveletet, amely bemeneti/kimeneti (I/O) műveleteket vagy mellékhatásokat foglal magában, tevékenységbe kell zárni.
Míg a munkafolyamat orchestrál, addig a tevékenység végrehajt. Ez az alapvető különbség, amelynek közvetlen következménye van: mivel a kockázatos munka a tevékenységeken belül van elszigetelve, a motor újrapróbálkozhat, mérhet és lejátszhat anélkül, hogy valaha is megismételné a mellékhatásokat.
Egy tevékenység felépítése
Egy tevékenység egy Python async függvény, amelyet a @workflows.activity() dekorátorral láttunk el:
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()
Ebben a néhány sorban négy elem érdemel figyelmet. A @workflows.activity() dekorátor regisztrálja a függvényt tevékenységként a motornál, így az hívhatóvá válik egy munkafolyamatból. Az async def kötelező: minden tevékenységnek aszinkronnak kell lennie, kivétel nélkül. A paramétereknek JSON-szerializálhatónak kell lenniük, ami egyszerű típusokat jelent – str, int, float, bool, list, dict – vagy Pydantic modelleket; ha kapcsolati objektumot vagy fájlkezelőt adsz át argumentumként, a szerializálás sikertelen lesz. Ugyanez a szabály vonatkozik a visszatérési értékre is, amely áthalad a hálózaton, mielőtt bekerülne az eseménynaplóba.
Konkrét tevékenységpéldák
Az első eset, amely valószínűleg a leggyakoribb ebben a tanfolyamban, egy Mistral modellhez intézett hívást zár be. Vegyük észre, hogy a tevékenység a tokenfelhasználást is visszaadja: ha ez a metaadat egyszer bekerül a naplóba, utólag rekonstruálhatod vele a végrehajtás költségét.
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
}
A második eset az adatbázis-hozzáférést illusztrálja. A try/finally blokk nem díszítés: ha a tevékenység meghiúsul és újrapróbálkozik, a minden egyes próbálkozásnál nyitva maradó kapcsolat gyorsan kimeríti a PostgreSQL-készletet.
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()
A harmadik eset, az e-mail küldése, az a pont, ahol a mellékhatások a legláthatóbbak: ha az üzenet egyszer elkelt, egyetlen újrapróbálkozás sem tudja „visszafogni“.
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}
Alapvető jellemzők
Először is, egy üdvözlendő szabadság: a munkafolyamatokkal ellentétben a tevékenységekre nincsenek determinisztikus kényszerek. Szabadon használhatsz datetime.now()-t, uuid.uuid4()-et, random.random()-t vagy bármilyen más nem determinisztikus hívást egy tevékenységen belül. Pontosan erre valók a tevékenységek – hogy elnyeljenek mindent, amit a munkafolyamat nem tehet meg.
A platform ezt követően minden tevékenységhívást atomikus egységként kezel: vagy teljesen sikerül, vagy teljesen meghiúsul, anélkül, hogy a munkafolyamat látna bármilyen közbenső állapotot. Ha a tevékenységed három dolgot csinál, és a második összeomlik, a munkafolyamat csak a hibát látja, nem a részleges sikert. Ezért kerüld el, hogy öt különálló műveletet zsúfolj egyetlen függvénybe.
Ha egy tevékenység sikerrel jár, az eredménye véglegesen rögzítésre kerül a munkafolyamat eseménynaplójában. Egy lejátszás során a tevékenység soha nem hajtódik végre újra: csak a rögzített eredményt használja fel a rendszer. Cserébe, mivel egy tevékenység hiba esetén újrapróbálkozhat – hálózati időtúllépés, átmeneti hiba –, idempotensnek kell lennie: ugyanazokkal a paraméterekkel többször végrehajtva ugyanazt az eredményt kell produkálnia. Egy stabil azonosítón alapuló POST-ról PUT-ra váltás gyakran elég ehhez a tulajdonsághoz, ahogy itt is, ahol az e-mail cím szolgál kulcsként:
@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()
Tevékenység elnevezése
A dekorátor elfogad egy explicit nevet, ami jelentősen javítja a nyomkövetés olvashatóságát, amikor egy technikai függvénynek olyan angol neve van, amit a csapat többi tagja nem kapcsol az üzleti doménhez:
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
Ez a név megjelenik az OpenTelemetry nyomokban, és megkönnyíti a hibakeresést. Szoktasd rá magad, hogy eleve beállítod: azon a napon, amikor azt kutatod, miért tartott negyven percig egy végrehajtás, értelmes címkéket fogsz olvasni a függvénynevek listája helyett.
Méretkorlátok
Két korlát szabályozza az adatcserét: maximum 2 MB a bemeneti paraméterek számára és maximum 2 MB a visszatérési érték számára. Ezek közvetlenül az eseményalapú tárolásból (event sourcing) adódnak, mivel ezeket az értékeket szerializálni kell és el kell tárolni a naplóban.
A gyakorlati következmény egyértelmű. Ha nagy fájlokat kell feldolgoznod – egy 40 MB-os szkennelt PDF-et, egy export archívumot –, ne add át őket tevékenységről tevékenységre. Tárold őket egy külső szolgáltatásban (S3, GCS), és csak az URL-t vagy az azonosítót keringesd: a tevékenység letölti a fájlt, feldolgozza, visszaírja az eredményt a tárolóba, és néhány száz bájt hosszú referenciát ad vissza.
Főbb megállapítások
- A tevékenység egy
asyncfüggvény, amelyet a@workflows.activity()dekorátorral láttunk el, és amely elvégzi a valódi munkát (I/O, API, adatbázis) - A paramétereknek és a visszatérési értékeknek JSON-szerializálhatónak kell lenniük
- A tevékenységekre nincsenek determinisztikus kényszerek
- Egy sikeres tevékenység soha nem hajtódik végre újra egy lejátszás során
- A tevékenységeknek idempotensnek kell lenniük (ugyanaz az eredmény többszöri végrehajtás esetén is)
- 2 MB-os korlát vonatkozik a bemenetre és a kimenetre tevékenységenként