Les développeurs sont souvent confrontés à des temps de réponse lents et des coûts réseau élevés lorsqu’ils envoient des milliers d’appels API distincts. Le Batch API résout ce problème en combinant plusieurs requêtes indépendantes en une seule opération, réduisant ainsi la latence, l’utilisation de la bande passante et la surcharge de connexion.
Cet article explique ce qu’est le Batch API, en quoi il diffère des API standard, et comment le Batch API de Novita AI permet l’inférence asynchrone à grande échelle via des entrées JSONL structurées, une gestion efficace des fichiers et un suivi fiable des erreurs. Il présente également les facteurs clés d’efficacité tels que le coût, la latence et le débit, ainsi qu’un guide concis pour l’implémentation et la surveillance.
[Essayez l’inférence par lot à 50 % de réduction
Exécutez des prédictions à grande échelle plus rapidement et à moindre coût avec les modèles pris en charge :
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-fp8.](https://novita.ai/docs/guides/llm-batch-api)
Essayez l’inférence par lot à 50 % de réduction
Exécutez des prédictions à grande échelle plus rapidement et à moindre coût avec les modèles pris en charge :
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-f
Qu’est-ce que le Batch API ?
Batch API : Combine plusieurs appels API indépendants (par ex. GET, POST, PUT, DELETE) en une seule requête HTTP.
Structure de la réponse : Le serveur renvoie les résultats de toutes les sous-requêtes dans l’ordre, en indiquant pour chacune si elle a réussi ou échoué.
Principales différences entre le Batch API et l’API standard
Requêtes normales
Client
├──► Request 1 (/user/1)
│ └──► Server Response 1
├──► Request 2 (/user/2)
│ └──► Server Response 2
└──► Request 3 (/order)
└──► Server Response 3
Requête de lot
Client
└──► Single Request (/batch)
├─ Sub-request 1: GET /user/1
├─ Sub-request 2: GET /user/2
└─ Sub-request 3: POST /order
↓
Server processes all
↓
Combined Response:
[Result1, Result2, Result3]
Le Batch API permet de :
Réduire la latence réseau en envoyant une seule requête combinée au lieu de plusieurs.
Diminuer la surcharge de bande passante et de connexion, car les en-têtes et les poignées de main sont partagés.
Améliorer les performances du client, notamment sur les réseaux mobiles ou lents.
Simplifier la logique transactionnelle, en permettant une gestion unifiée des erreurs ou des annulations.
Optimiser le débit de la passerelle API, en évitant l’inondation de requêtes.
Cas d’usage typiques du Batch API
| Scénario | Description |
|---|---|
| 1. Requêtes de données en masse | Récupérer plusieurs utilisateurs, produits ou publications en une seule fois pour éviter les requêtes répétées. |
| 2. Écriture ou mise à jour en masse | Créer ou mettre à jour plusieurs enregistrements en une seule opération (par ex. téléchargement par lot, mise à jour des stocks). |
| 3. Optimisation des performances front-end | Réduire le nombre d’appels HTTP depuis les navigateurs ou les applications mobiles pour des temps de chargement plus rapides. |
| 4. Agrégation des tâches backend | Dans les systèmes microservices, fusionner plusieurs appels API internes en un seul appel externe. |
| 5. Synchronisation des données | Synchroniser les états de plusieurs ressources ou exécuter des opérations par lot (par ex. étiquetage, suppression). |
| 6. Optimisation des limites de débit | Réduire la charge de la passerelle API et économiser de la bande passante en consolidant les requêtes. |
Facteurs clés influençant l’efficacité du Batch API
Quelle est l’économie de coûts réalisée par les Batch API par rapport aux API en temps réel ?
Une analyse sectorielle (Growth-onomics) montre des réductions de coûts d’environ 20 à 45 %, principalement grâce à moins d’allers-retours réseau, une surcharge de connexion réduite et un traitement concentré, bien que les économies exactes dépendent de la fréquence des appels, de la taille des lots et de la conception du système.
Qu’en est-il de la latence — les Batch API peuvent-ils vraiment se terminer « dans les 24 heures » ?
Les Batch API s’exécutent généralement de manière asynchrone avec une latence beaucoup plus élevée que les API en temps réel ; de nombreux systèmes s’exécutent toutes les heures ou tous les jours, donc « dans les 24 heures » dépend du SLA (accord de niveau de service) plutôt que d’être garanti.
La taille des lots ou la taille des fichiers affecte-t-elle la vitesse ?
Oui. Des lots plus volumineux (par ex. plus de lignes JSONL) augmentent le temps de transfert et d’analyse presque linéairement ; bien que le débit s’améliore, le temps total d’achèvement par lot augmente.
Pourquoi les Batch API sont-ils plus adaptés aux charges de travail à haut débit ?
En agrégeant des milliers de requêtes en un seul processus, les Batch API réduisent la surcharge par appel et permettent une exécution parallèle ou la réutilisation de cache, améliorant souvent le débit de 17 à 92 % dans les opérations à grande échelle, bien que cela se fasse au détriment d’une latence plus élevée.
Comment utiliser le Batch API ?
Le Batch API de Novita est hautement compatible avec l’interface d’OpenAI, prenant en charge
/v1/chat/completionset/v1/completions, de sorte que le code existant peut être réutilisé avec des modifications minimales. Il accepte des fichiers d’entrée.jsonloù chaque ligne représente une requête individuelle adressée au même modèle, identifiée par uncustom_idunique pour un suivi facile. La sortie est également au format JSONL, ce qui rend le post-traitement à grande échelle, l’analyse et l’intégration simples et efficaces.
1. Préparez votre fichier d’entrée de lot
Créez un fichier .jsonl, où chaque ligne correspond à une requête API au format JSON.
Exemple (batch_input.jsonl) :
{"custom_id": "req-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Summarize: batch API basics"}], "max_tokens": 200}}
{"custom_id": "req-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are concise."},{"role": "user", "content": "List 3 batch API use cases"}], "max_tokens": 150}}
Règles :
- Une requête par ligne.
- Toutes les requêtes doivent utiliser le même modèle.
- Chaque ligne doit inclure un
custom_idunique.
2. Téléchargez le fichier d’entrée et créez un lot
Utilisez Python ou curl pour télécharger le fichier et démarrer immédiatement le travail de lot.
Python
from openai import OpenAI
client = OpenAI(base_url="https://api.novita.ai/openai/v1", api_key="YOUR_API_KEY")
# Upload + create batch
uploaded = client.files.create(file=open("batch_input.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
input_file_id=uploaded.id,
endpoint="/v1/chat/completions",
completion_window="48h"
)
print("file_id:", uploaded.id)
print("batch_id:", batch.id)
curl
export API_KEY="YOUR_API_KEY"
# Upload file
upload_response=$(curl -s -X POST \
-H "Authorization: Bearer ${API_KEY}" \
-F 'file=@batch_input.jsonl' -F 'purpose=batch' \
https://api.novita.ai/openai/v1/files)
# Extract file_id and start batch
file_id=$(echo $upload_response | jq -r '.id')
curl -X POST https://api.novita.ai/openai/v1/batches \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"input_file_id\": \"$file_id\", \"endpoint\": \"/v1/chat/completions\", \"completion_window\": \"48h\"}"
3. Vérifiez l’état du lot
Vous pouvez vérifier l’avancement à tout moment à l’aide de l’identifiant du lot.
batch = client.batches.retrieve("batch_xxx")
print(batch.status)
Les états incluent :
VALIDATING– fichier d’entrée en cours de vérificationPROGRESS– en cours d’exécutionCOMPLETED– terminé avec succèsFAILED– échouéEXPIRED– fenêtre de 48 h dépassée
4. Récupérez les résultats
Une fois terminé, téléchargez le fichier de résultats via output_file_id :
output = client.files.content("file_xxx")
print(output.read().decode("utf-8"))
Chaque ligne de la sortie correspond à une entrée, associée par custom_id.
Conseils :
Seul le modèle
deepseek/deepseek-r1-0528est pris en chargeJusqu’à 50 000 requêtes par lot
Fichier d’entrée ≤ 100 Mo
Fenêtre d’exécution fixe de 48 heures
Sortie conservée pendant 30 jours
Comment gérer les requêtes échouées dans un Batch API ?
Les erreurs rencontrées lors du traitement par lot sont enregistrées dans un fichier d’erreurs séparé, accessible via le champ error_file_id. Chaque sous-requête échouée inclut un code d’erreur et une description. Exemples courants :
| Code d’erreur | Description | Solution |
|---|---|---|
| 400 | Format de requête invalide | Vérifiez la syntaxe JSONL et les champs requis |
| 401 | Échec de l’authentification | Vérifiez votre clé API |
| 404 | Lot introuvable | Vérifiez l’identifiant du lot |
| 429 | Limite de débit dépassée | Réduisez la fréquence des requêtes |
| 500 | Erreur serveur | Contactez le fournisseur ou réessayez plus tard |
Les développeurs ne doivent retraiter que les entrées échouées à l’aide d’une file de réessai ou d’un lot de suivi plus petit, au lieu de soumettre à nouveau l’intégralité du fichier original.
Quels endpoints Novita AI propose-t-il pour les opérations de Batch API ?
| Endpoint | Objectif |
|---|---|
| Créer un lot | Soumettre un nouveau travail de lot contenant plusieurs requêtes. |
| Récupérer un lot | Obtenir l’état ou les résultats d’un lot spécifique par son identifiant. |
| Annuler un lot | Arrêter un travail de lot en cours avant son achèvement. |
| Lister les lots | Lister tous les travaux de lot soumis pour le compte. |
| Télécharger un fichier | Télécharger des fichiers de données d’entrée (par ex. JSONL). |
| Lister les fichiers | Afficher tous les fichiers téléchargés. |
| Récupérer un fichier | Obtenir les métadonnées d’un fichier par son identifiant. |
| Supprimer un fichier | Supprimer un fichier téléchargé. |
| Récupérer le contenu d’un fichier | Télécharger le contenu réel d’un fichier (par ex. résultats ou journal d’erreurs). |
Le Batch API consolide de nombreuses petites requêtes en un flux de travail efficace. En utilisant le Batch API de Novita AI, les développeurs peuvent réduire les coûts réseau jusqu’à 45 %, augmenter le débit jusqu’à 50 000 requêtes par lot et simplifier la gestion des erreurs grâce aux endpoints de journalisation et de récupération intégrés. Bien qu’il sacrifie la vitesse en temps réel, il offre une efficacité exceptionnelle pour les charges de travail d’inférence en masse, de synchronisation et de traitement de données.
Novita AI est une plateforme cloud IA qui offre aux développeurs un moyen simple de déployer des modèles IA via notre API intuitive, tout en fournissant un cloud GPU abordable et fiable pour la construction et la mise à l’échelle.
