Salt la conținutul principal
Română— Alege o limbă
Meniu

Crearea unui flux de lucru

Lecția 5 din 14 Actualizată 2 noiembrie 2026 Avansat
Pe această pagină
  1. Rolul fluxului de lucru
  2. Structura fluxului de lucru
  3. Exemplu complet: pipeline de procesare
  4. Durabilitatea fluxului de lucru
  5. Flux de lucru cu ramificare condițională
  6. Intrări cu Pydantic
  7. Cele mai bune practici
  8. Puncte cheie

Rolul fluxului de lucru

Fluxul de lucru reprezintă stratul de orchestrare al aplicației dumneavoastră. Acesta definește ce trebuie să se întâmple, în ce ordine și sub ce condiții, fără a executa efectiv munca. Concret, el coordonează activitățile, așteaptă evenimente externe, gestionează temporizatoare și ramuri condiționale, dar nu accesează niciodată rețeaua sau discul.

Puteți rezuma acest lucru într-o singură frază de reținut de fiecare dată când revizuiți codul: activitățile execută munca, fluxul de lucru dirijează. Dacă observați httpx sau open() în interiorul unei clase de flux de lucru, ceva trebuie mutat.

Structura fluxului de lucru

Un flux de lucru este o clasă Python decorată cu @workflows.workflow.define(), care conține o metodă de intrare decorată cu @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

Decoratorul @workflows.workflow.define(name="...") înregistrează clasa ca fiind un flux de lucru. name pe care îl primește este identificatorul unic pe care îl veți utiliza pentru a declanșa o execuție; acest șir de caractere, nu numele clasei Python, este ceea ce vede apelantul. Decoratorul @workflows.workflow.entrypoint marchează metoda apelată la pornire. Primul parametru, self, rămâne instanța clasei, ca în orice obiect Python, iar fiecare apel de activitate utilizează await.

Exemplu complet: pipeline de procesare

Iată un flux de lucru realist care orchestrează mai multe activități pentru a procesa un document. Observați diviziunea muncii: cele trei funcții din partea de sus conțin tot codul care interacționează cu lumea exterioară, în timp ce clasa din partea de jos lansează doar apeluri await și asamblează un rezultat.

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

Fiecare await din fluxul de lucru constituie un punct de persistență. Merită să verificați acest lucru mental cu exemplul de mai sus: dacă procesul eșuează între pasul 2 și pasul 3, documentul nu va fi redescărcat, iar modelul nu va fi apelat din nou, deci nu se vor genera costuri suplimentare de tokeni. Fluxul de lucru va relua execuția direct la pasul de salvare.

Durabilitatea fluxului de lucru

Fluxurile de lucru supraviețuiesc repornirilor, defecțiunilor de infrastructură și erorilor tranzitorii, deoarece platforma înregistrează fiecare eveniment și reconstruiește starea fluxului de lucru în timpul redării. Această reconstrucție este fiabilă doar sub o singură condiție, menționată anterior: codul fluxului de lucru trebuie să producă întotdeauna aceeași secvență de operațiuni pentru aceleași intrări. Aceasta este constrângerea de determinism. Vom aborda detaliile în lecția 8.

Flux de lucru cu ramificare condițională

Un flux de lucru nu se limitează la o secvență liniară. Acesta poate conține logică condițională, ca în acest exemplu de procesare a comenzilor, unde calea depinde de stocul disponibil:

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

Ramurile if/else sunt complet suportate. Singura constrângere privește materialul utilizat pentru decizie: rezultatul ramurii trebuie să depindă de valoarea returnată a unei activități – o valoare înregistrată în jurnal și redată identic – nu de un apel direct către un serviciu extern din fluxul de lucru. Aici, verifier_stock interoghează inventarul în cadrul unei activități, iar instrucțiunea if citește doar un dicționar care a fost deja persistat.

Intrări cu Pydantic

Un flux de lucru care primește șase parametri poziționali devine rapid ilizibil. Pentru intrări structurate, utilizați modele Pydantic, care oferă, de asemenea, validarea tipurilor la începutul execuției:

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

Un punct de atenție la declanșarea acestui flux de lucru: atunci când utilizați un BaseModel, câmpurile devin chei de nivel superior în intrarea JSON trimisă fluxului de lucru. Veți trimite {"type_rapport": ..., "date_debut": ...}, nu un obiect imbricat sub o cheie params.

Cele mai bune practici

Patru obiceiuri fac diferența pe termen lung. În primul rând, respectați o singură responsabilitate per flux de lucru: amestecarea facturării și a urmăririi vânzărilor în aceeași clasă face imposibilă redarea uneia fără cealaltă. În al doilea rând, acordați atenție denumirilor, deoarece name fluxului de lucru este un identificator public apelat din alte sisteme; "traitement_commande" este ușor de întreținut, "workflow_1" nu este. Nu introduceți nicio operațiune I/O în fluxul de lucru: fiecare apel de rețea, acces la fișier sau interogare de bază de date aparține unei activități. În final, mențineți codul fluxului de lucru simplu, delegând logica complexă – analiză sintactică, transformări, calcule intensive – către activități, unde poate fi testată izolat, fără constrângeri de determinism.

Puncte cheie

  • Un flux de lucru este o clasă decorată cu @workflows.workflow.define() care orchestrează activități
  • Metoda @workflows.workflow.entrypoint este punctul de intrare apelat la pornire
  • Fiecare await al unei activități este un punct de persistență (reluare automată în caz de eșec)
  • Ramurile condiționale și buclele sunt suportate
  • Utilizați modele Pydantic pentru parametrii de intrare structurați
  • Fluxul de lucru nu trebuie să conțină nicio operațiune I/O directă