Migration du SDK V1 vers V2

Pourquoi une V2 ?

La version 2 du SDK Mistral (sortie en 2025) représente une refonte majeure de l’architecture client. Si vous maintenez du code écrit avec la V1 ou si vous consultez des tutoriels plus anciens, cette leçon vous guidera à travers les changements nécessaires pour migrer proprement.

Les principaux objectifs de la V2 étaient : une API plus cohérente entre Python et TypeScript, un meilleur support du streaming asynchrone, et l’intégration native des providers cloud (Azure, Google Cloud, AWS).

Changements en Python

Import du client

La modification la plus visible concerne l’import :

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

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

Méthodes d’appel

# 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"}]
)

Streaming

# 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)

Notez le .data supplémentaire en V2 pour accéder au contenu du chunk.

Embeddings

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

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

Le paramètre input (singulier) devient inputs (pluriel) en V2.

Changements en TypeScript

Import et initialisation

// 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 });

En V2, le client prend un objet de configuration au lieu d’un simple argument string.

Méthodes d’appel

// 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' }],
});

Streaming TypeScript

// 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' }],
});

Clients cloud intégrés

Un des avantages majeurs de la V2 : les clients pour Azure, Google Cloud et AWS sont maintenant intégrés au SDK principal.

Azure AI

# 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"
)

Le paramètre azure_endpoint de la V1 est remplacé par server_url en V2.

Google Cloud / Vertex AI

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

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

Plus besoin d’installer un package séparé.

Guide de migration pas à pas

1. Mettez à jour le package : pip install "mistralai>=2" ou npm install @mistralai/mistralai@latest
2. Recherchez les anciens imports : MistralClient, MistralAzure, chat_stream, chatStream
3. Remplacez les imports selon le tableau ci-dessus
4. Mettez à jour les appels de méthodes : client.chat(...) devient client.chat.complete(...)
5. Ajoutez .data dans les boucles de streaming
6. Testez chaque endpoint que vous utilisez
7. Supprimez les packages V1 séparés (mistralai-gcp, etc.)

Rétrocompatibilité

La V2 n’est pas rétrocompatible avec la V1. Si vous ne pouvez pas migrer immédiatement, figez la version dans vos dépendances :

# Python
pip install "mistralai<2"

# npm
npm install @mistralai/mistralai@1

Cependant, la V1 ne reçoit plus de nouvelles fonctionnalités. 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