max_completion_tokens et budget de tokens

Le plafond qui contrôle tout

Le paramètre max_completion_tokens est probablement le plus important à comprendre quand vous utilisez des modèles de raisonnement. Contrairement à max_tokens sur les modèles classiques, ce paramètre limite le total combiné des tokens de sortie et des tokens de raisonnement.

Différence entre max_tokens et max_completion_tokens

Sur un modèle classique (sans raisonnement), max_tokens contrôle uniquement la longueur de la réponse. Sur un modèle de raisonnement, la logique change :

max_completion_tokens = tokens de réponse visible + tokens de raisonnement

Si vous définissez max_completion_tokens: 2000 et que le modèle utilise 1500 tokens pour raisonner, il ne lui reste que 500 tokens pour sa réponse. Si son raisonnement nécessite 1900 tokens, il n’a plus que 100 tokens pour répondre, ce qui peut produire une réponse tronquée ou incomplète.

Impact concret

Scénario 1 : budget suffisant

{
  "model": "grok-4.20-reasoning",
  "max_completion_tokens": 4000,
  "messages": [{"role": "user", "content": "Expliquez le quicksort."}]
}

Résultat : le modèle utilise environ 800 tokens de raisonnement et 600 tokens de réponse. Total : 1400 tokens, bien en dessous du plafond. Tout va bien.

Scénario 2 : budget insuffisant

{
  "model": "grok-4.20-reasoning",
  "max_completion_tokens": 500,
  "reasoning": {"effort": "high"},
  "messages": [{"role": "user", "content": "Démontrez le théorème fondamental de l'algèbre."}]
}

Résultat : le modèle tente un raisonnement approfondi (effort high) qui nécessiterait 2000+ tokens. Avec un plafond de 500, le raisonnement est tronqué et la réponse est soit inexistante, soit incomplète.

Dimensionner correctement

La bonne approche est d’estimer la consommation totale et d’ajouter une marge. Voici des ordres de grandeur :

Gestion dynamique en production

En production, vous ne connaissez pas à l’avance la complexité de chaque requête. Une approche robuste est d’adapter dynamiquement le budget :

def get_max_tokens(effort, expected_response_length="medium"):
    base = {
        "low": 500,
        "medium": 2000,
        "high": 6000
    }
    response_budget = {
        "short": 500,
        "medium": 1000,
        "long": 3000
    }
    return base[effort] + response_budget[expected_response_length]

# Utilisation
max_tokens = get_max_tokens("high", "long")  # 9000

Détection de troncature

Quand la réponse est tronquée à cause de max_completion_tokens, le champ finish_reason de la réponse indique "length" au lieu de "stop". Vous pouvez détecter cette situation et réagir :

response = client.chat.completions.create(
    model="grok-4.20-reasoning",
    messages=[{"role": "user", "content": question}],
    max_completion_tokens=2000
)

if response.choices[0].finish_reason == "length":
    # La réponse a été tronquée - relancer avec un budget plus élevé
    response = client.chat.completions.create(
        model="grok-4.20-reasoning",
        messages=[{"role": "user", "content": question}],
        max_completion_tokens=8000
    )

Ne pas confondre avec la limite de contexte

max_completion_tokens est indépendant de la fenêtre de contexte du modèle (2M tokens pour grok-4.20-reasoning). La fenêtre de contexte limite la taille totale de l’entrée + sortie. max_completion_tokens limite uniquement la partie sortie.

En pratique, vous atteindrez la limite de max_completion_tokens bien avant la fenêtre de contexte.

Points clés à retenir

• max_completion_tokens = tokens de réponse + tokens de raisonnement combinés
• Un budget trop bas avec un effort élevé provoque une troncature (finish_reason: "length")
• Prévoyez 2x à 4x le budget d’un modèle classique pour un modèle de raisonnement
• Détectez la troncature via finish_reason et relancez si nécessaire
• Adaptez dynamiquement le budget en fonction de l’effort et de la taille de réponse attendue