Δημιουργία ροής εργασίας
Σε αυτήν τη σελίδα
Ο ρόλος της ροής εργασίας
Η ροή εργασίας αποτελεί το επίπεδο ενορχήστρωσης της εφαρμογής σας. Ορίζει τι πρέπει να συμβεί, με ποια σειρά και υπό ποιες συνθήκες—χωρίς όμως να εκτελεί η ίδια το έργο. Συγκεκριμένα, συντονίζει δραστηριότητες, αναμένει εξωτερικά γεγονότα, διαχειρίζεται χρονοδιακόπτες και υπό συνθήκη διακλαδώσεις, αλλά δεν έρχεται ποτέ σε επαφή με το δίκτυο ή τον δίσκο.
Μπορείτε να συνοψίσετε αυτή την έννοια σε μία φράση που πρέπει να θυμάστε κάθε φορά που ελέγχετε κώδικα: οι δραστηριότητες εκτελούν το έργο, η ροή εργασίας δίνει τις κατευθύνσεις. Αν δείτε httpx ή open() μέσα σε μια κλάση ροής εργασίας, κάτι πρέπει να μετακινηθεί.
Δομή ροής εργασίας
Μια ροή εργασίας είναι μια κλάση Python διακοσμημένη με @workflows.workflow.define(), η οποία περιέχει μια μέθοδο εισόδου διακοσμημένη με @workflows.workflow.entrypoint:
import mistralai.workflows as workflows
@workflows.workflow.define(name="mon_premier_workflow")
class MonPremierWorkflow:
@workflows.workflow.entrypoint
async def run(self, nom: str) -> dict:
"""Workflow entry point."""
resultat = await saluer(nom)
return resultat
Ο διακοσμητής @workflows.workflow.define(name="...") καταχωρίζει την κλάση ως ροή εργασίας. Το name που λαμβάνει είναι το μοναδικό αναγνωριστικό που θα χρησιμοποιήσετε για να ενεργοποιήσετε μια εκτέλεση—αυτό το συμβολοσειρά, και όχι το όνομα της κλάσης Python, είναι αυτό που βλέπει ο καλών. Ο διακοσμητής @workflows.workflow.entrypoint σηματοδοτεί τη μέθοδο που καλείται κατά την εκκίνηση. Η πρώτη παράμετρος, self, παραμένει το στιγμιότυπο της κλάσης, όπως σε κάθε αντικείμενο Python, και κάθε κλήση δραστηριότητας χρησιμοποιεί await.
Πλήρες παράδειγμα: αγωγός επεξεργασίας
Ακολουθεί μια ρεαλιστική ροή εργασίας που ενορχηστρώνει πολλαπλές δραστηριότητες για την επεξεργασία ενός εγγράφου. Παρατηρήστε τον διαχωρισμό των αρμοδιοτήτων: οι τρεις συναρτήσεις στην κορυφή περιέχουν όλο τον κώδικα που αλληλεπιδρά με τον εξωτερικό κόσμο, ενώ η κλάση στο κάτω μέρος απλώς αλυσιδώνει κλήσεις await και συνθέτει ένα αποτέλεσμα.
import mistralai.workflows as workflows
from mistralai.client import Mistral
# --- Activities ---
@workflows.activity()
async def extraire_texte(url_document: str) -> dict:
"""Download and extract text from a document."""
async with httpx.AsyncClient() as client:
response = await client.get(url_document)
texte = response.text
return {"texte": texte, "longueur": len(texte)}
@workflows.activity()
async def analyser_avec_mistral(texte: str) -> dict:
"""Analyze text with Mistral to extract key points."""
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Extract the 5 key points from this text."},
{"role": "user", "content": texte}
]
)
return {"analyse": response.choices[0].message.content}
@workflows.activity()
async def sauvegarder_resultat(analyse: dict) -> dict:
"""Save the analysis result."""
async with httpx.AsyncClient() as client:
response = await client.post(
"https://api.example.com/rapports",
json=analyse
)
return {"id_rapport": response.json()["id"]}
# --- Workflow ---
@workflows.workflow.define(name="pipeline_analyse_document")
class PipelineAnalyseDocument:
@workflows.workflow.entrypoint
async def run(self, url_document: str) -> dict:
"""Orchestrate extraction, analysis, and saving."""
# Step 1: Extract text
extraction = await extraire_texte(url_document)
# Step 2: Analyze with Mistral
analyse = await analyser_avec_mistral(extraction["texte"])
# Step 3: Save
sauvegarde = await sauvegarder_resultat(analyse)
return {
"url_source": url_document,
"longueur_texte": extraction["longueur"],
"id_rapport": sauvegarde["id_rapport"]
}
Κάθε await στη ροή εργασίας αποτελεί ένα σημείο επιμονής. Αξίζει να το επαληθεύσετε νοητικά με το παραπάνω παράδειγμα: αν η διαδικασία αποτύχει μεταξύ του βήματος 2 και του βήματος 3, το έγγραφο δεν θα ληφθεί ξανά και το μοντέλο δεν θα κληθεί εκ νέου—επομένως, δεν θα υπάρξουν επιπλέον χρεώσεις tokens. Η ροή εργασίας θα επαναληφθεί απευθείας στο βήμα της αποθήκευσης.
Ανθεκτικότητα ροής εργασίας
Οι ροές εργασίας επιβιώνουν από επανεκκινήσεις, αστοχίες υποδομής και παροδικά σφάλματα, επειδή η πλατφόρμα καταγράφει κάθε γεγονός και ανακατασκευάζει την κατάσταση της ροής εργασίας κατά την επαναφορά. Αυτή η ανακατασκευή είναι αξιόπιστη μόνο υπό μία προϋπόθεση, που αναφέρθηκε νωρίτερα: ο κώδικας της ροής εργασίας πρέπει πάντα να παράγει την ίδια ακολουθία λειτουργιών για τις ίδιες εισόδους. Αυτός είναι ο περιορισμός της ντετερμινιστικότητας. Θα καλύψουμε τις λεπτομέρειες στο μάθημα 8.
Ροή εργασίας με υπό συνθήκη διακλάδωση
Μια ροή εργασίας δεν περιορίζεται σε μια γραμμική ακολουθία. Μπορεί να περιέχει λογική υπό συνθήκη, όπως σε αυτό το παράδειγμα επεξεργασίας παραγγελίας όπου η διαδρομή εξαρτάται από την κατάσταση του αποθέματος:
@workflows.workflow.define(name="traitement_commande")
class OrderProcessing:
@workflows.workflow.entrypoint
async def run(self, order: dict) -> dict:
# Check stock
stock = await check_stock(order["produit_id"])
if stock["disponible"]:
# Standard path
payment = await process_payment(order["montant"])
shipment = await prepare_shipment(order)
await send_confirmation(order["email"], shipment)
return {"status": "confirmée", "tracking": shipment["tracking"]}
else:
# Alternative path
await notify_stockout(order["email"], order["produit_id"])
return {"status": "rupture_stock"}
Οι διακλαδώσεις if/else υποστηρίζονται πλήρως. Ο μόνος περιορισμός αφορά το υλικό που χρησιμοποιείται για την απόφαση: το αποτέλεσμα της διακλάδωσης πρέπει να εξαρτάται από την τιμή επιστροφής μιας δραστηριότητας—μια τιμή που καταγράφεται στο αρχείο καταγραφής και επαναλαμβάνεται πανομοιότυπα—και όχι από μια άμεση κλήση σε εξωτερική υπηρεσία από τη ροή εργασίας. Εδώ, η verifier_stock ερωτά το απόθεμα εντός μιας δραστηριότητας και η εντολή if διαβάζει μόνο ένα λεξικό που έχει ήδη επιμείνει.
Είσοδοι με Pydantic
Μια ροή εργασίας που δέχεται έξι παραμέτρους θέσης γίνεται γρήγορα δυσανάγνωστη. Για δομημένες εισόδους, χρησιμοποιήστε μοντέλα Pydantic, τα οποία παρέχουν επίσης επικύρωση τύπων κατά την έναρξη της εκτέλεσης:
from pydantic import BaseModel
class ReportParams(BaseModel):
report_type: str
include_details: bool = False
start_date: str
end_date: str
@workflows.workflow.define(name="generation_rapport")
class ReportGeneration:
@workflows.workflow.entrypoint
async def run(self, params: ReportParams) -> dict:
data = await collect_data(params.report_type, params.start_date, params.end_date)
if params.include_details:
data = await enrich_data(data)
report = await generate_pdf_report(data)
return {"url_rapport": report["url"]}
Ένα σημείο προσοχής κατά την ενεργοποίηση αυτής της ροής εργασίας: όταν χρησιμοποιείτε ένα BaseModel, τα πεδία γίνονται κλειδιά ανώτατου επιπέδου στο JSON input που αποστέλλεται στη ροή εργασίας. Θα στείλετε {"type_rapport": ..., "date_debut": ...}, και όχι ένα αντικείμενο ενσωματωμένο κάτω από ένα κλειδί params.
Βέλτιστες πρακτικές
Τέσσερις συνήθειες κάνουν τη διαφορά μακροπρόθεσμα. Πρώτον, τηρήστε μία ευθύνη ανά ροή εργασίας: η ανάμειξη χρέωσης και παρακολούθησης πωλήσεων στην ίδια κλάση καθιστά αδύνατη την επαναφορά της μίας χωρίς την άλλη. Στη συνέχεια, δώστε προσοχή στην ονοματοδοσία, καθώς το name της ροής εργασίας είναι ένα δημόσιο αναγνωριστικό που καλείται από άλλα συστήματα—το "traitement_commande" είναι συντηρήσιμο, το "workflow_1" όχι. Μην εισάγετε καμία λειτουργία I/O στη ροή εργασίας: κάθε κλήση δικτύου, πρόσβαση αρχείου ή ερώτημα βάσης δεδομένων ανήκει σε μια δραστηριότητα. Τέλος, διατηρήστε τον κώδικα της ροής εργασίας απλό αναθέτοντας την πολύπλοκη λογική—ανάλυση, μετασχηματισμούς, βαρείς υπολογισμούς—στις δραστηριότητες, όπου μπορεί να ελεγχθεί μεμονωμένα χωρίς περιορισμούς ντετερμινιστικότητας.
Βασικά σημεία
- Μια ροή εργασίας είναι μια κλάση διακοσμημένη με
@workflows.workflow.define()που ενορχηστρώνει δραστηριότητες - Η μέθοδος
@workflows.workflow.entrypointείναι το σημείο εισόδου που καλείται κατά την εκκίνηση - Κάθε
awaitδραστηριότητας είναι ένα σημείο επιμονής (αυτόματη επανέναρξη σε περίπτωση αποτυχίας) - Υποστηρίζονται υπό συνθήκη διακλαδώσεις και βρόχοι
- Χρησιμοποιήστε μοντέλα Pydantic για δομημένες παραμέτρους εισόδου
- Η ροή εργασίας δεν πρέπει να περιέχει άμεσες λειτουργίες I/O