API de traitement par lots

Découvrez comment utiliser l’API de traitement par lots d’OpenAI pour envoyer des groupes de requêtes asynchrones à un coût réduit de 50 %, avec des limites de débit distinctes et nettement plus élevées, et un délai de traitement de 24 heures. Ce service est idéal pour les tâches qui ne nécessitent pas de réponse immédiate. Vous pouvez également consulter directement la référence de l’API ici.

Vue d’ensemble

Certaines utilisations de la plateforme OpenAI nécessitent l’envoi de requêtes synchrones. Dans de nombreux cas, toutefois, les requêtes n’exigent pas de réponse immédiate, ou les limites de débit empêchent d’exécuter rapidement un grand nombre de requêtes. Le traitement par lots est souvent utile pour les cas d’utilisation suivants :

1. Exécution d’évaluations
2. Classification de grands jeux de données
3. Création de plongements vectoriels pour des collections de contenus
4. Mise en file d’attente de tâches importantes de rendu vidéo hors ligne

L’API de traitement par lots propose un ensemble de points de terminaison simples à utiliser. Ils permettent de regrouper des requêtes dans un seul fichier, de lancer leur traitement par lots, de consulter l’état du lot pendant l’exécution des requêtes, puis de récupérer l’ensemble des résultats une fois le traitement terminé.

Par rapport à l’utilisation directe des points de terminaison standard, l’API de traitement par lots offre les avantages suivants :

1. Coûts réduits : une réduction de 50 % par rapport aux API synchrones
2. Limites de débit plus élevées : une marge nettement plus importante que celle des API synchrones
3. Traitement rapide : chaque lot est traité en 24 heures maximum (et souvent plus rapidement)

Bien démarrer

1. Préparez votre fichier de lot

Le traitement d’un lot commence par un fichier .jsonl dont chaque ligne contient les détails d’une requête individuelle à l’API. Pour le moment, les points de terminaison disponibles sont les suivants :

• /v1/responses (API Responses)
• /v1/chat/completions (API Chat Completions)
• /v1/embeddings (API de plongements vectoriels)
• /v1/completions (API Completions)
• /v1/moderations (Guide de modération)
• /v1/images/generations (API Images)
• /v1/images/edits (API Images)
• /v1/videos (Guide de génération de vidéos)

Dans un fichier d’entrée donné, les paramètres du champ body de chaque ligne sont les mêmes que ceux du point de terminaison sous-jacent. Chaque requête doit inclure une valeur custom_id unique, qui permet de retrouver les résultats une fois le traitement terminé. Voici un exemple de fichier d’entrée contenant 2 requêtes. Chaque fichier d’entrée ne peut contenir que des requêtes destinées à un seul modèle.

Pour la génération de vidéos par lots :

• Le traitement par lots prend actuellement en charge uniquement POST /v1/videos.
• Les requêtes de génération de vidéos par lots doivent utiliser le format JSON, et non multipart.
• Importez les ressources à l’avance et transmettez des références prises en charge vers ces ressources dans le corps de la requête plutôt que d’effectuer des envois multipart.
• Utilisez input_reference pour les générations guidées par une image dans le traitement par lots. Dans les requêtes JSON, transmettez input_reference sous la forme d’un objet contenant soit file_id, soit image_url.
• Les envois multipart de input_reference, y compris les vidéos de référence en entrée, ne sont pas pris en charge dans le traitement par lots.
• Les vidéos générées par lots peuvent être téléchargées pendant une durée maximale de 24 heures après la fin du traitement du lot.

Lorsque vous ciblez /v1/moderations, incluez un champ input dans le corps de chaque requête. Le traitement par lots accepte les entrées en texte brut ainsi que les tableaux de contenus comprenant du texte ou des images avec omni-moderation-latest. Le processus de traitement par lots rejette les requêtes qui définissent stream=true, comme le fait le point de terminaison de modération synchrone.

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo-0125", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo-0125", "messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

Exemples d’entrées pour la modération

