Architettura asincrona e code
In questa pagina
Perché non devi mai bloccare una chiamata a un LLM
Una chiamata API a un modello linguistico richiede da uno a trenta secondi, a seconda del modello e della complessità della richiesta. Trenta secondi sono un’eternità per un processo server: durante quel lasso di tempo, il thread in attesa non fa nulla, eppure occupa comunque uno slot. Moltiplica questo scenario per cento richieste simultanee e la tua applicazione andrà in crash non perché sta calcolando troppo, ma perché sta aspettando troppo.
Un’architettura asincrona supportata da una coda risolve tre problemi contemporaneamente. Assorbe i picchi di traffico, poiché la coda cresce invece di rifiutare le richieste. Centralizza la logica di retry, perché un’attività fallita torna nella coda invece di svanire insieme alla richiesta HTTP che l’ha attivata. E disaccoppia i tuoi servizi: il componente che riceve le richieste non ha più bisogno di sapere quanto tempo impiega il componente esecutore per elaborarle.
Il pattern Producer / Consumer
La struttura di base si basa su due oggetti. Un’attività (task) descrive cosa deve essere fatto e lo stato di elaborazione corrente; una coda distribuisce queste attività a un pool di worker che le consumano in parallelo. Modellare lo stato come un’enumerazione invece che come una stringa libera evita la classe più comune di bug in questo tipo di codice: due parti del programma che scrivono "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:
"""Coda asincrona per chiamate 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:
"""Aggiunge un'attività alla coda."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Worker che elabora le attività dalla coda."""
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):
"""Avvia i worker."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Attende che tutte le attività siano elaborate."""
await self.queue.join()
Due dettagli in questo worker meritano la tua attenzione perché compaiono in ogni implementazione reale. Il contatore attempts risiede sull’attività stessa, non sul worker, permettendo a qualsiasi altro worker di riprendere un’attività rimessa in coda senza perderne la cronologia. La chiamata task_done() si trova all’interno di un blocco finally per garantire che la coda non si blocchi indefinitamente se un’eccezione imprevista bypassa il blocco except: senza di essa, un join() che non restituisce mai è il sintomo, ed è doloroso da diagnosticare.
Dal lato del chiamante, l’utilizzo è semplice: avvia i worker, metti in coda le attività, attendi, raccogli i risultati e ferma tutto.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Aggiungi attività
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Riassumi questo documento: {doc}",
)
await queue.add(task)
# Attendi il completamento
await queue.wait_completion()
# Raccogli i risultati
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Ferma i worker
for w in workers:
w.cancel()
Rispettare le quote invece di superarle
OpenAI impone due limiti simultanei: richieste al minuto e token al minuto. Un pool di dieci worker che inviano tutto ciò che possono colpirà l’uno o l’altro limite, riceverà errori di rate limit, riproverà e peggiorerà la congestione. È meglio rallentare volontariamente a monte piuttosto che essere rifiutati a valle.
Il limitatore sottostante applica un token bucket su una finestra scorrevole di un minuto. Mantiene due cronologie: timestamp delle richieste recenti e coppie timestamp/token, elimina le voci uscite dalla finestra, quindi attende se uno dei due limiti verrebbe superato. Il lock asyncio è essenziale: senza di esso, dieci worker valuterebbero la stessa situazione simultaneamente e tutti e dieci deciderebbero che c’è ancora spazio.
import asyncio
import time
class RateLimiter:
"""Limitatore di frequenza basato su un token bucket."""
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):
"""Attende se necessario per rispettare i limiti."""
async with self.lock:
now = time.time()
window = 60.0
# Pulisce le voci fuori dalla finestra
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
]
# Controlla RPM
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Controlla 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))
Il parametro estimated_tokens merita una parola: non conosci il costo effettivo finché la risposta non arriva, quindi lavori con una stima. Rendila generosa piuttosto che precisa. Sottostimare sistematicamente equivale a disattivare la protezione esattamente quando sarebbe utile.
Restituire il controllo immediatamente
Per elaborazioni che richiedono diversi minuti, far attendere un client HTTP non è più praticabile: i timeout di proxy, browser e load balancer scatteranno prima che tu abbia finito. Il pattern webhook inverte la responsabilità. Il tuo endpoint accetta la richiesta, restituisce immediatamente un ID attività e notifica il chiamante quando il risultato esiste, senza richiedere polling periodico.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Avvia un'analisi in background e notifica tramite 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,
):
"""Esegue l'analisi e invia il risultato tramite 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,
})
Salva sempre l’ID restituito e lo stato associato da qualche parte di durevole. Un webhook può andare perso e il chiamante deve mantenere la capacità di recuperare il risultato autonomamente.
Punti chiave
- Usa code asincrone per disaccoppiare l’ingestione dall’elaborazione
- Implementa un limitatore di frequenza per rispettare le quote di OpenAI
- Gestisci i retry con backoff esponenziale nei tuoi worker
- Per attività di lunga durata, preferisci il pattern webhook al polling