Tworzenie aktywności
Na tej stronie
Czym jest aktywność?
Aktywność to podstawowa jednostka operacyjna w przepływie pracy. To właśnie tutaj odbywa się właściwa praca: wywołania zewnętrznych API, zapytania do bazy danych, wysyłanie e-maili, przetwarzanie plików oraz odwołania do modeli AI. Podział zadań jest prosty i będzie Twoim kompasem podczas tego kursu: każda operacja obejmująca wejście/wyjście (I/O) lub skutki uboczne musi być zamknięta w aktywności.
Podczas gdy przepływ pracy koordynuje, aktywność wykonuje. To fundamentalna różnica, która ma bezpośrednią konsekwencję: ponieważ ryzykowna praca jest izolowana wewnątrz aktywności, silnik może ponawiać próby, mierzyć czas i odtwarzać stan, nigdy nie dublując skutków ubocznych.
Anatomia aktywności
Aktywność to funkcja Pythona async ozdobiona dekoratorem @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()
Cztery elementy w tych kilku liniach zasługują na Twoją uwagę. Dekorator @workflows.activity() rejestruje funkcję jako aktywność w silniku, czyniąc ją wywoływalną z poziomu przepływu pracy. async def jest obowiązkowe: wszystkie aktywności muszą być asynchroniczne, bez wyjątku. Parametry muszą być serializowalne do JSON, co oznacza typy proste – str, int, float, bool, list, dict – lub modele Pydantic; przekazanie obiektu połączenia lub uchwytu pliku jako argumentu spowoduje błąd serializacji. Ta sama zasada dotyczy wartości zwracanej, która podróżuje przez sieć, zanim zostanie zapisana w dzienniku zdarzeń.
Konkretne przykłady aktywności
Pierwszy przypadek, prawdopodobnie najczęstszy w tym kursie, encapsuluje wywołanie modelu Mistral. Zauważ, że aktywność zwraca również zużycie tokenów: gdy tylko trafią one do dziennika, tego rodzaju metadane pozwalają odtworzyć koszt wykonania post factum.
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 przypadek ilustruje dostęp do bazy danych. Blok try/finally nie jest ozdobnikiem: jeśli aktywność zakończy się niepowodzeniem i zostanie ponowiona, pozostawienie otwartego połączenia przy każdej próbie szybko wyczerpie pulę połączeń 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()
Trzeci przypadek, wysyłanie e-maili, to sytuacja, w której skutki uboczne są najbardziej widoczne: gdy tylko wiadomość zostanie wysłana, żadna ponowna próba tego nie cofnie.
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}
Kluczowe cechy
Po pierwsze, mile widziana swoboda: w przeciwieństwie do przepływów pracy, aktywności nie mają ograniczeń determinizmu. Możesz swobodnie używać datetime.now(), uuid.uuid4(), random.random() lub dowolnego innego niedeterministycznego wywołania wewnątrz aktywności. Dokładnie do tego służą aktywności – pochłaniają wszystko, czego przepływ pracy nie może robić.
Platforma traktuje każde wywołanie aktywności jako jednostkę atomową: albo kończy się pełnym sukcesem, albo pełną porażką, bez żadnego stanu pośredniego widocznego dla przepływu pracy. Jeśli Twoja aktywność robi trzy rzeczy, a druga ulegnie awarii, przepływ pracy zobaczy tylko niepowodzenie, a nie częściowy sukces. Dlatego powinieneś unikać upychania pięciu różnych operacji w jednej funkcji.
Gdy aktywność zakończy się sukcesem, jej wynik jest trwale zapisywany w dzienniku zdarzeń przepływu pracy. Podczas odtwarzania aktywność nigdy nie jest wykonywana ponownie: używany jest wyłącznie zapisany wynik. W zamian, ponieważ aktywność może być ponawiana w przypadku niepowodzenia (limit czasu sieci, błąd przejściowy), musi być idempotentna: wykonywana wielokrotnie z tymi samymi parametrami, musi dawać ten sam wynik. Przejście z POST na PUT ze stabilnym identyfikatorem często wystarcza, aby osiągnąć tę właściwość, jak tutaj, gdzie e-mail służy jako klucz:
@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()
Nazywanie aktywności
Dekorator przyjmuje jawną nazwę, co znacznie poprawia czytelność śladów, gdy techniczna funkcja nosi angielską nazwę, której nikt inny w zespole nie kojarzy z domeną biznesową:
@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
# ...
pass
Ta nazwa pojawi się w śladach OpenTelemetry i ułatwi debugowanie. Wyrób sobie nawyk ustawiania jej od samego początku: dnia, gdy będziesz szukać przyczyny, dla której wykonanie trwało czterdzieści minut, przeczytasz znaczące etykiety, a nie listę nazw funkcji.
Ograniczenia rozmiaru
Dwa limity rządzą wymianą danych: maksymalnie 2 MB dla parametrów wejściowych i maksymalnie 2 MB dla wartości zwracanej. Wynikają one bezpośrednio z event sourcingu, ponieważ wartości te są serializowane i przechowywane w dzienniku.
Praktyczna konsekwencja jest jasna. Jeśli musisz przetwarzać duże pliki – 40-megabajtowy zeskanowany PDF, archiwum eksportu – nie przekazuj ich z aktywności do aktywności. Przechowuj je w usłudze zewnętrznej (S3, GCS) i cyrkuluj tylko adres URL lub identyfikator: aktywność pobiera plik, przetwarza go, zapisuje wynik z powrotem w magazynie i zwraca referencję liczącą kilkaset bajtów.
Kluczowe wnioski
- Aktywność to funkcja
asyncozdobiona@workflows.activity(), która wykonuje właściwą pracę (I/O, API, baza danych) - Parametry i wartości zwracane muszą być serializowalne do JSON
- Aktywności nie mają ograniczeń determinizmu
- Udana aktywność nigdy nie jest wykonywana ponownie podczas odtwarzania
- Aktywności muszą być idempotentne (ten sam wynik przy wielokrotnym wykonaniu)
- Limit 2 MB na dane wejściowe i wyjściowe dla każdej aktywności