Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Tevékenység létrehozása

4. lecke 14 közül Frissítve 2026. november 2. Haladó
Ezen az oldalon
  1. Mi az a tevékenység?
  2. Egy tevékenység felépítése
  3. Konkrét tevékenységpéldák
  4. Alapvető jellemzők
  5. Tevékenység elnevezése
  6. Méretkorlátok
  7. Főbb megállapítások

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 async fü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