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

Tworzenie przepływu pracy

Lekcja 5 z 14 Zaktualizowano 2 listopada 2026 Zaawansowany
Na tej stronie
  1. Rola przepływu pracy
  2. Struktura przepływu pracy
  3. Pełny przykład: potok przetwarzania
  4. Trwałość przepływu pracy
  5. Przepływ pracy z rozgałęzieniami warunkowymi
  6. Dane wejściowe z Pydantic
  7. Najlepsze praktyki
  8. Kluczowe wnioski

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.entrypoint to punkt wejścia wywoływany przy starcie
  • Każde await aktywnoś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