Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Vytvorenie workflow

Lekcia 5 z 14 Aktualizované 2. novembra 2026 Pokročilý
Na tejto strane
  1. Úloha workflow
  2. Štruktúra workflow
  3. Kompletný príklad: spracovateľský pipeline
  4. Odolnosť workflow
  5. Workflow s podmieneným vetvením
  6. Vstupy s Pydantic
  7. Osvedčené postupy
  8. Kľúčové poznatky

Úloha workflow

Workflow predstavuje vrstvu orchestrácie tvojej aplikácie. Definuje, čo sa má stať, v akom poradí a za akých podmienok – bez toho, aby samotnú prácu vykonávalo. Konkrétne koordinuje aktivity, čaká na externé udalosti, spravuje časovače a podmienené vetvy, ale nikdy nepristupuje priamo k sieti ani disku.

Môžeš si to zhrnúť do jednej vety, ktorú si zapamätaj pri každej kontrole kódu: aktivity vykonávajú prácu, workflow ju riadi. Ak v triede workflow uvidíš httpx alebo open(), niečo musíš presunúť.

Štruktúra workflow

Workflow je Python trieda označená dekorátorom @workflows.workflow.define(), ktorá obsahuje vstupnú metódu označenú @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 triedu ako workflow. Parameter name, ktorý dostáva, je jedinečný identifikátor, ktorý použiješ na spustenie vykonania – práve tento reťazec, nie názov Python triedy, vidí volajúci. Dekorátor @workflows.workflow.entrypoint označuje metódu, ktorá sa volá pri štarte. Prvým parametrom zostáva self, čo je inštancia triedy ako pri každom Python objekte, a každé volanie aktivity používa await.

Kompletný príklad: spracovateľský pipeline

Tu je realistické workflow, ktoré orchestruje viacero aktivít na spracovanie dokumentu. Všimni si rozdelenie práce: tri funkcie hore obsahujú všetok kód, ktorý komunikuje s externým svetom, zatiaľ čo trieda dole iba reťazí volania await a zostavuje výsledok.

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 vo workflow predstavuje bod perzistencie. Stojí za to si to overiť v mysli na vyššie uvedenom príklade: ak proces zlyhá medzi krokom 2 a krokom 3, dokument sa znova nestiahne a model sa znova nevyvolá – žiadne dodatočné náklady za tokeny. Workflow sa obnoví priamo v kroku ukladania.

Odolnosť workflow

Workflow prežijú reštarty, zlyhania infraštruktúry a prechodné chyby, pretože platforma zaznamenáva každú udalosť a počas opätovného prehrávania obnoví stav workflow. Táto rekonštrukcia je spoľahlivá len za jednej podmienky, ktorú sme spomenuli skôr: kód workflow musí vždy produkovať rovnakú postupnosť operácií pre rovnaké vstupy. Toto je obmedzenie determinizmu. Podrobnosti si preberieme v lekcii 8.

Workflow s podmieneným vetvením

Workflow nie je obmedzené len na lineárnu postupnosť. Môže obsahovať podmienenú logiku, ako v tomto príklade spracovania objednávky, kde cesta závisí od stavu zásob:

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

Vetvy if/else sú plne podporované. Jediné obmedzenie sa týka materiálu použitého na rozhodovanie: výsledok vetvy musí závisieť od návratovej hodnoty aktivity – hodnoty zaznamenanej v logu a identicky prehranej – nie od priameho volania externej služby z workflow. Tu verifier_stock dopytuje inventár v rámci aktivity a príkaz if číta iba slovník, ktorý už bol perzistentne uložený.

Vstupy s Pydantic

Workflow, ktoré prijíma šesť pozičných parametrov, sa rýchlo stane nečitateľným. Pre štruktúrované vstupy používaj modely Pydantic, ktoré zároveň poskytujú validáciu typov na začiatku vykonávania:

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 pri spúšťaní tohto workflow: keď použiješ BaseModel, polia sa stanú kľúčmi najvyššej úrovne v JSON vstupe odoslanom do workflow. Odošleš {"type_rapport": ..., "date_debut": ...}, nie objekt vnorený pod kľúčom params.

Osvedčené postupy

Štyri návyky robia v dlhodobom horizonte rozdiel. Po prvé, dodržuj jednu zodpovednosť na jedno workflow: miešanie fakturácie a následnej starostlivosti o predaj v tej istej triede znemožňuje opätovné prehratie jednej časti bez druhej. Ďalej dbaj na pomenovanie, keďže name workflow je verejný identifikátor volaný z iných systémov – "traitement_commande" je udržateľné, "workflow_1" nie. Nezavádzaj do workflow žiadne operácie I/O: každé volanie siete, prístup k súboru alebo dopyt do databázy patrí do aktivity. Nakoniec udržuj kód workflow jednoduchý presunutím komplexnej logiky – parsingu, transformácií, náročných výpočtov – do aktivít, kde ju možno testovať izolovane bez obmedzení determinizmu.

Kľúčové poznatky

  • Workflow je trieda označená dekorátorom @workflows.workflow.define(), ktorá orchestruje aktivity
  • Metóda @workflows.workflow.entrypoint je vstupným bodom volaným pri štarte
  • Každé await aktivity je bodom perzistencie (automatické obnovenie pri zlyhaní)
  • Podmienené vetvy a cykly sú podporované
  • Na štruktúrované vstupné parametre používaj modely Pydantic
  • Workflow nesmie obsahovať žiadne priame operácie I/O