Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Produzione: Scalabilità e Monitoraggio

Lezione 18 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Produzione: Scalabilità e Monitoraggio
  2. Architettura di Produzione
  3. Gestione delle Sessioni Concorrenti
  4. Logging Strutturato
  5. Metriche Prometheus
  6. Gestione dei Costi
  7. Gestione degli Errori in Produzione
  8. Punti chiave
  9. Metti alla prova le tue conoscenze

Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati: tts-1, tts-1-hd e gpt-4o-mini-tts smetteranno di funzionare il 6 gennaio 2027 (sostituzione: gpt-realtime-2.1-mini, che la guida TTS di OpenAI indica come non supportata da /v1/audio/speech: la migrazione della sintesi vocale deve passare attraverso le Realtime API); gpt-realtime, gpt-4o-realtime e i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe e /v1/audio/translations il 26 febbraio 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Per la voce full-duplex, GPT-Live 1 è disponibile nelle API dal 10 settembre 2026.

Aggiornato il 3 novembre 2026. La gestione dei costi, precedentemente riassunta in una singola frase, riflette ora il modello di fatturazione descritto da OpenAI (fatturazione per risposta, conversazione restituita a ogni turno, audio conteggiato in token, caching automatico, trascrizione fatturata separatamente) e la troncatura tramite retention_ratio, il cui formato è stato verificato rispetto ai tipi SDK openai versione 3.42.1. Fonte: Ottimizzazione dei costi.

Produzione: Scalabilità e Monitoraggio

Passare da un prototipo di agente vocale a un servizio di produzione affidabile e scalabile richiede massima attenzione all’infrastruttura, al monitoraggio e alla gestione degli errori. Questa lezione finale copre gli elementi operativi essenziali per distribuire un agente vocale in condizioni reali.

Architettura di Produzione

In produzione, l’agente vocale gira dietro un load balancer e un pool di worker:

1

Load Balancer (nginx / HAProxy)

Distribuisce le connessioni WebSocket in arrivo tra i worker. Supporta le sessioni sticky per mantenere l'affinità.

2

Worker (FastAPI + uvicorn)

Ogni worker gestisce più sessioni Realtime simultanee grazie ad asyncio.

3

Database (PostgreSQL)

Archivia i log delle conversazioni, le metriche e la configurazione dell'agente.

4

Monitoraggio (Prometheus + Grafana)

Raccoglie metriche in tempo reale: latenza, numero di sessioni, errori, costi.

Gestione delle Sessioni Concorrenti

Ogni connessione WebSocket mantiene una sessione delle Realtime API. Il numero di sessioni simultanee è limitato dai tuoi rate limit di OpenAI e dalla capacità dei tuoi worker:

import asyncio
from dataclasses import dataclass

@dataclass
class SessionManager:
    """Gestisce le sessioni concurrenti delle Realtime API."""
    max_sessions: int = 50
    active_sessions: dict = None
    semaphore: asyncio.Semaphore = None

    def __post_init__(self):
        self.active_sessions = {}
        self.semaphore = asyncio.Semaphore(self.max_sessions)

    async def create_session(self, session_id: str, config: dict):
        """Crea una nuova sessione con controllo della concorrenza."""
        async with self.semaphore:
            if session_id in self.active_sessions:
                raise ValueError(f"Session {session_id} already active")

            self.active_sessions[session_id] = {
                "created_at": asyncio.get_event_loop().time(),
                "config": config,
                "status": "active"
            }
            return session_id

    async def close_session(self, session_id: str):
        """Chiude correttamente una sessione."""
        if session_id in self.active_sessions:
            del self.active_sessions[session_id]

    @property
    def active_count(self) -> int:
        return len(self.active_sessions)

    @property
    def available_slots(self) -> int:
        return self.max_sessions - self.active_count

session_manager = SessionManager(max_sessions=50)

Logging Strutturato

Registra ogni interazione per il debug e la conformità:

import logging
import json
from datetime import datetime

