Timeout, paramètres interdits et configuration
På denna sida
Mis à jour le 3 novembre 2026. Basé sur les meilleures pratiques de xAI et le guide Reasoning : le temps d’attente recommandé est d’au moins 900 secondes (3 600 dans les exemples), et non « 3 600 secondes minimum » ; la liste des modèles de raisonnement inclut grok-4.6 et grok-4.7 ; grok-4.7 diffuse en flux continu un résumé de son raisonnement ; les justifications des paramètres interdits, absentes de la documentation, sont supprimées. Sources : Bonnes pratiques · Reasoning.
Configure correctement tes 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 délais d’attente inattendus ou des réponses tronquées. Cette leçon couvre les paramètres de configuration essentiels.
Délai d’attente : au moins 900 secondes
Les meilleures pratiques de xAI exigent au moins 900 secondes par requête, et 1 800 secondes ou plus pour les évaluations longues ; les exemples du guide Reasoning définissent même le délai à 3 600 secondes (1 heure). Ces chiffres peuvent sembler élevés, mais ils reflètent la réalité : un raisonnement profond sur un problème complexe peut prendre plusieurs minutes. xAI recommande également de privilégier le streaming, qui maintient la connexion active pendant les générations longues.
Pourquoi un délai d’attente aussi long ?
Lorsqu’un modèle de raisonnement traite un problème difficile (démonstration mathématique, analyse de code complexe, raisonnement en plusieurs étapes), il génère potentiellement des milliers de jetons de raisonnement internes avant de formuler sa réponse. Ce processus est linéaire et ne peut pas être parallélisé.
Configuration du délai d’attente
import httpx
from openai import OpenAI
# Configuration avec un délai d'attente élevé
client = OpenAI(
api_key="your-api-key",
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: 'your-api-key',
baseURL: 'https://api.x.ai/v1',
timeout: 3600 * 1000 // 3600 secondes en millisecondes
});
Délai d’attente du serveur web
Si ton application se trouve derrière un proxy inverse (nginx, Apache), configure également le délai d’attente 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 : selon le guide Reasoning, une requête les contenant renvoie une erreur. La documentation ne donne pas la raison de ces interdictions ; retiens simplement la règle.
presencePenalty
// ERREUR sur les modèles de raisonnement
{
"model": "grok-4.20-0309-reasoning",
"presence_penalty": 0.5, // Interdit !
"messages": [...]
}
presencePenalty pénalise les jetons 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": [...]
}
frequencyPenalty pénalise les jetons 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 lorsqu’une séquence spécifique apparaît. Pour limiter la longueur de la réponse, utilise plutôt max_completion_tokens, qui plafonne uniquement la réponse visible, et une instruction de format dans l’invite.
Gestion des erreurs liées aux paramètres
Lors de la migration d’un code existant vers un modèle de raisonnement, nettoie les paramètres non pris en charge :
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, toujours présents dans le 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
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), reasoning_content apparaissait en clair dans le flux, avant les jetons de réponse. Sur grok-4.20-0309-reasoning, le raisonnement reste interne et n’est pas diffusé en flux : seule la réponse finale arrive dans le flux. Exception notable : sur l’API Responses, grok-4.7 diffuse un résumé de son raisonnement, dans les événements response.reasoning_summary_text.delta que tu peux 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": "Why is the sky blue?"}],
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"[Reasoning] {delta.reasoning_content}", end="")
elif delta.content:
print(f"[Response] {delta.content}", end="")
Viktiga punkter
- Accorde au moins 900 secondes par requête (3 600 dans les exemples du guide Reasoning) et privilégie le streaming
- Trois paramètres sont interdits :
presencePenalty,frequencyPenaltyetstop - Nettoie les paramètres lors de la migration depuis des modèles classiques
- Utilise
max_completion_tokensau lieu demax_tokens - Le streaming fonctionne, mais le comportement diffère selon le modèle