API de procesamiento por lotes

Aprende a usar la API de procesamiento por lotes de OpenAI para enviar grupos de solicitudes asíncronas con costos un 50 % menores, límites de solicitudes independientes y considerablemente más altos, y un plazo definido de 24 horas para obtener los resultados. El servicio es ideal para procesar trabajos que no requieren respuestas inmediatas. También puedes consultar directamente la referencia de la API aquí.

Descripción general

Aunque algunos usos de la plataforma de OpenAI requieren enviar solicitudes síncronas, en muchos casos las solicitudes no necesitan una respuesta inmediata o los límites de solicitudes impiden ejecutar una gran cantidad de consultas rápidamente. El procesamiento por lotes suele ser útil en casos de uso como:

1. Ejecutar evaluaciones
2. Clasificar grandes conjuntos de datos
3. Generar embeddings de repositorios de contenido
4. Poner en cola grandes trabajos de renderizado de video sin conexión

La API de procesamiento por lotes ofrece un conjunto sencillo de puntos de acceso que te permiten agrupar solicitudes en un solo archivo, iniciar un trabajo de procesamiento por lotes para ejecutarlas, consultar el estado del lote mientras se ejecutan las solicitudes y, finalmente, recuperar los resultados recopilados cuando se completa el lote.

En comparación con el uso directo de los puntos de acceso estándar, la API de procesamiento por lotes ofrece:

1. Menores costos: un descuento del 50 % en comparación con las API síncronas
2. Límites de solicitudes más altos: un margen considerablemente mayor en comparación con las API síncronas
3. Plazos de finalización breves: cada lote se completa en un plazo de 24 horas (y a menudo en menos tiempo)

Primeros pasos

1. Prepara tu archivo de lote

Los lotes comienzan con un archivo .jsonl en el que cada línea contiene los detalles de una solicitud individual a la API. Por ahora, los puntos de acceso disponibles son:

• /v1/responses (API Responses)
• /v1/chat/completions (API para completar chats)
• /v1/embeddings (API de embeddings)
• /v1/completions (API de completado)
• /v1/moderations (Guía de moderación)
• /v1/images/generations (API de imágenes)
• /v1/images/edits (API de imágenes)
• /v1/videos (Guía de generación de video)

En un archivo de entrada, los parámetros del campo body de cada línea son los mismos que los del punto de acceso correspondiente. Cada solicitud debe incluir un valor custom_id único, que puedes usar para identificar los resultados una vez completada. Aquí tienes un ejemplo de un archivo de entrada con 2 solicitudes. Ten en cuenta que cada archivo de entrada solo puede incluir solicitudes a un único modelo.

Para la generación de video mediante el procesamiento por lotes:

• Actualmente, el procesamiento por lotes solo admite POST /v1/videos.
• Las solicitudes de video por lotes deben usar JSON, no multipart.
• Carga los recursos con anticipación y pasa referencias compatibles a esos recursos en el cuerpo de la solicitud en lugar de usar cargas multipart.
• Usa input_reference para las generaciones guiadas por imágenes en el procesamiento por lotes. En las solicitudes JSON, pasa input_reference como un objeto con file_id o image_url.
• El procesamiento por lotes no admite cargas multipart de input_reference, incluidas las entradas de video de referencia.
• Los videos generados por lotes están disponibles para su descarga durante un máximo de 24 horas después de que se completa el lote.

Al enviar solicitudes a /v1/moderations, incluye un campo input en el cuerpo de cada solicitud. El procesamiento por lotes acepta entradas de texto sin formato y arreglos de contenido con entradas de texto o imágenes mediante omni-moderation-latest. El proceso de ejecución de lotes rechaza las solicitudes que establecen stream=true, al igual que el punto de acceso de moderación síncrono.

