Arquitetura Assíncrona e Filas
Nesta página
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