Rate limits et bonnes pratiques

Les contraintes à connaître

La Batch API impose des limites techniques que vous devez intégrer dans votre architecture. Les ignorer conduit à des erreurs silencieuses, des rejets de requêtes, ou des pertes de données. Cette leçon récapitule toutes les contraintes et les bonnes pratiques pour une utilisation en production.

Rate limits

Trois limites encadrent l’utilisation de la Batch API :

Création de batchs : la limite de 2 créations par seconde est rarement un problème. Dans la plupart des cas, vous créez un seul batch par opération. Si vous automatisez la création de multiples batchs, espacez les appels d’au moins 500 ms.

Ajout de requêtes : la limite de 1 000 appels par 30 secondes s’applique à la méthode JSON individuelle. Avec un débit soutenu de 33 requêtes par seconde, un lot de 10 000 requêtes prend environ 5 minutes à soumettre. Pour les volumes supérieurs, la méthode JSONL est recommandée.

Taille par requête : la limite de 25 MB par requête concerne principalement les requêtes avec des images ou vidéos encodées en base64. Les requêtes texte dépassent rarement quelques Ko.

Limites des fichiers JSONL

Si votre lot dépasse ces limites, deux approches :

• Plusieurs fichiers : découpez en fichiers de 50 000 requêtes et ajoutez-les au même batch
• Plusieurs batchs : créez un batch par tranche et traitez les résultats séparément

Expiration des URLs

Les URLs signées pour les résultats d’images et de vidéos expirent après 1 heure. C’est la contrainte la plus critique à gérer en production :

import requests
from datetime import datetime

def download_results(batch_results, output_dir):
    """Telecharge tous les résultats multimodaux immediatement."""
    start = datetime.now()

    for result in batch_results:
        if hasattr(result.response, "data"):
            for item in result.response.data:
                if hasattr(item, "url"):
                    response = requests.get(item.url)
                    filename = f"{output_dir}/{result.custom_id}.png"
                    with open(filename, "wb") as f:
                        f.write(response.content)

    elapsed = (datetime.now() - start).seconds
    print(f"Telechargement termine en {elapsed}s")

Planifiez le téléchargement automatique dès que le batch atteint l’état succeeded. N’attendez pas une intervention manuelle.

Bonnes pratiques en production

Idempotence des custom_id

Utilisez des identifiants déterministes basés sur vos données d’entrée. Si vous devez resoumettre un batch, les mêmes données produiront les mêmes custom_id, facilitant la déduplication :

import hashlib

def make_custom_id(document_id, operation):
    """Génère un custom_id deterministe."""
    raw = f"{document_id}:{operation}"
    return hashlib.sha256(raw.encode()).hexdigest()[:16]

Gestion des échecs partiels

Un batch succeeded peut contenir des requêtes individuelles en échec. Toujours vérifier chaque résultat :

succeeded = []
failed = []

for result in batch_results:
    if result.status == "succeeded":
        succeeded.append(result)
    else:
        failed.append(result)

if failed:
    print(f"{len(failed)} requetes echouees a resoumettre")
    # Créer un nouveau batch avec les requetes échouées

Logs et traçabilité

Enregistrez chaque opération pour pouvoir diagnostiquer les problèmes :

import logging

logger = logging.getLogger("batch_api")

logger.info(f"Batch cree : {batch_id}")
logger.info(f"Fichier uploade : {file_id}, {len(documents)} requetes")
logger.info(f"Statut final : {status.status}")
logger.info(f"Resultats : {len(succeeded)} OK, {len(failed)} KO")

Retry avec backoff

Pour les erreurs transitoires (timeout, rate limit), implémentez un retry :

import time

def api_call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt
            print(f"Retry dans {wait}s : {e}")
            time.sleep(wait)

Checklist pré-production

Avant de déployer un pipeline Batch API en production, vérifiez :

• Les custom_id sont uniques et déterministes
• Le fichier JSONL est valide (JSON par ligne, pas de doublons)
• Le pipeline de téléchargement des résultats multimodaux est automatisé
• Les erreurs partielles sont détectées et resoumises
• Les logs couvrent chaque étape du workflow
• Un timeout est configuré pour les batchs trop longs
• Les clés API sont stockées dans des variables d’environnement, pas en dur

Points clés à retenir

• Respectez les rate limits : 2 créations/sec, 1 000 ajouts/30s
• Les URLs d’images et vidéos expirent en 1 heure : téléchargez immédiatement
• Utilisez des custom_id déterministes pour la déduplication
• Vérifiez chaque résultat individuellement, même dans un batch succeeded
• Implémentez logs, retry avec backoff, et timeout pour la production

Testez vos connaissances

Traitement en masse : la Batch API sans zones d’ombre.

1. Quand la Batch API est-elle le bon choix ?

Réponse : Pour les gros volumes sans contrainte temps réel : classification, enrichissement, générations en masse — le traitement asynchrone qui libère vos quotas interactifs.

2. Quel est le workflow en quatre étapes ?

Réponse : Créer le batch, ajouter les requêtes (JSON direct ou fichier JSONL via la Files API), lancer, puis suivre le statut et récupérer les résultats — avec annulation possible.

3. Que peut-on mettre dans un batch ?

Réponse : Les endpoints supportés : Chat Completions et Responses, y compris images et vidéos, outils serveur et function calling — le batch n’est pas limité au texte simple.

4. Comment suit-on l'exécution ?

Réponse : Par les statuts du batch et de chaque requête : on interroge l’avancement, on identifie les échecs individuels, et on récupère les sorties une fois le lot terminé.

5. Quelles bonnes pratiques face aux rate limits ?

Réponse : Dimensionner ses lots, étaler les soumissions, prévoir la reprise des requêtes échouées — le batch se conçoit comme un pipeline robuste, pas comme un envoi massif aveugle.

Lots bien formés, suivi des statuts, reprise des échecs : la Batch API transforme le volume en routine — au meilleur coût.