Interruzioni e gestione dei turni
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 OpenAI TTS indica come non supportata da/v1/audio/speech: la migrazione della sintesi vocale passa alle 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 nell’API dal 10 settembre 2026.
Corretto il 3 novembre 2026. Gli eventi
session.updateposizionavano precedentementeturn_detectionalla radice della sessione, un formato della vecchia beta: con l’attuale Realtime API, l’impostazione risiede insession.audio.input.turn_detectione la sessione include"type": "realtime". La gestione delle interruzioni inviava precedentementeresponse.cancel, ma con il VAD il server annulla la risposta autonomamente e il codice utilizzava una variabile non definita. Questa lezione copre orasemantic_vad,create_responseeinterrupt_response, distinguendo tra WebSocket e WebRTC. Forme degli eventi verificate rispetto ai tipi SDKopenai3.42.1. Fonti: Rilevamento attività vocale · Conversazioni in tempo reale.
Interruzioni e gestione dei turni
Nelle conversazioni naturali, le persone si interrompono a vicenda, parlano contemporaneamente e si tagliano la parola. Un agente vocale incapace di gestire queste situazioni risulterà robotico e frustrante. La Realtime API offre due meccanismi per gestire l’avvicendamento dei turni: il rilevamento automatico dell’attività vocale (VAD) e il controllo manuale.
Rilevamento attività vocale (VAD)
Il VAD è abilitato per impostazione predefinita in una sessione di conversazione vocale, operando in modalità server_vad: il server analizza continuamente l’audio in ingresso, segmenta in base al silenzio e segnala l’inizio e la fine del parlato dell’utente. Lo configuri in session.audio.input.turn_detection:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"audio": {
"input": {
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"prefix_padding_ms": 300,
"silence_duration_ms": 500,
"create_response": True, # rispondi immediatamente alla fine del turno
"interrupt_response": True, # interrompi l'agente se l'utente parla
}
}
},
},
}))
Parametri del VAD
| Parametro | Descrizione | Impatto |
|---|---|---|
| threshold | Soglia di rilevamento (da 0.0 a 1.0) | Alto = meno sensibile, Basso = più sensibile |
| prefix_padding_ms | Audio conservato prima del rilevamento | Evita di tagliare l'inizio delle parole |
| silence_duration_ms | Durata del silenzio richiesta per terminare il turno | Breve = reattivo, Lungo = paziente |
Un silence_duration_ms troppo breve attiverà una risposta durante le pause naturali nel discorso dell’utente; troppo lungo e l’agente sembrerà poco reattivo. OpenAI non pubblica valori predefiniti specifici per lingua: inizia con l’esempio della documentazione (500 ms) e regola in base alle registrazioni dei tuoi utenti. Una threshold più alta richiede un suono più forte per attivarsi, il che aiuta in ambienti rumorosi.
Semantic VAD
La seconda modalità, semantic_vad, non si basa sul silenzio ma sulle parole: un classificatore stima se l’utente ha terminato la propria frase. Una frase lasciata in sospeso guadagna più tempo rispetto a un’affermazione chiara e il modello interrompe meno spesso. La sua impostazione eagerness può essere low (lascia tempo all’utente), medium, high (rispondi il prima possibile) o auto, il valore predefinito, equivalente a medium:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"audio": {"input": {"turn_detection": {"type": "semantic_vad", "eagerness": "low"}}},
},
}))
Gestione delle interruzioni
Quando l’utente parla mentre l’agente sta rispondendo, il server emette input_audio_buffer.speech_started. Con il VAD e interrupt_response abilitati, il server annulla la risposta corrente: invia quindi response.done con stato cancelled. Devi comunque fare due cose dalla tua parte, su una connessione WebSocket dove stai riproducendo l’audio:
- Interrompi la riproduzione immediatamente e scarta qualsiasi audio in coda, annotando quanti millisecondi l’utente ha effettivamente ascoltato.
- Tronca l’elemento dell’agente a quella durata usando
conversation.item.truncate.
Non aspettare response.done per fare nessuna delle due cose.
async def handle_interruption(ws, event: dict, player, item_id: str | None, ms_played: int) -> None:
"""Gestisce il parlato dell'utente mentre l'agente sta parlando (WebSocket)."""
if event["type"] != "input_audio_buffer.speech_started":
return
# 1. Interrompi la riproduzione e svuota il buffer audio in coda
player.stop_stream()
# 2. Rimuovi dalla cronologia la parte che l'utente non ha ascoltato
if item_id:
await ws.send(json.dumps({
"type": "conversation.item.truncate",
"item_id": item_id,
"content_index": 0,
"audio_end_ms": ms_played,
}))
# 3. Riapri la riproduzione per la prossima risposta
player.start_stream()
Calcola ms_played in base a ciò che hai effettivamente inviato all’altoparlante: in PCM mono a 16 bit a 24 kHz, 48.000 byte equivalgono a un secondo. In WebRTC o SIP, il server gestisce autonomamente il buffer di output, sa cosa è stato riprodotto e tronca automaticamente: non devi inviare nulla.
Perché troncare la risposta?
Senza troncamento, la cronologia della conversazione conterrebbe la risposta completa del modello, anche se l’utente ne ha ascoltato solo una parte. Se l’utente chiede: «Qual è l’ultima cosa che hai detto?», il modello penserebbe di averla detta tutta. Il troncamento allinea la cronologia a ciò che l’utente ha effettivamente ascoltato. La documentazione nota una limitazione: il troncamento taglia l’audio e rimuove la trascrizione della parte non riprodotta, ma non fornisce una trascrizione troncata parola per parola.
Modalità di controllo manuale
Per alcuni casi d’uso (menu IVR, dettatura, quiz), il VAD automatico non è adatto. La modalità manuale ti offre il controllo completo:
# Disabilita il VAD
await ws.send(json.dumps({
"type": "session.update",
"session": {"type": "realtime", "audio": {"input": {"turn_detection": None}}},
}))
# Pulsante premuto: se l'agente sta ancora parlando, annulla la sua risposta e tronca l'audio non riprodotto
await ws.send(json.dumps({"type": "response.cancel"}))
# Pulsante rilasciato: l'audio è stato inviato tramite input_audio_buffer.append, conferma il turno...
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
# ...quindi attiva la risposta
await ws.send(json.dumps({"type": "response.create"}))
Senza VAD, nulla è automatico: è qui che entra in gioco response.cancel, quando una risposta è in corso mentre l’utente riprende il controllo. Tra un turno e l’altro, input_audio_buffer.clear svuota il buffer di input.
Esiste una via di mezzo: mantieni il VAD abilitato in modo che continui a segmentare i turni ed emettere eventi, ma imposta create_response e interrupt_response su False. Nessuna risposta viene inviata senza il tuo esplicito response.create, dandoti il tempo di verificare o arricchire l’input (moderazione, recupero documenti), al costo di una certa latenza.
Casi d’uso della modalità manuale
- Menu IVR: attendi un tono DTMF o una parola chiave specifica prima di rispondere
- Dettatura: accumula segmenti audio lunghi senza interruzioni
- Conferma: attendi un «sì» o un «no» espliciti
- Push-to-talk: l’utente preme un pulsante per parlare
Architettura di gestione dello stato
Per una gestione robusta dei turni, mantieni una macchina a stati:
from enum import Enum
class ConversationState(Enum):
IDLE = "idle" # In attesa
USER_SPEAKING = "user_speaking" # L'utente sta parlando
PROCESSING = "processing" # Il modello sta elaborando
AGENT_SPEAKING = "agent_speaking" # L'agente sta rispondendo
INTERRUPTED = "interrupted" # Interruzione in corso
class TurnManager:
def __init__(self):
self.state = ConversationState.IDLE
self.current_response_item_id = None
self.played_audio_ms = 0
def on_event(self, event_type: str):
if event_type == "input_audio_buffer.speech_started":
if self.state == ConversationState.AGENT_SPEAKING:
self.state = ConversationState.INTERRUPTED
else:
self.state = ConversationState.USER_SPEAKING
elif event_type == "input_audio_buffer.speech_stopped":
self.state = ConversationState.PROCESSING
elif event_type == "response.output_audio.delta":
self.state = ConversationState.AGENT_SPEAKING
elif event_type == "response.done":
self.state = ConversationState.IDLE
Punti chiave
- Il VAD (
server_vadper impostazione predefinita) è configurato insession.audio.input.turn_detection semantic_vadsegmenta in base al significato;eagernessne controlla la pazienza- Con il VAD, il server annulla la risposta interrotta; su WebSocket, interrompi la riproduzione e tronca con
conversation.item.truncate(automatico in WebRTC e SIP) - La modalità manuale (
turn_detectionimpostato suNone) è adatta a push-to-talk, menu IVR e dettatura - Una macchina a stati esplicita previene comportamenti incoerenti nei casi limite