Sukurti veiklą
Šiame puslapyje
Kas yra veikla?
Veikla yra pagrindinis darbo eigos operacinis vienetas. Būtent čia atliekamas tikrasis darbas: išorinių API užklausos, duomenų bazių užklausos, el. laiškų siuntimas, failų apdorojimas ir kreipimaisi į DI modelius. Darbo pasiskirstymas yra paprastas ir taps tavo kompasu visame šiame kurse: bet kokia operacija, susijusi su įvestimi/išvestimi (I/O) ar šalutiniais poveikiais, turi būti įtraukta į veiklą.
Kol darbo eiga koordinuoja, veikla vykdo. Tai esminis skirtumas, turintis tiesioginę pasekmę: kadangi rizikingas darbas izoliuotas veiklose, variklis gali kartoti bandymus, matuoti ir atkurti būseną niekada nedubliuodamas šalutinių poveikių.
Veiklos sandara
Veikla yra Python async funkcija, papuošta dekoratoriumi @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()
Šiose keliose eilutėse keturi elementai nusipelno tavo dėmesio. Dekoratorius @workflows.activity() registruoja funkciją kaip veiklą variklyje, leisdamas ją iškviesti iš darbo eigos. async def yra privalomas: visos veiklos turi būti asinchroninės, be išimčių. Parametrai turi būti JSON serializuojami, tai reiškia paprastus tipus – str, int, float, bool, list, dict – arba Pydantic modelius; perdavus ryšio objektą ar failo rankenėlę kaip argumentą, serializavimas nepavyks. Ta pati taisyklė galioja grąžinamai reikšmei, kuri keliauja tinklu prieš būnant įrašyta į įvykių žurnalą.
Konkretūs veiklų pavyzdžiai
Pirmasis atvejis, tikėtina, dažniausias šiame kurse, įtraukia kreipimąsi į „Mistral“ modelį. Atkreipk dėmesį, kad veikla taip pat grąžina sunaudotų tokenų skaičių: vieną kartą atsidūręs žurnale, toks metaduomenys leidžia vėliau atkurti vykdymo kainą.
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
}
Antrasis atvejis iliustruoja prieigą prie duomenų bazės. Blokas try/finally nėra dekoratyvinis: jei veikla nepavyksta ir bandymas kartojamas, paliekant ryšį atvirą kiekvieno bandymo metu, greitai išseks „PostgreSQL“ jungčių telkinys.
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()
Trečiasis atvejis – el. laiško siuntimas – čia šalutiniai poveikiai labiausiai matomi: kai žinutė išsiųsta, joks pakartotinis bandymas jos nebesugaus.
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}
Pagrindinės savybės
Pirma, maloni laisvė: skirtingai nei darbo eigose, veikloms nėra determinizmo apribojimų. Veiklos viduje gali laisvai naudoti datetime.now(), uuid.uuid4(), random.random() ar bet kokį kitą nedeterministinį kreipinį. Būtent tam ir skirtos veiklos – sugerti viską, ko darbo eiga daryti negali.
Tada platforma kiekvieną veiklos iškvietimą traktuoja kaip atominį vienetą: ji arba visiškai pavyksta, arba visiškai nepavyksta, be jokios tarpinės būsenos, matomos darbo eigai. Jei tavo veikla atlieka tris dalykus ir antrasis žlunga, darbo eiga mato tik nesėkmę, o ne dalinį sėkmę. Štai kodėl reikėtų vengti krūti penkias skirtingas operacijas į vieną funkciją.
Kai veikla pavyksta, jos rezultatas yra visam laikui įrašomas į darbo eigos įvykių žurnalą. Atkuriant būseną (replay), veikla niekada nevykdoma iš naujo: naudojamas tik įrašytas rezultatas. Mainais, kadangi veikla gali būti kartojama nesėkmės atveju (tinklo laiko limitas, laikina klaida), ji turi būti idempotentiška: vykdoma kelis kartus su tais pačiais parametrais, ji turi duoti tą patį rezultatą. Perėjimas nuo POST prie PUT naudojant stabilų identifikatorių dažnai pakanka šiai savybei pasiekti, kaip čia, kur el. pašto adresas naudojamas kaip raktas:
@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()
Veiklos pavadinimas
Dekoratorius priima aiškų pavadinimą, kuris žymiai pagerina sekimo (trace) skaitomumą, kai techninė funkcija turi anglišką pavadinimą, kurio niekas kita komandoje nesieja su verslo domenu:
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
Šis pavadinimas atsiras „OpenTelemetry“ pėdsakuose ir palengvins derinimą. Įprask jį nustatyti iš pat pradžių: tą dieną, kai ieškosi priežasties, kodėl vykdymas užtruko keturiasdešimt minučių, skaitysi prasmingas etiketes, o ne funkcijų pavadinimų sąrašą.
Dydzio apribojimai
Du limitai valdo duomenų mainus: maksimaliai 2 MB įvesties parametrams ir maksimaliai 2 MB grąžinamai reikšmei. Tai tiesiogiai kyla iš įvykių šaltinio (event sourcing), nes šios reikšmės serializuojamos ir saugomos žurnale.
Praktinė pasekmė aiški. Jei reikia apdoroti didelius failus – 40 MB nuskaitytą PDF, eksporto archyvą – neperduok jų iš veiklos į veiklą. Saugok juos išorinėje tarnyboje (S3, GCS) ir cirkuliuok tik URL arba identifikatorių: veikla atsisiunčia failą, jį apdoroja, rezultatą vėl įrašo į saugyklą ir grąžina kelių šimtų baitų nuorodą.
Svarbiausi punktai
- Veikla yra
asyncfunkcija, papuošta@workflows.activity(), atliekanti tikrąjį darbą (I/O, API, DB) - Parametrai ir grąžinamos reikšmės turi būti JSON serializuojami
- Veikloms netaikomi determinizmo apribojimai
- Sėkmingai įvykdyta veikla niekada nevykdoma iš naujo atkuriant būseną
- Veiklos turi būti idempotentiškos (tas pats rezultatas vykdant kelis kartus)
- 2 MB riba įvestiai ir išvestiai vienai veiklai