Tegevuse loomine
Sellel lehel
Mis on tegevus?
Tegevus on töövoos põhiline operatiivüksus. Just siin toimub päris töö: välise API kutsumine, päringud andmebaasi, meilide saatmine, failide töötlemine ja tehisintellekti mudelite kasutamine. Tööjaotus on lihtne ja see saab sinu kompassiks kogu kursuse vältel: iga operatsioon, mis hõlmab sisend/väljundit (I/O) või kõrvalmõjusid, tuleb kapseldada tegevusse.
Kui töövoog orkestreerib, siis tegevus täidab. See on fundamentaalne erinevus ja sellel on otsene tagajärg: kuna riskantne töö on isoleeritud tegevuste sees, saab mootor katsetusi sooritada, mõõta ja taasesitada, dubleerimata seejuures kunagi kõrvalmõjusid.
Tegevuse anatoomia
Tegevus on Pythoni async funktsioon, mida kaunistab dekorator @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()
Nendes paaris reas on neli elementi, mis väärivad sinu tähelepanu. Dekorator @workflows.activity() registreerib funktsiooni mootris tegevusena, muutes selle töövoost kutsutavaks. async def on kohustuslik: kõik tegevused peavad olema asünkroonsed, erandeid pole. Parameetrid peavad olema JSON-serialiseeritavad, mis tähendab lihttüüpe – str, int, float, bool, list, dict – või Pydanticu mudeleid; ühendusobjekti või failihalduri edastamine argumendina põhjustab serialiseerimise nurjumise. Sama reegel kehtib tagastusväärtuse kohta, mis liigub üle võrgu enne sündmuste logisse kirjutamist.
Tegevuse konkreetsed näited
Esimene juhtum, mis on selles kursuses tõenäoliselt kõige levinum, kapseldab Mistrali mudeli väljakutse. Pane tähele, et tegevus tagastab ka tokenite tarbimise: kui see metaandmed on logis, saad pärast seda taastada täitmise kulud.
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
}
Teine juhtum illustreerib andmebaasile juurdepääsu. Plokk try/finally ei ole dekoratiivne: kui tegevus nurjub ja seda korratakse, kurnab iga katsega avatud ühenduse jätmine PostgreSQLi ühenduste basseini kiiresti tühjaks.
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()
Kolmas juhtum, meilide saatmine, on koht, kus kõrvalmõjud on kõige nähtavamad: kui sõnum on saadetud, ei suuda ükski korduskatse seda enam kinni püüda.
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}
Põhiomadused
Esiteks, meeldiv vabadus: erinevalt töövoogudest ei kehti tegevustele determinismi piiranguid. Saad vabalt kasutada datetime.now(), uuid.uuid4(), random.random() või mis tahes muud mittedeterministlikku väljakutset tegevuse sees. Just selleks tegevused mõeldudki on – neelama kõike, mida töövoog teha ei tohi.
Platvorm kohtleb iga tegevuse väljakutset aatomse üksusena: see kas õnnestub täielikult või nurjub täielikult, ilma et töövoog näeks vahepealset olekut. Kui sinu tegevus teeb kolm asja ja teine neist kukub läbi, näeb töövoog ainult nurjumist, mitte osalist õnnestumist. Seetõttu peaksid vältima viie erineva operatsiooni kuhjamist ühte funktsiooni.
Kui tegevus õnnestub, salvestatakse selle tulemus töövoosündmuste logi jäädavalt. Taasesituse käigus tegevust kunagi uuesti ei täideta: kasutatakse ainult salvestatud tulemust. Vastutasuks, kuna tegevust võib nurjumise korral uuesti proovida (võrgu aegumine, mööduv viga), peab see olema idempotentne: sama parameetritega mitu korda täidetuna peab see andma sama tulemuse. Üleminek POST-ilt PUT-ile stabiilse identifikaatori puhul on sageli piisav selle omaduse saavutamiseks, nagu siin, kus meiliaadress toimib võtmena:
@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()
Tegevuse nimetamine
Dekorator aktsepteerib selget nime, mis parandab oluliselt jälituse loetavust, kui tehnilisel funktsioonil on ingliskeelne nimi, mida keegi teine meeskonnas äridomeeniga ei seosta:
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
See nimi ilmub OpenTelemetry jälitustesse ja hõlbustab silumist. Tee sellest harjumus algusest peale: päeval, mil jahid põhjust, miks täitmine võttis nelikümmend minutit, loed sisukaid silte, mitte lihtsalt funktsiooninimede loetelu.
Suuruse piirangud
Vahetust reguleerivad kaks piiri: sisendparameetritele maksimaalselt 2 MB ja tagastusväärtusele maksimaalselt 2 MB. Need tulenevad otseselt sündmustepõhisest salvestamisest (event sourcing), kuna need väärtused serialiseeritakse ja salvestatakse logi.
Praktiline järeldus on selge. Kui pead töötlema suuri faile – 40 MB skaneeritud PDF, ekspordiarhiiv – ära edasta neid tegevuselt tegevusele. Salvesta need välisesse teenusesse (S3, GCS) ja liiguta ainult URL-i või identifikaatorit: tegevus laeb faili alla, töötleb selle, kirjutab tulemuse tagasi salvestusse ja tagastab mõnesaja baiti suuruse viite.
Peamised punktid
- Tegevus on
asyncfunktsioon, mida kaunistab@workflows.activity()ja mis teeb päris töö (I/O, API, andmebaas) - Parameetrid ja tagastusväärtused peavad olema JSON-serialiseeritavad
- Tegevustele ei kehti determinismi piirangud
- Õnnestunud tegevust taasesituse käigus kunagi uuesti ei täideta
- Tegevused peavad olema idempotentsed (sama tulemus mitmekordsel täitmisel)
- Sisendi ja väljundi limiit on tegevuse kohta 2 MB