API de processamento em lote

Aprenda a usar a API de processamento em lote da OpenAI para enviar grupos de solicitações assíncronas com custos 50% menores, limites de taxa separados e significativamente mais altos e um prazo definido de 24 horas para conclusão. O serviço é ideal para processar tarefas que não exigem respostas imediatas. Você também pode consultar a referência da API diretamente aqui.

Visão geral

Embora alguns usos da plataforma da OpenAI exijam o envio de solicitações síncronas, há muitos casos em que as solicitações não precisam de uma resposta imediata ou em que os limites de taxa impedem a execução rápida de um grande número de consultas. O processamento em lote costuma ser útil em casos de uso como:

1. Executar avaliações
2. Classificar grandes conjuntos de dados
3. Gerar embeddings de repositórios de conteúdo
4. Enfileirar grandes tarefas de renderização de vídeo offline

A API de processamento em lote oferece um conjunto simples de endpoints que permitem reunir solicitações em um único arquivo, iniciar uma tarefa de processamento em lote para executá-las, consultar o status do lote enquanto as solicitações são executadas e, por fim, recuperar os resultados reunidos quando o lote for concluído.

Em comparação com o uso direto dos endpoints padrão, a API de processamento em lote oferece:

1. Custos menores: desconto de 50% em relação às APIs síncronas
2. Limites de taxa mais altos: Capacidade significativamente maior em comparação com as APIs síncronas
3. Conclusão rápida: Cada lote é concluído em até 24 horas (e muitas vezes antes disso)

Primeiros passos

1. Prepare seu arquivo de lote

Os lotes começam com um arquivo .jsonl em que cada linha contém os detalhes de uma solicitação individual à API. Por enquanto, os endpoints disponíveis são:

• /v1/responses (Responses API)
• /v1/chat/completions (API chat completions)
• /v1/embeddings (API de embeddings)
• /v1/completions (API de completions)
• /v1/moderations (Guia de moderação)
• /v1/images/generations (API de imagens)
• /v1/images/edits (API de imagens)
• /v1/videos (Guia de geração de vídeos)

Em um arquivo de entrada, os parâmetros do campo body de cada linha são os mesmos do endpoint correspondente. Cada solicitação deve incluir um valor exclusivo de custom_id, que você pode usar para identificar os resultados após a conclusão. Veja um exemplo de arquivo de entrada com 2 solicitações. Cada arquivo de entrada só pode incluir solicitações a um único modelo.

Para geração de vídeos no processamento em lote:

• Atualmente, o processamento em lote oferece suporte apenas a POST /v1/videos.
• As solicitações de vídeo no processamento em lote devem usar JSON, e não multipart.
• Envie os recursos com antecedência e passe referências a eles em um formato compatível no corpo da solicitação, em vez de usar uploads multipart.
• Use input_reference para gerações guiadas por imagens no processamento em lote. Nas solicitações JSON, passe input_reference como um objeto com file_id ou image_url.
• O processamento em lote não oferece suporte a uploads multipart de input_reference, incluindo entradas de vídeo de referência.
• Os vídeos gerados por processamento em lote ficam disponíveis para download por até 24 horas após a conclusão do lote.

Ao enviar solicitações para /v1/moderations, inclua um campo input no corpo de cada solicitação. O processamento em lote aceita entradas de texto simples e arrays de conteúdo com entradas de texto ou imagem usando omni-moderation-latest. O processo executor do processamento em lote rejeita solicitações que definem stream=true, assim como o endpoint síncrono de moderação.

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

Exemplos de entrada para moderação

Solicitação somente com texto:

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

Solicitação com entrada de texto e imagem:

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. Envie seu arquivo de entrada do lote

Assim como na nossa API de ajuste fino, você precisa primeiro enviar seu arquivo de entrada para poder referenciá-lo corretamente ao iniciar os lotes. Envie seu arquivo .jsonl usando a API de arquivos.

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. Crie o lote

Após enviar seu arquivo de entrada com sucesso, você pode usar o ID do objeto File correspondente para criar um lote. Neste caso, vamos supor que o ID do arquivo seja file-abc123. Por enquanto, a janela de conclusão só pode ser definida como 24h. Você também pode fornecer metadados personalizados pelo 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 solicitação retornará um objeto Batch com metadados sobre seu 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. Consulte o status de um lote

Você pode consultar o status de um lote a qualquer momento. Essa consulta também retorna um 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

O status de um objeto Batch pode ser qualquer um dos seguintes:

5. Obtenha os resultados

Quando o lote for concluído, você poderá baixar a saída fazendo uma requisição à Files API com o campo output_file_id do objeto Batch e salvando o conteúdo em um arquivo na sua máquina, neste 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

O arquivo de saída .jsonl terá uma linha de resposta para cada linha de requisição bem-sucedida no arquivo de entrada. As informações de erro de todas as requisições que falharem no lote serão gravadas em um arquivo de erros, que pode ser localizado pelo campo error_file_id do lote.

Para /v1/videos, o resultado de um lote concluído contém objetos de vídeo que já atingiram um estado terminal, como completed, failed ou expired. Você pode usar os IDs de vídeo retornados para baixar os arquivos finais assim que o lote terminar.

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

O arquivo de saída será excluído automaticamente 30 dias após a conclusão do lote.

6. Cancele um lote

Se necessário, você pode cancelar um lote em andamento. O status do lote mudará para cancelling até que as requisições em andamento sejam concluídas (até 10 minutos). Depois disso, o status mudará para 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. Obtenha uma lista de todos os lotes

Você pode visualizar todos os seus lotes a qualquer momento. Se tiver muitos lotes, pode usar os parâmetros limit e after para paginar os 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

Disponibilidade dos modelos

A Batch API está disponível para a maioria dos nossos modelos, mas não para todos. Consulte a documentação de referência dos modelos para confirmar se o modelo que você está usando oferece suporte à Batch API.

Limites de taxa

Os limites de taxa da Batch API são separados dos limites de taxa existentes por modelo. A Batch API tem três tipos de limites de taxa:

1. Limites por lote: Um único lote pode incluir até 50.000 requisições, e o arquivo de entrada de um lote pode ter até 200 MB. Observe que os lotes de /v1/embeddings também estão limitados a um total de 50.000 entradas para embeddings, somando todas as requisições do lote.
2. Tokens de prompt na fila por modelo: Cada modelo tem um número máximo de tokens de prompt que podem ficar na fila para processamento em lote. Você pode consultar esses limites na página de configurações da plataforma.
3. Limite de taxa de criação de lotes: Você pode criar até 2.000 lotes por hora. Se precisar enviar mais requisições, aumente o número de requisições por lote.

Atualmente, a Batch API não tem limite de tokens de saída. Como os limites de taxa da Batch API compõem uma nova cota separada, usar a Batch API não consumirá tokens dos seus limites de taxa padrão por modelo. Isso oferece uma maneira prática de aumentar o número de requisições e de tokens processados ao consultar nossa API.

Expiração de lotes

Os lotes que não forem concluídos dentro do prazo acabarão passando para o estado expired. As requisições não concluídas nesses lotes serão canceladas, e as respostas das requisições concluídas ficarão disponíveis no arquivo de saída do lote. Você será cobrado pelos tokens consumidos em todas as requisições concluídas.

As requisições expiradas serão gravadas no arquivo de erros com a mensagem mostrada abaixo. Você pode usar custom_id para recuperar os dados das requisições expiradas.

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