class ConversationLogger:
    """Logger strutturato per conversazioni vocali."""

    def __init__(self, session_id: str):
        self.session_id = session_id
        self.logger = logging.getLogger(f"voice.{session_id}")
        self.events = []

    def log_event(self, event_type: str, data: dict = None):
        entry = {
            "timestamp": datetime.utcnow().isoformat(),
            "session_id": self.session_id,
            "event_type": event_type,
            "data": data or {}
        }
        self.events.append(entry)
        self.logger.info(json.dumps(entry))

    def log_transcription(self, role: str, text: str):
        self.log_event("transcription", {
            "role": role,
            "text": text
        })

    def log_function_call(self, name: str, args: dict, result: dict, duration_ms: float):
        self.log_event("function_call", {
            "name": name,
            "arguments": args,
            "result": result,
            "duration_ms": round(duration_ms)
        })

    def log_error(self, error_type: str, message: str):
        self.log_event("error", {
            "type": error_type,
            "message": message
        })

    async def save_to_db(self, db_pool):
        """Persiste il log completo nel database."""
        async with db_pool.acquire() as conn:
            await conn.execute(
                "INSERT INTO conversation_logs (session_id, events, created_at) "
                "VALUES ($1, $2, NOW())",
                self.session_id, json.dumps(self.events)
            )

Metriche Prometheus

Esponi le metriche per il monitoraggio in tempo reale:

from prometheus_client import Counter, Histogram, Gauge, start_http_server

# Metriche chiave
sessions_active = Gauge(
    "voice_sessions_active",
    "Number of active voice sessions"
)

session_duration = Histogram(
    "voice_session_duration_seconds",
    "Duration of voice sessions",
    buckets=[30, 60, 120, 300, 600, 1800]
)

response_latency = Histogram(
    "voice_response_latency_ms",
    "Response latency (end of speech → first audio)",
    buckets=[200, 400, 600, 800, 1000, 1500, 2000, 3000]
)

errors_total = Counter(
    "voice_errors_total",
    "Total number of errors",
    ["error_type"]
)

tokens_used = Counter(
    "voice_tokens_total",
    "Tokens consumed",
    ["type"]  # input_audio, output_audio, input_text, output_text
)

# Avvia il server delle metriche
start_http_server(9090)

Gestione dei Costi

Secondo la guida Cost optimization di OpenAI, una sessione di conversazione Realtime viene fatturata per risposta, in token di input e output per testo, audio e immagini. Tre meccanismi guidano la maggior parte della fattura:

  • L’intera conversazione viene inviata al modello a ogni risposta: i turni successivi costano più di quelli iniziali.
  • L’audio è conteggiato in token: 1 token ogni 100 ms di audio utente, 1 token ogni 50 ms di audio dell’assistente.
  • Il caching del prompt si applica automaticamente: finché l’inizio della conversazione non cambia, viene fatturato alla tariffa ridotta per token in cache. Modificare o eliminare un elemento più vecchio “rompe” la cache da quel punto in poi.

La trascrizione in input, se abilitata, è fatturata separatamente alla tariffa del proprio modello: gpt-transcribe viene addebitato per durata, letta dall’evento conversation.item.input_audio_transcription.completed. Il consumo per ogni risposta appare in response.done, sotto response.usage (total_tokens, input_tokens, output_tokens, più il dettaglio per testo, audio, immagine e cache).

Per limitare la dimensione del contesto — e quindi il costo dei turni successivi — la sessione accetta una regola di troncatura: oltre il limite, i messaggi più vecchi vengono eliminati. Con retention_ratio impostato sotto 1, il server rimuove leggermente più del necessario, il che distanzia le troncature e preserva la cache:

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "truncation": {
            "type": "retention_ratio",
            "retention_ratio": 0.8,
            "token_limits": {"post_instructions": 8000},
        },
    },
}))

Il compromesso: un agente che mantiene meno contesto dimentica più velocemente. Completa questo con limiti di sessione nel tuo codice:

