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

Oħloq ħaddiem

Lezzjoni 6 / 14 Aġġornat 29 ta’ Lulju 2026 Avvanzat
F'din il-paġna
  1. Ir-rwol tal-ħaddiem
  2. Oħloq ħaddiem minimu
  3. X’jagħmel run_worker()
  4. Ħaddiem b’ħafna flussi tax-xogħol
  5. Struttura tal-fajls rakkomandata
  6. Ibda l-ħaddiem
  7. Il-ħaddiem fil-produzzjoni
  8. Punti Ewlenin

Ir-rwol tal-ħaddiem

Il-ħaddiem huwa l-proċess Python li attwalment jesegwixxi l-flussi tax-xogħol u l-attivitajiet tiegħek. Dan jikkonnettja mal-pjattaforma Mistral, jisma’ għal kompiti pendenti, u jmexxihom lokalment fuq il-magna jew is-server tiegħek. Dan id-dettall arkitettoniku spiss jissorpriża lil dawk li għadhom kemm bdew: il-kodiċi tiegħek qatt ma jitlaq mill-ambjent tiegħek; biss l-istat tal-orkestrazzjoni jibqa’ ma’ Mistral.

L-implikazzjoni hija diretta u tispjega l-biċċa l-kbira tal-problemi ta’ “xejn ma qed jiġri” li jiltaqgħu magħhom fil-bidu ta’ proġett: mingħajr ħaddiem li qed jaħdem, il-flussi tax-xogħol tiegħek ma jistgħux jiġu eżegwiti. Tista’ tniedi eżekuzzjoni, iżda din sempliċiment tibqa’ tistenna sakemm jidher ħaddiem kapaċi. Il-ħaddiem huwa r-rabta bejn il-pjattaforma ta’ orkestrazzjoni Mistral u l-kodiċi lokali tiegħek.

Oħloq ħaddiem minimu

Ħaddiem funzjonali jidħol f’ftit linji biss. L-eżempju hawn taħt jgħaqqad b’mod intenzjonat l-attività, il-fluss tax-xogħol, u l-loġika tal-bidu f’fajl wieħed sabiex tkun tista’ tħaddmu minnufih:

import asyncio
import mistralai.workflows as workflows

# Import your workflows and activities
@workflows.activity()
async def dire_bonjour(nom: str) -> dict:
    return {"message": f"Bonjour, {nom} !"}

@workflows.workflow.define(name="salutation_workflow")
class SalutationWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, nom: str) -> dict:
        resultat = await dire_bonjour(nom)
        return resultat

# Start the worker
async def main() -> None:
    await workflows.run_worker([SalutationWorkflow])

if __name__ == "__main__":
    asyncio.run(main())

Il-funzjoni ewlenija hija workflows.run_worker(). Din tieħu lista ta’ klassijiet ta’ flussi tax-xogħol li dan il-ħaddiem jista’ jesegwixxi—u biss flussi tax-xogħol. L-attivitajiet jiġu skoperti permezz tagħhom, allura m’għandekx bżonn telenka l-attivitajiet separatament.

X’jagħmel run_worker()

Meta ssejjaħ workflows.run_worker([MyWorkflow]), iseħħu ħames affarijiet f’sekwenza. L-ewwel, il-ħaddiem jawtentika ruħu mal-pjattaforma Mistral bl-użu taċ-ċavetta API tiegħek. Imbagħad, jirreġistra l-flussi tax-xogħol u l-attivitajiet iddikjarati. Din ir-reġistrazzjoni tgħarraf lill-pjattaforma li jeżisti eżekutur għall-identifikatur salutation_workflow. Sussegwentement, tiftaħ konnessjoni persistenti u tistenna għal kompiti, tibqa’ intenzjonalment idle sakemm tiġi nnidata eżekuzzjoni. Meta tasal eżekuzzjoni, il-ħaddiem iħaddem il-kodiċi lokalment, u r-riżultati jintbagħtu lura lill-pjattaforma għall-persistenza.

Il-ħaddiem jibqa’ attiv sakemm il-proċess Python ikun qed jaħdem, għalhekk qatt ma jerġa’ jagħti l-kontroll lit-terminal tiegħek. Uża Ctrl+C biex twaqqfu b’mod nadif.

Ħaddiem b’ħafna flussi tax-xogħol

Xejn ma jeħtieġ ħaddiem wieħed għal kull fluss tax-xogħol. Proċess wieħed jista’ jospita flussi tax-xogħol multipli, anke meta jaqsmu l-attivitajiet. Hawnhekk, extraire_texte u analyser_sentiment iservu lit-tnejn:

import asyncio
import mistralai.workflows as workflows

# --- Activities ---

@workflows.activity()
async def extraire_texte(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
    return {"texte": response.text}

@workflows.activity()
async def analyser_sentiment(texte: str) -> dict:
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "Analysez le sentiment : positif, négatif ou neutre."},
            {"role": "user", "content": texte}
        ]
    )
    return {"sentiment": response.choices[0].message.content}

