Inštalácia Workflows SDK
Na tejto strane
Technické predpoklady
Predtým, ako napíšeš prvý riadok kódu workflow, musíš mať pripravené štyri veci. Po prvé, potrebuješ Python 3.12 alebo vyšší, pretože workflow využívajú moderné asynchrónne funkcie uvedené v tejto verzii. Python 3.11 zlyhá už pri importe, nie behu programu, čo aspoň znamená, že chyba je okamžitá. Po druhé, potrebuješ uv, správca balíkov, ktorý Mistral odporúča pre projekty v Pythone. Stará sa o virtuálne prostredia aj závislosti. Nakoniec potrebuješ účet Mistral AI. Ak ho ešte nemáš, vytvor si ho na console.mistral.ai a v sekcii API Keys v konzole vygeneruj API kľúč.
Skontroluj verziu Pythonu
Začni najčastejšou prekážkou: verziou interpretu.
python --version
# Musí zobrazovať Python 3.12.x alebo vyšší
Ak máš verziu nižšiu ako 3.12, aktualizuj Python pred pokračovaním. Na Ubuntu/Debian:
sudo apt update
sudo apt install python3.12 python3.12-venv
Na macOS s Homebrew:
brew install [email protected]
Inštalácia uv
Ak ešte nemáš uv, nainštaluj ho. Príkaz sa líši podľa systému:
# 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"
Potom over, či je binárny súbor v tvojom PATH. Ak nasledujúci príkaz vráti „not found“, otvor nový terminál. Inštalátor upraví profil tvojej shellu:
uv --version
Vytvorenie projektu
Vytvor nový projekt v Pythone pomocou uv:
mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init
Tým sa vytvorí súbor pyproject.toml a štandardná štruktúra projektu. Súbor pyproject.toml obsahuje zoznam závislostí a umožňuje kolegovi recreated presne rovnaké prostredie.
Inštalácia Workflows SDK
Máš dve možnosti inštalácie a výber záleží. Ak potrebuješ len engine workflow – pretože tvoje aktivity volajú interné API, databázu alebo služby tretích strán – stačí základná verzia:
uv add mistralai-workflows
Ak chceš vo svojich workflow priamo používať odolných agentov, volanie nástrojov a odovzdávanie medzi viacerými agentmi, použite variant s extras:
uv add "mistralai-workflows[mistralai]"
Druhá možnosť nainštaluje Mistral AI SDK ako závislosť a umožní natívnu integráciu s modelmi Mistral. Ak si na začiatku projektu nie si istý, základná verzia je ľahšia. Extra môžeš pridať neskôr bez toho, aby si niečo pokazil.
Overenie inštalácie
Úspešný import nahradí dlhú manuálnu kontrolu:
uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"
Mal by si vidieť:
Workflows SDK installed successfully!
Ak dostaneš ModuleNotFoundError, neinštaluj hneď znova. Najprv skontroluj, či si v priečinku projektu, kde si spustil uv add. Príkaz uv run rieši virtuálne prostredie z aktuálneho adresára.
Konfigurácia API kľúča
SDK sa autentifikuje pomocou premennej prostredia MISTRAL_API_KEY. Číta ju automaticky; nemusíš ju odovzdávať ako argument. Nastav ju v termináli:
# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"
# Aby bola trvalá, pridaj ju do ~/.bashrc alebo ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc
Táto metóda funguje pre lokálny vývoj. Pre produkčné projekty uprednostni súbor .env načítaný cez python-dotenv alebo správcu tajomstiev tvojej nasadzovacej platformy. Kľúč v súbore .bashrc sa časom dostane do zálohy alebo zdieľania obrazovky.
Rýchle vytvorenie kostry (voliteľné)
Mistral poskytuje nástroj CLI, ktorý generuje kompletný projekt workflow. Je to užitočné na to, aby si videl očakávanú štruktúru predtým, ako napíšeš vlastný kód:
uvx mistralai-workflows-cli setup
Príkaz vytvorí vzorový súbor workflow, súbor aktivity, pripraveného workera a základnú konfiguráciu. Za pár sekúnd máš fungujúci projekt. Potom ho môžeš rozobrať časť po časti, aby si pochopil úlohu každej zložky, než začneš od nuly.
Odporúčaná štruktúra projektu
Pre produkčný projekt workflow odporúčame túto štruktúru:
mon-workflow-mistral/
├── pyproject.toml # Závislosti (mistralai-workflows)
├── .env # API kľúč (nekomitovať)
├── activities/
│ ├── __init__.py
│ ├── email.py # Aktivity súvisiace s e-mailom
│ └── data_processing.py # Aktivity spracovania dát
├── workflows/
│ ├── __init__.py
│ └── pipeline.py # Definície workflow
└── worker.py # Vstupný bod workeru
Oddelenie aktivít od workflow uľahčuje údržbu a unit testovanie. Aktivita je štandardná asynchrónna funkcia, ktorú môžeš priamo zavolať v teste, zatiaľ čo workflow vyžaduje na spustenie engine. Toto oddelenie zaberie na začiatku projektu päť minút a ušetrí ti veľa času, keď budeš mať viac ako desať aktivít.
Kľúčové poznatky
- Pre Workflows SDK sú potrebné Python 3.12+ a uv
- Dva režimy inštalácie: základný (
mistralai-workflows) alebo s AI integráciou (mistralai-workflows[mistralai]) - API kľúč nakonfiguruj cez premennú prostredia
MISTRAL_API_KEY - Príkaz
uvx mistralai-workflows-cli setupgeneruje kompletný vzorový projekt - Pre lepšiu udržateľnosť oddeľ aktivity, workflow a worker do samostatných súborov