Requête contenant uniquement du texte :

123456789{
  "custom_id": "moderation-text-1",
  "method": "POST",
  "url": "/v1/moderations",
  "body": {
    "model": "omni-moderation-latest",
    "input": "This is a harmless test sentence."
  }
}

Requête contenant du texte et une image en entrée :

1234567891011121314151617181920{
  "custom_id": "moderation-mm-1",
  "method": "POST",
  "url": "/v1/moderations",
  "body": {
    "model": "omni-moderation-latest",
    "input": [
      {
        "type": "text",
        "text": "Describe this image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"
        }
      }
    ]
  }
}

2. Importez le fichier d’entrée de votre lot

Comme avec notre API d’affinage, vous devez d’abord importer votre fichier d’entrée afin de pouvoir le référencer correctement lors du lancement des lots. Importez votre fichier .jsonl à l’aide de l’API Files.

1
2
3
4
5
6
7
8
9
10import fs from "fs";
import OpenAI from "openai";
const openai = new OpenAI();

const file = await openai.files.create({
  file: fs.createReadStream("fixtures/batchinput.jsonl"),
  purpose: "batch",
});

console.log(file);

1
2
3
4
5
6
7
8
9from openai import OpenAI

client = OpenAI()

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

print(batch_input_file)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	file, err := os.Open("batchinput.jsonl")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	uploaded, err := client.Files.New(context.Background(), openai.FileNewParams{
		File:    file,
		Purpose: openai.FilePurposeBatch,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(uploaded.ID)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileCreateParams;
import com.openai.models.files.FilePurpose;
import java.nio.file.Path;

var file =
    client
        .files()
        .create(
            FileCreateParams.builder()
                .file(Path.of(System.getenv("OPENAI_EXAMPLE_FILE_PATH")))
                .purpose(FilePurpose.BATCH)
                .build());

System.out.println(file.id());

1
2
3
4
5
6
7require "openai"
require "pathname"

client = OpenAI::Client.new
file = Pathname("batchinput.jsonl")
uploaded = client.files.create(file: file, purpose: :batch)
puts(uploaded.id)

1
2
3
4curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@batchinput.jsonl"

1
2
3openai files create \
  --file batchinput.jsonl \
  --purpose batch

3. Créez le lot

Une fois votre fichier d’entrée importé, vous pouvez utiliser l’identifiant de l’objet File correspondant pour créer un lot. Dans cet exemple, supposons que l’identifiant du fichier soit file-abc123. Pour le moment, le délai de traitement ne peut être défini que sur 24h. Vous pouvez également fournir des métadonnées personnalisées à l’aide du paramètre facultatif metadata.

1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.create({
  input_file_id: "file-abc123",
  endpoint: "/v1/chat/completions",
  completion_window: "24h",
});

console.log(batch);

1
2
3
4
5
6
7batch = client.batches.create(
    input_file_id=batch_input_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={"description": "nightly eval job"},
)
print(batch)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.New(context.Background(), openai.BatchNewParams{
		InputFileID:      "file-abc123",
		Endpoint:         openai.BatchNewParamsEndpointV1ChatCompletions,
		CompletionWindow: openai.BatchNewParamsCompletionWindow24h,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.ID)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.batches.BatchCreateParams;

String fileId = "file-abc123";

var batch =
    client
        .batches()
        .create(
            BatchCreateParams.builder()
                .inputFileId(fileId)
                .endpoint(BatchCreateParams.Endpoint.V1_RESPONSES)
                .completionWindow(BatchCreateParams.CompletionWindow._24H)
                .build());

System.out.println(batch.id());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.create(input_file_id: "file-abc123", endpoint: "/v1/responses", completion_window: "24h")
puts(batch.id)

1
2
3
4
5
6
7
8curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

1
2
3
4openai batches create \
  --input-file-id file-abc123 \
  --endpoint /v1/chat/completions \
  --completion-window 24h

Cette requête renvoie un objet Batch contenant des métadonnées sur votre lot :

1234567891011121314151617181920212223{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1714508499,
  "in_progress_at": null,
  "expires_at": 1714536634,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}

4. Vérifiez l’état d’un lot

Vous pouvez vérifier l’état d’un lot à tout moment. Cette opération renvoie également un objet Batch.

1
2
3
4
5import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.retrieve("batch_abc123");
console.log(batch);

1
2batch = client.batches.retrieve(batch.id)
print(batch)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.Get(context.Background(), "batch_abc123")
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.Status)
}

1
2
3
4
5
6
7
8import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

String batchId = "batch_abc123";

var batch = client.batches().retrieve(batchId);

System.out.println(batch.status());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.retrieve("batch_abc123")
puts(batch.status)

1
2
3curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2openai batches retrieve \
  --batch-id batch_abc123

L’état d’un objet Batch peut prendre l’une des valeurs suivantes :

5. Récupérez les résultats

Une fois le traitement du lot terminé, vous pouvez télécharger les résultats en envoyant une requête à l’API Files à l’aide du champ output_file_id de l’objet Batch, puis en les enregistrant dans un fichier sur votre machine, ici batch_output.jsonl

1
2
3
4
5
6
7import OpenAI from "openai";
const openai = new OpenAI();

const fileResponse = await openai.files.content("file-xyz123");
const fileContents = await fileResponse.text();

console.log(fileContents);

1
2
3
4
5
6
7
8
9# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI

output_file_id = "file_123"
client = OpenAI()

file_response = client.files.content(output_file_id)
print(file_response.text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"
	"io"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	response, err := client.Files.Content(context.Background(), "file-xyz123")
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	contents, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(contents))
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponse;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

String fileId = "file-xyz123";

try (HttpResponse content = client.files().content(fileId)) {
  Files.copy(
      content.body(), Path.of("batch_output.jsonl"), StandardCopyOption.REPLACE_EXISTING);
}

1
2
3
4
5require "openai"

client = OpenAI::Client.new
content = client.files.content("file-xyz123")
puts(content.read)

1
2curl https://api.openai.com/v1/files/file-xyz123/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > batch_output.jsonl

1
2
3openai files content \
  --file-id file-xyz123 \
  --output batch_output.jsonl

Le fichier de sortie .jsonl contiendra une ligne de réponse pour chaque ligne du fichier d’entrée dont la requête a réussi. Pour les requêtes du lot qui ont échoué, les informations d’erreur seront enregistrées dans un fichier d’erreurs accessible via le champ error_file_id du lot.

Pour /v1/videos, les résultats d’un lot terminé contiennent des objets vidéo qui ont déjà atteint un état final, tel que completed, failed ou expired. Vous pouvez utiliser les identifiants vidéo renvoyés pour télécharger les fichiers finaux dès la fin du traitement du lot.

{"id": "batch_req_123", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_123", "body": {"id": "chatcmpl-123", "object": "chat.completion", "created": 1711652795, "model": "gpt-3.5-turbo-0125", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello."}, "logprobs": null, "finish_reason": "stop"}], "usage": {"prompt_tokens": 22, "completion_tokens": 2, "total_tokens": 24}, "system_fingerprint": "fp_123"}}, "error": null}
{"id": "batch_req_456", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req_789", "body": {"id": "chatcmpl-abc", "object": "chat.completion", "created": 1711652789, "model": "gpt-3.5-turbo-0125", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello! How can I assist you today?"}, "logprobs": null, "finish_reason": "stop"}], "usage": {"prompt_tokens": 20, "completion_tokens": 9, "total_tokens": 29}, "system_fingerprint": "fp_3ba"}}, "error": null}

