Ustvari dejavnost
Na tej strani
Kaj je dejavnost?
Dejavnost je osnovna operativna enota v poteku dela. Tu se odvija pravo delo: klici zunanjih API-jev, poizvedbe v bazi podatkov, pošiljanje e-pošte, obdelava datotek in klici modelov umetne inteligence. Delitev dela je preprosta in bo tvoj kompas skozi celoten tečaj: vsaka operacija, ki vključuje vhod/izhod (I/O) ali stranske učinke, mora biti zaprta v dejavnost.
Medtem ko potek dela usklajuje, dejavnost izvaja. To je temeljna razlika, ki ima neposredno posledico: ker je tvegano delo izolirano znotraj dejavnosti, lahko pogon poskuša znova, meri in predvaja brez podvajanja stranskih učinkov.
Anatomija dejavnosti
Dejavnost je asinhrona funkcija Python async, okrašena z @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()
V teh nekaj vrsticah si zaslužijo tvojo pozornost štirje elementi. Okras @workflows.activity() registrira funkcijo kot dejavnost pri pogonu, kar omogoča njen klic iz poteka dela. async def je obvezen: vse dejavnosti morajo biti asinhrone, brez izjem. Parametri morajo biti seriabilni v JSON, kar pomeni preproste tipe – str, int, float, bool, list, dict – ali modele Pydantic; poskus posredovanja objekta povezave ali ročaja datoteke kot argumenta bo spodletel pri serializaciji. Enako pravilo velja za vrnjeno vrednost, ki potuje prek omrežja, preden se zapiše v dnevnik dogodkov.
Konkretni primeri dejavnosti
Prvi primer, ki je verjetno najpogostejši v tem tečaju, zapira klic modela Mistral. Upoštevaj, da dejavnost vrne tudi porabo žetonov: ko je enkrat v dnevniku, ti takšni metapodatki omogočajo naknadno rekonstrukcijo stroškov izvajanja.
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
}
Drugi primer ponazarja dostop do baze podatkov. Blok try/finally ni okrasen: če dejavnost spodleti in se poskusi znova, bo puščanje odprte povezave ob vsakem poskusu hitro izčrpalo bazen 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()
Tretji primer, pošiljanje e-pošte, je tam, kjer so stranski učinki najbolj vidni: ko je sporočilo enkrat poslano, ga noben ponovni poskus ne more ujeti.
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}
Temeljne značilnosti
Najprej dobrodošla svoboščina: za razliko od potekov dela dejavnosti nimajo omejitev determinizma. Znotraj dejavnosti lahko svobodno uporabljaš datetime.now(), uuid.uuid4(), random.random() ali kateri koli drug nedeterministični klic. Prav za to so dejavnosti namenjene – da prevzamejo vse, kar potek dela ne sme početi.
Platforma nato vsak klic dejavnosti obravnava kot atomsko enoto: ali v celoti uspe ali v celoti spodleti, brez vmesnega stanja, vidnega za potek dela. Če tvoja dejavnost naredi tri stvari in druga odpove, potek dela vidi le napako, ne delnega uspeha. Zato se izogibaj združevanju petih različnih operacij v eno samo funkcijo.
Ko dejavnost uspe, je njen rezultat trajno zapisan v dnevniku dogodkov poteka dela. Med ponovnim predvajanjem se dejavnost nikoli ne izvede znova: uporabi se le zapisani rezultat. V zameno pa mora biti dejavnost, ker se lahko ob napaki (časovni potek omrežja, prehodna napaka) poskusi znova, idempotentna: ob večkratnem izvajanju z istimi parametri mora proizvesti enak rezultat. Prehod s POST na PUT na stabilnem identifikatorju je pogosto dovolj za dosego te lastnosti, kot tukaj, kjer e-poštni naslov služi kot ključ:
@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()
Poimenovanje dejavnosti
Okras sprejme eksplicitno ime, kar bistveno izboljša berljivost sledenja, ko tehnična funkcija nosi angleško ime, ki ga nihče drug v ekipi ne poveže z poslovno domeno:
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
To ime se bo pojavilo v sledéh OpenTelemetry in olajšalo odpravljanje napak. Naj bo tvoja navada, da ga nastaviš takoj od začetka: ko boš nekega dne lovil razlog, zakaj je izvajanje trajalo štirideset minut, boš bral smiselne oznake namesto seznama imen funkcij.
Omejitve velikosti
Izmenjave urejata dve omejitvi: največ 2 MB za vhodne parametre in največ 2 MB za vrnjeno vrednost. Ti izhajata neposredno iz izvora dogodkov (event sourcing), saj so te vrednosti serializirane in shranjene v dnevniku.
Praktična posledica je jasna. Če moraš obdelovati velike datoteke – 40 MB skeniran PDF, arhiv izvoza – jih ne posreduj od dejavnosti do dejavnosti. Shrani jih v zunanjo storitev (S3, GCS) in kroži le URL ali identifikator: dejavnost prenese datoteko, jo obdela, rezultat zapiše nazaj v shrambo in vrne referenco, veliko nekaj sto bajtov.
Ključne ugotovitve
- Dejavnost je funkcija
async, okrašena z@workflows.activity(), ki opravlja pravo delo (I/O, API, baza podatkov) - Parametri in vrnjene vrednosti morajo biti seriabilni v JSON
- Dejavnosti nimajo omejitev determinizma
- Uspešna dejavnost se med ponovnim predvajanjem nikoli ne izvede znova
- Dejavnosti morajo biti idempotentne (enak rezultat ob večkratnem izvajanju)
- Omejitev 2 MB za vhod in izhod na dejavnost