Arquitectura asíncrona y colas
En esta página
Por qué nunca debes bloquear una llamada a un LLM
Una llamada a la API de un modelo de lenguaje tarda entre uno y treinta segundos, dependiendo del modelo y la complejidad de la solicitud. Treinta segundos es una eternidad para un proceso de servidor: durante ese tiempo, el hilo en espera no hace nada, pero sigue ocupando una ranura. Multiplica eso por cien solicitudes simultáneas y tu aplicación se caerá, no porque esté calculando demasiado, sino porque está esperando demasiado.
Una arquitectura asíncrona respaldada por una cola resuelve tres problemas a la vez. Absorbe picos de tráfico, ya que la cola crece en lugar de rechazar solicitudes. Centraliza la lógica de reintentos, porque una tarea fallida vuelve a la cola en lugar de desaparecer con la solicitud HTTP que la desencadenó. Y desacopla tus servicios: el componente que recibe solicitudes ya no necesita saber cuánto tarda el componente de ejecución en procesarlas.
El patrón Productor / Consumidor
La estructura básica se basa en dos objetos. Una tarea describe qué hay que hacer y el estado actual del procesamiento; una cola distribuye estas tareas a un grupo de trabajadores que las consumen en paralelo. Modelar el estado como una enumeración en lugar de una cadena de texto libre evita la clase más común de errores en este tipo de código: que dos partes del programa escriban "terminee" y "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:
"""Cola asíncrona para llamadas 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:
"""Añade una tarea a la cola."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Trabajador que procesa tareas de la cola."""
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 los trabajadores."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Espera hasta que se procesen todas las tareas."""
await self.queue.join()
Dos detalles de este trabajador merecen tu atención porque aparecen en cualquier implementación real. El contador attempts vive en la propia tarea, no en el trabajador, lo que permite que cualquier otro trabajador recoja una tarea reencolada sin perder su historial. La llamada task_done() reside dentro de un bloque finally para garantizar que la cola nunca se quede colgada indefinidamente si una excepción inesperada evade el bloque except: sin él, un join() que nunca retorna es el síntoma, y es doloroso de diagnosticar.
Por parte del llamador, el uso es sencillo: inicia los trabajadores, encola las tareas, espera, recoge los resultados y detén el proceso.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Añadir tareas
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Resume este documento: {doc}",
)
await queue.add(task)
# Esperar a que finalicen
await queue.wait_completion()
# Recoger resultados
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Detener trabajadores
for w in workers:
w.cancel()
Respetar las cuotas en lugar de chocar contra ellas
OpenAI impone dos límites simultáneos: solicitudes por minuto y tokens por minuto. Un grupo de diez trabajadores enviando todo lo que puedan chocará contra uno u otro, recibirá errores de límite de tasa, reintentará y empeorará la congestión. Es mejor ralentizarse voluntariamente aguas arriba que ser rechazado aguas abajo.
El limitador siguiente aplica un cubo de tokens sobre una ventana deslizante de un minuto. Mantiene dos historiales —marcas de tiempo de solicitudes recientes y pares de marca de tiempo/token—, purga las entradas que han salido de la ventana y luego espera si se superaría cualquiera de los límites. El bloqueo asyncio es esencial: sin él, diez trabajadores evaluarían la misma situación simultáneamente y los diez decidirían que aún hay espacio.
import asyncio
import time
class RateLimiter:
"""Limitador de tasa basado en un cubo 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):
"""Espera si es necesario para respetar los límites."""
async with self.lock:
now = time.time()
window = 60.0
# Limpiar entradas fuera de la ventana
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
]
# Comprobar RPM
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Comprobar 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))
El parámetro estimated_tokens merece una mención: no conoces el coste real hasta que llega la respuesta, así que trabajas con una estimación. Sé generoso en lugar de preciso. Subestimar sistemáticamente equivale a desactivar la protección exactamente cuando sería útil.
Devolver el control inmediatamente
Para un procesamiento que tarda varios minutos, hacer esperar a un cliente HTTP ya no es viable: los tiempos de espera de proxy, navegador y balanceador de carga saltarán antes de que termines. El patrón de webhook invierte la responsabilidad. Tu endpoint acepta la solicitud, devuelve inmediatamente un ID de tarea y notifica al llamador cuando existe el resultado, sin requerir sondeos periódicos.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Inicia un análisis en segundo plano y notifica vía 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,
):
"""Ejecuta el análisis y envía el resultado vía 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,
})
Guarda siempre el ID devuelto y el estado asociado en algún lugar persistente. Un webhook puede perderse, y el llamador debe conservar la capacidad de obtener el resultado por sí mismo.
Puntos clave
- Usa colas asíncronas para desacoplar la ingestión del procesamiento
- Implementa un limitador de tasa para respetar las cuotas de OpenAI
- Gestiona los reintentos con retroceso exponencial en tus trabajadores
- Para tareas de larga duración, prefiere un patrón de webhook frente al sondeo