Tworzenie przepływu pracy
Na tej stronie
Rola przepływu pracy
Przepływ pracy to warstwa orkiestracji Twojej aplikacji. Definiuje, co musi się wydarzyć, w jakiej kolejności i pod jakimi warunkami – nie wykonując przy tym samej pracy. Konkretnie: koordynuje aktywności, oczekuje na zdarzenia zewnętrzne, zarządza timerami i gałęziami warunkowymi, ale nigdy nie dotyka sieci ani dysku.
Możesz to podsumować jednym zdaniem, które warto pamiętać przy każdej recenzji kodu: aktywności wykonują pracę, przepływ pracy nią kieruje. Jeśli widzisz httpx lub open() wewnątrz klasy przepływu pracy, coś trzeba przenieść.
Struktura przepływu pracy
Przepływ pracy to klasa Pythona ozdobiona dekoratorem @workflows.workflow.define(), zawierająca metodę wejściową ozdobioną @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
Dekorator @workflows.workflow.define(name="...") rejestruje klasę jako przepływ pracy. Przekazany parametr name to unikalny identyfikator, którego użyjesz do uruchomienia wykonania – to ten ciąg znaków, a nie nazwa klasy Pythona, widzi wywołujący. Dekorator @workflows.workflow.entrypoint oznacza metodę wywoływaną przy starcie. Pierwszy parametr, self, pozostaje instancją klasy, jak w każdym obiekcie Pythona, a każde wywołanie aktywności używa await.
Pełny przykład: potok przetwarzania
Oto realistyczny przepływ pracy, który orkiestruje wiele aktywności w celu przetworzenia dokumentu. Zwróć uwagę na podział obowiązków: trzy funkcje na górze zawierają cały kod stykający się ze światem zewnętrznym, podczas gdy klasa na dole jedynie łączy wywołania await i składa wynik.
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"]
}
Każde await w przepływie pracy stanowi punkt trwałości. Warto to zweryfikować mentalnie na powyższym przykładzie: jeśli proces ulegnie awarii między krokiem 2 a 3, dokument nie zostanie pobrany ponownie, a model nie zostanie wywołany jeszcze raz – więc nie poniesiesz dodatkowych opłat za tokeny. Przepływ pracy wznowi działanie bezpośrednio od kroku zapisu.
Trwałość przepływu pracy
Przepływy pracy przetrwają restarty, awarie infrastruktury i błędy przejściowe, ponieważ platforma rejestruje każde zdarzenie i odtwarza stan przepływu pracy podczas ponownego odtwarzania. To odtwarzanie jest niezawodne tylko pod jednym warunkiem, wspomnianym wcześniej: kod przepływu pracy musi zawsze generować tę samą sekwencję operacji dla tych samych danych wejściowych. To ograniczenie determinizmu. Szczegóły omówimy w lekcji 8.
Przepływ pracy z rozgałęzieniami warunkowymi
Przepływ pracy nie ogranicza się do sekwencji liniowej. Może zawierać logikę warunkową, jak w tym przykładzie przetwarzania zamówienia, gdzie ścieżka zależy od stanu magazynu:
@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"}
Gałęzie if/else są w pełni obsługiwane. Jedyne ograniczenie dotyczy materiału użytego do podjęcia decyzji: wynik gałęzi musi zależeć od wartości zwracanej przez aktywność – wartości zapisanej w dzienniku i odtwarzanej identycznie – a nie od bezpośredniego wywołania usługi zewnętrznej z poziomu przepływu pracy. Tutaj verifier_stock odpytuje stan magazynu wewnątrz aktywności, a instrukcja if odczytuje jedynie słownik, który został już utrwalony.
Dane wejściowe z Pydantic
Przepływ pracy przyjmujący sześć parametrów pozycyjnych szybko staje się nieczytelny. W przypadku strukturalizowanych danych wejściowych użyj modeli Pydantic, które zapewniają również walidację typów na początku wykonania:
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"]}
Jeden punkt ostrożności przy uruchamianiu tego przepływu pracy: gdy używasz BaseModel, pola stają się kluczami najwyższego poziomu w danych JSON wysyłanych do przepływu pracy. Wyślesz {"type_rapport": ..., "date_debut": ...}, a nie obiekt zagnieżdżony pod kluczem params.
Najlepsze praktyki
Cztery nawyki mają długoterminowe znaczenie. Po pierwsze, przestrzegaj zasady jednej odpowiedzialności na przepływ pracy: mieszanie rozliczeń i follow-upów sprzedażowych w tej samej klasie uniemożliwia ponowne odtworzenie jednego bez drugiego. Następnie zwracaj uwagę na nazewnictwo, ponieważ name przepływu pracy to publiczny identyfikator wywoływany z innych systemów – "traitement_commande" jest łatwe w utrzymaniu, "workflow_1" już nie. Nie wprowadzaj żadnego I/O w przepływie pracy: każde wywołanie sieciowe, dostęp do pliku czy zapytanie do bazy danych należy do aktywności. Na koniec utrzymuj kod przepływu pracy w prostocie, przenosząc złożoną logikę – parsowanie, transformacje, ciężkie obliczenia – do aktywności, gdzie może być testowana w izolacji bez ograniczeń determinizmu.
Kluczowe wnioski
- Przepływ pracy to klasa ozdobiona
@workflows.workflow.define(), która orkiestruje aktywności - Metoda
@workflows.workflow.entrypointto punkt wejścia wywoływany przy starcie - Każde
awaitaktywności to punkt trwałości (automatyczne wznowienie w przypadku awarii) - Rozgałęzienia warunkowe i pętle są obsługiwane
- Używaj modeli Pydantic do strukturalizowanych parametrów wejściowych
- Przepływ pracy nie może zawierać bezpośrednich operacji I/O