Timeout, paramètres interdits et configuration — Modèles de raisonnement Grok

Leçon corrigée le 3 novembre 2026 d’après les bonnes pratiques et le guide Reasoning de xAI : le délai d’attente conseillé est d’au moins 900 secondes (3 600 dans les exemples), et non « 3 600 secondes minimum » ; la liste des modèles de raisonnement intègre grok-4.6 et grok-4.7 ; grok-4.7 diffuse un résumé de son raisonnement en streaming ; les justifications des paramètres interdits, absentes de la documentation, sont retirées. Sources : Best practices · Reasoning.

Configurer correctement vos requêtes de raisonnement

Les modèles de raisonnement ont des contraintes spécifiques que les modèles classiques n’ont pas. Ignorer ces contraintes peut provoquer des erreurs silencieuses, des timeouts inattendus ou des réponses tronquées. Cette leçon couvre les paramètres de configuration essentiels.

Timeout : au moins 900 secondes

Les bonnes pratiques de xAI demandent de laisser au moins 900 secondes à chaque requête, et 1 800 secondes ou plus pour les évaluations longues ; les exemples du guide Reasoning fixent même le délai à 3 600 secondes (1 heure). Ces chiffres peuvent sembler élevés, mais ils reflètent une réalité : un raisonnement poussé sur un problème complexe peut durer plusieurs minutes. xAI conseille aussi de préférer le streaming, qui maintient la connexion active pendant les longues générations.

Pourquoi un timeout aussi long ?

Quand un modèle de raisonnement traite un problème difficile (preuve mathématique, analyse de code complexe, raisonnement multi-étapes), il génère potentiellement des milliers de tokens de raisonnement interne avant de formuler sa réponse. Ce processus est linéaire et ne peut pas être parallélisé.

Configuration du timeout

import httpx
from openai import OpenAI

# Configuration avec timeout élevé
client = OpenAI(
    api_key="votre-cle-api",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0, connect=10.0)
)

En JavaScript avec le SDK OpenAI :

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'votre-cle-api',
  baseURL: 'https://api.x.ai/v1',
  timeout: 3600 * 1000  // 3600 secondes en millisecondes
});

Timeout côté serveur web

Si votre application est derrière un reverse proxy (nginx, Apache), pensez aussi à configurer le timeout côté serveur :

# nginx
location /api/ {
    proxy_read_timeout 3600s;
    proxy_connect_timeout 10s;
    proxy_send_timeout 3600s;
}

Paramètres interdits sur les modèles de raisonnement

Trois paramètres couramment utilisés avec les modèles classiques ne peuvent pas être envoyés aux modèles de raisonnement de xAI : d’après le guide Reasoning, une requête qui les contient renvoie une erreur. La documentation ne donne pas la raison de ces interdictions ; retenez la règle.

presencePenalty

// ERREUR sur les modèles de raisonnement
{
  "model": "grok-4.20-0309-reasoning",
  "presence_penalty": 0.5,  // Interdit !
  "messages": [...]
}

Le presencePenalty pénalise les tokens déjà apparus dans la réponse pour encourager la diversité.

frequencyPenalty

// ERREUR sur les modèles de raisonnement
{
  "model": "grok-4.20-0309-reasoning",
  "frequency_penalty": 0.3,  // Interdit !
  "messages": [...]
}

Le frequencyPenalty pénalise les tokens proportionnellement à leur fréquence d’apparition.

stop

// ERREUR sur les modèles de raisonnement
{
  "model": "grok-4.20-0309-reasoning",
  "stop": ["\n\n"],  // Interdit !
  "messages": [...]
}

Le paramètre stop arrête la génération quand une séquence spécifique apparaît. Pour borner la longueur d’une réponse, utilisez plutôt max_completion_tokens, qui ne plafonne que la réponse visible, et une consigne de format dans le prompt.

Gestion des erreurs liées aux paramètres

Quand vous migrez du code existant vers un modèle de raisonnement, nettoyez les paramètres non supportés :

def prepare_params(model, base_params):
    """Nettoie les paramètres pour les modèles de raisonnement."""
    reasoning_models = [
        # gamme actuelle
        "grok-4.7", "grok-4.6", "grok-4.5", "grok-4.20-0309-reasoning",
        # identifiants historiques, encore présents dans du code existant
        "grok-3-mini", "grok-4-fast-reasoning",
    ]

    params = {**base_params, "model": model}

    if model in reasoning_models:
        # Supprimer les paramètres interdits
        for forbidden in ["presence_penalty", "frequency_penalty", "stop"]:
            params.pop(forbidden, None)

        # Remplacer max_tokens par max_completion_tokens
        if "max_tokens" in params:
            params["max_completion_tokens"] = params.pop("max_tokens")

    return params

Le streaming avec les modèles de raisonnement

Le streaming fonctionne avec les modèles de raisonnement, mais le comportement dépend de la génération : sur grok-3-mini (génération précédente), le reasoning_content apparaissait en clair dans le flux, avant les tokens de réponse. Sur grok-4.20-0309-reasoning, le raisonnement reste interne et n’est pas streamé : seule la réponse finale arrive dans le flux. Exception notable : sur la Responses API, grok-4.7 diffuse un résumé de son raisonnement, dans des événements response.reasoning_summary_text.delta que vous pouvez afficher avant la réponse.

Exemple historique avec grok-3-mini :

stream = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{"role": "user", "content": "Pourquoi le ciel est bleu ?"}],
    reasoning_effort="high",
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if hasattr(delta, 'reasoning_content') and delta.reasoning_content:
        print(f"[Raisonnement] {delta.reasoning_content}", end="")
    elif delta.content:
        print(f"[Réponse] {delta.content}", end="")

Points clés à retenir

Laissez au moins 900 secondes à chaque requête (3 600 dans les exemples du guide Reasoning), et préférez le streaming
Trois paramètres sont interdits : presencePenalty, frequencyPenalty et stop
Nettoyez les paramètres lors de la migration depuis des modèles classiques
Utilisez max_completion_tokens au lieu de max_tokens
Le streaming fonctionne mais le comportement diffère selon le modèle