Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Instalacija Workflows SDK-a

Lekcija 3 od 14 Ažurirano 29. srpnja 2026. Napredno
Na ovoj stranici
  1. Tehnički preduvjeti
  2. Provjera verzije Pythona
  3. Instalacija alata uv
  4. Izrada projekta
  5. Instalacija Workflows SDK-a
  6. Provjera instalacije
  7. Konfiguracija API ključa
  8. Brzo skeletiranje (opcionalno)
  9. Preporučena struktura projekta
  10. Ključne točke

Tehnički preduvjeti

Prije nego napišeš prvu liniju koda za workflow, moraš imati četiri stvari. Prvo, treba ti Python 3.12 ili noviji jer se workflowi oslanjaju na moderne asinkrone značajke uvedene u ovoj verziji. Python 3.11 će pasti pri uvozu, a ne tijekom izvršavanja, što barem odmah signalizira grešku. Drugo, treba ti uv, upravitelj paketa koji Mistral preporučuje za Python projekte. On upravlja i virtualnim okruženjima i ovisnostima. Konačno, treba ti Mistral AI račun. Ako ga još nemaš, izradi ga na console.mistral.ai i generiraj API ključ u odjeljku API Keys unutar konzole.

Provjera verzije Pythona

Započni s najčešćom preprekom: verzijom interpretera.

python --version
# Mora prikazati Python 3.12.x ili noviji

Ako je tvoja verzija starija od 3.12, ažuriraj Python prije nastavka. Na Ubuntu/Debian sustavima:

sudo apt update
sudo apt install python3.12 python3.12-venv

Na macOS-u s Homebrewom:

brew install [email protected]

Instalacija alata uv

Ako još nemaš uv, instaliraj ga. Naredba se razlikuje ovisno o sustavu:

# 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"

Zatim provjeri nalazi li se binarna datoteka u tvom PATH-u. Ako sljedeća naredba vrati „not found“, otvori novi terminal. Instalacijski program modificira tvoj profil ljuske:

uv --version

Izrada projekta

Izradi novi Python projekt pomoću uv:

mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init

Ovo stvara datoteku pyproject.toml i standardnu strukturu projekta. Datoteka pyproject.toml navodi tvoje ovisnosti i omogućuje kolegi da rekreira potpuno isto okruženje.

Instalacija Workflows SDK-a

Imaš dvije opcije instalacije, a izbor je bitan. Ako ti treba samo pogon za workflowe – jer tvoje aktivnosti pozivaju interne API-je, bazu podataka ili usluge trećih strana – osnovna verzija je dovoljna:

uv add mistralai-workflows

Ako želiš koristiti trajne agente (durable agents), pozivanje alata i predaju između više agenata izravno u svojim workflowima, upotrijebi varijantu s dodacima:

uv add "mistralai-workflows[mistralai]"

Druga opcija instalira Mistral AI SDK kao ovisnost i omogućuje izvorne integracije s Mistral modelima. Ako na početku projekta nisi siguran, osnovna verzija je lakša. Dodatak možeš naknadno dodati bez ikakvih problema.

Provjera instalacije

Uspješan uvoz bolji je od duge ručne provjere:

uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"

Trebao bi vidjeti:

Workflows SDK installed successfully!

Ako dobiješ ModuleNotFoundError, nemoj odmah ponovno instalirati. Prvo provjeri nalaziš li se u mapi projekta gdje si pokrenuo uv add. Naredba uv run rješava virtualno okruženje iz trenutnog direktorija.

Konfiguracija API ključa

SDK se autentificira putem varijable okruženja MISTRAL_API_KEY. Ona se čita automatski; ne moraš je proslijediti kao argument. Postavi je u svom terminalu:

# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"

# Da bi postavka bila trajna, dodaj je u ~/.bashrc ili ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc

Ova metoda funkcionira za lokalni razvoj. Za produkcijske projekte, radije koristi .env datoteku učitavanu putem python-dotenv ili upravitelja tajni tvoje platforme za implementaciju. Ključ u .bashrc datoteci će se prije ili kasnije naći u sigurnosnoj kopiji ili na snimci zaslona tijekom dijeljenja ekrana.

Brzo skeletiranje (opcionalno)

Mistral nudi CLI alat koji generira kompletan projekt workflowa. Ovo je korisno za uvid u očekivanu strukturu prije nego napišeš vlastiti kod:

uvx mistralai-workflows-cli setup

Naredba proizvodi uzorku datoteku workflowa, datoteku aktivnosti, radnika spremnog za pokretanje i osnovnu konfiguraciju. U nekoliko sekundi dobivaš funkcionalan projekt. Zatim ga možeš rastaviti dio po dio kako bi razumio ulogu svake komponente prije nego kreneš od nule.

Preporučena struktura projekta

Za produkcijski projekt workflowa, preporučujemo ovu strukturu:

mon-workflow-mistral/
├── pyproject.toml          # Ovisnosti (mistralai-workflows)
├── .env                    # API ključ (ne commitaj)
├── activities/
│   ├── __init__.py
│   ├── email.py            # Aktivnosti vezane uz e-poštu
│   └── data_processing.py  # Aktivnosti obrade podataka
├── workflows/
│   ├── __init__.py
│   └── pipeline.py         # Definicije workflowa
└── worker.py               # Ulazna točka radnika

Odvojene aktivnosti od workflowa olakšava održavanje i jedinično testiranje. Aktivnost je standardna asinkrona funkcija koju možeš izravno pozvati u testu, dok workflow zahtijeva pogon za izvršavanje. Ovo odvajanje oduzima pet minuta na početku projekta, a štedi ti puno vremena jednom kada imaš više od deset aktivnosti.

Ključne točke

  • Python 3.12+ i uv su obavezni za Workflows SDK
  • Dva načina instalacije: osnovni (mistralai-workflows) ili s AI integracijom (mistralai-workflows[mistralai])
  • Konfiguriraj API ključ putem varijable okruženja MISTRAL_API_KEY
  • Naredba uvx mistralai-workflows-cli setup generira kompletan uzorak projekta
  • Odvoji svoje aktivnosti, workflowe i radnika u zasebne datoteke radi bolje održivosti