Aktiviteetin luominen
Tällä sivulla
Mikä on aktiviteetti?
Aktiviteetti on työnkulun perusyksikkö. Juuri täällä varsinainen työ tehdään: ulkoiset API-kutsut, tietokantakyselyt, sähköpostien lähetys, tiedostojen käsittely ja tekoälymallien kutsuminen. Työnjako on yksinkertainen ja toimii oppaana koko kurssin ajan: kaikki syöte/tuloste (I/O) -toiminnot tai sivuvaikutuksia aiheuttavat operaatiot on kapseloitava aktiviteettiin.
Kun työnkulku orkestroi, aktiviteetti suorittaa. Tämä on perustavanlaatuinen ero, ja sillä on suora seuraus: koska riskialtis työ on eristetty aktiviteetteihin, moottori voi yrittää uudelleen, mitata ja toistaa ilman, että sivuvaikutukset koskaan monistuvat.
Aktiviteetin anatomia
Aktiviteetti on Pythonin async-funktio, jota koristaa @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()
Näissä muutamassa rivissä on neljä elementtiä, jotka ansaitsevat huomiosi. @workflows.activity()-koriste rekisteröi funktion aktiviteettina moottorille, jolloin työnkulku voi kutsua sitä. async def on pakollinen: kaikkien aktiviteettien on oltava asynkronisia, ilman poikkeuksia. Parametrien on oltava JSON-serialisoitavia, eli yksinkertaisia tyyppejä (str, int, float, bool, list, dict) tai Pydantic-malleja; yhteysolion tai tiedostokahvan välittäminen argumenttina epäonnistuu serialisoinnissa. Sama sääntö pätee palautusarvoon, joka matkaa verkon yli ennen kuin se kirjoitetaan tapahtumalokiin.
Konkreettisia aktiviteettiesimerkkejä
Ensimmäinen tapaus, todennäköisesti yleisin tällä kurssilla, kapseloi kutsun Mistral-malliin. Huomaa, että aktiviteetti palauttaa myös token-kulutuksen: kun tämäntyyppinen metadata on lokissa, voit jälkikäteen rekonstruoida suorituksen kustannukset.
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
}
Toinen tapaus havainnollistaa tietokantayhteyttä. try/finally-lohko ei ole koriste: jos aktiviteetti epäonnistuu ja sitä yritetään uudelleen, yhteyden jättäminen auki jokaisella yrityksellä tyhjentää PostgreSQL-yhteyspoolin nopeasti.
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 tapaus, sähköpostin lähetys, on tilanne, jossa sivuvaikutukset ovat näkyvimpiä: kun viesti on lähetetty, mikään uudelleenyrittäminen ei voi peruuttaa sitä.
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}
Keskeiset ominaisuudet
Ensinnäkin, tervetullut vapaus: toisin kuin työnkulut, aktiviteeteilla ei ole determinismivaatimuksia. Voit vapaasti käyttää datetime.now(), uuid.uuid4(), random.random() tai mitä tahansa muuta ei-determinististä kutsua aktiviteetin sisällä. Juuri siihen aktiviteetit on tarkoitettu – ne absorboivat kaiken, mitä työnkulku ei saa tehdä.
Alusta kohtelee jokaista aktiviteettikutsua atomisena yksikkönä: se joko onnistuu kokonaan tai epäonnistuu kokonaan, eikä työnkulku näe välitilaa. Jos aktiviteettisi tekee kolme asiaa ja toinen niistä kaatuu, työnkulku näkee vain epäonnistumisen, ei osittaista onnistumista. Siksi sinun tulisi välttää viiden eri operaation pinomista samaan funktioon.
Kun aktiviteetti on onnistunut, sen tulos tallennetaan pysyvästi työnkulun tapahtumalokiin. Toiston aikana aktiviteettia ei koskaan suoriteta uudelleen: käytössä on vain tallennettu tulos. Vastineeksi, koska aktiviteetti voidaan yrittää uudelleen epäonnistumisen sattuessa (verkon aikakatkaisu, ohimenevä virhe), sen on oltava idempotentti: useamman kerran samoilla parametreilla suoritettuna sen on tuotettava sama tulos. Siirtyminen POST:sta PUT:iin vakaan tunnisteen avulla riittää usein tämän ominaisuuden saavuttamiseen, kuten tässä, jossa sähköpostiosoite toimii avaimena:
@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()
Aktiviteetin nimeäminen
Koriste hyväksyy eksplisiittisen nimen, mikä parantaa merkittävästi jäljitettävyyden luettavuutta, kun tekninen funktio kantaa englanninkielistä nimeä, jota kukaan muu tiimissä ei yhdistä liiketoimintadomainiin:
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
Tämä nimi näkyy OpenTelemetry-jäljissä ja helpottaa vianetsintää. Tee siitä tapa asettaa se alusta alkaen: sinä päivänä, kun metsästät syytä siihen, miksi suoritus kesti neljäkymmentä minuuttia, luet mielekkäitä etikettejä etkä luetteloa funktioiden nimistä.
Kokorajoitukset
Kahta rajaa säätelee viestintää: syöteparametreille enintään 2 Mt ja palautusarvolle enintään 2 Mt. Nämä johtuvat suoraan tapahtumalähteistöstä (event sourcing), sillä nämä arvot serialisoidaan ja tallennetaan lokiin.
Käytännön seuraus on selvä. Jos sinun tarvitsee käsitellä suuria tiedostoja – 40 Mt:n skannattu PDF, vientiarkisto – älä välitä niitä aktiviteetista toiseen. Tallenna ne ulkoiseen palveluun (S3, GCS) ja kierrätä vain URL-osoite tai tunniste: aktiviteetti lataa tiedoston, käsittelee sen, kirjoittaa tuloksen takaisin tallennustilaan ja palauttaa muutaman sadan tavun viittauksen.
Keskeiset asiat
- Aktiviteetti on
async-funktio, jota koristaa@workflows.activity()ja joka suorittaa varsinaisen työn (I/O, API, tietokanta) - Parametrien ja palautusarvojen on oltava JSON-serialisoitavia
- Aktiviteeteilla ei ole determinismivaatimuksia
- Onnistunutta aktiviteettia ei koskaan suoriteta uudelleen toiston aikana
- Aktiviteettien on oltava idempotentteja (sama tulos, jos suoritetaan useita kertoja)
- 2 Mt raja syötteelle ja tulosteelle aktiviteettia kohden