Installa l'SDK Python di Mistral
In questa pagina
Prerequisiti
Aggiornato il 2 novembre 2026 — Mistral SDK 3. Questa lezione trattava in precedenza la versione 2 dell’SDK e Python 3.9. La versione corrente è la 3.7.0 (rilasciata il 1° novembre 2026); richiede Python 3.10 o superiore e il client viene importato tramite
from mistralai.client import Mistrala partire dalla versione 2.0 (marzo 2026). Fonti: mistralai su PyPI · note di rilascio v2.0.0 · note di rilascio v3.0.0.
L’installazione dell’SDK richiede tre elementi: Python 3.10 o superiore, che puoi verificare con python --version; una versione aggiornata di pip, ottenuta tramite pip install --upgrade pip; e la tua chiave API Mistral già impostata come variabile d’ambiente, come visto nella lezione precedente. Se Python non è ancora installato sulla tua macchina, scarica l’ultima versione stabile da python.org o usa il gestore pacchetti del tuo sistema.
Isola il tuo progetto prima di installare qualsiasi cosa
Lavora sempre all’interno di un ambiente virtuale. Questa abitudine ti risparmia un mal di testa comune: due progetti sulla stessa macchina, uno che richiede una versione specifica dell’SDK e l’altro una versione diversa, dove un singolo pip install rompe silenziosamente il primo progetto aggiornando il secondo. Un ambiente virtuale fornisce a ogni progetto le proprie dipendenze isolate, separate dai pacchetti di sistema.
# Crea l'ambiente virtuale
python -m venv mistral-env
# Attiva su Linux / macOS
source mistral-env/bin/activate
# Attiva su Windows
mistral-env\Scripts\activate
Una volta attivato, il prompt del tuo terminale sarà preceduto dal nome dell’ambiente tra parentesi: (mistral-env). Questo piccolo indicatore garantisce che i comandi successivi si applichino alla posizione corretta: se non appare, non installare nulla.
Installa l’SDK ufficiale
L’installazione dell’SDK Mistral richiede un solo comando:
pip install mistralai
Questo installa l’ultima versione dell’SDK: la 3.7.0 al 1° novembre 2026. La generazione 3 è iniziata con la versione 3.0, rilasciata il 28 settembre 2026. Per confermare che tutto sia a posto, esegui pip show mistralai per visualizzare il nome del pacchetto, la versione e le dipendenze.
A volte un progetto richiede una versione specifica, ad esempio per mantenere tutto il team allineato durante una migrazione. Puoi specificare i vincoli a due livelli:
# Rimani nella generazione 3
pip install "mistralai>=3,<4"
# Installa una versione esatta
pip install "mistralai==3.7.0"
Lungo il percorso, pip scarica alcune dipendenze che appaiono nell’elenco. È utile riconoscerle, in particolare httpx2, il client HTTP che gestisce le chiamate di rete (l’SDK usa questo invece di httpx a partire dalla versione 3.0), e pydantic, che valida e serializza i dati scambiati. Non interagirai direttamente con questi, ma la loro presenza spiega perché un’installazione che sembra minuscola occupi comunque qualche megabyte.
Verifica l’installazione con una chiamata API reale
Eseguire pip show prova che il pacchetto esiste, non che la tua configurazione funzioni. Il test reale interroga l’API. Crea un file chiamato test_mistral.py:
import os
from mistralai.client import Mistral
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
print("Error: MISTRAL_API_KEY environment variable is not set.")
else:
client = Mistral(api_key=api_key)
print("Mistral client initialized successfully!")
# Elenca i modelli disponibili
models = client.models.list()
print(f"Available models: {len(models.data)}")
for model in models.data[:5]:
print(f" - {model.id}")
Poi eseguilo:
python test_mistral.py
Questo script verifica due cose contemporaneamente. Il controllo su api_key distingue immediatamente una variabile d’ambiente mancante da un vero problema di rete: senza di esso, potresti passare dieci minuti a sospettare del tuo firewall quando il terminale è stato semplicemente riaperto senza la variabile. Se l’elenco dei modelli viene visualizzato, l’SDK è installato correttamente e la tua chiave è accettata dall’API.
Rendi l’ambiente riproducibile
In un progetto di team, l’installazione deve essere riproducibile. Congela le tue dipendenze:
pip freeze > requirements.txt
I tuoi colleghi potranno quindi ricostruire esattamente lo stesso ambiente con un singolo comando:
pip install -r requirements.txt
Anche il tuo server di deployment leggerà questo file. Prendi l’abitudine di rigenerarlo ogni volta che aggiungi una libreria; altrimenti, il codice funzionerà sulla tua macchina e da nessun’altra parte.
Quattro errori comuni e come diagnosticarli
L’errore ModuleNotFoundError: No module named mistralai significa quasi sempre che il terminale non sta usando l’ambiente virtuale corretto. Verificalo con which python, che dovrebbe puntare al tuo venv, e poi con pip list | grep mistralai.
L’errore ImportError: cannot import name 'Mistral' from 'mistralai' indica un codice scritto per la versione 1 dell’SDK. Dalla versione 2.0, tutti gli import passano attraverso mistralai.client: scrivi from mistralai.client import Mistral. La lezione sulle versioni dell’SDK dettaglia altre modifiche.
Un errore SSL o di rete rivela spesso un proxy aziendale seduto tra te e il mondo esterno. Indica esplicitamente a pip dove trovarlo:
pip install mistralai --proxy http://proxy.entreprise.com:8080
Infine, se l’installazione rifiuta la tua versione di Python, ricorda che l’SDK richiede Python 3.10 come minimo dalla versione 2.0. Aggiorna Python o installa pyenv per eseguire più versioni fianco a fianco senza toccare l’interprete di sistema.
Punti chiave
- Installa l’SDK con
pip install mistralaiall’interno di un ambiente virtuale - La versione corrente è la 3.7.0 (1° novembre 2026); importa il client tramite
from mistralai.client import Mistral - Verifica l’installazione elencando i modelli disponibili
- Congela le dipendenze in
requirements.txtper la riproducibilità - È richiesto Python 3.10 o superiore