Installazzjoni tas-SDK tal-Workflows
F'din il-paġna
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 setupjiġġ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