Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Δημιουργία μιας Δραστηριότητας

Μάθημα 4 / 14 Ενημερώθηκε 2 Νοεμβρίου 2026 Προχωρημένος
Σε αυτήν τη σελίδα
  1. Τι είναι μια Δραστηριότητα;
  2. Ανατομία μιας Δραστηριότητας
  3. Παραδείγματα Συγκεκριμένων Δραστηριοτήτων
  4. Βασικά Χαρακτηριστικά
  5. Ονομασία μιας Δραστηριότητας
  6. Περιορισμοί Μεγέθους
  7. Βασικά σημεία

Τι είναι μια Δραστηριότητα;

Μια δραστηριότητα αποτελεί τη βασική λειτουργική μονάδα μέσα σε μια ροή εργασίας. Εδώ πραγματοποιείται η πραγματική εργασία: κλήσεις σε εξωτερικά API, ερωτήματα βάσεων δεδομένων, αποστολή emails, επεξεργασία αρχείων και κλήσεις σε μοντέλα Τεχνητής Νοημοσύνης. Ο διαχωρισμός των αρμοδιοτήτων είναι απλός και θα λειτουργήσει ως πυξίδα σας σε όλη τη διάρκεια αυτού του μαθήματος: κάθε λειτουργία που περιλαμβάνει είσοδο/έξοδο (I/O) ή παρενέργειες πρέπει να encapsulated (περικλείεται) μέσα σε μια δραστηριότητα.

Ενώ η ροή εργασίας συντονίζει, η δραστηριότητα εκτελεί. Αυτή είναι η θεμελιώδης διάκριση και έχει μια άμεση συνέπεια: επειδή η επικίνδυνη εργασία απομονώνεται εντός των δραστηριοτήτων, ο μηχανισμός μπορεί να κάνει επαναδοκιμές, μετρήσεις και επαναλήψεις χωρίς ποτέ να διπλασιάζει τις παρενέργειες.

Ανατομία μιας Δραστηριότητας

Μια δραστηριότητα είναι μια Python async συνάρτηση διακοσμημένη με @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()

Τέσσερα στοιχεία σε αυτές τις λίγες γραμμές αξίζουν την προσοχή σας. Ο διακοσμητής @workflows.activity() καταχωρίζει τη συνάρτηση ως δραστηριότητα στον μηχανισμό, καθιστώντας την καλέσιμη από μια ροή εργασίας. Το async def είναι υποχρεωτικό: όλες οι δραστηριότητες πρέπει να είναι ασύγχρονες, χωρίς εξαίρεση. Οι παράμετροι πρέπει να είναι JSON-serializable, που σημαίνει απλοί τύποιι—str, int, float, bool, list, dict—ή μοντέλα Pydantic· η μετάδοση ενός αντικειμένου σύνδεσης ή ενός χειριστή αρχείου ως όρισμα θα αποτύχει κατά τη σειριοποίηση. Ο ίδιος κανόνας ισχύει και για την τιμή επιστροφής, η οποία ταξιδεύει μέσω του δικτύου πριν εγγραφεί στο αρχείο συμβάντων.

Παραδείγματα Συγκεκριμένων Δραστηριοτήτων

Η πρώτη περίπτωση, πιθανότατα η πιο συχνή σε αυτό το μάθημα, περικλείει μια κλήση σε ένα μοντέλο Mistral. Σημειώστε ότι η δραστηριότητα επιστρέφει επίσης την κατανάλωση tokens: μόλις βρεθεί στο αρχείο καταγραφής, αυτό το είδος μεταδεδομένων σάς επιτρέπει να ανακατασκευάσετε το κόστος μιας εκτέλεσης εκ των υστέρων.

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
    }

Η δεύτερη περίπτωση απεικονίζει την πρόσβαση σε βάση δεδομένων. Το μπλοκ try/finally δεν είναι διακοσμητικό: εάν η δραστηριότητα αποτύχει και γίνει επαναδοκιμή, το να αφήνετε μια σύνδεση ανοιχτή σε κάθε προσπάθεια θα εξαντλήσει γρήγορα το pool της 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()

Η τρίτη περίπτωση, η αποστολή email, είναι εκεί όπου οι παρενέργειες είναι πιο ορατές: μόλις σταλεί το μήνυμα, καμία επαναδοκιμή δεν μπορεί να το ανακαλέσει.

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}

Βασικά Χαρακτηριστικά

Πρώτον, μια ευπρόσδεκτη ελευθερία: σε αντίθεση με τις ροές εργασίας, οι δραστηριότητες δεν έχουν περιορισμούς ντετερμινισμού. Μπορείτε ελεύθερα να χρησιμοποιήσετε datetime.now(), uuid.uuid4(), random.random() ή οποιαδήποτε άλλη μη ντετερμινιστική κλήση μέσα σε μια δραστηριότητα. Αυτό ακριβώς είναι ο σκοπός των δραστηριοτήτων—να απορροφούν ό,τι η ροή εργασίας δεν επιτρέπεται να κάνει.