class CostController:
    """Controlla i costi per una sessione Realtime."""

    def __init__(self, max_duration_s: int = 600, max_tokens: int = 50000):
        self.max_duration_s = max_duration_s
        self.max_tokens = max_tokens
        self.total_tokens = 0
        self.start_time = None

    def start(self):
        self.start_time = asyncio.get_event_loop().time()

    def update_tokens(self, usage: dict):
        self.total_tokens += usage.get("total_tokens", 0)

    @property
    def elapsed_seconds(self) -> float:
        if not self.start_time:
            return 0
        return asyncio.get_event_loop().time() - self.start_time

    @property
    def should_terminate(self) -> bool:
        if self.elapsed_seconds > self.max_duration_s:
            return True
        if self.total_tokens > self.max_tokens:
            return True
        return False

    @property
    def warning_message(self) -> str:
        remaining = self.max_duration_s - self.elapsed_seconds
        if remaining < 60:
            return f"This session will end in {int(remaining)} seconds."
        return ""

Gestione degli Errori in Produzione

async def production_event_loop(ws, logger, cost_ctrl):
    """Loop eventi robusto per la produzione."""
    cost_ctrl.start()

    try:
        async for raw in ws:
            event = json.loads(raw)
            t = event["type"]

            # Controlla i limiti di costo
            if cost_ctrl.should_terminate:
                logger.log_event("session_limit_reached")
                await ws.send(json.dumps({
                    "type": "conversation.item.create",
                    "item": {
                        "type": "message",
                        "role": "user",
                        "content": [{"type": "input_text",
                                     "text": "The session is approaching its duration limit."}]
                    }
                }))
                break

            if t == "response.done":
                usage = event["response"].get("usage", {})
                cost_ctrl.update_tokens(usage)
                tokens_used.labels(type="total").inc(usage.get("total_tokens", 0))

            elif t == "error":
                error = event["error"]
                logger.log_error(error["type"], error["message"])
                errors_total.labels(error_type=error["type"]).inc()

                if error["type"] == "rate_limit_error":
                    await asyncio.sleep(1)

    except websockets.exceptions.ConnectionClosed as e:
        logger.log_error("connection_closed", str(e))
    except Exception as e:
        logger.log_error("unexpected", str(e))
    finally:
        session_duration.observe(cost_ctrl.elapsed_seconds)
        sessions_active.dec()

Punti chiave

  • L’architettura di produzione separa load balancer, worker asyncio, database e monitoraggio
  • Un SessionManager con un semaforo controlla il numero di sessioni simultanee
  • Il logging strutturato JSON abilita il debug e la conformità (registrazione conversazioni)
  • Le metriche Prometheus (TTFA, durata, token, errori) sono essenziali per le operazioni quotidiane
  • Il CostController limita la durata della sessione e i token per prevenire sforamenti di budget

Metti alla prova le tue conoscenze

Cinque domande che coprono l’intera catena vocale, dal WebSocket al deployment in produzione.

1. Perché le Realtime API usano WebSocket invece di richieste HTTP?

Risposta: Perché una connessione persistente e bidirezionale permette di streammare l’audio del microfono e ricevere risposte continuamente, senza pagare l’overhead di stabilire una richiesta per ogni scambio. Questo è il prerequisito per una conversazione a bassa latenza.

2. Cosa devi inviare immediatamente dopo `session.created`, e perché?

Risposta: session.update, immediatamente: è qui che configuri la voce, le istruzioni, gli strumenti e il formato audio. Finché questo messaggio non viene inviato, la sessione gira con valori predefiniti.

3. Perché un server proxy è essenziale in produzione?

Risposta: Previene l’esposizione della chiave API nel client e ti permette di autenticare l’utente, limitare il consumo e registrare le chiamate — tre cose impossibili se il browser parla direttamente alle API.

4. Qual è lo scopo del parametro `prompt` nell'API di trascrizione?

Risposta: Orientare il riconoscimento verso il vocabolario atteso: nomi propri, marchi, gergo di settore. I termini che elenchi lì vengono trascritti con molta più accuratezza.

5. Qual è la leva principale per la latenza percepita in un agente vocale?

Risposta: Streaming end-to-end: riprodurre l’audio non appena arrivano i primi frammenti invece di aspettare la risposta completa, e gestire l’interruzione così che l’utente possa intervenire in qualsiasi momento.