Migration du SDK V1 vers V2 — API Mistral — Démarrage Rapide

Pourquoi une V2 ?

La version 2 du SDK Mistral, sortie en 2025, représente une refonte majeure de l’architecture client. 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 compilent plus. Dans les deux cas, la cause est la même et cette leçon vous donne la table de correspondance pour migrer proprement.

Trois objectifs guidaient cette refonte : rendre l’API cohérente entre Python et TypeScript, pour qu’un exemple se transpose d’un langage à l’autre sans surprise ; mieux supporter le streaming asynchrone ; et intégrer nativement les providers cloud — Azure, Google Cloud, AWS — plutôt que de les reléguer dans des packages annexes.

Ce qui change en Python

La modification la plus visible concerne l’import et la construction du client. MistralClient disparaît au profit de Mistral, et le module d’origine change également :

# V1 (ancien)
from mistralai.client import MistralClient
client = MistralClient(api_key="...")

# V2 (actuel)
from mistralai import Mistral
client = Mistral(api_key="...")

Vient ensuite le passage des méthodes à plat aux méthodes chaînées. En V1, client.chat(...) était un appel direct ; en V2, chat devient un espace de noms qui regroupe les opérations de conversation, et l’on descend d’un cran pour atteindre complete(). C’est cette structure qui rend le SDK lisible quand les fonctionnalités se multiplient.

# V1 — méthode à plat
response = client.chat(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Bonjour"}]
)

# V2 — méthode chaînée
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Bonjour"}]
)

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

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

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

Les embeddings changent eux aussi de forme, et pas seulement de méthode : le paramètre input au singulier devient inputs au pluriel, ce qui reflète mieux le fait que l’endpoint traite un lot de textes.

# V1
response = client.embeddings(model="mistral-embed", input=["texte"])

# V2
response = client.embeddings.create(model="mistral-embed", inputs=["texte"])

Ce qui change en TypeScript

Côté TypeScript, l’import passe d’un export par défaut à un export nommé, et le constructeur n’accepte plus une simple chaîne : il prend un objet de configuration. C’est ce qui permet d’ajouter d’autres options — une URL de serveur, une région — sans multiplier les arguments positionnels.

// V1 (ancien)
import MistralClient from '@mistralai/mistralai';
const client = new MistralClient(process.env.MISTRAL_API_KEY);

// V2 (actuel)
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

Le chaînage des méthodes s’applique de la même façon qu’en Python, ce qui est précisément l’intérêt de la refonte : un exemple Python se traduit désormais ligne à ligne.

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

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

Le streaming abandonne le nom chatStream pour chat.stream, et devient une méthode asynchrone qu’il faut attendre avant de parcourir le flux. Oublier ce await produit une erreur peu explicite au moment du for await — gardez-le en tête.

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

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

Les clients cloud rapatriés dans le SDK

L’un des gains les plus concrets de la V2 concerne les providers cloud : les clients Azure, Google Cloud et AWS ne vivent plus dans des packages séparés à installer et à versionner à part, ils font partie du SDK principal. Pour Azure, le client dédié cède la place au client standard configuré avec une URL de serveur, et le paramètre azure_endpoint de la V1 devient server_url :

# V1 — package séparé
from mistralai.azure.client import MistralAzure

# V2 — intégré, paramètre renommé
from mistralai import Mistral

client = Mistral(
    api_key="votre-cle-azure",
    server_url="https://votre-endpoint.inference.ai.azure.com"
)

Même principe pour Google Cloud : le package mistralai-gcp, qu’il fallait installer en plus et maintenir aligné avec le SDK principal, n’a plus lieu d’être. Le client se trouve désormais dans le sous-module mistralai.gcp.

# V1 — package séparé mistralai-gcp
from mistralai_gcp import MistralGCP

# V2 — intégré
from mistralai.gcp import MistralGCP
client = MistralGCP()

Conduire la migration

Sur un projet réel, procédez dans un ordre défini plutôt qu’au fil des erreurs de compilation. Commencez par mettre à jour le package, avec pip install "mistralai>=2" ou npm install @mistralai/mistralai@latest selon le langage : tant que l’ancienne version est installée, vous corrigerez du code à l’aveugle. Enchaînez ensuite sur les quatre opérations suivantes :

Recherchez les anciens imports : MistralClient, MistralAzure, chat_stream, chatStream
Remplacez les imports selon les correspondances vues plus haut
Mettez à jour les appels de méthodes : client.chat(...) devient client.chat.complete(...)
Ajoutez .data dans les boucles de streaming

Testez enfin chaque endpoint que vous utilisez, un par un : ce n’est pas une formalité, car chat, embeddings et streaming ont chacun leur propre changement de signature, et rien ne garantit qu’un projet qui compile appelle correctement les trois. Terminez par le ménage en désinstallant les packages V1 séparés, mistralai-gcp et consorts, sans quoi un import oublié continuera de fonctionner en silence et vous croirez la migration terminée alors qu’une partie du code tourne encore sur l’ancienne bibliothèque.

Si vous ne pouvez pas migrer tout de suite

La V2 n’est pas rétrocompatible avec la V1 : il n’existe pas de mode de transition ni d’alias de compatibilité. Si un gel de production vous empêche de migrer maintenant, la seule stratégie tenable consiste à figer explicitement la version dans vos dépendances, faute de quoi la prochaine installation de l’environnement récupérera la V2 et cassera l’application.

# Python
pip install "mistralai<2"

# npm
npm install @mistralai/mistralai@1

Considérez toutefois ce gel comme un sursis, pas comme une solution : la V1 ne reçoit plus de nouvelles fonctionnalités, et tout ce qui arrivera dans le SDK vous sera inaccessible. La migration vers la V2 est fortement recommandée pour tout projet actif.

Points clés à retenir

La V2 unifie l’API entre Python et TypeScript avec des méthodes chaînées (client.chat.complete())
Les imports changent : Mistral remplace MistralClient
Le streaming ajoute un niveau .data pour accéder au contenu des chunks
Les clients cloud (Azure, GCP) sont intégrés au SDK principal — plus de packages séparés
La V1 n’est plus maintenue — planifiez votre migration vers la V2