Comptage des tokens de raisonnement

Comprendre les tokens de raisonnement

Les modèles de raisonnement consomment deux types de tokens de sortie : les tokens de la réponse visible et les tokens de raisonnement (la réflexion interne du modèle). Comprendre cette distinction est essentiel pour maîtriser vos coûts et dimensionner vos requêtes correctement.

L’objet usage dans la réponse

Chaque réponse de l’API inclut un objet usage qui détaille la consommation de tokens. Pour les modèles de raisonnement, un champ spécifique indique les tokens de raisonnement :

{
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 856,
    "total_tokens": 898,
    "completion_tokens_details": {
      "reasoning_tokens": 612
    }
  }
}

Dans cet exemple :

• prompt_tokens (42) : tokens du message d’entrée
• completion_tokens (856) : total des tokens de sortie (réponse + raisonnement)
• reasoning_tokens (612) : tokens consacrés au raisonnement interne

La réponse visible consomme donc 856 - 612 = 244 tokens, mais la facturation porte sur les 856 tokens de sortie au complet.

Accéder aux tokens de raisonnement en code

response = client.responses.create(
    model="grok-4.20-reasoning",
    input="Résolvez l'intégrale de x^2 * e^x dx.",
    reasoning={"effort": "high"}
)

# Tokens totaux
total = response.usage.completion_tokens
# Tokens de raisonnement
reasoning = response.usage.completion_tokens_details.reasoning_tokens
# Tokens de réponse visible
visible = total - reasoning

print(f"Tokens de raisonnement : {reasoning}")
print(f"Tokens de réponse : {visible}")
print(f"Total sortie : {total}")
print(f"Ratio raisonnement : {reasoning/total*100:.0f}%")

Facturation comme tokens de sortie

Les tokens de raisonnement sont facturés au même tarif que les tokens de sortie classiques. Pour grok-4.20-reasoning à 6,00 $ par million de tokens en sortie, chaque token de raisonnement coûte exactement le même prix qu’un token de réponse.

Cela signifie qu’une requête avec un effort high peut facilement coûter 5 à 10 fois plus qu’un effort low, principalement à cause du volume de tokens de raisonnement.

Exemple de calcul de coût

# grok-4.20-reasoning : 6.00 $/M tokens sortie
cout_par_token = 6.00 / 1_000_000

# Requête avec effort high
reasoning_tokens = 2400
response_tokens = 350
total_sortie = reasoning_tokens + response_tokens  # 2750

cout = total_sortie * cout_par_token
print(f"Coût sortie : ${cout:.4f}")  # $0.0165

Le rôle de max_completion_tokens

Le paramètre max_completion_tokens plafonne le nombre total de tokens de sortie, raisonnement inclus. C’est un point crucial : si vous définissez max_completion_tokens: 1000 et que le modèle consomme 800 tokens de raisonnement, il ne reste que 200 tokens pour la réponse visible.

{
  "model": "grok-4.20-reasoning",
  "messages": [
    {"role": "user", "content": "Expliquez la relativité restreinte."}
  ],
  "max_completion_tokens": 2000
}

Risque de troncature

Avec un effort high et un max_completion_tokens trop bas, le modèle peut épuiser son budget de tokens sur le raisonnement et produire une réponse tronquée ou incomplète. La bonne pratique est de prévoir un budget suffisant pour les deux :

• Effort low : max_completion_tokens = 2x la taille attendue de la réponse
• Effort medium : max_completion_tokens = 4x la taille attendue
• Effort high : max_completion_tokens = 8x la taille attendue ou plus

Points clés à retenir

• Les tokens de raisonnement sont dans usage.completion_tokens_details.reasoning_tokens
• Ils sont facturés au tarif des tokens de sortie
• completion_tokens = tokens de réponse + tokens de raisonnement
• max_completion_tokens plafonne le total (réponse + raisonnement)
• Prévoyez un budget de tokens suffisant pour éviter la troncature de la réponse