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

Installazzjoni tas-SDK tal-Workflows

Lezzjoni 3 / 14 Aġġornat 29 ta’ Lulju 2026 Avvanzat
F'din il-paġna
  1. Prerekwiżiti tekniċi
  2. Iċċekkja l-verżjoni ta’ Python tiegħek
  3. Installa uv
  4. Oħloq proġett
  5. Installa s-SDK tal-Workflows
  6. Ivverifika l-installazzjoni
  7. Ikkonfigura ċ-ċavetta tal-API tiegħek
  8. Scaffolding rapidu (għażlieni)
  9. Struttura tal-proġett irrakkomandata
  10. Punti Ewlenin

Prerekwiżiti tekniċi

Għandek bżonn erba’ affarijiet qabel ma tikteb l-ewwel linja ta’ kodiċi tal-workflow. L-ewwel, għandek bżonn Python 3.12 jew ogħla għax il-workflows jiddependu fuq karatteristiċi async moderni introdotti f’din il-verżjoni. Python 3.11 se jfalli waqt l-importazzjoni, mhux waqt l-eżekuzzjoni, li mill-inqas jagħmel l-iżball immedjat. It-tieni, għandek bżonn uv, il-maniġer tal-pakketti rrakkomandat minn Mistral għal proġetti Python. Dan jimmaniġġja kemm ambjenti virtwali kif ukoll id-dipendenzi. Fl-aħħar nett, għandek bżonn kont ta’ Mistral AI. Oħloq wieħed fuq console.mistral.ai jekk għadek ma għamiltx, u ġġenera ċavetta tal-API fit-taqsima API Keys tal-console.

Iċċekkja l-verżjoni ta’ Python tiegħek

Ibda bl-aktar ostaklu komuni: il-verżjoni tal-interpreter.

python --version
# Trid turi Python 3.12.x jew ogħla

Jekk il-verżjoni tiegħek hija inqas minn 3.12, aġġorna Python qabel ma tkompli. Fuq Ubuntu/Debian:

sudo apt update
sudo apt install python3.12 python3.12-venv

Fuq macOS b’Homebrew:

brew install [email protected]

Installa uv

Jekk m’għandekx uv għaddek, installah. Il-kmand jiddependi mis-sistema:

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Imbagħad ivverifika li l-binary jinsab fil-PATH tiegħek. Jekk il-kmand li ġej jirritorna “not found”, iftaħ terminal ġdid. L-installatur jimmodifika l-profil tal-shell tiegħek:

uv --version

Oħloq proġett

Oħloq proġett Python ġdid b’uv:

mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init

Dan joħloq fajl pyproject.toml u struttura standard tal-proġett. Il-fajl pyproject.toml jelenka d-dipendenzi tiegħek u jippermetti lil kollega jerġa’ joħloq l-istess ambjent eżatt.

Installa s-SDK tal-Workflows

Għandek żewġ għażliet ta’ installazzjoni, u l-għażla hija importanti. Jekk għandek bżonn biss tal-magna tal-workflow—għax l-attivitajiet tiegħek isejħu APIs interni, database, jew servizzi ta’ partijiet terzi—il-verżjoni bażika hija biżżejjed:

uv add mistralai-workflows

Jekk trid tuża aġenti durabbli, sejħiet ta’ għodod (tool calling), u trasferimenti bejn diversi aġenti direttament fil-workflows tiegħek, uża l-varjant bl-estensjonijiet (extras):

uv add "mistralai-workflows[mistralai]"

It-tieni għażla tinstalla s-SDK ta’ Mistral AI bħala dipendenza u tippermetti integrazzjonijiet nattivi mal-mudelli ta’ Mistral. Jekk m’intix ċert fil-bidu ta’ proġett, il-verżjoni bażika hija eħfef. Tista’ żżid l-estensjoni aktar tard mingħajr ma tkisser xejn.

Ivverifika l-installazzjoni

Importazzjoni suċċessura taqbeż kontroll manwali twil:

uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"

Għandek tara:

Workflows SDK installed successfully!

Jekk tikseb ModuleNotFoundError, terġax tinstalla minnufih. L-ewwel, iċċekkja li tinsab fil-folder tal-proġett fejn ġrejt uv add. Il-kmand uv run isolvi l-ambjent virtwali mid-direttorju kurrenti.

Ikkonfigura ċ-ċavetta tal-API tiegħek

L-SDK jawtentika permezz tal-varjabbli tal-ambjent MISTRAL_API_KEY. Dan jaqraha awtomatikament; m’għandekx għalfejn tgħaddiha bħala argument. Issettjaha fit-terminal tiegħek:

# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"

# Biex tagħmilha permanenti, żidha mal-~/.bashrc jew ~/.zshrc tiegħek
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc

Dan il-metodu jaħdem għall-iżvilupp lokali. Għal proġetti tal-produzzjoni, ippreferi fajl .env imħaddem permezz ta’ python-dotenv jew il-maniġer tas-sigrieti tal-pjattaforma ta’ deploy tiegħek. Ċavetta f’fajl .bashrc eventwalment se tispiċċa f’backup jew f’kondiviżjoni tal-iskrin.

Scaffolding rapidu (għażlieni)

Mistral jipprovdi għodda CLI li tiġġenera proġett sħiħ ta’ workflow. Dan huwa utli biex tara l-istruttura mistennija qabel ma tikteb tiegħek stess:

uvx mistralai-workflows-cli setup

Il-kmand jipproduċi fajl ta’ workflow ta’ kampjun, fajl ta’ attività, ħaddiem (worker) lest biex jibda, u konfigurazzjoni bażika. F’sekondi, ikollok proġett li qed jaħdem. Imbagħad tista’ tifredha biċċa biċċa biex tifhem ir-rwol ta’ kull komponent qabel ma tibda minn xejn.

Struttura tal-proġett irrakkomandata

Għal proġett ta’ workflow tal-produzzjoni, nirrakkomandaw din l-istruttura:

mon-workflow-mistral/
├── pyproject.toml          # Dipendenzi (mistralai-workflows)
├── .env                    # Ċavetta tal-API (tikkomittjax)
├── activities/
│   ├── __init__.py
│   ├── email.py            # Attivitajiet relatati mal-email
│   └── data_processing.py  # Attivitajiet ta' ipproċessar tad-data
├── workflows/
│   ├── __init__.py
│   └── pipeline.py         # Definizzjonijiet tal-workflow
└── worker.py               # Punt tad-dħul tal-ħaddiem (worker)

Is-separazzjoni tal-attivitajiet mill-workflows tagħmel il-manutenzjoni u t-testijiet tal-unità aktar faċli. Attività hija funzjoni async standard li tista’ ssejjaħ direttament f’test, filwaqt li workflow jeħtieġ il-magna biex taħdem. Din is-separazzjoni tieħu ħames minuti fil-bidu ta’ proġett u tiffrankalek ħafna ħin meta jkollok aktar minn għaxar attivitajiet.

Punti Ewlenin

  • Python 3.12+ u uv huma meħtieġa għas-SDK tal-Workflows
  • Żewġ modi ta’ installazzjoni: bażiku (mistralai-workflows) jew b’integrazzjoni AI (mistralai-workflows[mistralai])
  • Ikkonfigura ċ-ċavetta tal-API permezz tal-varjabbli tal-ambjent MISTRAL_API_KEY
  • Il-kmand uvx mistralai-workflows-cli setup jiġġenera proġett ta’ kampjun sħiħ
  • Separa l-attivitajiet, il-workflows u l-ħaddiem (worker) tiegħek f’fajls distinti għal manutenibbiltà aħjar