Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Oħloq workflow

Lezzjoni 5 / 14 Aġġornat 2 ta’ Novembru 2026 Avvanzat
F'din il-paġna
  1. Ir-rwol tal-workflow
  2. L-istruttura tal-workflow
  3. Eżempju sħiħ: pipeline ta’ ipproċessar
  4. Id-durabbiltà tal-workflow
  5. Workflow b’fergħat kondizzjonali
  6. Inputs b’Pydantic
  7. L-aħjar prattiki
  8. Punti Ewlenin

Ir-rwol tal-workflow

Il-workflow huwa s-saff ta’ orkestrazzjoni tal-applikazzjoni tiegħek. Jiddefinixxi x’għandu jiġri, f’liema ordni, u taħt liema kundizzjonijiet—mingħajr ma jeżegwixxi x-xogħol innifsu. Konkretament, jikkoordina l-attivitajiet, jistenna avvenimenti esterni, jimmaniġġja timers u fergħat kondizzjonali, iżda qatt ma jmiss in-network jew id-disk.

Tista’ tgħaqqad dan f’frażi waħda biex iżżomm f’moħħok kull darba li tirrevedi l-kodiċi: l-attivitajiet jagħmlu x-xogħol, il-workflow jidderieġi. Jekk tara httpx jew open() ġewwa klassi ta’ workflow, hemm xi ħaġa li trid tiġi mċaqalqa.

L-istruttura tal-workflow

Workflow huwa klassi Python imżejna b’@workflows.workflow.define(), li fiha metodu ta’ dħul imżejjen b’@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

Id-dekoratur @workflows.workflow.define(name="...") jirreġistra l-klassi bħala workflow. L-name li jirċievi huwa l-identifikatur uniku li se tuża biex tħaffer eżekuzzjoni—din l-istringa, mhux l-isem tal-klassi Python, hija dak li jara s-sejjaħ. Id-dekoratur @workflows.workflow.entrypoint jimmarka l-metodu msejjaħ fil-bidu. L-ewwel parametru, self, jibqa’ l-istanza tal-klassi, bħal f’kull oġġett Python, u kull sejħa ta’ attività tuża await.

Eżempju sħiħ: pipeline ta’ ipproċessar

Hawnhekk hemm workflow realistiku li jorkestra attivitajiet multipli biex jipproċessa dokument. Innota d-diviżjoni tax-xogħol: it-tliet funzjonijiet fil-quċċata fihom il-kodiċi kollu li jmiss id-dinja ta’ barra, filwaqt li l-klassi fil-qiegħ sempliċiment tgħaqqad sejħiet await u jfassal riżultat.

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

Kull await fil-workflow jikkostitwixxi punt ta’ persistenza. Jiswa li tivverifika dan mentalment bl-eżempju ta’ hawn fuq: jekk il-proċess ifalli bejn il-pass 2 u l-pass 3, id-dokument ma jerġax jitniżżel u l-mudell ma jerġax jissejjaħ—għalhekk l-ebda ħlas addizzjonali ta’ tokens. Il-workflow jerġa’ jibda direttament fil-pass tas-salvataġġ.

Id-durabbiltà tal-workflow

Il-workflows jibqgħu ħajjin wara restarts, fallimenti fl-infrastruttura, u żbalji tranżitorji għax il-pjattaforma tirreġistra kull avveniment u terġa’ tibni l-istat tal-workflow waqt ir-replay. Din ir-rikostruzzjoni hija affidabbli biss taħt kundizzjoni waħda, imsemmija qabel: il-kodiċi tal-workflow irid dejjem jipproduċi l-istess sekwenza ta’ operazzjonijiet għall-istess inputs. Din hija r-restrizzjoni tad-determiniżmu. Se nkopru d-dettalji fil-lezzjoni 8.

Workflow b’fergħat kondizzjonali

Workflow mhux limitat għal sekwenza lineari. Jista’ jkun fih loġika kondizzjonali, bħal f’dan l-eżempju ta’ ipproċessar ta’ ordni fejn il-mogħdija tiddependi mill-istatus tal-istokk:

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

Il-fergħat if/else huma appoġġjati bis-sħiħ. L-unika restrizzjoni tikkonċerna l-materjal użat għad-deċiżjoni: ir-riżultat tal-fergħa jrid jiddependi mill-valur ta’ ritorn ta’ attività—valur irreġistrat fil-log u rreplikat bl-istess mod—mhux fuq sejħa diretta għal servizz estern mill-workflow. Hawnhekk, verifier_stock jistaqsi l-inventarju ġewwa attività, u l-istatement if jaqra biss dizzjunarju li diġà ġie ppersistit.

Inputs b’Pydantic

Workflow li jieħu sitt parametri pożizzjonali malajr isir mhux leġibbli. Għal inputs strutturati, uża mudelli Pydantic, li jipprovdu wkoll validazzjoni tat-tip fil-bidu tal-eżekuzzjoni:

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

Punt ta’ kawtela meta tħaffer dan il-workflow: meta tuża BaseModel, il-kampijiet isiru ċwievet ta’ livell għoli fl-input JSON mibgħut lill-workflow. Se tibgħat {"type_rapport": ..., "date_debut": ...}, mhux oġġett innestjat taħt ċavetta params.

L-aħjar prattiki

Erba’ drawwiet jagħmlu differenza fit-tul. L-ewwel, imxi ma’ responsabbiltà waħda għal kull workflow: it-taħlit tal-fatturazzjoni u s-segwitu tal-bejgħ fl-istess klassi jagħmilha impossibbli li terġa’ tgħaddi wieħed mingħajr l-ieħor. Imbagħad, agħti attenzjoni lit-tismija, peress li l-name tal-workflow huwa identifikatur pubbliku msejjaħ minn sistemi oħra—"traitement_commande" huwa manutenibbli, "workflow_1" mhux. Mintroduċi l-ebda I/O fil-workflow: kull sejħa tan-network, aċċess għall-fajls, jew mistoqsija tad-database tappartjeni għal attività. Fl-aħħar, żomm il-kodiċi tal-workflow sempliċi billi tħalli loġika kumplessa—parsing, trasformazzjonijiet, kalkoli tqal—lill-attivitajiet, fejn tista’ tiġi ttestjata b’mod iżolat mingħajr restrizzjonijiet ta’ determiniżmu.

Punti Ewlenin

  • Workflow huwa klassi mżejna b’@workflows.workflow.define() li torkestra attivitajiet
  • Il-metodu @workflows.workflow.entrypoint huwa l-punt ta’ dħul imsejjaħ fil-bidu
  • Kull await ta’ attività huwa punt ta’ persistenza (rikupru awtomatiku fil-każ ta’ falliment)
  • Fergħat kondizzjonali u loops huma appoġġjati
  • Uża mudelli Pydantic għal parametri ta’ input strutturati
  • Il-workflow m’għandux ikun fih l-ebda operazzjoni diretta ta’ I/O