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 adopte dans l’ecosysteme Python, fonctionne avec l’API xAI grace a la compatibilite du format. Cette approche vous permet de reutiliser du code existant ecrit pour OpenAI et de beneficier de l’ecosysteme d’outils autour de ce SDK.

Configurer AsyncOpenAI pour xAI

L’initialisation requiert trois parametres : la cle API, l’URL de base xAI, et un timeout adapte aux modeles 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 defaut est de 10 minutes. Pour les modeles de raisonnement de Grok, vous devez l’augmenter a 3600 secondes (une heure) pour eviter les deconnexions prematurees.

Comprendre httpx.Timeout

La classe httpx.Timeout accepte plusieurs parametres qui controlent differentes phases de la connexion :

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

# Timeout granulaire
timeout = httpx.Timeout(
    connect=10.0,    # delai de connexion initiale
    read=3600.0,     # delai de lecture de la reponse
    write=30.0,      # delai d'envoi de la requete
    pool=10.0        # delai d'attente d'une connexion libre
)

En production, vous pouvez affiner ces valeurs. La connexion initiale devrait echouer rapidement si le serveur est injoignable (10 secondes suffisent), tandis que la lecture doit etre patiente pour attendre le raisonnement du modele.

Envoyer des requetes

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-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 meme structure que l’API OpenAI : un tableau messages avec des roles et du contenu. La reponse suit egalement le meme schema, accessible via response.choices[0].message.content.

Gestion des erreurs avec httpx

Le SDK OpenAI avec httpx fournit des exceptions specifiques 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-reasoning",
            messages=[{"role": "user", "content": prompt}]
        )
        return response.choices[0].message.content
    except APITimeoutError:
        print("Timeout depasse - requete 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 frequentes sont APITimeoutError (le modele n’a pas repondu dans le delai imparti), RateLimitError (vous avez depasse les limites RPM/TPM), et APIConnectionError (probleme reseau).

Quand choisir AsyncOpenAI plutot que le xAI SDK

Le SDK OpenAI est preferable si vous avez deja 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 acces plus direct aux fonctionnalites specifiques de Grok, comme les outils integres.

Points cles a retenir

• AsyncOpenAI fonctionne avec l’API xAI via base_url="https://api.x.ai/v1"
• httpx.Timeout(3600.0) est obligatoire pour les modeles de raisonnement
• Le format de requete et de reponse est identique a l’API OpenAI standard
• Les exceptions APITimeoutError, RateLimitError et APIConnectionError couvrent les cas d’erreur principaux
• Ce choix est ideal pour reutiliser du code existant ou integrer des outils tiers compatibles OpenAI