Modo em segundo plano
Nesta página
Uma terceira via entre o síncrono e o lote
O modo em segundo plano da API de Respostas preenche um nicho específico no seu conjunto de ferramentas. Uma chamada síncrona fornece a resposta imediatamente, mas obriga-o a manter a ligação aberta durante toda a geração. A API de Lote processa milhares de pedidos a metade do preço, mas os resultados demoram horas. O modo em segundo plano situa-se entre ambos: gere pedidos individuais à tarifa padrão sem necessidade de uma ligação aberta. Submete o pedido, recebe um ID e recupera o resultado quando este estiver pronto.
Este compromisso visa um caso de uso preciso: um pedido único que demora demasiado tempo para uma chamada bloqueante, mas que não pode esperar até ao dia seguinte. Este é exatamente o cenário ao executar um modelo de raciocínio elevado num documento complexo.
Lançamento e recuperação
A ativação requer apenas um parâmetro. A resposta imediata não contém texto; devolve um ID e um estado, tipicamente queued ou in_progress.
import openai
client = openai.OpenAI()
# Lançar o pedido em segundo plano
response = client.responses.create(
model="gpt-5.6-sol", # Ideal para tarefas lentas (raciocínio elevado)
input="Analyze the economic implications of European AI regulation "
"for French SMEs. Propose a 10-point action plan.",
background=True, # Modo em segundo plano
)
print(f"Response ID: {response.id}")
print(f"Status: {response.status}") # "queued" ou "in_progress"
Este ID é a sua única ligação ao trabalho em curso: persista-o antes de fazer qualquer outra coisa. Perdê-lo significa pagar por uma geração que nunca recuperará. A recuperação envolve então sondar a API até que o estado se torne terminal, tratando a falha e o cancelamento separadamente, uma vez que têm consequências comerciais distintas.
import time
def wait_for_response(response_id: str, interval: int = 5) -> str:
"""Aguarda a conclusão de uma resposta em segundo plano."""
while True:
response = client.responses.retrieve(response_id)
match response.status:
case "completed":
return response.output_text
case "failed":
raise RuntimeError(
f"Request failed: {response.error}"
)
case "cancelled":
raise RuntimeError("Request was cancelled.")
case _:
print(f"Status: {response.status}...")
time.sleep(interval)
Tarefas de raciocínio longo
Um modelo como o GPT-5.6 Sol, com raciocínio elevado ativado, pode demorar entre 30 segundos e dois minutos antes de produzir o seu primeiro token visível. Numa chamada síncrona, estas durações atingem os tempos limite predefinidos dos clientes HTTP, proxies e gateways. O modo em segundo plano elimina este problema na raiz e, incidentalmente, permite-lhe lançar várias análises pesadas sem ocupar tantas ligações.
async def deep_analysis(document: str) -> str:
"""Lança uma análise com o GPT-5.6 Sol sem bloquear."""
response = client.responses.create(
model="gpt-5.6-sol",
input=f"Perform a thorough legal analysis of this contract. "
f"Identify all potential risks, problematic clauses, "
f"and propose modifications.\n\n{document}",
background=True,
)
return response.id
# Lançar múltiplas análises em paralelo
task_ids = []
for doc in documents:
task_id = await deep_analysis(doc)
task_ids.append(task_id)
# Recuperar resultados mais tarde
results = {}
for task_id in task_ids:
results[task_id] = wait_for_response(task_id)
Este padrão estende-se naturalmente aos webhooks quando o chamador é outro serviço. O seu endpoint lança o pedido, devolve o ID e delega uma tarefa em segundo plano para monitorizar a conclusão e enviar notificações. O chamador não sonda; é notificado.
from fastapi import FastAPI, BackgroundTasks
import httpx
app = FastAPI()
@app.post("/api/long-analysis")
async def launch_analysis(request: dict, background_tasks: BackgroundTasks):
"""Lança uma análise e notifica via webhook quando concluída."""
response = client.responses.create(
model="gpt-5.6-sol",
input=request["prompt"],
background=True,
)
# Monitorizar em segundo plano
background_tasks.add_task(
monitor_and_notify,
response_id=response.id,
webhook_url=request["webhook_url"],
)
return {"response_id": response.id, "status": "launched"}
async def monitor_and_notify(response_id: str, webhook_url: str):
"""Monitoriza um pedido em segundo plano e notifica via webhook."""
result = wait_for_response(response_id)
async with httpx.AsyncClient() as http:
await http.post(webhook_url, json={
"response_id": response_id,
"result": result,
})
Escolher o modo correto
A regra de decisão resume-se a duas perguntas. Quantos pedidos? E o utilizador está à espera? Para além de cem pedidos sem requisito de imediatismo, a API de Lote vence no preço: resultados em horas a metade do custo. Se alguém estiver à espera perante o ecrã, as chamadas síncronas permanecem a única escolha aceitável à tarifa padrão. O modo em segundo plano preenche o restante espaço: poucos pedidos, resultados em minutos, preço padrão. Vale a pena codificar esta lógica uma vez, em vez de a repensar para cada novo serviço.
def choose_mode(
num_requests: int,
urgency: str,
budget: str,
) -> str:
"""Recomenda o modo de execução ótimo."""
if num_requests > 100 and urgency != "immediate":
return "batch"
elif urgency == "immediate":
return "synchronous"
else:
return "background"
Finalmente, planeie uma válvula de escape. Um pedido em segundo plano que exceda largamente a sua duração esperada ocupa orçamento e atrasa o restante da sua pipeline; a API permite cancelá-lo explicitamente. Defina este limite no dobro da duração que observa na prática, não na média, ou corre o risco de cancelar pedidos que estavam prestes a ter sucesso.
def cancel_if_too_long(response_id: str, timeout: int = 120):
"""Cancela um pedido se exceder o tempo limite."""
start = time.time()
while time.time() - start < timeout:
response = client.responses.retrieve(response_id)
if response.status == "completed":
return response.output_text
time.sleep(5)
# Tempo limite excedido — cancelar
client.responses.cancel(response_id)
raise TimeoutError(
f"Request {response_id} cancelled after {timeout}s."
)
Pontos-chave
- O modo em segundo plano lança pedidos sem manter uma ligação aberta
- Ideal para configurações de raciocínio elevado (GPT-5.6 Sol) e tarefas longas
- Combine com um webhook para uma arquitetura orientada a eventos
- Persista o ID da resposta: é a sua única ligação ao trabalho em curso
- Para processamento em massa de baixo custo, prefira a API de Lote