Vytvorenie aktivity
Na tejto strane
Čo je to aktivita?
Aktivita je základnou operačnou jednotkou vo workflowe. Práve tu sa deje skutočná práca: volania externých API, dotazy do databázy, odosielanie e-mailov, spracovanie súborov a volania modelov umelej inteligencie. Rozdelenie úloh je jednoduché a bude ti slúžiť ako kompas počas celého kurzu: akákoľvek operácia zahŕňajúca vstup/výstup (I/O) alebo vedľajšie účinky musí byť zapuzdrená v aktivite.
Zatiaľ čo workflow orchestrátor riadi, aktivita vykonáva. To je zásadný rozdiel, ktorý má priamy dôsledok: keďže je riziková práca izolovaná v aktivitách, engine môže retryovať, merať a prehrávať bez toho, aby niekedy duplikoval vedľajšie účinky.
Anatómia aktivity
Aktivita je Python funkcia async označená dekorátorom @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()
Štyri prvky v týchto niekoľkých riadkoch si zaslúžia tvoju pozornosť. Dekorátor @workflows.activity() registruje funkciu ako aktivitu v engine, čím ju sprístupní pre volanie z workflow. Kľúčové slovo async def je povinné: všetky aktivity musia byť asynchrónne, bez výnimky. Parametre musia byť sériovateľné do formátu JSON, čo znamená jednoduché typy – str, int, float, bool, list, dict – alebo modely Pydantic; pokus o odovzdanie objektu pripojenia alebo handle súboru ako argumentu zlyhá pri serializácii. To isté pravidlo platí pre návratovú hodnotu, ktorá cestuje po sieti predtým, než sa zapíše do logu udalostí.
Konkrétne príklady aktivít
Prvý prípad, pravdepodobne najbežnejší v tomto kurze, zapuzdruje volanie modelu Mistral. Všimni si, že aktivita tiež vracia spotrebu tokenov: keďže je táto metadáta v logu, umožňuje ti dodatočne rekonštruovať náklady na vykonanie.
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
}
Druhý prípad ilustruje prístup do databázy. Blok try/finally nie je len ozdobný: ak aktivita zlyhá a je retryovaná, ponechanie otvoreného pripojenia pri každom pokuse rýchlo vyčerpá pool 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()
Tretí prípad, odosielanie e-mailu, je miestom, kde sú vedľajšie účinky najviditeľnejšie: akonáhle je správa odoslaná, žiadny retry ju už nezachytí.
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}
Kľúčové vlastnosti
Po prvé, vítaná sloboda: na rozdiel od workflow, aktivity nemajú obmedzenia determinizmu. Môžeš voľne používať datetime.now(), uuid.uuid4(), random.random() alebo akékoľvek iné nedeterministické volanie priamo v aktivite. Presne na to sú aktivity určené – absorbujú všetko, čo workflow robiť nesmie.
Platforma následne zaobchádza s každým volaním aktivity ako s atomickou jednotkou: buď úplne uspeje, alebo úplne zlyhá, pričom workflow nevidí žiadny medzistav. Ak tvoja aktivita robí tri veci a druhá z nich zlyhá, workflow vidí iba zlyhanie, nie čiastočný úspech. Preto by si sa mal vyhnúť nahromadeniu piatich rôznych operácií do jednej funkcie.
Akonáhle aktivita uspeje, jej výsledok je trvalo zaznamenaný v logu udalostí workflow. Počas prehrávania sa aktivita nikdy nevykoná znova: použije sa iba zaznamenaný výsledok. Na oplátku, pretože sa aktivita môže pri zlyhaní retryovať (časový limit siete, prechodná chyba), musí byť idempotentná: pri viacerých vykonaniach s rovnakými parametrami musí produkovať rovnaký výsledok. Prechod z POST na PUT so stabilným identifikátorom často stačí na dosiahnutie tejto vlastnosti, ako je to tu, kde e-mail slúži ako kľúč:
@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()
Pomenovanie aktivity
Dekorátor akceptuje explicitný názov, čo výrazne zlepšuje čitateľnosť stôp (traces), keď technická funkcia nesie anglický názov, ktorý nikto iný v tíme nespája s business doménou:
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
Tento názov sa objaví v stopách OpenTelemetry a uľahčí ladenie. Urob si zvyk nastaviť ho hneď na začiatku: v deň, keď budeš pátrať po dôvode, prečo vykonanie trvalo štyridsať minút, budeš čítať zmysluplné štítky namiesto zoznamu názvov funkcií.
Obmedzenia veľkosti
Výmenu dát riadia dva limity: maximálne 2 MB pre vstupné parametre a maximálne 2 MB pre návratovú hodnotu. Vyplývajú priamo z event sourcingu, keďže tieto hodnoty sú serializované a uložené v logu.
Praktický dôsledok je jasný. Ak potrebuješ spracovávať veľké súbory – 40 MB naskenovaný PDF, exportný archív – nepredávaj ich z aktivity do aktivity. Ulož ich do externej služby (S3, GCS) a cirkuluj iba URL alebo identifikátor: aktivita si súbor stiahne, spracuje ho, zapíše výsledok späť do úložiska a vráti odkaz s veľkosťou niekoľkých stoviek bajtov.
Kľúčové poznatky
- Aktivita je funkcia
asyncoznačená dekorátorom@workflows.activity(), ktorá vykonáva skutočnú prácu (I/O, API, DB) - Parametre a návratové hodnoty musia byť sériovateľné do formátu JSON
- Aktivity nemajú obmedzenia determinizmu
- Úspešná aktivita sa počas prehrávania nikdy nevykoná znova
- Aktivity musia byť idempotentné (rovnaký výsledok pri viacerých vykonaniach)
- Limit 2 MB na vstup a výstup na jednu aktivitu