Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Modo em segundo plano

Aula 9 de 20 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. Uma terceira via entre o síncrono e o lote
  2. Lançamento e recuperação
  3. Tarefas de raciocínio longo
  4. Escolher o modo correto
  5. Pontos-chave

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