Cache x-grok-conv-id et timeout reasoning

Optimiser les couts avec le cache

Chaque requete envoyee a l’API xAI est facturee au prix standard des tokens. Mais quand vous envoyez plusieurs requetes liees (meme conversation, meme sujet), une partie du contexte se repete. Le header x-grok-conv-id permet a xAI d’identifier ces requetes liees et d’augmenter le taux de cache, reduisant ainsi vos couts.

Le header x-grok-conv-id

Pour activer le cache conversationnel, ajoutez un header personnalise 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",
    messages=[{"role": "user", "content": prompt}],
    extra_headers={
        "x-grok-conv-id": conversation_id
    }
)

Toutes les requetes qui partagent le meme x-grok-conv-id beneficient d’un taux de cache ameliore. Les tokens en cache sont factures a un tarif reduit par rapport aux tokens standards.

Regles d’utilisation

• Generez un nouvel UUID pour chaque conversation ou session logique
• Reutilisez le meme UUID pour toutes les requetes d’une meme conversation
• Ne reutilisez pas un UUID entre des conversations differentes (cela degraderait 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",
            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 modeles de raisonnement (grok-4.20-reasoning et similaires) effectuent une reflexion interne avant de repondre. Cette reflexion peut durer plusieurs minutes pour des problemes complexes. Le timeout par defaut 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 delai maximal entre le moment ou le serveur commence a traiter votre requete et le moment ou vous recevez la reponse. Pour un modele de raisonnement qui reflechit pendant 5 minutes, vous avez besoin de cette marge.

Quand reduire le timeout

Le timeout de 3600 secondes n’est pas toujours necessaire :

• grok-4 (non-reasoning) : un timeout de 120-300 secondes suffit generalement
• Requetes simples : meme avec un modele reasoning, les questions courtes repondent en moins d’une minute
• Environnement de test : un timeout de 60 secondes permet de detecter rapidement les problemes

# 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 differents est un pattern courant en production.

Note sur grok-4 et le reasoning

Le modele grok-4 ne retourne pas le champ reasoning_content en clair dans la reponse. 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 preserver entre les requetes sans pouvoir le lire, ou grok-4.20-reasoning qui expose davantage de son processus.

Verifier l’impact du cache

Pour mesurer l’efficacite du cache, comparez le champ usage entre les requetes avec et sans x-grok-conv-id :

response = await client.chat.completions.create(
    model="grok-4",
    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 eleve signifie que vos tokens de contexte sont reutilises au lieu d’etre retraites, ce qui reduit directement votre facture.

Points cles a retenir

• x-grok-conv-id avec un UUID v4 active le cache conversationnel pour les requetes liees
• Les tokens en cache sont factures a tarif reduit
• Le timeout de 3600 secondes est necessaire pour les modeles de raisonnement
• Utilisez des clients separes pour les requetes rapides et les requetes de raisonnement
• grok-4 ne retourne pas reasoning_content en clair
• Surveillez le taux de cache dans usage.prompt_tokens_details pour valider l’optimisation