Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura asincrona e code

Lezione 7 di 20 Aggiornata il 28 luglio 2026 Avanzato
In questa pagina
  1. Perché non devi mai bloccare una chiamata a un LLM
  2. Il pattern Producer / Consumer
  3. Rispettare le quote invece di superarle
  4. Restituire il controllo immediatamente
  5. Punti chiave

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