Le fichier de sortie sera automatiquement supprimé 30 jours après la fin du traitement du lot.

6. Annulez le traitement d’un lot

Si nécessaire, vous pouvez annuler le traitement d’un lot en cours. L’état du lot passera à cancelling jusqu’à la fin des requêtes en cours d’exécution (jusqu’à 10 minutes), puis à cancelled.

1
2
3
4
5import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.cancel("batch_abc123");
console.log(batch);

1
2
3
4
5
6
7
8# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI

batch_id = "batch_123"
client = OpenAI()

client.batches.cancel(batch_id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.Cancel(context.Background(), "batch_abc123")
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.Status)
}

1
2
3
4
5
6import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

String batchId = "batch_abc123";

System.out.println(client.batches().cancel(batchId).status());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.cancel("batch_abc123")
puts(batch.status)

1
2
3
4curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST

1
2openai batches cancel \
  --batch-id batch_abc123

7. Obtenez la liste de tous les lots

Vous pouvez consulter tous vos lots à tout moment. Si vous en avez beaucoup, vous pouvez utiliser les paramètres limit et after pour paginer les résultats.

1
2
3
4
5
6
7
8import OpenAI from "openai";
const openai = new OpenAI();

const list = await openai.batches.list();

for await (const batch of list) {
  console.log(batch);
}

