Les Modèles Magistral

⚠️ Modèle déprécié (mise à jour du 28 juillet 2026) : les modèles Magistral sont dépréciés par Mistral, avec des retraits échelonnés jusqu’à mi-2026. Le raisonnement est désormais intégré aux modèles généralistes (Mistral Small 4, Medium 3.5). Les concepts de ce cours restent instructifs, mais ne construisez plus de nouveau projet sur Magistral — consultez le cours « Mistral en 2026 » pour la migration.

Une famille dédiée au raisonnement

Les modèles Magistral de Mistral AI ne sont pas des modèles génériques auxquels on ajoute du raisonnement. Ce sont des modèles conçus dès le départ pour raisonner. Chaque token généré par un Magistral passe par un processus de réflexion structuré, sans qu’il soit nécessaire d’activer quoi que ce soit — aucun paramètre équivalent à reasoning_effort n’entre en jeu.

Les deux modèles disponibles

magistral-small-latest est la version compacte, optimisée pour le rapport performance/coût. Elle brille sur la recherche, le raisonnement efficace et les tâches qui demandent une réflexion structurée sans profondeur extrême : prototypage rapide, applications à fort volume, problèmes de complexité modérée. Son alias -latest pointe vers -2509, dernière version publiée avant la dépréciation.

magistral-medium-latest est le modèle plus puissant, à l’équilibre entre performance et coût. Il vise le raisonnement approfondi, les problèmes complexes multi-étapes et l’analyse détaillée : tâches critiques, debugging avancé, démonstrations mathématiques, architecture logicielle. Son alias pointe lui aussi vers -2509.

En pratique, le choix se fait à l’appel, et l’écart de difficulté entre les deux exemples ci-dessous résume à lui seul la ligne de partage :

from mistralai import Mistral

client = Mistral(api_key="VOTRE_CLE_API")

# Pour les tâches courantes nécessitant du raisonnement
response_small = client.chat.complete(
    model="magistral-small-latest",
    messages=[{"role": "user", "content": "Résous 2x + 5 = 17"}]
)

# Pour les problèmes complexes nécessitant une réflexion profonde
response_medium = client.chat.complete(
    model="magistral-medium-latest",
    messages=[{"role": "user", "content": "Démontrez le théorème fondamental de l'algèbre par l'approche topologique."}]
)

Versions et évolution

Les modèles Magistral ont connu plusieurs versions, et la méthode de génération des traces de raisonnement a évolué en cours de route. Les versions récentes, -2509 et -2507, utilisent des control tokens tokenisés pour délimiter les traces : la séparation entre réflexion et réponse est gérée au niveau des tokens du modèle, pas par des balises textuelles. Vous récupérez donc des chunks structurés, exploitables sans expression régulière.

# Les versions récentes retournent des chunks structurés
response = client.chat.complete(
    model="magistral-medium-latest",  # pointe vers -2509
    messages=[{"role": "user", "content": "Votre question..."}]
)

# content est un tableau de chunks
for chunk in response.choices[0].message.content:
    print(f"Type: {chunk.type}")

La version -2506 fonctionnait tout autrement : elle délimitait le raisonnement par des tags XML placés dans une simple chaîne de caractères.

<think>
Voici mon raisonnement étape par étape...
1. D'abord, j'analyse le problème...
2. Ensuite, je considère les options...
</think>

Voici ma réponse finale structurée.

Cette approche est désormais obsolète. Si vous migrez depuis -2506, votre code de parsing doit changer de nature : on ne découpe plus une chaîne, on parcourt un tableau typé. Le contraste entre les deux fonctions suivantes montre exactement ce qui doit disparaître et ce qui le remplace.

# ANCIEN code pour -2506
def parse_old_response(text):
    """Parse les tags <think> de l'ancienne version."""
    if "<think>" in text:
        thinking = text.split("<think>")[1].split("</think>")[0]
        answer = text.split("</think>")[1].strip()
        return thinking, answer
    return None, text

# NOUVEAU code pour -2509
def parse_new_response(response):
    """Parse les chunks structurés de la nouvelle version."""
    thinking = None
    answer = ""
    for chunk in response.choices[0].message.content:
        if chunk.type == "thinking":
            # Accès aux sous-éléments du thinking
            thinking_parts = chunk.thinking
            thinking = " ".join(part.text for part in thinking_parts)
        elif chunk.type == "text":
            answer = chunk.text
    return thinking, answer

Structure de réponse Magistral

Un détail de cette fonction mérite qu’on s’y arrête, car il piège quiconque arrive du raisonnement ajustable. La structure de réponse Magistral n’est pas tout à fait celle de mistral-small-latest :

{
  "content": [
    {
      "type": "thinking",
      "thinking": [
        {"type": "text", "text": "Étape 1 : J'analyse le problème..."},
        {"type": "text", "text": "Étape 2 : Je considère les cas..."}
      ]
    },
    {
      "type": "text",
      "text": "Voici ma réponse finale..."
    }
  ]
}

Chez Magistral, le chunk thinking contient un sous-tableau thinking composé d’éléments de type text. Dans le raisonnement ajustable, ce même chunk expose directement un champ text. Un code écrit pour Small qui lirait chunk.text sur une réponse Magistral n’obtiendrait donc rien d’exploitable — d’où la jointure " ".join(...) du parseur précédent.

Spécifier une version précise

Pour garantir la stabilité de votre application en production, spécifiez une version exacte plutôt que l’alias mouvant :

# Version précise pour la production
response = client.chat.complete(
    model="magistral-medium-2509",  # version fixe
    messages=[{"role": "user", "content": "..."}]
)

# Version -latest pour le développement (suit les mises à jour)
response = client.chat.complete(
    model="magistral-medium-latest",  # pointe vers la dernière version
    messages=[{"role": "user", "content": "..."}]
)

Gardez -latest pour le développement, où suivre les mises à jour est un avantage, et privilégiez toujours une version fixe en production. Le passage silencieux de -2506 à un format de traces entièrement différent illustre assez bien ce qu’un alias peut faire subir à une application qui dormait tranquille.

Points clés à retenir

• Deux modèles : magistral-small-latest (efficace) et magistral-medium-latest (puissant)
• -latest pointe vers -2509, dernière version publiée avant la dépréciation
• Les versions récentes (-2509/-2507) utilisent des control tokens, pas des tags <think>
• La structure de réponse Magistral a un sous-tableau thinking dans le chunk thinking
• En production, spécifiez une version fixe pour la stabilité
• Migrez le parsing si vous venez de la version -2506