AsyncOpenAI avec httpx.Timeout

L’alternative OpenAI SDK

Le xAI SDK natif n’est pas la seule option pour travailler en asynchrone avec l’API Grok. Le SDK OpenAI, largement adopté dans l’écosystème Python, fonctionne avec l’API xAI grâce à la compatibilité du format. Cette approche vous permet de réutiliser du code existant écrit pour OpenAI et de bénéficier de l’écosystème d’outils autour de ce SDK.

Configurer AsyncOpenAI pour xAI

L’initialisation requiert trois paramètres : la clé API, l’URL de base xAI, et un timeout adapté aux modèles de raisonnement :

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(3600.0)
)

Le point essentiel ici est httpx.Timeout(3600.0). Le SDK OpenAI utilise httpx comme client HTTP sous-jacent, et le timeout par défaut est de 10 minutes. Pour les modèles de raisonnement de Grok, vous devez l’augmenter à 3600 secondes (une heure) pour éviter les déconnexions prematurees.

Comprendre httpx.Timeout

La classe httpx.Timeout accepte plusieurs paramètres qui contrôlent différentes phases de la connexion :

# Timeout uniforme : 3600s pour tout
timeout = httpx.Timeout(3600.0)

# Timeout granulaire
timeout = httpx.Timeout(
    connect=10.0,    # délai de connexion initiale
    read=3600.0,     # délai de lecture de la réponse
    write=30.0,      # délai d'envoi de la requête
    pool=10.0        # délai d'attente d'une connexion libre
)

En production, vous pouvez affiner ces valeurs. La connexion initiale devrait échouer rapidement si le serveur est injoignable (10 secondes suffisent), tandis que la lecture doit être patiente pour attendre le raisonnement du modèle.

Envoyer des requêtes

La syntaxe suit le format standard du SDK OpenAI, avec await :

import asyncio

async def query_grok(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

result = asyncio.run(query_grok("Quels sont les avantages de Rust sur C++ ?"))

Vous retrouvez la même structure que l’API OpenAI : un tableau messages avec des rôles et du contenu. La réponse suit également le même schéma, accessible via response.choices[0].message.content.

Gestion des erreurs avec httpx

Le SDK OpenAI avec httpx fournit des exceptions spécifiques que vous devez intercepter :

from openai import APITimeoutError, APIConnectionError, RateLimitError

async def safe_query(prompt: str) -> str | None:
    try:
        response = await client.chat.completions.create(
            model="grok-4.20-0309-reasoning",
            messages=[{"role": "user", "content": prompt}]
        )
        return response.choices[0].message.content
    except APITimeoutError:
        print("Timeout depasse - requête trop longue")
        return None
    except RateLimitError:
        print("Rate limit atteint - ralentir les requetes")
        return None
    except APIConnectionError:
        print("Connexion impossible au serveur xAI")
        return None

Les trois exceptions les plus fréquentes sont APITimeoutError (le modèle n’a pas répondu dans le délai imparti), RateLimitError (vous avez dépasse les limites RPM/TPM), et APIConnectionError (problème réseau).

Quand choisir AsyncOpenAI plutôt que le xAI SDK

Le SDK OpenAI est préférable si vous avez déjà une base de code OpenAI, si vous utilisez des outils tiers compatibles OpenAI (langchain, litellm), ou si vous souhaitez pouvoir basculer entre fournisseurs sans modifier votre code. Le xAI SDK natif offre en revanche un accès plus direct aux fonctionnalités spécifiques de Grok, comme les outils intégrés.

Points clés à retenir

• AsyncOpenAI fonctionne avec l’API xAI via base_url="https://api.x.ai/v1"
• httpx.Timeout(3600.0) est obligatoire pour les modèles de raisonnement
• Le format de requête et de réponse est identique à l’API OpenAI standard
• Les exceptions APITimeoutError, RateLimitError et APIConnectionError couvrent les cas d’erreur principaux
• Ce choix est idéal pour réutiliser du code existant ou intégrer des outils tiers compatibles OpenAI