Reasoning effort : low, medium et high

Leçon corrigée le 3 novembre 2026 d’après la référence de l’API xAI : max_completion_tokens ne plafonne que la réponse visible ; les tokens de raisonnement n’y comptent pas, et c’est l’effort qui règle leur quantité. Source : Chat Completions. Complément du 3 novembre : la leçon liait l’effort à l’API (Chat Completions ou Responses) et l’appliquait à grok-4.20-0309-reasoning, qui ne le prend pas ; d’après la page Reasoning de xAI, il dépend du modèle (grok-4.7, grok-4.6, grok-4.5, grok-4.20-multi-agent). L’exemple lisait aussi usage.completion_tokens, absent des réponses de l’API Responses (output_tokens, output_tokens_details.reasoning_tokens). Source : Reasoning.

Contrôler la profondeur de réflexion

L’effort de raisonnement vous permet de calibrer la quantité de réflexion que le modèle investit avant de répondre. C’est un levier direct sur le compromis entre qualité, vitesse et consommation de tokens.

Ce n’est pas l’API qui décide s’il est disponible, c’est le modèle. D’après la documentation de xAI :

Le raisonnement ne se désactive pas sur ces modèles : sans réglage, l’effort vaut high. Seul le nom du paramètre change selon l’API : reasoning_effort au premier niveau en Chat Completions, reasoning.effort dans un objet reasoning avec l’API Responses.

{
  "model": "grok-4.7",
  "input": "Résolvez le système d'équations : 3x + 2y = 12, x - y = 1",
  "reasoning": {
    "effort": "medium"
  }
}

Les niveaux d’effort

La documentation décrit chaque niveau et l’usage qui lui convient :

• low : utilise un peu de raisonnement tout en restant rapide. Pour les usages agentiques sensibles à la latence et les appels d’outils simples.
• medium : davantage de réflexion, pour les applications moins sensibles à la latence. Pour l’analyse de données complexe et le raisonnement sur un long contexte.
• high (par défaut) : beaucoup plus de tokens de raisonnement. Pour les problèmes très difficiles, les mathématiques complexes, la logique en plusieurs étapes.
• xhigh : la profondeur maximale, avec une latence à l’avenant. Pour les problèmes les plus durs, quand la qualité compte plus que le temps de réponse.

Les bonnes pratiques de xAI ajoutent une règle simple : fixez l’effort explicitement à chaque requête, et notez-le avec chaque résultat, pour que vos mesures restent comparables.

Les modèles de raisonnement refusent aussi trois paramètres : presence_penalty, frequency_penalty et stop font échouer la requête.

Impact sur les tokens

Le niveau d’effort a un impact direct sur la consommation de tokens de raisonnement :

• low : peu de tokens de raisonnement, réponse rapide, coût faible
• medium : consommation modérée, bon compromis
• high et xhigh : nombreux tokens de raisonnement, réponse plus lente, coût élevé

Ces tokens de raisonnement sont facturés comme des tokens de sortie (voir leçon 8). Le plafond de sortie (max_completion_tokens en Chat Completions, max_output_tokens dans l’API Responses) ne limite, lui, que la réponse visible : le raisonnement n’y compte pas, et c’est donc l’effort qui en règle la quantité.

Choisir le bon niveau

Exemple pratique : même question, trois efforts

for effort in ["low", "medium", "high"]:
    response = client.responses.create(
        model="grok-4.7",
        input="Expliquez pourquoi 0.1 + 0.2 != 0.3 en informatique.",
        reasoning={"effort": effort},
    )
    usage = response.usage
    print(f"Effort {effort} : {usage.output_tokens} tokens de sortie, "
          f"dont {usage.output_tokens_details.reasoning_tokens} de raisonnement")

L’écart entre les niveaux dépend de la question : mesurez-le sur vos propres cas plutôt que de vous fier à un ratio général, et notez l’effort avec chaque résultat.

Points clés à retenir

• L’effort dépend du modèle : low, medium, high (par défaut) et xhigh sur grok-4.7 et grok-4.6, sans xhigh sur grok-4.5 ; grok-4.20-0309-reasoning ne le prend pas
• reasoning_effort en Chat Completions, reasoning.effort dans l’API Responses ; le raisonnement ne se désactive pas
• Le niveau d’effort impacte directement le nombre de tokens de raisonnement et donc le coût
• Sans réglage, l’effort vaut high : fixez-le explicitement à chaque requête, comme le recommande xAI
• Adaptez l’effort à la complexité réelle de la tâche pour optimiser vos coûts