{"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}}

Ejemplos de entradas de moderación

Solicitud de solo texto:

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

Solicitud con entrada de texto e imagen:

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. Carga tu archivo de entrada del lote

Al igual que con nuestra API de ajuste fino, primero debes cargar tu archivo de entrada para poder hacer referencia a él correctamente al iniciar los lotes. Carga tu archivo .jsonl con la API de archivos.

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. Crea el lote

Una vez que hayas cargado correctamente tu archivo de entrada, puedes usar el ID del objeto File de entrada para crear un lote. En este caso, supongamos que el ID del archivo es file-abc123. Por ahora, el plazo de finalización solo se puede establecer en 24h. También puedes proporcionar metadatos personalizados mediante el parámetro opcional 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

Esta solicitud devolverá un objeto Batch con metadatos sobre tu lote:

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. Consulta el estado de un lote

Puedes consultar el estado de un lote en cualquier momento; esta consulta también devolverá un objeto 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

El estado de un objeto Batch puede ser cualquiera de los siguientes:

5. Obtener los resultados

Una vez que se complete el lote, puedes descargar los resultados haciendo una solicitud a la API de archivos con el campo output_file_id del objeto Batch y guardarlos en un archivo en tu equipo, en este caso 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

El archivo de salida .jsonl tendrá una línea de respuesta por cada línea de solicitud del archivo de entrada que se haya procesado correctamente. La información de error de las solicitudes fallidas del lote se guardará en un archivo de errores que puedes encontrar mediante el campo error_file_id del lote.

Para /v1/videos, el resultado de un lote completado contiene objetos de video que ya alcanzaron un estado final, como completed, failed o expired. Puedes usar los ID de video devueltos para descargar los archivos finales inmediatamente después de que termine el lote.

{"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}

El archivo de salida se eliminará automáticamente 30 días después de que se complete el lote.

6. Cancelar un lote

Si es necesario, puedes cancelar un lote en curso. El estado del lote cambiará a cancelling hasta que se completen las solicitudes en curso (hasta 10 minutos), tras lo cual cambiará a 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. Obtener una lista de todos los lotes

Puedes ver todos tus lotes en cualquier momento. Si tienes muchos lotes, puedes usar los parámetros limit y after para paginar los resultados.

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

Disponibilidad por modelo

La API de procesamiento por lotes está disponible para la mayoría de nuestros modelos, pero no para todos. Consulta la documentación de referencia de los modelos para asegurarte de que el modelo que usas sea compatible con la API de procesamiento por lotes.

Límites de solicitudes

Los límites de solicitudes de la API de procesamiento por lotes son independientes de los límites existentes por modelo. La API de procesamiento por lotes tiene tres tipos de límites de solicitudes:

1. Límites por lote: un solo lote puede incluir hasta 50 000 solicitudes, y un archivo de entrada de lote puede tener un tamaño de hasta 200 MB. Ten en cuenta que los lotes de /v1/embeddings también están limitados a un máximo de 50 000 entradas para embeddings entre todas las solicitudes del lote.
2. Tokens de prompt en cola por modelo: cada modelo tiene un número máximo de tokens de prompt que se pueden poner en cola para el procesamiento por lotes. Puedes consultar estos límites en la página de configuración de la plataforma.
3. Límite de frecuencia de creación de lotes: puedes crear hasta 2000 lotes por hora. Si necesitas enviar más solicitudes, aumenta el número de solicitudes por lote.

La API de procesamiento por lotes actualmente no tiene un límite de tokens de salida. Como sus límites de solicitudes ofrecen una capacidad nueva e independiente, usar la API de procesamiento por lotes no consumirá tokens de tus límites de solicitudes estándar por modelo. Esto te ofrece una forma práctica de aumentar el número de solicitudes y de tokens procesados al consultar nuestra API.

Vencimiento de los lotes

Los lotes que no se completan a tiempo terminan pasando al estado expired; las solicitudes sin terminar de ese lote se cancelan, y las respuestas de las solicitudes completadas quedan disponibles en el archivo de salida del lote. Se te cobrarán los tokens consumidos por todas las solicitudes completadas.

Las solicitudes vencidas se registrarán en tu archivo de errores con el mensaje que se muestra a continuación. Puedes usar custom_id para obtener los datos de las solicitudes vencidas.

{"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."}}