Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura di produzione: monitoraggio, allerta, scalabilità

Lezione 20 di 20 Aggiornata il 3 novembre 2026 Avanzato
In questa pagina
  1. La tua applicazione in produzione: i tre pilastri
  2. Osservare: cosa misurare
  3. Reagire: allerte graduate
  4. Assorbire: tre meccanismi di resilienza
  5. Checklist di deployment in produzione
  6. Punti chiave
  7. Metti alla prova le tue conoscenze

La tua applicazione in produzione: i tre pilastri

Mettere in produzione un’applicazione LLM non riguarda solo il codice. Tre pilastri garantiscono l’affidabilità: il monitoraggio per osservare, l’allerta per reagire e la scalabilità per assorbire il carico. Formano una catena, e una catena è forte quanto il suo anello più debole: le metriche che nessuno guarda sono inutili, gli allarmi senza una procedura di risposta sono solo rumore e una scalabilità che interviene troppo tardi è semplicemente un’interruzione del servizio. Questa lezione finale riunisce tutti i concetti del corso in un’architettura di produzione completa.

Osservare: cosa misurare

Quattro famiglie di metriche coprono l’essenziale: volume delle chiamate, latenza, errori e costi, suddivisi per modello. La suddivisione per modello è ciò che rende la dashboard utilizzabile: un tasso di errore globale del 3% non ti dice nulla, mentre lo stesso valore concentrato su un singolo modello indica immediatamente il colpevole.

La classe sottostante accumula queste metriche in memoria, utilizzando una finestra scorrevole di 10.000 valori di latenza per impedire che il processo cresca indefinitamente. Nota l’uso dei percentili invece delle medie: la latenza media di un servizio LLM è quasi sempre fuorviante perché una manciata di chiamate molto lente scompare nella media, eppure sono proprio quelle di cui si lamentano i tuoi utenti.

import time
from dataclasses import dataclass, field
from collections import defaultdict

@dataclass
class ProductionMetrics:
    """Raccoglie le metriche essenziali di produzione."""

    counters: dict = field(default_factory=lambda: defaultdict(int))
    latencies: dict = field(default_factory=lambda: defaultdict(list))
    errors: dict = field(default_factory=lambda: defaultdict(int))
    costs: dict = field(default_factory=lambda: defaultdict(float))

    def record_call(
        self,
        model: str,
        latency: float,
        input_tokens: int,
        output_tokens: int,
        cost: float,
        success: bool,
    ):
        self.counters[model] += 1
        self.latencies[model].append(latency)
        self.costs[model] += cost

        if not success:
            self.errors[model] += 1

        # Mantieni solo le ultime 10.000 latenze
        if len(self.latencies[model]) > 10_000:
            self.latencies[model] = self.latencies[model][-10_000:]

    def percentile(self, model: str, p: float) -> float:
        """Calcola un percentile di latenza."""
        values = sorted(self.latencies.get(model, []))
        if not values:
            return 0.0
        idx = int(len(values) * p / 100)
        return values[min(idx, len(values) - 1)]

    def error_rate(self, model: str) -> float:
        total = self.counters.get(model, 0)
        if total == 0:
            return 0.0
        return self.errors.get(model, 0) / total

    def dashboard(self) -> dict:
        """Genera una dashboard completa."""
        dashboard = {}
        for model in self.counters:
            dashboard[model] = {
                "calls": self.counters[model],
                "latency_p50": f"{self.percentile(model, 50):.2f}s",
                "latency_p99": f"{self.percentile(model, 99):.2f}s",
                "error_rate": f"{self.error_rate(model):.2%}",
                "total_cost": f"${self.costs[model]:.2f}",
            }
        return dashboard

Ovviamente, la raccolta deve essere sistematica. Strumentare manualmente ogni chiamata garantisce che ne dimenticherai una, e probabilmente sarà proprio quella a causare problemi. Il decoratore sottostante sposta la misurazione a livello della funzione di chiamata: il blocco finally registra latenza e successo indipendentemente da ciò che accade, anche quando un’eccezione si propaga.

import openai
import functools

metrics = ProductionMetrics()

