Przejdź do głównej treści
Polski— Wybierz język
Menu

Instalacja Workflows SDK

Lekcja 3 z 14 Zaktualizowano 29 lipca 2026 Zaawansowany
Na tej stronie
  1. Wymagania techniczne
  2. Sprawdź wersję Pythona
  3. Instalacja uv
  4. Utwórz projekt
  5. Instalacja Workflows SDK
  6. Weryfikacja instalacji
  7. Konfiguracja klucza API
  8. Szybkie szkicowanie projektu (opcjonalne)
  9. Zalecana struktura projektu
  10. Kluczowe wnioski

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 setup generuje kompletny przykładowy projekt
  • Rozdziel aktywności, przepływy pracy i worker na osobne pliki dla lepszej utrzymywalności