Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Interruzioni e gestione dei turni

Lezione 5 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Interruzioni e gestione dei turni
  2. Rilevamento attività vocale (VAD)
  3. Gestione delle interruzioni
  4. Modalità di controllo manuale
  5. Architettura di gestione dello stato
  6. Punti chiave

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 OpenAI TTS indica come non supportata da /v1/audio/speech: la migrazione della sintesi vocale passa alle 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 nell’API dal 10 settembre 2026.

Corretto il 3 novembre 2026. Gli eventi session.update posizionavano precedentemente turn_detection alla radice della sessione, un formato della vecchia beta: con l’attuale Realtime API, l’impostazione risiede in session.audio.input.turn_detection e la sessione include "type": "realtime". La gestione delle interruzioni inviava precedentemente response.cancel, ma con il VAD il server annulla la risposta autonomamente e il codice utilizzava una variabile non definita. Questa lezione copre ora semantic_vad, create_response e interrupt_response, distinguendo tra WebSocket e WebRTC. Forme degli eventi verificate rispetto ai tipi SDK openai 3.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:

  1. Interrompi la riproduzione immediatamente e scarta qualsiasi audio in coda, annotando quanti millisecondi l’utente ha effettivamente ascoltato.
  2. 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_vad per impostazione predefinita) è configurato in session.audio.input.turn_detection
  • semantic_vad segmenta in base al significato; eagerness ne 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_detection impostato su None) è adatta a push-to-talk, menu IVR e dettatura
  • Una macchina a stati esplicita previene comportamenti incoerenti nei casi limite