def monitor(func):
    """Decoratore che monitora ogni chiamata API."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        model = kwargs.get("model", args[0] if args else "unknown")
        start = time.perf_counter()
        success = True

        try:
            result = func(*args, **kwargs)
            return result
        except Exception as e:
            success = False
            raise
        finally:
            latency = time.perf_counter() - start
            metrics.record_call(
                model=model,
                latency=latency,
                input_tokens=0,
                output_tokens=0,
                cost=0,
                success=success,
            )

    return wrapper

I contatori di token e i costi rimangono a zero in questa versione perché l’oggetto di risposta non è disponibile al momento della registrazione. Completali leggendo i campi usage restituiti dall’API: senza queste informazioni, la tua dashboard mostrerà fedelmente una colonna di costi pari a zero.

Reagire: allerte graduate

Un allarme ha valore solo se richiede un’azione. Ecco perché il sistema distingue due soglie per ogni metrica: una soglia di avvertimento, che segnala una deriva da esaminare durante il giorno, e una soglia critica, che giustifica il risveglio di qualcuno. Confondere le due produce il peggior risultato possibile: un team che ha imparato a ignorare le notifiche.

from enum import Enum

class AlertLevel(Enum):
    INFO = "info"
    WARNING = "warning"
    CRITICAL = "critical"

class AlertSystem:
    """Attiva gli allarmi in base alle metriche."""

    def __init__(self):
        self.thresholds = {
            "error_rate": {"warning": 0.05, "critical": 0.15},
            "latency_p99": {"warning": 10.0, "critical": 30.0},
            "hourly_cost": {"warning": 50.0, "critical": 200.0},
        }
        self.sent_alerts: list[dict] = []

    def check(self, metrics: ProductionMetrics) -> list[dict]:
        """Controlla le metriche e genera allarmi."""
        alerts = []

        for model in metrics.counters:
            # Tasso di errore
            rate = metrics.error_rate(model)
            if rate >= self.thresholds["error_rate"]["critical"]:
                alerts.append({
                    "level": AlertLevel.CRITICAL,
                    "message": (
                        f"Tasso di errore CRITICO per {model}: "
                        f"{rate:.1%}"
                    ),
                    "model": model,
                })
            elif rate >= self.thresholds["error_rate"]["warning"]:
                alerts.append({
                    "level": AlertLevel.WARNING,
                    "message": (
                        f"Tasso di errore elevato per {model}: "
                        f"{rate:.1%}"
                    ),
                    "model": model,
                })

            # Latenza
            p99 = metrics.percentile(model, 99)
            if p99 >= self.thresholds["latency_p99"]["critical"]:
                alerts.append({
                    "level": AlertLevel.CRITICAL,
                    "message": (
                        f"Latenza p99 CRITICA per {model}: "
                        f"{p99:.1f}s"
                    ),
                    "model": model,
                })

        self.sent_alerts.extend(alerts)
        return alerts

    async def notify(self, alerts: list[dict]):
        """Invia notifiche (webhook, email, Slack)."""
        import httpx

        for alert in alerts:
            if alert["level"] == AlertLevel.CRITICAL:
                # Notifica immediata
                async with httpx.AsyncClient() as http:
                    await http.post(
                        "https://your-webhook.example.com/alerts",
                        json={
                            "level": alert["level"].value,
                            "message": alert["message"],
                        },
                    )

Gli allarmi sui costi orari sono quelli più spesso dimenticati, ed è un peccato: un ciclo di retry illimitato o un job batch lanciato due volte si traducono in una fattura, non in un errore. È l’unica rete di sicurezza che rileva questo tipo di incidente mentre sta accadendo.

Assorbire: tre meccanismi di resilienza

Quando l’API restituisce un errore, ritentare peggiora le cose: aggiungi carico a un servizio già in difficoltà e fai aspettare i tuoi utenti per nulla. Il circuit breaker inverte questa logica. Dopo un numero definito di fallimenti consecutivi, apre il circuito e rifiuta immediatamente le chiamate successive, per poi ritentare dopo un ritardo di reset.

class CircuitBreaker:
    """Interrompe le chiamate quando si verificano troppi errori."""

    def __init__(
        self,
        open_threshold: int = 5,
        reset_delay: float = 60.0,
    ):
        self.threshold = open_threshold
        self.reset_delay = reset_delay
        self.consecutive_failures = 0
        self.opened_at: float | None = None

    @property
    def is_open(self) -> bool:
        if self.opened_at is None:
            return False
        if time.time() - self.opened_at > self.reset_delay:
            # Tentativo di chiudere il circuito
            self.opened_at = None
            self.consecutive_failures = 0
            return False
        return True

    def record_success(self):
        self.consecutive_failures = 0
        self.opened_at = None

    def record_failure(self):
        self.consecutive_failures += 1
        if self.consecutive_failures >= self.threshold:
            self.opened_at = time.time()

    def call(self, func, *args, **kwargs):
        """Esegue la funzione se il circuito è chiuso."""
        if self.is_open:
            raise RuntimeError(
                "Circuito aperto — API non disponibile. "
                f"Riprova tra {self.reset_delay}s."
            )
        try:
            result = func(*args, **kwargs)
            self.record_success()
            return result
        except Exception as e:
            self.record_failure()
            raise

Il circuit breaker protegge la tua applicazione; non la fa funzionare, però. Questo è il ruolo del fallback del modello, che prova alternative in ordine, saltando quelle i cui circuiti sono già aperti. Un punto di progettazione da ricordare: l’ordine della lista è una decisione di prodotto, non tecnica. Metti per primo il modello che eroga il servizio atteso, seguito da quelli che offrono un servizio degradato ma accettabile: una risposta leggermente meno precisa è meglio di un messaggio di indisponibilità.

class ModelFallback:
    """Passa a un modello di backup in caso di fallimento."""

    def __init__(self):
        self.models = ["gpt-5.6-terra", "gpt-5.6-sol", "gpt-5.6-luna"]
        self.circuits = {
            m: CircuitBreaker() for m in self.models
        }

    def call(self, prompt: str) -> str:
        """Prova ogni modello fino a ottenere una risposta."""
        client = openai.OpenAI()

        for model in self.models:
            circuit = self.circuits[model]
            if circuit.is_open:
                continue

            try:
                response = circuit.call(
                    client.responses.create,
                    model=model,
                    input=prompt,
                )
                return response.output_text
            except Exception:
                continue

        raise RuntimeError("Tutti i modelli non sono disponibili.")

Il terzo meccanismo riguarda il dimensionamento. Guidare il numero di worker in base alla dimensione della coda piuttosto che al carico della CPU è il riflesso giusto per un servizio che passa la maggior parte del tempo ad aspettare risposte di rete: la CPU rimane inattiva mentre la coda cresce. Nota l’asimmetria nella regola applicata: raddoppiamo in scala ascendente e dimezziamo in scala discendente, con soglie ampiamente separate (100 contro 10). Questo divario previene l’oscillazione: senza di esso, il sistema passerebbe il tempo a creare e distruggere worker intorno al punto di svolta.

class AutoScaler:
    """Regola il numero di worker in base al carico."""

    def __init__(
        self,
        min_workers: int = 2,
        max_workers: int = 50,
        scale_up_threshold: int = 100,
        scale_down_threshold: int = 10,
    ):
        self.min_workers = min_workers
        self.max_workers = max_workers
        self.up_threshold = scale_up_threshold
        self.down_threshold = scale_down_threshold
        self.active_workers = min_workers

    def adjust(self, queue_size: int) -> int:
        """Restituisce il numero consigliato di worker."""
        if queue_size > self.up_threshold:
            self.active_workers = min(
                self.active_workers * 2,
                self.max_workers,
            )
        elif queue_size < self.down_threshold:
            self.active_workers = max(
                self.active_workers // 2,
                self.min_workers,
            )

        return self.active_workers

Checklist di deployment in produzione

Questo corso si conclude con la checklist da eseguire prima di aprire la tua applicazione al pubblico. Ogni voce si riferisce a una lezione che hai affrontato; se qualcuna sembra poco chiara, rileggi quella lezione prima del deployment.

  • Monitoraggio della latenza (p50, p95, p99) e dei tassi di errore
  • Allarmi configurati su soglie critiche
  • Circuit breaker per proteggersi dai fallimenti delle API
  • Fallback del modello configurato
  • Moderazione degli input e degli output abilitata
  • Rate limiting lato client implementato
  • Log strutturati per il debug
  • Valutazioni (evals) automatizzate in CI/CD
  • Budget di costo con allarmi
  • Documentazione versionata dei prompt

Punti chiave

  • Il monitoraggio copre latenza, errori, costi e qualità della risposta
  • Traccia i percentili di latenza, mai solo la media
  • Gli allarmi devono essere graduati: avvertimento poi critico
  • Il circuit breaker protegge dalle cascate di fallimenti; il fallback garantisce la disponibilità
  • Una checklist di produzione previene omissioni critiche

Metti alla prova le tue conoscenze

Latenza, costi, evals: i riflessi di produzione in cinque domande.

1. Quali sono le leve principali per ridurre la latenza?

Risposta: Streaming (latenza percepita), caching dei prompt (prefissi stabili), Predicted Outputs quando la risposta è largamente prevedibile (Chat Completions, su modelli ritirati il 14 gennaio 2027) e ottimizzazione del prompt stesso, misurata end-to-end.

2. Quando dovresti usare la Batch API?

Risposta: Per elaborazioni massive senza vincoli di tempo reale: batch asincroni a costo ridotto. Ranking, arricchimento o generazione di volumi non hanno posto nel percorso sincrono.

3. Cosa fa la compattazione della conversazione?

Risposta: Comprime la cronologia lunga (riassunti, pruning) per rientrare nel contesto e controllare i costi, essenziale per gli agent e le sessioni lunghe.

4. Qual è lo scopo del framework Evals in CI/CD?

Risposta: Eseguire automaticamente le tue valutazioni ad ogni modifica di prompt o modello: la regressione viene rilevata al commit, non in produzione.

5. Cosa include un'architettura di produzione completa?

Risposta: Monitoraggio (latenza, costi, qualità), allerta, code asincrone, moderazione su larga scala e un piano di scalabilità: l’IA in produzione è un sistema, non una chiamata API.

Misura, memorizza nella cache, usa i batch, valuta continuamente: quattro abitudini che rendono le applicazioni veloci, snelle e affidabili.