1
2
3
4
5from openai import OpenAI

client = OpenAI()

client.batches.list(limit=10)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	list := client.Batches.ListAutoPaging(context.Background(), openai.BatchListParams{Limit: openai.Int(10)})
	for list.Next() {
		fmt.Println(list.Current().ID)
	}
	if err := list.Err(); err != nil {
		panic(err)
	}
}

1
2
3
4
5
6
7
8
9import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.batches.BatchListParams;

client
    .batches()
    .list(BatchListParams.builder().limit(10).build())
    .autoPager()
    .forEach(batch -> System.out.println(batch.id()));

1
2
3
4
5
6require "openai"

client = OpenAI::Client.new
client.batches.list(limit: 10).auto_paging_each do |batch|
  puts(batch.id)
end

1
2
3curl https://api.openai.com/v1/batches?limit=10 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2openai batches list \
  --limit 10

Disponibilité des modèles

L’API de traitement par lots est disponible pour la plupart de nos modèles, mais pas tous. Consultez la documentation de référence des modèles pour vérifier que le modèle que vous utilisez prend en charge l’API de traitement par lots.

Limites de débit

Les limites de débit de l’API de traitement par lots sont distinctes des limites existantes propres à chaque modèle. L’API de traitement par lots comporte trois types de limites de débit :

1. Limites par lot : Un lot peut contenir jusqu’à 50 000 requêtes, et son fichier d’entrée peut atteindre 200 Mo. Notez que les lots destinés à /v1/embeddings sont également limités à un total de 50 000 entrées à convertir en embeddings, toutes requêtes du lot confondues.
2. Tokens de prompt en attente par modèle : Chaque modèle impose un nombre maximal de tokens de prompt pouvant être mis en file d’attente pour un traitement par lots. Vous trouverez ces limites sur la page Paramètres de la plateforme.
3. Limite de débit de création des lots : Vous pouvez créer jusqu’à 2 000 lots par heure. Si vous devez envoyer davantage de requêtes, augmentez le nombre de requêtes par lot.

L’API de traitement par lots n’impose actuellement aucune limite de tokens de sortie. Ses limites de débit constituant un nouveau quota distinct, son utilisation ne décompte aucun token des limites de débit standard propres à chaque modèle. Elle vous permet ainsi d’augmenter facilement le nombre de requêtes et de tokens traités lorsque vous interrogez notre API.

Expiration des lots

Les lots dont le traitement ne se termine pas dans le délai imparti finissent par passer à l’état expired. Les requêtes inachevées sont alors annulées, et les réponses aux requêtes terminées sont disponibles dans le fichier de sortie du lot. Les tokens consommés par les requêtes terminées vous seront facturés.

Les requêtes expirées seront enregistrées dans votre fichier d’erreurs avec le message ci-dessous. Vous pouvez utiliser custom_id pour retrouver les données de ces requêtes.

{"id": "batch_req_123", "custom_id": "request-3", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_123", "custom_id": "request-7", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}