Migrare tra le versioni dell'SDK Mistral
In questa pagina
Lezione riscritta il 2 novembre 2026. La versione precedente parlava di “passaggio da V1 a V2”, che era in realtà la transizione dal client legacy 0.x alla versione 1.0 nell’agosto 2024. Da allora, l’SDK Python ha visto altre due major release: la 2.0 a marzo 2026 e la 3.0 a settembre 2026. Questa lezione ricostruisce l’intera storia basandosi sulle guide ufficiali di migrazione e sulle note di rilascio. Aggiornato il 3 novembre 2026: corretto il loop di streaming TypeScript, che precedentemente passava il contenuto
string | ContentChunk[]direttamente aprocess.stdout.write, causando errori in strict mode.
Perché questa lezione è importante
Ti imbatterai in questo materiale in due scenari: stai riprendendo un progetto scritto tempo fa che si rifiuta di avviarsi dopo un aggiornamento delle dipendenze, oppure stai seguendo un tutorial online i cui esempi non funzionano più. In entrambi i casi, poni sempre la stessa prima domanda: per quale generazione dell’SDK è stato scritto questo codice? Quasi sempre, una singola riga te lo dice: l’istruzione di importazione.
Quattro generazioni in due anni
| Generazione | Python (mistralai) | TypeScript (@mistralai/mistralai) | Caratteristica distintiva del codice |
|---|---|---|---|
| 0.x | fino a 0.4.2 (luglio 2024) | fino a 0.5.0 (giugno 2024) | MistralClient, metodi piatti: client.chat(...) |
| 1.x | 1.0.0 (7 ago 2024) → 1.9.11 (ott 2025) | da ago 2024 | from mistralai import Mistral, metodi a catena: client.chat.complete(...) |
| 2.x | 2.0.0 (10 mar 2026) | 2.0.0 (18 mar 2026) | Python: from mistralai.client import Mistral; TypeScript: solo moduli ES |
| 3.x | 3.0.0 (28 set 2026), 3.7.0 al 1° nov 2026 | 3.0 (ott 2026), 3.5.0 oggi | Python: client HTTP httpx2 |
In TypeScript, l’import import { Mistral } from '@mistralai/mistralai' non è cambiato dalla 1.x. In Python, è cambiato due volte: è qui che si verificano la maggior parte delle interruzioni.
Da 0.x a 1.x: il client Mistral e i metodi a catena
La versione 1.0 ha sostituito i due client, MistralClient (sincrono) e MistralAsyncClient (asincrono), con un’unica classe, Mistral. Ha anche sostituito i metodi piatti con i namespace: chat raggruppa le operazioni di conversazione e devi scendere di un livello per raggiungere complete(). I messaggi, che precedentemente venivano scritti usando la classe ChatMessage, ora si scrivono come dizionari o utilizzando le classi UserMessage, SystemMessage, AssistantMessage e ToolMessage.
# 0.x (legacy)
from mistralai.client import MistralClient
from mistralai.models.chat_completion import ChatMessage
client = MistralClient(api_key="...")
response = client.chat(
model="mistral-small-latest",
messages=[ChatMessage(role="user", content="Hello")],
)
# 1.x
from mistralai import Mistral
client = Mistral(api_key="...")
response = client.chat.complete(
model="mistral-small-latest",
messages=[{"role": "user", "content": "Hello"}],
)
Lo streaming segue la stessa logica, con una trappola che spesso costa mezz’ora di debug: il frammento ricevuto è ora incapsulato e il suo contenuto si legge attraverso un livello intermedio .data. Il codice legacy 0.x copiato così com’è solleva un AttributeError sul primo frammento.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x e successive
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
La guida ufficiale 1.0 fornisce la tabella completa. Le mappature più frequenti sono:
| 0.x | 1.x e successive |
|---|---|
client.chat / client.chat_stream | client.chat.complete / client.chat.stream |
client.completions (FIM) | client.fim.complete |
client.embeddings(model=..., input=[...]) | client.embeddings.create(model=..., inputs=[...]) |
client.list_models() | client.models.list() |
client.files.create(...) | client.files.upload(...) |
client.jobs.create(...) | client.fine_tuning.jobs.create(...) |
MistralAsyncClient e i suoi metodi | Varianti _async: client.chat.complete_async, client.chat.stream_async… |
Da 1.x a 2.x: tutto si sposta sotto mistralai.client
La versione 2.0 non ha toccato i nomi dei metodi: client.chat.complete rimane client.chat.complete. Ha cambiato l’indirizzo di tutto il resto. L’SDK è diventato un namespace package (PEP 420) e tutte le importazioni sono migrate da mistralai a mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x e successive
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Nota la terza riga: le classi di errore non vivono più tra i modelli ma in mistralai.client.errors, con MistralError come base comune (da cui ereditano SDKError e HTTPValidationError).
I client per i cloud provider si sono uniti allo stesso namespace. Nella 1.x, venivano distribuiti con il pacchetto mistralai ma in moduli separati, mistralai_azure e mistralai_gcp:
# 1.x
from mistralai_azure import MistralAzure
client = MistralAzure(azure_endpoint="https://your-endpoint.inference.ai.azure.com", azure_api_key="your-azure-key")
from mistralai_gcp import MistralGoogleCloud
client = MistralGoogleCloud(region="europe-west4", project_id="my-project")
# 2.x e successive
from mistralai.azure.client import MistralAzure
client = MistralAzure(server_url="https://your-endpoint.inference.ai.azure.com", api_key="your-azure-key")
from mistralai.gcp.client import MistralGCP # pip install "mistralai[gcp]"
client = MistralGCP(region="europe-west4", project_id="my-project")
Altri tre cambiamenti nella 2.0 potrebbero riguardarti. La versione minima è ora Python 3.10 (la 1.9.11 accettava Python 3.9). 42 tipi sono stati rinominati secondo una convenzione regolare: {Verb}{Entity}Request per le richieste e {Verb}{Entity}Response per le risposte. L’unica rinomina visibile nel codice comune è Tools, diventato ConversationRequestTool. Infine, le enumerazioni accettano ora valori sconosciuti, quindi un nuovo valore aggiunto dall’API non manda più in crash una versione precedente dell’SDK.
Da 2.x a 3.x: httpx2 e strumenti integrati
La versione 3.0, rilasciata il 28 settembre 2026, non cambia né le importazioni né i metodi comuni. Tuttavia, tre punti possono bloccare un progetto:
- Il client HTTP diventa
httpx2. Se passi il tuo client all’SDK (parametriclient=oasync_client=, ad esempio per un proxy o header comuni), deve essere un clienthttpx2; anche le richieste di trasporto grezze, le risposte e gli errori sono tipihttpx2. - Gli strumenti integrati lasciano le completamenti chat.
client.chat.completeeclient.agents.completenon accettano più gli strumentiweb_search,web_search_premiumecode_interpreter: si usano tramite le API Conversations (client.beta.conversations) o un agente. La documentazione Mistral spiega il perché: le risposte di completamento chat non possono trasportare i riferimenti restituiti da questi strumenti. - Gli extra
mcpeagentssi basano ora su MCP 2.2.
La versione 3.0 aggiunge anche l’autenticazione tramite token di service account: Mistral() legge il token dal file specificato dalla variabile d’ambiente MISTRAL_SA_TOKEN_PATH.
E per TypeScript?
Il passaggio dal client JavaScript legacy 0.x all’SDK TypeScript 1.x rispecchia quasi esattamente la transizione Python. L’importazione cambia da un export default a un named export, il costruttore accetta un oggetto di configurazione e i metodi diventano a catena:
// 0.x (legacy)
import MistralClient from '@mistralai/mistralai';
const client = new MistralClient(process.env.MISTRAL_API_KEY);
const response = await client.chat({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
// 1.x e successive
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const response = await client.chat.complete({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
Lo streaming passa da client.chatStream(...) a client.chat.stream(...), e, come in Python, il contenuto si legge tramite chunk.data:
const stream = await client.chat.stream({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
for await (const chunk of stream) {
const content = chunk.data.choices[0]?.delta.content;
// content può anche essere una lista di frammenti: scriviamo solo testo
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18 marzo 2026) ha mantenuto queste importazioni, ma l’SDK è ora pubblicato come solo moduli ES: un require('@mistralai/mistralai') in CommonJS non funziona più. La validazione runtime passa a Zod v4, il che influisce solo sui progetti che importano schemi direttamente dall’SDK. E i client cloud vivono in pacchetti separati: @mistralai/mistralai-azure (MistralAzure) e @mistralai/mistralai-gcp (MistralGCP, ex MistralGoogleCloud).
Eseguire la migrazione
Su un progetto reale, procedi in un ordine definito invece di correggere gli errori man mano che appaiono. Inizia identificando la generazione del codice tramite le sue importazioni, quindi aggiorna il pacchetto (pip install --upgrade mistralai o npm install @mistralai/mistralai@latest): finché è installata la vecchia versione, stai correggendo alla cieca. Poi procedi come segue:
- Cerca le vecchie importazioni:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Sostituiscile secondo le mappature di questa lezione, non dimenticare gli errori, che si spostano in
mistralai.client.errors - Aggiorna le chiamate: metodi a catena,
inputsal plurale per gli embedding,.datanei loop di streaming - Sposta gli strumenti integrati (
web_search,code_interpreter) dai completamenti chat alle API Conversations
Infine, testa ogni endpoint che usi, uno per uno: chat, embedding e streaming hanno ciascuno le proprie modifiche, e un progetto che si avvia non chiama necessariamente tutti e tre correttamente.
Se non puoi migrare immediatamente
Nessuna di queste versioni offre una modalità di transizione o alias di compatibilità. Se un blocco della produzione ti impedisce di migrare, fissa esplicitamente la versione nelle tue dipendenze; altrimenti, la prossima installazione recupererà l’ultima versione e romperà l’applicazione:
# Python: resta sulla 1.x
pip install "mistralai<2"
# Python: resta sulla 2.x
pip install "mistralai>=2,<3"
# npm: resta sulla 1.x
npm install @mistralai/mistralai@1
Considera questo fissaggio come una tregua: le nuove funzionalità arrivano solo nella versione corrente.
Fonti ufficiali: Guida migrazione 0.x → 1.0 · Note di rilascio Python 2.0.0 · Note di rilascio Python 3.0.0 · Note di rilascio TypeScript 2.0.0 · Cronologia versioni su PyPI · Websearch — strumenti integrati
Punti chiave
- Identifica la generazione del codice dalla sua importazione:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x e 3.x) - La 1.0 (ago 2024) ha introdotto il client
Mistral, i metodi a catena e il livello.dataper lo streaming - La 2.0 (mar 2026) ha spostato tutte le importazioni Python sotto
mistralai.client, gli errori sottomistralai.client.errorse alzato il minimo a Python 3.10 - La 3.0 (set 2026) passa a
httpx2e riservaweb_searchecode_interpreterper le API Conversations e gli agenti - In TypeScript, l’importazione non è cambiata dalla 1.x, ma la 2.0 accetta solo moduli ES