Η πλατφόρμα στη συνέχεια αντιμετωπίζει κάθε κλήση δραστηριότητας ως ατομική μονάδα: είτε succeeds (πετυχαίνει) πλήρως είτε fails (αποτυγχάνει) πλήρως, χωρίς ενδιάμεση κατάσταση ορατή στη ροή εργασίας. Εάν η δραστηριότητά σας κάνει τρία πράγματα και το δεύτερο καταρρεύσει, η ροή εργασίας βλέπει μόνο μια αποτυχία, όχι μερική επιτυχία. Γι’ αυτόν τον λόγο πρέπει να αποφεύγετε να στοιβάζετε πέντε διακριτές λειτουργίες σε μια μόνο συνάρτηση.

Μόλις μια δραστηριότητα ολοκληρωθεί επιτυχώς, το αποτέλεσμά της καταγράφεται μόνιμα στο αρχείο συμβάντων της ροής εργασίας. Κατά τη διάρκεια μιας επανάληψης (replay), η δραστηριότητα δεν εκτελείται ποτέ ξανά: χρησιμοποιείται μόνο το καταγεγραμμένο αποτέλεσμα. Σε αντάλλαγμα, επειδή μια δραστηριότητα μπορεί να υποβληθεί σε επαναδοκιμή σε περίπτωση αποτυχίας (χρονικό όριο δικτύου, παροδικό σφάλμα), πρέπει να είναι idempotent: εκτελούμενη πολλές φορές με τις ίδιες παραμέτρους, πρέπει να παράγει το ίδιο αποτέλεσμα. Η μετάβαση από ένα POST σε ένα PUT σε ένα σταθερό αναγνωριστικό συχνά αρκεί για να επιτευχθεί αυτή η ιδιότητα, όπως εδώ όπου το email serves ως κλειδί:

@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()

Ονομασία μιας Δραστηριότητας

Ο διακοσμητής δέχεται ένα ρητό όνομα, το οποίο βελτιώνει σημαντικά την αναγνωσιμότητα της ιχνηλασιμότητας όταν μια τεχνική συνάρτηση φέρει ένα αγγλικό όνομα που κανείς άλλος στην ομάδα δεν συνδέει με τον επιχειρηματικό τομέα:

@workflows.activity(name="Process Customer Emails")
async def process_customer_emails(batch_id: str) -> dict:
    # ...
    pass

Αυτό το όνομα θα εμφανίζεται στα ίχνη OpenTelemetry και θα διευκολύνει την αποσφαλμάτωση. Κάντε το συνήθεια να το ορίζετε από την αρχή: την ημέρα που θα ψάχνετε να βρείτε γιατί μια εκτέλεση πήρε σαράντα λεπτά, θα διαβάζετε εύλογες ετικέτες αντί για μια λίστα ονομάτων συναρτήσεων.

Περιορισμοί Μεγέθους

Δύο όρια διέπουν τις ανταλλαγές: μέγιστο 2 MB για τις παραμέτρους εισόδου και μέγιστο 2 MB για την τιμή επιστροφής. Αυτά προκύπτουν άμεσα από το event sourcing, καθώς αυτές οι τιμές σειριοποιούνται και αποθηκεύονται στο αρχείο καταγραφής.

Η πρακτική συνέπεια είναι ξεκάθαρη. Εάν χρειάζεται να επεξεργαστείτε μεγάλα αρχεία—ένα σαρωμένο PDF 40 MB, ένα αρχείο εξαγωγής—μην τα περνάτε από δραστηριότητα σε δραστηριότητα. Αποθηκεύστε τα σε μια εξωτερική υπηρεσία (S3, GCS) και κυκλοφορήστε μόνο το URL ή το αναγνωριστικό: η δραστηριότητα κατεβάζει το αρχείο, το επεξεργάζεται, γράφει το αποτέλεσμα πίσω στην αποθήκευση και επιστρέφει μια αναφορά μερικών εκατοντάδων bytes.

Βασικά σημεία

  • Μια δραστηριότητα είναι μια async συνάρτηση διακοσμημένη με @workflows.activity() που εκτελεί την πραγματική εργασία (I/O, API, DB)
  • Οι παράμετροι και οι τιμές επιστροφής πρέπει να είναι JSON-serializable
  • Οι δραστηριότητες δεν έχουν περιορισμούς ντετερμινισμού
  • Μια επιτυχής δραστηριότητα δεν εκτελείται ποτέ ξανά κατά τη διάρκεια μιας επανάληψης
  • Οι δραστηριότητες πρέπει να είναι idempotent (ίδιο αποτέλεσμα αν εκτελεστούν πολλές φορές)
  • Όριο 2 MB στην είσοδο και την έξοδο ανά δραστηριότητα