A Workflows SDK telepítése
Ezen az oldalon
Technikai előfeltételek
Négy dologra van szükséged, mielőtt megírnád az első sor workflow kódot. Először is szükséged van Python 3.12 vagy újabb verzióra, mert a munkafolyamatok ezen verzióban bevezetett modern aszinkron funkciókra támaszkodnak. A Python 3.11 már az importáláskor elbukik, nem futás időben, ami legalább azonnali hibaüzenetet eredményez. Másodszor szükséged van az uv-re, a Mistral által ajánlott csomagkezelőre Python projektekhez. Ez kezeli mind a virtuális környezeteket, mind a függőségeket. Végül szükséged van egy Mistral AI fiókra. Hozz létre egyet a console.mistral.ai oldalon, ha még nem tetted meg, és generálj egy API kulcsot a konzol API Keys szekciójában.
A Python verzió ellenőrzése
Kezdjük a leggyakoribb akadállyal: az értelmező verziójával.
python --version
# A Python 3.12.x vagy újabb verziót kell mutatnia
Ha a verziód alacsonyabb, mint a 3.12, frissítsd a Pythont, mielőtt folytatnád. Ubuntu/Debian rendszeren:
sudo apt update
sudo apt install python3.12 python3.12-venv
macOS rendszeren Homebrew segítségével:
brew install [email protected]
Az uv telepítése
Ha még nincs meg az uv, telepítsd. A parancs rendszertől függően eltér:
# 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"
Ezután ellenőrizd, hogy a bináris fájl benne van-e a PATH változódban. Ha a következő parancs „nem található“ üzenetet ad, nyiss egy új terminált. A telepítő módosítja a shell profilodat:
uv --version
Projekt létrehozása
Hozz létre egy új Python projektet az uv segítségével:
mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init
Ez létrehoz egy pyproject.toml fájlt és egy szabványos projektszerkezetet. A pyproject.toml fájl felsorolja a függőségeidet, és lehetővé teszi egy kollégád számára, hogy pontosan ugyanazt a környezetet állítsa elő.
A Workflows SDK telepítése
Két telepítési lehetőség közül választhatsz, és a döntés számít. Ha csak a workflow motorra van szükséged – mert a tevékenységeid belső API-kat, adatbázist vagy harmadik féltől származó szolgáltatásokat hívnak meg –, akkor az alapverzió elegendő:
uv add mistralai-workflows
Ha tartós ügynököket (durable agents), eszközlehívást (tool calling) és többügynökös átadásokat szeretnél használni közvetlenül a munkafolyamataidban, használd a kiegészítőkkel ellátott változatot:
uv add "mistralai-workflows[mistralai]"
A második lehetőség telepíti a Mistral AI SDK-t függőségként, és lehetővé teszi a natív integrációt a Mistral modellekkel. Ha a projekt elején bizonytalan vagy, az alapverzió könnyebb. Később hozzáadhatod a kiegészítőt anélkül, hogy bármit elrontanál.
A telepítés ellenőrzése
Egy sikeres importálás többet ér, mint egy hosszú kézi ellenőrzés:
uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"
A következőt kell látnod:
Workflows SDK installed successfully!
Ha ModuleNotFoundError hibaüzenetet kapsz, ne telepítsd újra azonnal. Először ellenőrizd, hogy abban a projektmappában vagy-e, ahol lefuttattad az uv add parancsot. Az uv run parancs a virtuális környezetet az aktuális könyvtárból oldja fel.
Az API kulcs konfigurálása
Az SDK a MISTRAL_API_KEY környezeti változón keresztül hitelesít. Ezt automatikusan olvassa be; nem kell argumentumként átadnod. Állítsd be a terminálodban:
# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"
# Hogy végleges legyen, add hozzá a ~/.bashrc vagy ~/.zshrc fájlhoz
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc
Ez a módszer helyi fejlesztéshez működik. Éles projektek esetén előnyösebb egy .env fájlt használni, amelyet a python-dotenv vagy a telepítési platformod titokkezelője tölt be. Egy kulcs, amely a .bashrc fájlban van, előbb-utóbb bekerül egy biztonsági mentésbe vagy egy képernyőmegosztásba.
Gyors alapozás (opcionális)
A Mistral biztosít egy CLI eszközt, amely egy teljes workflow projektet generál. Ez hasznos arra, hogy lásd a várt szerkezetet, mielőtt megírnád a sajátodat:
uvx mistralai-workflows-cli setup
A parancs létrehoz egy minta workflow fájlt, egy tevékenységfájlt, egy indításra kész munkást és egy alap konfigurációt. Másodpercek alatt egy működő projekted lesz. Ezután darabonként szétszedheted, hogy megértsd az egyes komponensek szerepét, mielőtt a nulláról kezdenéd.
Ajánlott projektszerkezet
Éles workflow projektekhez ezt a szerkezetet ajánljuk:
mon-workflow-mistral/
├── pyproject.toml # Függőségek (mistralai-workflows)
├── .env # API kulcs (ne commitold)
├── activities/
│ ├── __init__.py
│ ├── email.py # E-maillel kapcsolatos tevékenységek
│ └── data_processing.py # Adatfeldolgozási tevékenységek
├── workflows/
│ ├── __init__.py
│ └── pipeline.py # Workflow definíciók
└── worker.py # Munkás belépési pont
A tevékenységek és a workflowok szétválasztása megkönnyíti a karbantartást és az egységtesztelést. Egy tevékenység egy szabványos aszinkron függvény, amelyet közvetlenül meghívhatsz egy tesztben, míg egy workflow futtatásához a motorra van szükség. Ez a szétválasztás öt percet vesz igénybe a projekt elején, és rengeteg időt spórol meg, ha már több mint tíz tevékenységed van.
Főbb megállapítások
- A Workflows SDK-hoz Python 3.12+ és uv szükséges
- Két telepítési mód: alap (
mistralai-workflows) vagy AI integrációval (mistralai-workflows[mistralai]) - Az API kulcsot a
MISTRAL_API_KEYkörnyezeti változón keresztül kell konfigurálni - Az
uvx mistralai-workflows-cli setupparancs generál egy teljes mintaprojektet - A jobb karbantarthatóság érdekében válaszd szét a tevékenységeket, workflowokat és a munkást külön fájlokba