Migrer entre les versions du SDK Mistral

Leçon réécrite le 2 novembre 2026. La version précédente appelait « passage de la V1 à la V2 » ce qui était en réalité le passage de l’ancien client 0.x à la version 1.0, en août 2024. Depuis, le SDK Python a connu deux autres versions majeures : la 2.0 en mars 2026 et la 3.0 en septembre 2026. Cette leçon reprend l’historique complet d’après les guides de migration et les notes de version officiels. Corrigé le 3 novembre 2026 : la boucle de streaming TypeScript passait à process.stdout.write un contenu que le SDK type string | ContentChunk[], ce que le mode strict refuse.

Pourquoi cette leçon vous servira

Vous la croiserez dans deux situations : vous reprenez un projet écrit il y a quelque temps et il refuse de démarrer après une mise à jour de dépendances, ou vous suivez un tutoriel trouvé en ligne dont les exemples ne fonctionnent plus. Dans les deux cas, la première question à se poser est la même : pour quelle génération du SDK ce code a-t-il été écrit ? Une ligne suffit presque toujours à le savoir, celle de l’import.

Quatre générations en deux ans

En TypeScript, l’import import { Mistral } from '@mistralai/mistralai' n’a pas changé depuis la 1.x. En Python, il a changé deux fois : c’est là que se concentrent les pannes.

De la 0.x à la 1.x : le client Mistral et les méthodes chaînées

La 1.0 a remplacé les deux clients MistralClient (synchrone) et MistralAsyncClient (asynchrone) par une classe unique, Mistral, et les méthodes à plat par des espaces de noms : chat regroupe les opérations de conversation, et l’on descend d’un cran pour atteindre complete(). Les messages, qui s’écrivaient avec la classe ChatMessage, s’écrivent désormais en dictionnaires ou avec les classes UserMessage, SystemMessage, AssistantMessage et ToolMessage.

# 0.x (ancien)
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="Bonjour")],
)

# 1.x
from mistralai import Mistral

client = Mistral(api_key="...")
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Bonjour"}],
)

Le streaming suit la même logique, avec un piège qui coûte souvent une demi-heure de débogage : le fragment reçu est désormais enveloppé, et son contenu se lit à travers un niveau .data intermédiaire. Un code 0.x recopié tel quel lève une AttributeError dès le premier fragment.

# 0.x
for chunk in client.chat_stream(model=..., messages=...):
    print(chunk.choices[0].delta.content)

# 1.x et suivantes
for chunk in client.chat.stream(model=..., messages=...):
    print(chunk.data.choices[0].delta.content)

Le guide officiel de la 1.0 donne la table complète. Les correspondances les plus fréquentes :

De la 1.x à la 2.x : tout passe sous mistralai.client

La 2.0 n’a pas touché aux noms des méthodes : client.chat.complete reste client.chat.complete. Elle a changé l’adresse de tout le reste. Le SDK est devenu un namespace package (PEP 420), et tous les imports ont migré de mistralai vers mistralai.client :

# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError

# 2.x et suivantes
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError

Notez la troisième ligne : les classes d’erreur ne vivent plus parmi les modèles mais dans mistralai.client.errors, avec pour base commune MistralError (dont héritent SDKError et HTTPValidationError).

Les clients des fournisseurs cloud ont rejoint le même espace de noms. En 1.x, ils étaient livrés avec le package mistralai mais sous des modules à part, mistralai_azure et mistralai_gcp :

# 1.x
from mistralai_azure import MistralAzure
client = MistralAzure(azure_endpoint="https://votre-endpoint.inference.ai.azure.com", azure_api_key="votre-cle-azure")

from mistralai_gcp import MistralGoogleCloud
client = MistralGoogleCloud(region="europe-west4", project_id="mon-projet")

# 2.x et suivantes
from mistralai.azure.client import MistralAzure
client = MistralAzure(server_url="https://votre-endpoint.inference.ai.azure.com", api_key="votre-cle-azure")

from mistralai.gcp.client import MistralGCP  # pip install "mistralai[gcp]"
client = MistralGCP(region="europe-west4", project_id="mon-projet")

Trois autres changements de la 2.0 peuvent vous concerner. Le minimum passe à Python 3.10 (la 1.9.11 acceptait Python 3.9). 42 types ont été renommés selon une convention régulière, {Verbe}{Entité}Request pour les requêtes et {Verbe}{Entité}Response pour les réponses ; le seul renommage visible dans un code courant est Tools, devenu ConversationRequestTool. Enfin, les énumérations acceptent désormais des valeurs inconnues, si bien qu’une nouvelle valeur ajoutée par l’API ne fait plus planter une ancienne version du SDK.

De la 2.x à la 3.x : httpx2 et les outils intégrés

La 3.0, publiée le 28 septembre 2026, ne change ni les imports ni les méthodes courantes. Trois points peuvent pourtant casser un projet :

