Rate limits et bonnes pratiques

Les contraintes a connaitre

La Batch API impose des limites techniques que vous devez integrer dans votre architecture. Les ignorer conduit a des erreurs silencieuses, des rejets de requetes, ou des pertes de donnees. Cette lecon recapitule toutes les contraintes et les bonnes pratiques pour une utilisation en production.

Rate limits

Trois limites encadrent l’utilisation de la Batch API :

Creation de batchs : la limite de 2 creations par seconde est rarement un probleme. Dans la plupart des cas, vous creez un seul batch par operation. Si vous automatisez la creation de multiples batchs, espacez les appels d’au moins 500 ms.

Ajout de requetes : la limite de 1 000 appels par 30 secondes s’applique a la methode JSON individuelle. Avec un debit soutenu de 33 requetes par seconde, un lot de 10 000 requetes prend environ 5 minutes a soumettre. Pour les volumes superieurs, la methode JSONL est recommandee.

Taille par requete : la limite de 25 MB par requete concerne principalement les requetes avec des images ou videos encodees en base64. Les requetes texte depassent rarement quelques Ko.

Limites des fichiers JSONL

Si votre lot depasse ces limites, deux approches :

• Plusieurs fichiers : decoupez en fichiers de 50 000 requetes et ajoutez-les au meme batch
• Plusieurs batchs : creez un batch par tranche et traitez les resultats separement

Expiration des URLs

Les URLs signees pour les resultats d’images et de videos expirent apres 1 heure. C’est la contrainte la plus critique a gerer en production :

import requests
from datetime import datetime

def download_results(batch_results, output_dir):
    """Telecharge tous les resultats 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 telechargement automatique des que le batch atteint l’etat succeeded. N’attendez pas une intervention manuelle.

Bonnes pratiques en production

Idempotence des custom_id

Utilisez des identifiants deterministes bases sur vos donnees d’entree. Si vous devez resoumettre un batch, les memes donnees produiront les memes custom_id, facilitant la deduplication :

import hashlib

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

Gestion des echecs partiels

Un batch succeeded peut contenir des requetes individuelles en echec. Toujours verifier chaque resultat :

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")
    # Creer un nouveau batch avec les requetes echouees

Logs et tracabilite

Enregistrez chaque operation pour pouvoir diagnostiquer les problemes :

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), implementez 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 pre-production

Avant de deployer un pipeline Batch API en production, verifiez :

• Les custom_id sont uniques et deterministes
• Le fichier JSONL est valide (JSON par ligne, pas de doublons)
• Le pipeline de telechargement des resultats multimodaux est automatise
• Les erreurs partielles sont detectees et resoumises
• Les logs couvrent chaque etape du workflow
• Un timeout est configure pour les batchs trop longs
• Les cles API sont stockees dans des variables d’environnement, pas en dur

Points cles a retenir

• Respectez les rate limits : 2 creations/sec, 1 000 ajouts/30s
• Les URLs d’images et videos expirent en 1 heure : telechargez immediatement
• Utilisez des custom_id deterministes pour la deduplication
• Verifiez chaque resultat individuellement, meme dans un batch succeeded
• Implementez logs, retry avec backoff, et timeout pour la production