Instalacja Workflows SDK
Na tej stronie
Wymagania techniczne
Zanim napiszesz pierwszą linię kodu przepływu pracy, musisz przygotować cztery elementy. Po pierwsze, potrzebujesz Pythona w wersji 3.12 lub nowszej, ponieważ przepływy pracy opierają się na nowoczesnych funkcjach asynchronicznych wprowadzonych w tej wersji. Python 3.11 zakończy się błędem już podczas importu, a nie w trakcie działania, co przynajmniej sprawia, że błąd jest natychmiastowy. Po drugie, potrzebujesz uv – menedżera pakietów rekomendowanego przez Mistral dla projektów Pythona. Zarządza on zarówno środowiskami wirtualnymi, jak i zależnościami. Wreszcie, potrzebujesz konta Mistral AI. Jeśli jeszcze go nie masz, utwórz je na stronie console.mistral.ai i wygeneruj klucz API w sekcji API Keys konsoli.
Sprawdź wersję Pythona
Zacznij od najczęstszej przeszkody: wersji interpretera.
python --version
# Musi wyświetlić Python 3.12.x lub wyższy
Jeśli Twoja wersja jest niższa niż 3.12, zaktualizuj Pythona przed kontynuowaniem. Na Ubuntu/Debian:
sudo apt update
sudo apt install python3.12 python3.12-venv
Na macOS z Homebrew:
brew install [email protected]
Instalacja uv
Jeśli nie masz jeszcze uv, zainstaluj go. Polecenie różni się w zależności od systemu:
# 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"
Następnie upewnij się, że plik binarny znajduje się w Twojej ścieżce PATH. Jeśli poniższe polecenie zwróci „not found“, otwórz nowy terminal. Instalator modyfikuje profil Twojej powłoki:
uv --version
Utwórz projekt
Utwórz nowy projekt Pythona za pomocą uv:
mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init
Spowoduje to utworzenie pliku pyproject.toml oraz standardowej struktury projektu. Plik pyproject.toml zawiera listę zależności i pozwala współpracownikowi odtworzyć dokładnie takie samo środowisko.
Instalacja Workflows SDK
Masz dwie opcje instalacji i wybór ma znaczenie. Jeśli potrzebujesz tylko silnika przepływów pracy – ponieważ Twoje aktywności wywołują wewnętrzne API, bazę danych lub usługi zewnętrzne – wersja podstawowa wystarczy:
uv add mistralai-workflows
Jeśli chcesz używać trwałych agentów, wywoływania narzędzi i przekazywania zadań między wieloma agentami bezpośrednio w swoich przepływach pracy, użyj wariantu z dodatkami:
uv add "mistralai-workflows[mistralai]"
Druga opcja instaluje Mistral AI SDK jako zależność i umożliwia natywną integrację z modelami Mistral. Jeśli na początku projektu nie masz pewności, wersja podstawowa jest lżejsza. Możesz dodać rozszerzenie później, nie psując niczego.
Weryfikacja instalacji
Pomyślny import jest lepszy niż długa ręczna kontrola:
uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"
Powinieneś zobaczyć:
Workflows SDK installed successfully!
Jeśli otrzymasz błąd ModuleNotFoundError, nie reinstaluj pakietu od razu. Najpierw sprawdź, czy znajdujesz się w folderze projektu, w którym uruchomiłeś uv add. Polecenie uv run rozwiązuje środowisko wirtualne na podstawie bieżącego katalogu.
Konfiguracja klucza API
SDK uwierzytelnia się za pomocą zmiennej środowiskowej MISTRAL_API_KEY. Odczytuje ją automatycznie; nie musisz przekazywać jej jako argumentu. Ustaw ją w terminalu:
# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"
# Aby ustawienie było trwałe, dodaj je do ~/.bashrc lub ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc
Ta metoda działa do celów deweloperskich lokalnie. W projektach produkcyjnych preferuj plik .env ładowany przez python-dotenv lub menedżera sekretów swojej platformy wdrożeniowej. Klucz w pliku .bashrc prędzej czy później trafi do kopii zapasowej lub udostępnienia ekranu.
Szybkie szkicowanie projektu (opcjonalne)
Mistral udostępnia narzędzie CLI, które generuje kompletny projekt przepływu pracy. Jest to przydatne, aby zobaczyć oczekiwaną strukturę przed napisaniem własnego kodu:
uvx mistralai-workflows-cli setup
Polecenie tworzy przykładowy plik przepływu pracy, plik aktywności, gotowego do uruchomienia worker oraz podstawową konfigurację. W kilka sekund otrzymujesz działający projekt. Możesz następnie rozebrać go na części, aby zrozumieć rolę każdego komponentu, zanim zaczniesz od zera.
Zalecana struktura projektu
Dla produkcyjnego projektu przepływu pracy rekomendujemy następującą strukturę:
mon-workflow-mistral/
├── pyproject.toml # Zależności (mistralai-workflows)
├── .env # Klucz API (nie commituj)
├── activities/
│ ├── __init__.py
│ ├── email.py # Aktywności związane z e-mailem
│ └── data_processing.py # Aktywności przetwarzania danych
├── workflows/
│ ├── __init__.py
│ └── pipeline.py # Definicje przepływów pracy
└── worker.py # Punkt wejścia worker
Rozdzielenie aktywności od przepływów pracy ułatwia utrzymanie i testy jednostkowe. Aktywność to standardowa funkcja asynchroniczna, którą możesz wywołać bezpośrednio w teście, podczas gdy przepływ pracy wymaga do działania silnika. To rozdzielenie zajmuje pięć minut na początku projektu, a oszczędza dużo czasu, gdy masz już więcej niż dziesięć aktywności.
Kluczowe wnioski
- Do Workflows SDK wymagane są Python 3.12+ oraz uv
- Dwa tryby instalacji: podstawowy (
mistralai-workflows) lub z integracją AI (mistralai-workflows[mistralai]) - Skonfiguruj klucz API poprzez zmienną środowiskową
MISTRAL_API_KEY - Polecenie
uvx mistralai-workflows-cli setupgeneruje kompletny przykładowy projekt - Rozdziel aktywności, przepływy pracy i worker na osobne pliki dla lepszej utrzymywalności