API Timeout : diagnostiquer les coupures et configurer des retries fiables pour les LLM

Localisation des coupures : les phases du cycle de requête HTTP

Une requête vers une API de modèle de langage se compose de quatre phases techniques distinctes :

[Client] --- (1. Connect Timeout) ---> [API Gateway]
[Client] --- (2. Write Timeout)   ---> [Envoi du Prompt]
[Modèle] --- (3. Read / TTFT)     ---> [Raisonnement & Génération]
[Client] <--- (4. Pool Timeout)    --- [Maintien de la Connexion]

1. Connect Timeout : Délai alloué pour établir la connexion TCP et finaliser le protocole TLS (5 à 10 secondes recommandées).
2. Write Timeout : Temps nécessaire pour téléverser la charge utile (essentiel pour les contextes de plus de 100k jetons).
3. Read Timeout : Temps d'attente avant la réponse initiale ou entre les fragments successifs du flux SSE.
4. Pool Timeout : Temps d'attente pour acquérir un socket disponible dans le pool sous forte charge concurrente.

---

Matrice de diagnostic des erreurs de timeout

---

Configuration des timeouts granulaires en Python (HTTPX)

La valeur par défaut timeout=10.0 des bibliothèques standard entraîne systématiquement des coupures avec les modèles de raisonnement. Voici une configuration robuste :

import os
import httpx
from openai import OpenAI

API_KEY = os.environ.get("BETTERTOKEN_API_KEY", "your_api_key_here")

custom_timeout = httpx.Timeout(
    connect=5.0,    # Échec rapide si le réseau est inaccessible
    read=120.0,     # Marge suffisante pour les réflexions longues
    write=10.0,     # Téléversement de la requête
    pool=10.0       # Obtention d'un socket disponible
)

http_client = httpx.Client(
    timeout=custom_timeout,
    limits=httpx.Limits(max_keepalive_connections=50, max_connections=100)
)

client = OpenAI(
    base_url="https://www.bettertoken.ai/v1",
    api_key=API_KEY,
    http_client=http_client
)

response = client.chat.completions.create(
    model="claude-3-7-sonnet-20250219",
    messages=[
        {"role": "system", "content": "You are a senior systems architect."},
        {"role": "user", "content": "Design a high-throughput distributed message broker."}
    ],
    stream=True
)

for chunk in response:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)
Afficher plus

---

Stabilisation des flux SSE et retries sécurisés

Pour éviter les coûts superflus lors des pannes, les tentatives de rejeu doivent respecter trois règles :

1. Ne pas retenter si le streaming a déjà débuté : Si des jetons ont déjà été reçus, relancer la requête intégrale générera une double facturation.
2. Backoff exponentiel avec Full Jitter : Les nouvelles tentatives doivent être espacées par des délais progressifs et aléatoires.
3. Clés d'idempotence : Utilisez des identifiants uniques dans vos traitements par lots pour éviter les doublons.

import time
import random
import httpx

def execute_with_safe_retry(client, model, messages, max_retries=3):
    base_delay = 1.0
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages,
                stream=True
            )
            return response
        except (httpx.ConnectTimeout, httpx.ReadTimeout, httpx.NetworkError) as err:
            if attempt == max_retries - 1:
                raise err
            sleep_time = random.uniform(0, base_delay * (2 ** attempt))
            time.sleep(sleep_time)

Validation finale

• Statut HTTP 200 OK.
• Transmission fluide de tous les fragments SSE sans coupure.
• Libération immédiate des sockets une fois le flux terminé.

Pour en savoir plus, consultez la référence d'API BetterToken.