Batch API: Processamento Assíncrono em Massa
Nesta página
Atualizado a 3 de novembro de 2026 com base no guia da Batch API e na estrutura de resposta da Responses API: a leitura dos resultados já não assume que o primeiro elemento de
outputé a mensagem (um elemento de raciocínio pode precedê-la), e a chave do código de erro, escrita sem aspas, gerava umNameError. Fonte: Batch API.
Troque Latência por Custo
A Batch API opera num princípio de mercado simples: aceita que os seus pedidos sejam processados de forma assíncrona numa janela de até vinte e quatro horas e, em troca, paga cinquenta por cento menos. Tudo o que não precise de servir um humano à espera diante do ecrã entra nesta categoria. À escala, isto não é uma micro-otimização; corta a sua linha orçamental ao meio.
O hábito a criar numa equipa é perguntar, para cada nova tarefa de processamento, se alguém está à espera do resultado. Analisar um stock de contratos, gerar fichas de produto para um catálogo, executar um benchmark em milhares de casos de teste, classificar um backlog de tickets de seis meses, extrair campos de um lote de faturas: em todos estes casos, a resposta vai parar a um dashboard ou a uma base de dados, não a uma interface conversacional. O atraso é invisível, mas a poupança não.
Construa e Lance um Lote
O formato de entrada é um ficheiro JSONL: uma linha por pedido, onde cada linha é um objeto completo e independente. O campo custom_id é o que lhe permite ligar cada resposta ao seu pedido original, já que nada garante a ordem do ficheiro de saída. Escolha um ID que seja estável e significativo — um ID de documento da sua base de dados em vez de um número de iteração — caso contrário, a fase de reconciliação tornar-se-á um pesadelo.
import json
requests = [
{
"custom_id": f"doc-{i}",
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "gpt-5.6-luna",
"input": f"Summarize this document in 3 key points: {doc}",
"max_output_tokens": 500,
},
}
for i, doc in enumerate(documents_list)
]
# Write the JSONL file
with open("batch_input.jsonl", "w") as f:
for request in requests:
f.write(json.dumps(request) + "\n")
O ficheiro é depois carregado e referenciado aquando da criação do lote. Os metadados não servem nenhum propósito técnico, mas salvar-lhe-ão o dia quando tiver três lotes a correr em paralelo e precisar de descobrir qual corresponde a qual versão do prompt.
import openai
client = openai.OpenAI()
# Upload the file
file_obj = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Create the batch
batch = client.batches.create(
input_file_id=file_obj.id,
endpoint="/v1/responses",
completion_window="24h",
metadata={"project": "contract-analysis", "version": "2.1"},
)
print(f"Batch created: {batch.id}")
print(f"Status: {batch.status}")
A monitorização envolve consultar o lote repetidamente até que este saia do estado «em progresso», descarregando depois o ficheiro de saída, que também está no formato JSONL. O ciclo abaixo distingue três resultados terminais — failed, expired, cancelled — e gera uma exceção para cada um: um lote expirado é aquele em que a janela de vinte e quatro horas passou antes de tudo ser processado, e tratá-lo como um sucesso parcial silencioso seria a pior opção.
import time
def wait_for_batch(batch_id: str, interval: int = 60) -> list:
"""Waits for a batch to finish and returns the results."""
while True:
batch = client.batches.retrieve(batch_id)
print(
f"Status: {batch.status} | "
f"Completed: {batch.request_counts.completed}/"
f"{batch.request_counts.total} | "
f"Failed: {batch.request_counts.failed}"
)
if batch.status == "completed":
break
elif batch.status in ("failed", "expired", "cancelled"):
raise RuntimeError(f"Batch failed: {batch.status}")
time.sleep(interval)
# Download results
content = client.files.content(batch.output_file_id)
results = []
for line in content.text.strip().split("\n"):
results.append(json.loads(line))
return results
results = wait_for_batch(batch.id)
# Process results
for result in results:
custom_id = result["custom_id"]
response = result["response"]
if response["status_code"] == 200:
# output may contain other elements before the message
# (reasoning, for example): look for the message text
text = next(
part["text"]
for item in response["body"]["output"] if item["type"] == "message"
for part in item["content"] if part["type"] == "output_text"
)
print(f"{custom_id}: {text[:100]}...")
else:
print(f"{custom_id}: ERROR {response['status_code']}")
Planeie Falhas Parciais
Num lote grande, alguns pedidos falharão: um documento truncado, um excesso de contexto ou um erro transitório do lado do servidor. Um lote, portanto, nunca é simplesmente «bem-sucedido» ou «falhado» — é parcialmente bem-sucedido, e tem de saber isolar a parte em falta. O padrão a adotar é separar imediatamente os sucessos das falhas e regenerar um ficheiro JSONL pronto para ser relançado, em vez de vasculhar registos três dias depois para reconstruir o que falta.
def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
"""Separates successes from failures for reprocessing."""
successes = []
failures = []
for r in results:
if r["response"]["status_code"] == 200:
successes.append(r)
else:
failures.append(r)
if failures:
print(f"Warning: {len(failures)} failed requests out of {len(results)}")
# Rewrite a JSONL file with failures for retry
with open("batch_retry.jsonl", "w") as f:
for failure in failures:
original_request = {
"custom_id": failure["custom_id"],
"method": "POST",
"url": "/v1/responses",
"body": failure["request"]["body"],
}
f.write(json.dumps(original_request) + "\n")
return successes, failures
Potencie as Suas Poupanças
Numa execução de processamento de dez mil documentos com o GPT-5.6 Luna, a API síncrona representa o custo base, a Batch API representa metade disso, e o cache de prompts soma-se, já que os tokens em cache também beneficiam da sua própria redução. Os dois mecanismos não competem: se os seus dez mil pedidos partilharem o mesmo prompt de sistema longo, estruture-o como um prefixo estável e potenciará ambos os efeitos.
Finalmente, há a questão da divisão. Um lote não deve ser infinito, e é mais confortável monitorizar vários lotes geríveis do que um único monólito cuja falha custe um dia inteiro. A função seguinte divide uma lista de pedidos em lotes de tamanho limitado.
def create_optimized_batches(
requests: list[dict],
max_size: int = 50_000,
) -> list[list[dict]]:
"""Splits into batches of optimal size."""
batches = []
current_batch = []
for request in requests:
current_batch.append(request)
if len(current_batch) >= max_size:
batches.append(current_batch)
current_batch = []
if current_batch:
batches.append(current_batch)
return batches
Pontos-chave
- A Batch API oferece uma redução de 50% para processamento não em tempo real
- Prepare os seus pedidos num ficheiro JSONL com um
custom_idúnico por pedido - Planeie um mecanismo de repetição para pedidos falhados
- Combine com o cache de prompts para maximizar as poupanças