Inférence par lots

L’API Batch pour les grands modèles de langage permet le traitement asynchrone de nombreuses requêtes d’inférence et est entièrement compatible avec le standard de l’API OpenAI. L’API Batch est une solution économique lorsque des résultats d’inférence immédiats ne sont pas nécessaires. Elle offre des limites de débit plus élevées que les appels en ligne, garantissant que les résultats sont livrés dans un délai raisonnable de 24 heures. Cette API est idéale pour :

Réaliser des évaluations et des analyses de données.
Classer de vastes ensembles de données.
Générer des résumés de documents en mode hors ligne.

Modèles pris en charge :

Démarrage rapide

1. Préparer les fichiers batch

L’API Batch utilise des fichiers au format .jsonl comme entrée, chaque ligne représentant les détails d’une requête d’inférence API. Les endpoints disponibles incluent /v1/chat/completions et /v1/completions.

Définissez le paramètre endpoint sur /v1/chat/completions ou /v1/completions pour la compatibilité avec l’API OpenAI.

Chaque requête doit inclure un custom_id unique afin de localiser les résultats d’inférence dans le fichier de sortie une fois le batch terminé. Les paramètres du champ body de chaque ligne sont envoyés comme paramètres réels de requête d’inférence à l’endpoint.

Toutes les requêtes d’un même fichier JSONL de batch doivent cibler le même modèle. Ne mélangez pas des requêtes destinées à différents modèles dans un même batch.

Voici un exemple de fichier d’entrée contenant 2 requêtes :

{"custom_id": "request-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 400}}
{"custom_id": "request-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

2. Téléverser le fichier d’entrée du batch

Téléversez le fichier d’entrée du batch afin qu’il puisse être référencé avec précision lors de la création d’un batch. Utilisez la Files API pour téléverser votre fichier .jsonl et définissez le purpose sur batch. Notez que le fichier sera conservé pendant 15 jours.

Pour savoir comment obtenir une clé API, consultez la section Gestion des clés API.

Exemple de code Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch_input_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

print(batch_input_file)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/files \
  --header 'Authorization: Bearer ${API_KEY}' \
  --form 'file=@"/your/batch_input.jsonl"' \
  --form 'purpose="batch"'

Exemple de réponse après un téléversement de fichier réussi :

{
    "id": "file_d2co***as73c0cjd0",
    "object": "file",
    "bytes": 238,
    "filename": "batch_input.jsonl",
    "created_at": 1754894162,
    "purpose": "batch",
    "metadata": {
        "total_requests": 2
    }
}

3. Créer un batch

Une fois le fichier d’entrée téléversé avec succès, vous pouvez lancer un batch en utilisant l’ID de l’objet File téléversé. La fenêtre de complétion est fixée à 24h et n’est actuellement pas modifiable. Exemple de code Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch = client.batches.create(
  input_file_id="file_d2cor0es1cas73c0cj60",
  endpoint="/v1/chat/completions",
  completion_window="24h"
)
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}' \
  --data '{
      "input_file_id": "file_d2co***as73c0cjd0",
      "endpoint": "/v1/chat/completions",
      "completion_window": "24h"
  }'

Cette requête renverra un objet Batch qui inclut des métadonnées sur votre batch, comme illustré dans l’exemple ci-dessous :

{
    "id": "batch_d2cq***73a68lu0",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "input_file_id": "file_d2co***as73c0cjd0",
    "output_file_id": "",
    "error_file_id": "",
    "completion_window": "24h",
    "in_progress_at": null,
    "expires_at": null,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "status": "validating",
    "errors": "",
    "version": 0,
    "created_at": "2025-08-11T16:31:52.949816948+08:00",
    "updated_at": null,
    "created_by": "8f242aa1-f725-4a67-8***9-cb68025e0976",
    "created_by_key_id": "key_cc19f96c***e7390644a37da21",
    "remark": "",
    "total": 0,
    "completed": 0,
    "failed": 0,
    "metadata": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    }
}

