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

Arquitetura Assíncrona e Filas

Aula 7 de 20 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. Por Que Nunca Deve Bloquear numa Chamada a um LLM
  2. O Padrão Produtor / Consumidor
  3. Respeitar Quotas em Vez de as Atingir
  4. Devolver o Controlo Imediatamente
  5. Pontos-chave

Por Que Nunca Deve Bloquear numa Chamada a um LLM

Uma chamada de API a um modelo de linguagem demora entre um e trinta segundos, consoante o modelo e a complexidade do pedido. Trinta segundos é uma eternidade para um processo de servidor: durante esse tempo, a thread em espera não faz nada, mas continua a ocupar uma vaga. Multiplique isso por cem pedidos simultâneos e a sua aplicação falha, não porque esteja a computar demasiado, mas porque está à espera demais.

Uma arquitetura assíncrona suportada por uma fila resolve três problemas de uma vez. Absorve picos de tráfego, pois a fila cresce em vez de rejeitar pedidos. Centraliza a lógica de novas tentativas, porque uma tarefa falhada regressa à fila em vez de desaparecer com o pedido HTTP que a desencadeou. E desacopla os seus serviços: o componente que recebe pedidos já não precisa de saber quanto tempo demora o componente de execução a processá-los.

O Padrão Produtor / Consumidor

A estrutura base assenta em dois objetos. Uma tarefa descreve o que precisa de ser feito e o estado atual do processamento; uma fila distribui essas tarefas por um conjunto de trabalhadores que as consomem em paralelo. Modelar o estado como uma enumeração em vez de uma cadeia de caracteres livre evita a classe mais comum de erros neste tipo de código: duas partes do programa a escreverem "terminee" e "terminée".

import asyncio
from dataclasses import dataclass, field
from enum import Enum

class TaskStatus(Enum):
    PENDING = "pending"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    FAILED = "failed"

@dataclass
class Task:
    id: str
    prompt: str
    model: str = "gpt-5.6-terra"
    status: TaskStatus = TaskStatus.PENDING
    result: str | None = None
    attempts: int = 0
    max_attempts: int = 3

class ProcessingQueue:
    """Fila assíncrona para chamadas a LLM."""

    def __init__(self, num_workers: int = 5):
        self.queue: asyncio.Queue[Task] = asyncio.Queue()
        self.results: dict[str, Task] = {}
        self.num_workers = num_workers

    async def add(self, task: Task) -> str:
        """Adiciona uma tarefa à fila."""
        self.results[task.id] = task
        await self.queue.put(task)
        return task.id

    async def worker(self, worker_id: int):
        """Trabalhador que processa tarefas da fila."""
        import openai
        client = openai.AsyncOpenAI()

        while True:
            task = await self.queue.get()
            task.status = TaskStatus.IN_PROGRESS
            task.attempts += 1

            try:
                response = await client.responses.create(
                    model=task.model,
                    input=task.prompt,
                )
                task.result = response.output_text
                task.status = TaskStatus.COMPLETED

            except Exception as e:
                if task.attempts < task.max_attempts:
                    task.status = TaskStatus.PENDING
                    await self.queue.put(task)
                else:
                    task.status = TaskStatus.FAILED
                    task.result = str(e)

            finally:
                self.queue.task_done()

    async def start(self):
        """Inicia os trabalhadores."""
        workers = [
            asyncio.create_task(self.worker(i))
            for i in range(self.num_workers)
        ]
        return workers

    async def wait_completion(self):
        """Aguarda até todas as tarefas serem processadas."""
        await self.queue.join()

Dois detalhes neste trabalhador merecem a sua atenção, pois aparecem em qualquer implementação real. O contador attempts reside na própria tarefa, não no trabalhador, permitindo que qualquer outro trabalhador recupere uma tarefa reenfileirada sem perder o seu histórico. A chamada task_done() situa-se dentro de um bloco finally para garantir que a fila nunca fica bloqueada indefinidamente se uma exceção inesperada contornar o bloco except: sem isto, um join() que nunca retorna é o sintoma, e é doloroso de diagnosticar.

Do lado do chamador, a utilização é direta: inicie os trabalhadores, coloque tarefas na fila, aguarde, recolha os resultados e pare.