• Le client HTTP devient httpx2. Si vous passez votre propre client au SDK (paramètres client= ou async_client=, par exemple pour un proxy ou des en-têtes communs), ce doit être un client httpx2 ; les requêtes, réponses et erreurs de transport brutes sont aussi des types httpx2.
• Les outils intégrés quittent les chat completions. client.chat.complete et client.agents.complete n’acceptent plus les outils web_search, web_search_premium et code_interpreter : ils s’utilisent à travers l’API Conversations (client.beta.conversations) ou un agent. La documentation Mistral en donne la raison : les réponses des chat completions ne savent pas transporter les références que ces outils renvoient.
• Les extras mcp et agents s’appuient désormais sur MCP 2.2.

La 3.0 ajoute aussi l’authentification par jeton de compte de service : Mistral() lit le jeton dans le fichier indiqué par la variable MISTRAL_SA_TOKEN_PATH.

Et en TypeScript ?

Le passage de l’ancien client JavaScript 0.x au SDK TypeScript 1.x ressemble trait pour trait à celui de Python. L’import passe d’un export par défaut à un export nommé, le constructeur prend un objet de configuration, et les méthodes deviennent chaînées :

// 0.x (ancien)
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: 'Bonjour' }],
});

// 1.x et suivantes
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: 'Bonjour' }],
});

Le streaming passe de client.chatStream(...) à client.chat.stream(...), et, comme en Python, le contenu se lit à travers chunk.data :

const stream = await client.chat.stream({
  model: 'mistral-small-latest',
  messages: [{ role: 'user', content: 'Bonjour' }],
});

for await (const chunk of stream) {
  const content = chunk.data.choices[0]?.delta.content;
  // content peut aussi être une liste de fragments : on n'écrit que le texte
  if (typeof content === 'string') process.stdout.write(content);
}

La 2.0 TypeScript (18 mars 2026) a gardé ces imports, mais le SDK n’est plus publié qu’en modules ES : un require('@mistralai/mistralai') en CommonJS ne fonctionne plus. La validation à l’exécution passe à Zod v4, ce qui ne concerne que les projets qui importent directement les schémas du SDK. Et les clients cloud vivent dans des paquets séparés : @mistralai/mistralai-azure (MistralAzure) et @mistralai/mistralai-gcp (MistralGCP, anciennement MistralGoogleCloud).

Conduire la migration

Sur un projet réel, procédez dans un ordre défini plutôt qu’au fil des erreurs. Commencez par identifier la génération du code grâce à ses imports, puis mettez à jour le package (pip install --upgrade mistralai ou npm install @mistralai/mistralai@latest) : tant que l’ancienne version est installée, vous corrigez à l’aveugle. Enchaînez ensuite :

1. Recherchez les anciens imports : MistralClient, from mistralai import, from mistralai.models import, mistralai_azure, mistralai_gcp, require('@mistralai/mistralai')
2. Remplacez-les selon les correspondances de cette leçon, sans oublier les erreurs, qui passent dans mistralai.client.errors
3. Mettez à jour les appels : méthodes chaînées, inputs au pluriel pour les embeddings, .data dans les boucles de streaming
4. Déplacez les outils intégrés (web_search, code_interpreter) des chat completions vers l’API Conversations

Testez enfin chaque endpoint que vous utilisez, un par un : chat, embeddings et streaming ont chacun leurs changements, et un projet qui démarre n’appelle pas forcément correctement les trois.

Si vous ne pouvez pas migrer tout de suite

Aucune de ces versions n’offre de mode de transition ni d’alias de compatibilité. Si un gel de production vous empêche de migrer, figez explicitement la version dans vos dépendances, faute de quoi la prochaine installation récupérera la dernière version et cassera l’application :

# Python : rester en 1.x
pip install "mistralai<2"

# Python : rester en 2.x
pip install "mistralai>=2,<3"

# npm : rester en 1.x
npm install @mistralai/mistralai@1

Considérez ce gel comme un sursis : les nouvelles fonctionnalités n’arrivent que dans la version courante.

Sources officielles : guide de migration 0.x → 1.0 · notes de version Python 2.0.0 · notes de version Python 3.0.0 · notes de version TypeScript 2.0.0 · historique des versions sur PyPI · Websearch — outils intégrés

Points clés à retenir

• Repérez la génération d’un code à son import : MistralClient (0.x), from mistralai import Mistral (1.x), from mistralai.client import Mistral (2.x et 3.x)
• La 1.0 (août 2024) a introduit le client Mistral, les méthodes chaînées et le niveau .data du streaming
• La 2.0 (mars 2026) a déplacé tous les imports Python sous mistralai.client, les erreurs sous mistralai.client.errors, et relevé le minimum à Python 3.10
• La 3.0 (septembre 2026) passe à httpx2 et réserve web_search et code_interpreter à l’API Conversations et aux agents
• En TypeScript, l’import ne change pas depuis la 1.x, mais la 2.0 n’accepte plus que les modules ES