Guia do formato JSONL para a Batch API da OpenAI
Aprenda a estruturar arquivos JSONL para a Batch API da OpenAI e economize 50% nos custos
O que é a Batch API da OpenAI?
A Batch API da OpenAI permite enviar grandes volumes de requisições à API em um único job de processamento em lote. Em vez de fazer milhares de chamadas individuais à API, você envia um arquivo JSONL com todas as requisições, e a OpenAI as processa de forma assíncrona em até 24 horas.
A principal vantagem é o custo: as requisições em lote são 50% mais baratas que as chamadas à API em tempo real. Por isso, a Batch API é ideal para tarefas que dispensam respostas imediatas, como geração de conteúdo, classificação de dados, cálculo de embeddings e pipelines de avaliação.
Formato das requisições em JSONL
Cada linha do arquivo JSONL de entrada do lote representa uma requisição à API. Cada linha deve conter três campos obrigatórios e seguir uma estrutura específica.
custom_id — Um identificador exclusivo para cada requisição, usado para associar as respostas às requisições correspondentes. Pode ser qualquer string de até 512 caracteres.method — O método HTTP. Atualmente, só há suporte a POST.url — O caminho do endpoint da API. Para chat completions: /v1/chat/completions. Para embeddings: /v1/embeddings.body — O corpo da requisição, no mesmo formato exigido pelo endpoint correspondente da API.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}Chat completions em lote
O uso mais comum da Batch API é o envio de várias requisições de chat completion. Cada linha contém uma requisição completa, com model, messages e parâmetros opcionais, como max_tokens ou temperature.
Uma requisição
Cada linha contém uma requisição completa de chat completion, com model, messages e parâmetros opcionais.
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}Arquivo JSONL com várias requisições
Um arquivo de lote costuma conter centenas ou milhares de requisições. O exemplo a seguir contém três tarefas diferentes: resumo, classificação e tradução.
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}Embeddings em lote
A Batch API também aceita requisições de embeddings, o que é útil para processar grandes coleções de documentos. Os lotes de embeddings usam a mesma estrutura JSONL, mas as requisições são enviadas ao endpoint /v1/embeddings.
As requisições de embeddings têm um corpo mais simples, com model e o texto de entrada.
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}Formato das respostas
Quando o processamento do lote termina, a OpenAI disponibiliza um arquivo JSONL de saída em que cada linha contém a resposta a uma requisição. A resposta inclui o custom_id original para que você possa associá-la à requisição correspondente.
Resposta de sucesso
Uma resposta de sucesso inclui o custom_id, o código de status da resposta e o corpo completo da resposta da API.
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}Resposta de erro
As requisições que falham incluem um objeto de erro com um código e uma mensagem que explica o problema.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}Fluxo completo de uso da Batch API
Veja o fluxo completo, em cinco etapas, para usar a Batch API com o SDK para Python, desde a criação do arquivo JSONL até o download e a leitura dos resultados.
- 1Crie um arquivo JSONL com uma requisição por linha
- 2Envie o arquivo pela Files API com purpose definido como batch
- 3Crie um job de processamento em lote usando o ID do arquivo enviado
- 4Consulte periodicamente o status do lote até que seja completed, failed ou cancelled
- 5Baixe e leia o arquivo JSONL de saída para extrair os resultados
from openai import OpenAI
import json
import time
client = OpenAI()
# Step 1: Create the JSONL batch file
prompts = [
"Summarize the benefits of renewable energy.",
"Classify this text as positive or negative: Great product!",
"Translate to French: Hello, how are you?",
]
requests = [
{
"custom_id": f"req-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 200,
},
}
for i, prompt in enumerate(prompts)
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# Step 2: Upload the file
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Step 3: Create the batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(f"Batch created: {batch.id}")
# Step 4: Poll for completion
while True:
status = client.batches.retrieve(batch.id)
print(f"Status: {status.status}")
if status.status in ("completed", "failed", "cancelled"):
break
time.sleep(60)
# Step 5: Download results
if status.output_file_id:
content = client.files.content(status.output_file_id)
with open("batch_output.jsonl", "wb") as f:
f.write(content.read())Batch API ou API em tempo real
Saber quando usar a Batch API ou a API padrão em tempo real ajuda você a otimizar os custos e o desempenho.
Para saber mais sobre o formato JSONL usado no fine-tuning da OpenAI, consulte nosso Guia do formato JSONL da OpenAI.
Prepare seus arquivos de lote
Use nossas ferramentas gratuitas para criar, validar e inspecionar seus arquivos JSONL de lote antes de enviá-los à OpenAI.
Guia completo para preparar arquivos JSONL para a OpenAI. Conheça o formato dos dados de fine-tuning, as requisições da Batch API, os erros comuns e as dicas de validação.
Divida arquivos JSONL grandes em partes menores e gerenciáveis por número de linhas.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
Estratégias para processar gigabytes de dados JSONL: leitura por streaming, gerenciamento de memória, divisão de arquivos, compressão e ferramentas online.
Aprenda a preparar dados de treinamento em JSONL para fine-tuning de IA/ML. Conheça os formatos de datasets da OpenAI, do Anthropic Claude e do HuggingFace, com validação e pipelines de preparação de dados.