async def process_documents(documents: list[str]):
    queue = ProcessingQueue(num_workers=10)
    workers = await queue.start()

    # Adicionar tarefas
    for i, doc in enumerate(documents):
        task = Task(
            id=f"doc-{i}",
            prompt=f"Summarize this document: {doc}",
        )
        await queue.add(task)

    # Aguardar conclusão
    await queue.wait_completion()

    # Recolher resultados
    for task_id, task in queue.results.items():
        print(f"{task_id}: {task.status.value}")

    # Parar trabalhadores
    for w in workers:
        w.cancel()

Respeitar Quotas em Vez de as Atingir

A OpenAI impõe dois limites simultâneos: pedidos por minuto e tokens por minuto. Um conjunto de dez trabalhadores a enviar tudo o que podem atingirá um ou outro, receberá erros de limite de taxa, tentará novamente e agravará o congestionamento. É melhor abrandar voluntariamente a montante do que ser rejeitado a jusante.

O limitador abaixo aplica um balde de tokens numa janela deslizante de um minuto. Mantém dois históricos — carimbos de tempo de pedidos recentes e pares de carimbo de tempo/token —, expurga as entradas que saíram da janela e, em seguida, aguarda se algum limite for excedido. O bloqueio asyncio é essencial: sem ele, dez trabalhadores avaliariam a mesma situação simultaneamente e todos decidiriam que ainda há espaço.

import asyncio
import time

class RateLimiter:
    """Limitador de taxa baseado num balde de tokens."""

    def __init__(self, rpm: int = 500, tpm: int = 200_000):
        self.rpm = rpm
        self.tpm = tpm
        self.recent_requests: list[float] = []
        self.recent_tokens: list[tuple[float, int]] = []
        self.lock = asyncio.Lock()

    async def wait(self, estimated_tokens: int = 1000):
        """Aguarda se necessário para respeitar os limites."""
        async with self.lock:
            now = time.time()
            window = 60.0

            # Limpar entradas fora da janela
            self.recent_requests = [
                t for t in self.recent_requests
                if now - t < window
            ]
            self.recent_tokens = [
                (t, n) for t, n in self.recent_tokens
                if now - t < window
            ]

            # Verificar RPM
            if len(self.recent_requests) >= self.rpm:
                wait_time = self.recent_requests[0] + window - now
                await asyncio.sleep(wait_time)

            # Verificar TPM
            tokens_used = sum(n for _, n in self.recent_tokens)
            if tokens_used + estimated_tokens > self.tpm:
                wait_time = self.recent_tokens[0][0] + window - now
                await asyncio.sleep(wait_time)

            self.recent_requests.append(time.time())
            self.recent_tokens.append((time.time(), estimated_tokens))

O parâmetro estimated_tokens merece uma palavra: não conhece o custo real até a resposta chegar, por isso trabalha com uma estimativa. Torne-a generosa em vez de precisa. Subestimar sistematicamente equivale a desativar a proteção exatamente quando seria útil.

Devolver o Controlo Imediatamente

Para processamentos que demoram vários minutos, fazer um cliente HTTP esperar já não é viável: os tempos limite de proxy, navegador e balanceador de carga serão acionados antes de terminar. O padrão webhook inverte a responsabilidade. O seu endpoint aceita o pedido, devolve imediatamente um ID de tarefa e notifica o chamador quando o resultado existe, sem exigir sondagens periódicas.

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

@app.post("/api/analyze")
async def start_analysis(
    request: dict,
    background_tasks: BackgroundTasks,
):
    """Inicia uma análise em segundo plano e notifica via webhook."""
    task_id = generate_id()

    background_tasks.add_task(
        run_analysis,
        task_id=task_id,
        document=request["document"],
        webhook_url=request.get("webhook_url"),
    )

    return {"task_id": task_id, "status": "in_progress"}


async def run_analysis(
    task_id: str,
    document: str,
    webhook_url: str | None,
):
    """Executa a análise e envia o resultado via webhook."""
    import httpx

    result = await call_llm(document)

    if webhook_url:
        async with httpx.AsyncClient() as http:
            await http.post(webhook_url, json={
                "task_id": task_id,
                "status": "completed",
                "result": result,
            })

Guarde sempre o ID devolvido e o estado associado num local durável. Um webhook pode perder-se e o chamador deve manter a capacidade de obter o resultado por si próprio.

Pontos-chave

  • Utilize filas assíncronas para desacoplar a ingestão do processamento
  • Implemente um limitador de taxa para respeitar as quotas da OpenAI
  • Trate as novas tentativas com recuo exponencial nos seus trabalhadores
  • Para tarefas de longa duração, prefira um padrão webhook em vez de sondagem