Salt la conținutul principal
Română— Alege o limbă
Meniu

Instalarea SDK-ului Workflows

Lecția 3 din 14 Actualizată 29 iulie 2026 Avansat
Pe această pagină
  1. Condiții tehnice prealabile
  2. Verificarea versiunii Python
  3. Instalarea uv
  4. Crearea unui proiect
  5. Instalarea SDK-ului Workflows
  6. Verificarea instalării
  7. Configurarea cheii API
  8. Schelet rapid (opțional)
  9. Structura de proiect recomandată
  10. Puncte cheie

Condiții tehnice prealabile

Aveți nevoie de patru elemente înainte de a scrie prima linie de cod pentru un workflow. În primul rând, aveți nevoie de Python 3.12 sau o versiune superioară, deoarece workflow-urile se bazează pe funcționalități asincrone moderne introduse în această versiune. Python 3.11 va eșua la momentul importului, nu la runtime, ceea ce are cel puțin avantajul de a genera o eroare imediată. În al doilea rând, aveți nevoie de uv, managerul de pachete recomandat de Mistral pentru proiectele Python. Acesta gestionează atât mediile virtuale, cât și dependențele. În final, aveți nevoie de un cont Mistral AI. Creați unul la console.mistral.ai dacă nu aveți deja, și generați o cheie API în secțiunea API Keys a consolei.

Verificarea versiunii Python

Începeți cu cel mai frecvent obstacol: versiunea interpretorului.

python --version
# Trebuie să afișeze Python 3.12.x sau o versiune superioară

Dacă versiunea dumneavoastră este mai mică de 3.12, actualizați Python înainte de a continua. Pe Ubuntu/Debian:

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

Pe macOS cu Homebrew:

brew install [email protected]

Instalarea uv

Dacă nu aveți încă uv, instalați-l. Comanda diferă în funcție de sistem:

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

Apoi verificați dacă binarul se află în PATH. Dacă următoarea comandă returnează „not found“, deschideți un nou terminal. Programul de instalare modifică profilul shell-ului dumneavoastră:

uv --version

Crearea unui proiect

Creați un nou proiect Python cu uv:

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

Acest lucru creează un fișier pyproject.toml și o structură standard de proiect. Fișierul pyproject.toml listează dependențele dumneavoastră și permite unui coleg să recreeze exact același mediu.

Instalarea SDK-ului Workflows

Aveți două opțiuni de instalare, iar alegerea contează. Dacă aveți nevoie doar de motorul de workflow—deoarece activitățile dumneavoastră apelează API-uri interne, o bază de date sau servicii terțe—versiunea de bază este suficientă:

uv add mistralai-workflows

Dacă doriți să utilizați agenți durabili, apelarea de instrumente (tool calling) și transferuri între mai mulți agenți direct în workflow-urile dumneavoastră, utilizați varianta cu extra:

uv add "mistralai-workflows[mistralai]"

A doua opțiune instalează SDK-ul Mistral AI ca dependență și activează integrările native cu modelele Mistral. Dacă nu sunteți sigur la începutul unui proiect, versiunea de bază este mai ușoară. Puteți adăuga extra-ul mai târziu fără a strica nimic.

Verificarea instalării

Un import reușit valorează mai mult decât o verificare manuală lungă:

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

Ar trebui să vedeți:

Workflows SDK installed successfully!

Dacă primiți o eroare ModuleNotFoundError, nu reinstalați imediat. Mai întâi, verificați dacă vă aflați în folderul proiectului unde ați rulat uv add. Comanda uv run rezolvă mediul virtual din directorul curent.

Configurarea cheii API

SDK-ul se autentifică prin variabila de mediu MISTRAL_API_KEY. Aceasta este citită automat; nu trebuie să o transmiteți ca argument. Setați-o în terminalul dumneavoastră:

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

# Pentru a o face permanentă, adăugați-o în ~/.bashrc sau ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc

Această metodă funcționează pentru dezvoltarea locală. Pentru proiectele de producție, preferați un fișier .env încărcat prin python-dotenv sau managerul de secrete al platformei dumneavoastră de deploy. O cheie într-un fișier .bashrc va ajunge eventual într-o copie de rezervă sau într-o partajare de ecran.

Schelet rapid (opțional)

Mistral oferă un instrument CLI care generează un proiect complet de workflow. Acest lucru este util pentru a vedea structura așteptată înainte de a scrie propriul cod:

uvx mistralai-workflows-cli setup

Comanda produce un fișier sample de workflow, un fișier de activitate, un worker gata de pornire și o configurație de bază. În câteva secunde, obțineți un proiect funcțional. Puteți apoi să îl dezasamblați bucată cu bucată pentru a înțelege rolul fiecărei componente înainte de a începe de la zero.

Structura de proiect recomandată

Pentru un proiect de workflow de producție, recomandăm această structură:

mon-workflow-mistral/
├── pyproject.toml          # Dependențe (mistralai-workflows)
├── .env                    # Cheie API (nu faceți commit)
├── activities/
│   ├── __init__.py
│   ├── email.py            # Activități legate de email
│   └── data_processing.py  # Activități de procesare a datelor
├── workflows/
│   ├── __init__.py
│   └── pipeline.py         # Definiții de workflow
└── worker.py               # Punct de intrare pentru worker

Separarea activităților de workflow-uri facilitează mentenanța și testarea unitară. O activitate este o funcție asincronă standard pe care o puteți apela direct într-un test, în timp ce un workflow necesită motorul pentru a rula. Această separare durează cinci minute la începutul unui proiect și vă economisește mult timp odată ce aveți mai mult de zece activități.

Puncte cheie

  • Python 3.12+ și uv sunt necesare pentru SDK-ul Workflows
  • Două moduri de instalare: de bază (mistralai-workflows) sau cu integrare AI (mistralai-workflows[mistralai])
  • Configurați cheia API prin variabila de mediu MISTRAL_API_KEY
  • Comanda uvx mistralai-workflows-cli setup generează un proiect sample complet
  • Separați activitățile, workflow-urile și worker-ul în fișiere distincte pentru o mai bună mentenanță