Przejdź do głównej treści
Polski— Wybierz język
Menu

Tworzenie aktywności

Lekcja 4 z 14 Zaktualizowano 2 listopada 2026 Zaawansowany
Na tej stronie
  1. Czym jest aktywność?
  2. Anatomia aktywności
  3. Konkretne przykłady aktywności
  4. Kluczowe cechy
  5. Nazywanie aktywności
  6. Ograniczenia rozmiaru
  7. Kluczowe wnioski

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 async ozdobiona @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