Timeout, paramètres interdits et configuration

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 : 3600 secondes minimum

La recommandation officielle de xAI est de configurer un timeout d’au moins 3600 secondes (1 heure) pour les requêtes aux modèles de raisonnement. Ce chiffre peut sembler élevé, mais il reflète une réalité : les modèles de raisonnement peuvent prendre plusieurs minutes pour les problèmes complexes.

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 sont pas supportés par les modèles de raisonnement de xAI. Les inclure dans votre requête provoquera une erreur :

presencePenalty

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

Le presencePenalty pénalise les tokens déjà apparus dans la réponse pour encourager la diversité. Sur un modèle de raisonnement, ce paramètre interférerait avec le processus de réflexion interne qui peut légitimement répéter des concepts.

frequencyPenalty

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

Le frequencyPenalty pénalise les tokens proportionnellement à leur fréquence d’apparition. Là encore, le raisonnement interne a besoin de répéter des termes clés pour maintenir la cohérence de la chaîne logique.

stop

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

Le paramètre stop arrête la génération quand une séquence spécifique apparaît. Sur un modèle de raisonnement, cela pourrait interrompre le processus de réflexion prématurément.

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 = [
        "grok-3-mini", "grok-4",
        "grok-4-fast-reasoning", "grok-4.20-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 avec une particularité : les tokens de raisonnement peuvent apparaître dans le flux avant les tokens de réponse. Sur grok-3-mini, vous verrez le reasoning_content en streaming. Sur grok-4, le raisonnement chiffré n’est pas streamé.

stream = client.chat.completions.create(
    model="grok-3-mini",
    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

• Configurez un timeout d’au moins 3600 secondes pour les modèles de raisonnement
• 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