Cache x-grok-conv-id et timeout reasoning

Optimiser les coûts avec le cache

Chaque requête envoyée à l’API xAI est facturée au prix standard des tokens. Mais quand vous envoyez plusieurs requêtes liées (même conversation, même sujet), une partie du contexte se répète. Le header x-grok-conv-id permet à xAI d’identifier ces requêtes liées et d’augmenter le taux de cache, réduisant ainsi vos coûts.

Le header x-grok-conv-id

Pour activer le cache conversationnel, ajoutez un header personnalisé avec un UUID v4 unique par conversation :

import uuid

conversation_id = str(uuid.uuid4())

# Avec le SDK OpenAI
response = await client.chat.completions.create(
    model="grok-4.5",
    messages=[{"role": "user", "content": prompt}],
    extra_headers={
        "x-grok-conv-id": conversation_id
    }
)

Toutes les requêtes qui partagent le même x-grok-conv-id bénéficient d’un taux de cache améliore. Les tokens en cache sont facturés à un tarif réduit par rapport aux tokens standards.

Règles d’utilisation

• Générez un nouvel UUID pour chaque conversation ou session logique
• Réutilisez le même UUID pour toutes les requêtes d’une même conversation
• Ne réutilisez pas un UUID entre des conversations différentes (cela dégraderait le cache)

# Pattern pour un chatbot
class ConversationManager:
    def __init__(self):
        self.conv_id = str(uuid.uuid4())
        self.messages = []

    async def send(self, user_message: str) -> str:
        self.messages.append({"role": "user", "content": user_message})

        response = await client.chat.completions.create(
            model="grok-4.5",
            messages=self.messages,
            extra_headers={"x-grok-conv-id": self.conv_id}
        )

        assistant_message = response.choices[0].message.content
        self.messages.append({"role": "assistant", "content": assistant_message})
        return assistant_message

Timeout de 3600 secondes pour le reasoning

Les modèles de raisonnement (grok-4.20-0309-reasoning et similaires) effectuent une réflexion interne avant de répondre. Cette réflexion peut durer plusieurs minutes pour des problèmes complexes. Le timeout par défaut de la plupart des clients HTTP (30-120 secondes) est insuffisant.

# Configuration correcte pour le reasoning
from openai import AsyncOpenAI
import httpx

client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(
        connect=10.0,     # connexion rapide
        read=3600.0,      # 1 heure pour la lecture
        write=30.0,       # envoi du prompt
        pool=10.0         # attente de connexion
    )
)

Le read=3600.0 est la valeur critique. C’est le délai maximal entre le moment où le serveur commence à traiter votre requête et le moment où vous recevez la réponse. Pour un modèle de raisonnement qui réfléchit pendant 5 minutes, vous avez besoin de cette marge.

Quand réduire le timeout

Le timeout de 3600 secondes n’est pas toujours nécessaire :

• grok-4.5 (non-reasoning) : un timeout de 120-300 secondes suffit généralement
• Requêtes simples : même avec un modèle reasoning, les questions courtes répondent en moins d’une minute
• Environnement de test : un timeout de 60 secondes permet de détecter rapidement les problèmes

# Client pour requetes rapides
fast_client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(120.0)
)

# Client pour raisonnement complexe
reasoning_client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0)
)

Utiliser deux clients avec des timeouts différents est un pattern courant en production.

Note sur grok-4.5 et le reasoning

Le modèle grok-4.5 ne retourne pas le champ reasoning_content en clair dans la réponse. Le raisonnement interne est effectue mais reste opaque. Si vous avez besoin de voir le processus de raisonnement, utilisez use_encrypted_content=True pour le préserver entre les requêtes sans pouvoir le lire, ou grok-4.20-0309-reasoning qui expose davantage de son processus.

Vérifier l’impact du cache

Pour mesurer l’efficacité du cache, comparez le champ usage entre les requêtes avec et sans x-grok-conv-id :

response = await client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    extra_headers={"x-grok-conv-id": conv_id}
)

usage = response.usage
if hasattr(usage, 'prompt_tokens_details'):
    cached = usage.prompt_tokens_details.cached_tokens
    total = usage.prompt_tokens
    print(f"Cache hit : {cached}/{total} tokens ({cached/total*100:.0f}%)")

Un taux de cache élevé signifie que vos tokens de contexte sont réutilisés au lieu d’être retraites, ce qui réduit directement votre facture.

Points clés à retenir

• x-grok-conv-id avec un UUID v4 active le cache conversationnel pour les requêtes liées
• Les tokens en cache sont facturés à tarif réduit
• Le timeout de 3600 secondes est nécessaire pour les modèles de raisonnement
• Utilisez des clients séparés pour les requêtes rapides et les requêtes de raisonnement
• grok-4.5 ne retourne pas reasoning_content en clair
• Surveillez le taux de cache dans usage.prompt_tokens_details pour valider l’optimisation