Le paramètre reasoning_effort

Leçon réécrite le 2 novembre 2026. La version précédente affirmait que reasoning_effort n’acceptait que deux valeurs et n’existait que sur Mistral Small. Les valeurs dépendent en réalité du modèle, et Mistral Large 4 en propose trois. Source : Reasoning (documentation Mistral).

Régler la profondeur de réflexion

Le raisonnement ajustable repose sur un principe simple : vous décidez, requête par requête, combien le modèle doit réfléchir avant de répondre. Le levier s’appelle reasoning_effort. Il se passe dans l’appel au même niveau que le modèle et les messages, sans aucune autre configuration.

Les valeurs acceptées, modèle par modèle

C’est le point qui piège le plus souvent : les valeurs acceptées dépendent du modèle.

Sur Small 4 et Medium 3.5, high produit un fragment de réflexion complet avant la réponse, au prix d’une consommation de tokens accrue ; none réduit la réflexion au minimum et l’omet de la réponse. Sur Large 4, l’échelle compte trois niveaux : low pour les tâches simples, medium pour équilibrer qualité, tokens et latence, high pour les tâches complexes. Large 4 n’accepte pas none : la documentation précise que le niveau autrefois appelé none dans sa préversion s’appelle désormais low.

Une dernière subtilité : le type ReasoningEffort des SDK énumère aussi minimal, xhigh et max, parce que l’énumération couvre tous les modèles de la plateforme (max sert par exemple au modèle tiers zai-glm-5-3). Qu’une valeur figure dans l’énumération ne signifie pas que votre modèle l’accepte.

Implémentation en Python

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Mistral Small 4, raisonnement poussé
response_high = client.chat.complete(
    model="mistral-small-2603",
    messages=[{"role": "user", "content": "Résous x^3 - 6x^2 + 11x - 6 = 0 et vérifie chaque racine."}],
    reasoning_effort="high",
)

# Mistral Small 4, réponse directe
response_none = client.chat.complete(
    model="mistral-small-2603",
    messages=[{"role": "user", "content": "Quelle est la capitale du Portugal ?"}],
    reasoning_effort="none",
)

# Mistral Large 4, niveau intermédiaire
response_medium = client.chat.complete(
    model="mistral-large-4-0",
    messages=[{"role": "user", "content": "Compare deux stratégies de cache pour une API à fort trafic."}],
    reasoning_effort="medium",
)

La forme de la réponse change avec le réglage. Avec high, message.content est une liste qui commence par un fragment de réflexion ; avec none, c’est une simple chaîne de caractères. Votre code doit donc accepter les deux formes, ce que montre la leçon suivante.

En TypeScript, le paramètre suit la casse JavaScript et s’écrit reasoningEffort :

import { Mistral } from '@mistralai/mistralai';

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.chat.complete({
  model: 'mistral-small-2603',
  messages: [{ role: 'user', content: 'Résous x^3 - 6x^2 + 11x - 6 = 0.' }],
  reasoningEffort: 'high',
});

Choisir le niveau selon la tâche

Réservez le raisonnement poussé aux problèmes mathématiques multi-étapes, au debugging de code complexe, à l’analyse comparative, à la planification, aux énigmes logiques et à l’évaluation de risques. Leur point commun : plusieurs chemins sont possibles, et se tromper de chemin coûte cher.

Coupez-le (ou descendez au plus bas) pour les questions factuelles simples, la traduction, la reformulation, l’extraction directe d’informations et les échanges conversationnels courants. Le modèle n’a alors rien à arbitrer : il restitue ou transforme, et une phase de réflexion n’ajouterait que de la latence.

Mesurer le coût

Le raisonnement se paie en tokens de sortie. L’exemple de la documentation officielle donne un ordre de grandeur : une énigme d’âges, posée à Mistral Small 4 en high, consomme 77 tokens d’entrée et 1 114 tokens de sortie. Au tarif affiché de Small 4, 0,15 $ par million de tokens d’entrée et 0,60 $ par million en sortie, la requête coûte environ 0,0007 $. C’est négligeable à l’unité, mais sur un million de requêtes comparables la seule réflexion représente plusieurs centaines de dollars, sans gain si la moitié des questions n’en demandait aucune.

Le champ usage de chaque réponse vous donne la mesure exacte : suivez completion_tokens par type de requête avant de généraliser un réglage.

Router selon la complexité

Une parade simple consiste à choisir le niveau à partir de la question, avec une table par modèle pour ne jamais envoyer une valeur refusée :

NIVEAUX = {
    "mistral-small-2603": {"simple": "none", "complexe": "high"},
    "mistral-large-4-0": {"simple": "low", "complexe": "high"},
}

MOTS_COMPLEXES = ("calcule", "démontre", "compare", "analyse", "optimise", "debug", "pourquoi")

def interroger(client, question, model="mistral-small-2603", niveau=None):
    """Choisit reasoning_effort selon la question, ou applique le niveau imposé."""
    if niveau is None:
        complexe = any(mot in question.lower() for mot in MOTS_COMPLEXES)
        niveau = NIVEAUX[model]["complexe" if complexe else "simple"]
    return client.chat.complete(
        model=model,
        messages=[{"role": "user", "content": question}],
        reasoning_effort=niveau,
    )

L’heuristique par mots-clés reste grossière ; elle suffit à réserver le raisonnement aux requêtes qui en tirent profit, et l’argument niveau permet de forcer un réglage. La leçon 12 propose une architecture de routage plus complète.

Limites à connaître

Le raisonnement augmente la probabilité d’une réponse juste, il ne la garantit pas : les résultats critiques se vérifient (leçon 9). Il allonge aussi la latence, ce qui compte dans une interface conversationnelle. Enfin, la valeur passée doit correspondre au modèle appelé : prévoyez une table comme celle ci-dessus plutôt que des chaînes dispersées dans le code.

Points clés à retenir

• reasoning_effort règle la réflexion requête par requête, sans autre configuration
• Small 4 et Medium 3.5 acceptent high et none ; Large 4 accepte low, medium et high, pas none
• L’énumération des SDK contient des valeurs que tous les modèles n’acceptent pas
• Avec high, content est une liste de fragments ; avec none, une chaîne
• Mesurez le coût avec usage.completion_tokens et routez selon la complexité