Produzione: Scalabilità e Monitoraggio
In questa pagina
Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati:
tts-1,tts-1-hdegpt-4o-mini-ttssmetteranno 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-realtimee 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-transcribee/v1/audio/translationsil 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 SDKopenaiversione 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:
Load Balancer (nginx / HAProxy)
Distribuisce le connessioni WebSocket in arrivo tra i worker. Supporta le sessioni sticky per mantenere l'affinità.
Worker (FastAPI + uvicorn)
Ogni worker gestisce più sessioni Realtime simultanee grazie ad asyncio.
Database (PostgreSQL)
Archivia i log delle conversazioni, le metriche e la configurazione dell'agente.
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
SessionManagercon 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
CostControllerlimita 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.