Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Migrare tra le versioni dell'SDK Mistral

Lezione 10 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Perché questa lezione è importante
  2. Quattro generazioni in due anni
  3. Da 0.x a 1.x: il client Mistral e i metodi a catena
  4. Da 1.x a 2.x: tutto si sposta sotto mistralai.client
  5. Da 2.x a 3.x: httpx2 e strumenti integrati
  6. E per TypeScript?
  7. Eseguire la migrazione
  8. Se non puoi migrare immediatamente
  9. Punti chiave

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 a process.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

GenerazionePython (mistralai)TypeScript (@mistralai/mistralai)Caratteristica distintiva del codice
0.xfino a 0.4.2 (luglio 2024)fino a 0.5.0 (giugno 2024)MistralClient, metodi piatti: client.chat(...)
1.x1.0.0 (7 ago 2024) → 1.9.11 (ott 2025)da ago 2024from mistralai import Mistral, metodi a catena: client.chat.complete(...)
2.x2.0.0 (10 mar 2026)2.0.0 (18 mar 2026)Python: from mistralai.client import Mistral; TypeScript: solo moduli ES
3.x3.0.0 (28 set 2026), 3.7.0 al 1° nov 20263.0 (ott 2026), 3.5.0 oggiPython: 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.x1.x e successive
client.chat / client.chat_streamclient.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 metodiVarianti _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 (parametri client= o async_client=, ad esempio per un proxy o header comuni), deve essere un client httpx2; anche le richieste di trasporto grezze, le risposte e gli errori sono tipi httpx2.
  • Gli strumenti integrati lasciano le completamenti chat. client.chat.complete e client.agents.complete non accettano più gli strumenti web_search, web_search_premium e code_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 mcp e agents si 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:

  1. Cerca le vecchie importazioni: MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
  2. Sostituiscile secondo le mappature di questa lezione, non dimenticare gli errori, che si spostano in mistralai.client.errors
  3. Aggiorna le chiamate: metodi a catena, inputs al plurale per gli embedding, .data nei loop di streaming
  4. 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 .data per lo streaming
  • La 2.0 (mar 2026) ha spostato tutte le importazioni Python sotto mistralai.client, gli errori sotto mistralai.client.errors e alzato il minimo a Python 3.10
  • La 3.0 (set 2026) passa a httpx2 e riserva web_search e code_interpreter per le API Conversations e gli agenti
  • In TypeScript, l’importazione non è cambiata dalla 1.x, ma la 2.0 accetta solo moduli ES