Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Vytvoření workflow

Lekce 5 z 14 Aktualizováno 2. listopadu 2026 Pokročilý
Na této stránce
  1. Role workflow
  2. Struktura workflow
  3. Kompletní příklad: zpracovatelský pipeline
  4. Odolnost workflow
  5. Workflow s podmíněným větvením
  6. Vstupy s Pydantic
  7. Doporučené postupy
  8. Klíčové poznatky

Role workflow

Workflow představuje vrstvu orchestrace tvé aplikace. Definuje, co se má stát, v jakém pořadí a za jakých podmínek – samotnou práci však neprovádí. Konkrétně koordinuje aktivity, čeká na externí události, spravuje časovače a podmíněné větve, ale nikdy přímo nekomunikuje se sítí ani diskem.

Můžeš si to shrnout do jedné věty, kterou měj na paměti při každé revizi kódu: aktivity vykonávají práci, workflow ji řídí. Pokud uvnitř třídy workflow vidíš httpx nebo open(), něco je potřeba přesunout.

Struktura workflow

Workflow je třída v Pythonu ozdobená dekorátorem @workflows.workflow.define(), která obsahuje vstupní metodu označenou dekorátorem @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

Dekorátor @workflows.workflow.define(name="...") registruje třídu jako workflow. Parametr name, který přijímá, je unikátní identifikátor, který použiješ ke spuštění exekuce – právě tento řetězec, nikoliv název Python třídy, vidí volající strana. Dekorátor @workflows.workflow.entrypoint označuje metodu volanou při startu. Prvním parametrem zůstává self, tedy instance třídy, jako u každého Python objektu, a každé volání aktivity používá klíčové slovo await.

Kompletní příklad: zpracovatelský pipeline

Zde je realistické workflow, které orchestruje více aktivit pro zpracování dokumentu. Všimni si rozdělení práce: tři funkce nahoře obsahují veškerý kód, který komunikuje s vnějším světem, zatímco třída dole pouze řetězí volání await a sestavuje výsledek.

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ždé await ve workflow představuje bod perzistence. Stojí za to si to u výše uvedeného příkladu mentálně ověřit: pokud proces selže mezi krokem 2 a krokem 3, dokument se znovu nestáhne a model se znovu nevyvolá – žádné dodatečné poplatky za tokeny. Workflow se obnoví přímo v kroku ukládání.

Odolnost workflow

Workflow přežijí restarty, selhání infrastruktury a přechodné chyby, protože platforma zaznamenává každou událost a během přehrávání obnovuje stav workflow. Tato rekonstrukce je spolehlivá pouze za jedné podmínky, kterou jsme již zmínili: kód workflow musí pro stejné vstupy vždy produkovat stejnou sekvenci operací. Toto je omezení determinismu. Podrobnosti probereme v lekci 8.

Workflow s podmíněným větvením

Workflow není omezeno pouze na lineární sekvenci. Může obsahovat podmíněnou logiku, jako v tomto příkladu zpracování objednávky, kde cesta závisí na stavu skladu:

@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"}

Větve if/else jsou plně podporovány. Jediné omezení se týká materiálu použitého pro rozhodování: výsledek větve musí záviset na návratové hodnotě aktivity – hodnotě zaznamenané v logu a přehrané identicky – nikoliv na přímém volání externí služby z workflow. Zde verifier_stock dotazuje inventář uvnitř aktivity a příkaz if čte pouze slovník, který byl již perzistentně uložen.

Vstupy s Pydantic

Workflow, které přijímá šest pozičních parametrů, se rychle stane nečitelným. Pro strukturované vstupy použij modely Pydantic, které navíc poskytují validaci typů na začátku exekuce:

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"]}

Jedna důležitá poznámka při spouštění tohoto workflow: když použiješ BaseModel, pole se stanou klíči nejvyšší úrovně v JSON vstupu zasílaném do workflow. Pošleš tedy {"type_rapport": ..., "date_debut": ...}, nikoliv objekt vnořený pod klíčem params.

Doporučené postupy

Čtyři návyky dělají z dlouhodobého hlediska rozdíl. Zaprvé, drž se jedné odpovědnosti na jedno workflow: míchání fakturace a sledování prodejů ve stejné třídě znemožňuje přehrát jedno bez druhého. Zadruhé, věnuj pozornost pojmenování, protože name workflow je veřejný identifikátor volaný z jiných systémů – "traitement_commande" je udržovatelné, "workflow_1" nikoliv. Zatřetí, nezaváděj do workflow žádné operace I/O: každé volání sítě, přístup k souboru nebo dotaz do databáze patří do aktivity. Nakonec udržuj kód workflow jednoduchý přesunem složité logiky – parsování, transformace, náročné výpočty – do aktivit, kde ji lze testovat izolovaně bez omezení determinismu.

Klíčové poznatky

  • Workflow je třída ozdobená @workflows.workflow.define(), která orchestruje aktivity
  • Metoda @workflows.workflow.entrypoint je vstupním bodem volaným při startu
  • Každé await aktivity je bodem perzistence (automatické obnovení při selhání)
  • Podmíněné větve a smyčky jsou podporovány
  • Pro strukturované vstupní parametry používej modely Pydantic
  • Workflow nesmí obsahovat žádné přímé operace I/O