4. Vérifier le statut d’un batch

Vous pouvez vérifier le statut d’un batch à tout moment afin d’obtenir les informations les plus récentes sur celui-ci. Les valeurs d’énumération du statut de l’objet Batch sont les suivantes :

Statut	Description
VALIDATING	Le fichier d’entrée est en cours de validation avant que le batch puisse commencer
PROGRESS	Le batch est en cours
COMPLETED	Le traitement du batch s’est terminé avec succès
FAILED	Le traitement du batch a échoué
EXPIRED	Le batch a dépassé l’échéance
CANCELLING	Le batch est en cours d’annulation
CANCELLED	Le batch a été annulé

Exemple de code Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)
batch = client.batches.retrieve("batch_d2cq***73a68lu0")
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/batches/{batch_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

5. Récupérer les résultats

Une fois l’inférence par batch terminée, vous pouvez télécharger le fichier de sortie des résultats à l’aide du champ output_file_id de l’objet Batch. Le fichier de sortie des résultats sera supprimé 30 jours après la fin de l’inférence par batch ; veuillez donc le récupérer rapidement via l’interface. Exemple de code Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

content = client.files.content("example-250811-1")
print(content.read())

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/files/{file_id}/content \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

La réponse renvoie le contenu brut du fichier. Pour les fichiers de sortie de batch, chaque ligne contient une réponse comme celle-ci :

{
  "custom_id": "request-2589",
  "error": null,
  "id": "batch_req_task_d2c",
  "response": {
    "body": {
      "id": "29e1432c-edfb-44a4-b531-c23c600abfae",
      "object": "chat.completion",
      "created": 1754902266,
      "model": "deepseek-test",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! 👋 How can I assist you today? 😊"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 13,
        "total_tokens": 18
      }
    },
    "request_id": "request-2589",
    "status_code": 200
  }
}

Instructions

Limitations

Chaque batch peut contenir jusqu’à 50 000 requêtes.
La taille maximale du fichier d’entrée par batch est de 100MB.

Gestion des erreurs

Les erreurs rencontrées lors du traitement du batch sont enregistrées dans un fichier d’erreurs séparé, accessible via le champ error_file_id. Les codes d’erreur courants incluent :

Code d’erreur	Description	Solution
400	Format de requête non valide	Vérifiez la syntaxe JSONL et les champs requis
401	Échec de l’authentification	Vérifiez la clé API
404	Batch introuvable	Vérifiez l’ID du batch
429	Limite de débit dépassée	Réduisez la fréquence des requêtes
500	Erreur serveur	Contactez-nous

Expiration des batchs

Les batchs qui ne sont pas terminés dans les 24 heures passeront à l’état EXPIRED. Les requêtes non terminées seront annulées, tandis que les requêtes terminées seront fournies via un fichier de sortie. Vous ne payez que les tokens consommés par les requêtes terminées. Le batch fait tout son possible pour se terminer dans les 24 heures.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Démarrage rapide

1. Préparer les fichiers batch

2. Téléverser le fichier d’entrée du batch

3. Créer un batch

4. Vérifier le statut d’un batch

5. Récupérer les résultats

Instructions

Limitations

Gestion des erreurs

Expiration des batchs

Toutes les API Batch

​Démarrage rapide

​1. Préparer les fichiers batch

​2. Téléverser le fichier d’entrée du batch

​3. Créer un batch

​4. Vérifier le statut d’un batch

​5. Récupérer les résultats

​Instructions

​Limitations

​Gestion des erreurs

​Expiration des batchs

​Toutes les API Batch

Démarrage rapide

1. Préparer les fichiers batch

2. Téléverser le fichier d’entrée du batch

3. Créer un batch

4. Vérifier le statut d’un batch

5. Récupérer les résultats

Instructions

Limitations

Gestion des erreurs

Expiration des batchs

Toutes les API Batch