@workflows.activity()
async def envoyer_alerte(message: str) -> dict:
    # Envoi vers Slack, email, etc.
    return {"status": "envoyé"}

# --- Workflows ---

@workflows.workflow.define(name="analyse_document")
class DocumentAnalysis:
    @workflows.workflow.entrypoint
    async def run(self, url: str) -> dict:
        extraction = await extraire_texte(url)
        sentiment = await analyser_sentiment(extraction["texte"])
        return sentiment

@workflows.workflow.define(name="surveillance_mentions")
class MentionMonitoring:
    @workflows.workflow.entrypoint
    async def run(self, url: str, seuil: str) -> dict:
        extraction = await extraire_texte(url)
        sentiment = await analyser_sentiment(extraction["texte"])
        if sentiment["sentiment"] == "négatif":
            await envoyer_alerte(f"Mention négative détectée : {url}")
        return sentiment

# --- Worker ---

async def main() -> None:
    await workflows.run_worker([
        DocumentAnalysis,
        MentionMonitoring,
    ])

if __name__ == "__main__":
    asyncio.run(main())

Struttura tal-fajls rakkomandata

Fajl wieħed jaħdem għat-tagħlim, iżda mhux għal proġett ħaj. Għall-produzzjoni, ifred il-kodiċi tiegħek f’moduli skont it-tip:

mon-projet/
├── activities/
│   ├── __init__.py
│   ├── extraction.py      # extraire_texte()
│   ├── analyse.py          # analyser_sentiment()
│   └── notifications.py    # envoyer_alerte()
├── workflows/
│   ├── __init__.py
│   ├── analyse_document.py
│   └── surveillance.py
└── worker.py               # Single entry point

Il-fajl worker.py imbagħad ikun fih biss imports u loġika tal-bidu, u jagħmlu inventarju leġibbli ta’ x’jista’ jesegwixxi dan il-proċess:

import asyncio
import mistralai.workflows as workflows

from workflows.document_analysis import DocumentAnalysis
from workflows.monitoring import MentionMonitoring

async def main() -> None:
    await workflows.run_worker([
        DocumentAnalysis,
        MentionMonitoring,
    ])

if __name__ == "__main__":
    asyncio.run(main())

Ibda l-ħaddiem

uv run python worker.py

Il-ħaddiem juri messaġġ ta’ konnessjoni u jibqa’ attiv, jistenna għal kompiti. Għandek tara xi ħaġa bħal din:

Worker connected. Listening for tasks...

Sa ma tidher din il-linja, ma tniedi xejn. L-ewwel, iċċekkja ċ-ċavetta API tiegħek u l-konnessjoni tan-network.

Il-ħaddiem fil-produzzjoni

Ħaddiem imniedi manwalment f’terminal jisparixxi wara l-ewwel diskonnessjoni SSH. Fdahlu lil maniġer tal-proċessi—systemd, supervisor, jew pm2—li awtomatikament jerġa’ jibdieh wara ħsara jew riavvju:

# With pm2 (if Node.js is available)
pm2 start "uv run python worker.py" --name workflow-worker

# With systemd (create a .service file)

Dan ir-riavvju awtomatiku jmur tajjeb mad-durabbiltà: il-flussi tax-xogħol li qed jaħdmu jerġgħu jibdew waħedhom hekk kif il-proċess il-ġdid jikkonnettja. Fir-rigward tas-sigrieti, qatt ma tikteb iċ-ċavetta API b’mod iebsor fil-fajl tal-ħaddiem, inkella tispiċċa fir-repożitorju Git tiegħek. L-SDK jaqra l-varjabbli tal-ambjent awtomatikament:

import os

# The SDK automatically reads MISTRAL_API_KEY
# No need to pass it explicitly

Fl-aħħar nett, ikkunsidra l-logging. Il-ħaddiem jemetti messaġġi permezz tal-modulu standard logging ta’ Python. Konfigurazzjoni sempliċi fil-bidu tagħtik traċċa tal-attivitajiet eżegwiti, li hija prezzjuża biex tifhem x’kien qed jaħdem waqt inċident:

import logging
logging.basicConfig(level=logging.INFO)

Punti Ewlenin

  • Il-ħaddiem huwa l-proċess li jesegwixxi l-flussi tax-xogħol u l-attivitajiet tiegħek lokalment
  • workflows.run_worker([...]) tieħu lista ta’ klassijiet ta’ flussi tax-xogħol biex jiġu eżegwiti
  • Ħaddiem wieħed jista’ jesegwixxi flussi tax-xogħol differenti multipli
  • Il-ħaddiem jibqa’ attiv u jisma’ għal kompiti sakemm il-proċess ikun qed jaħdem
  • Fil-produzzjoni, uża maniġer tal-proċessi biex iżżomm il-ħaddiem jaħdem
  • Iċ-ċavetta API tinqara awtomatikament minn MISTRAL_API_KEY