Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Onderbrekingen en beurtbeheer

Les 5 van 18 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Onderbrekingen en beurtbeheer
  2. Voice Activity Detection (VAD)
  3. Onderbrekingen afhandelen
  4. Handmatige besturingsmodus
  5. Architectuur voor statusbeheer
  6. Belangrijkste punten

Bijgewerkt 2 november 2026 — Audiomodellen. Verschillende modellen in deze cursus zijn verouderd: tts-1, tts-1-hd en gpt-4o-mini-tts stoppen op 6 januari 2027 (vervanger: gpt-realtime-2.1-mini, waarvan de OpenAI TTS-gids aangeeft dat deze niet wordt ondersteund door /v1/audio/speech: migratie van spraaksynthese gaat naar de Realtime API); gpt-realtime, gpt-4o-realtime en legacy audiomodellen op 20 januari 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe en /v1/audio/translations op 26 februari 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Voor full-duplex spraak is GPT-Live 1 beschikbaar in de API sinds 10 september 2026.

Gecorrigeerd 3 november 2026. session.update-events plaatsten turn_detection eerder aan de root van de sessie, een indeling uit de oude bèta: met de huidige Realtime API staat de instelling in session.audio.input.turn_detection, en de sessie bevat "type": "realtime". Afhandeling van onderbrekingen stuurde eerder response.cancel, maar met VAD annuleert de server de respons zelf, en de code gebruikte een niet-gedefinieerde variabele. Deze les behandelt nu semantic_vad, create_response en interrupt_response, en maakt onderscheid tussen WebSocket en WebRTC. Event-shapes zijn geverifieerd tegen openai SDK-types 3.42.1. Bronnen: Voice activity detection · Realtime conversations.

Onderbrekingen en beurtbeheer

In natuurlijke gesprekken onderbreken mensen elkaar, praten ze door elkaar heen en kapen ze elkaars zinnen. Een voice-agent die deze situaties niet aankan, voelt robotachtig en frustrerend. De Realtime API biedt twee mechanismen voor beurtbeheer: automatische Voice Activity Detection (VAD) en handmatige besturing.

Voice Activity Detection (VAD)

VAD is standaard ingeschakeld in een spraaksessie en werkt in de modus server_vad: de server analyseert continu binnenkomende audio, segmenteert op basis van stilte en signaleert het begin en einde van gebruikersspraak. U configureert dit 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,      # direct reageren wanneer beurt eindigt
                    "interrupt_response": True,   # agent onderbreken als gebruiker spreekt
                }
            }
        },
    },
}))

VAD-parameters

Parameter Beschrijving Impact
threshold Detectiedrempel (0,0 tot 1,0) Hoog = minder gevoelig, Laag = gevoeliger
prefix_padding_ms Audio behouden vóór detectie Voorkomt afkappen van begin van woorden
silence_duration_ms Vereiste stilte om beurt te beëindigen Kort = responsief, Lang = geduldig

Een silence_duration_ms die te kort is, activeert een respons tijdens natuurlijke pauzes in de spraak van de gebruiker; is deze te lang, dan lijkt de agent traag. OpenAI publiceert geen taalspecifieke standaardwaarden: begin met het voorbeeld uit de documentatie (500 ms) en pas dit aan op basis van opnames van uw gebruikers. Een hogere threshold vereist harder geluid om te activeren, wat helpt in lawaaierige omgevingen.

Semantische VAD

De tweede modus, semantic_vad, vertrouwt niet op stilte maar op woorden: een classifier schat of de gebruiker zijn zin heeft afgerond. Een onafgemaakte zin geeft meer tijd dan een duidelijke uitspraak, en het model onderbreekt minder vaak. De instelling eagerness kan low zijn (geef de gebruiker de tijd), medium, high (reageer zo snel mogelijk) of auto, de standaardwaarde, wat gelijkstaat aan medium:

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "audio": {"input": {"turn_detection": {"type": "semantic_vad", "eagerness": "low"}}},
    },
}))

Onderbrekingen afhandelen

Wanneer de gebruiker spreekt terwijl de agent antwoordt, zendt de server input_audio_buffer.speech_started uit. Met VAD en interrupt_response ingeschakeld, annuleert de server de huidige respons: deze stuurt vervolgens response.done met status cancelled. U moet zelf nog twee dingen doen op een WebSocket-verbinding waar u de audio afspeelt:

  1. Stop het afspelen onmiddellijk en verwijder alle audio in de wachtrij, waarbij u noteert hoeveel milliseconden de gebruiker daadwerkelijk heeft gehoord.
  2. Kort de agent-item in tot die duur met conversation.item.truncate.

Wacht niet op response.done om dit te doen.

async def handle_interruption(ws, event: dict, player, item_id: str | None, ms_played: int) -> None:
    """Verwerkt gebruikersspraak terwijl de agent spreekt (WebSocket)."""
    if event["type"] != "input_audio_buffer.speech_started":
        return

    # 1. Stop afspelen en wis de audio-buffer in de wachtrij
    player.stop_stream()

    # 2. Verwijder het deel dat de gebruiker niet heeft gehoord uit de geschiedenis
    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. Heropen afspelen voor de volgende respons
    player.start_stream()

Bereken ms_played op basis van wat u daadwerkelijk naar de luidspreker heeft gestuurd: bij 16-bit mono PCM op 24 kHz staat 48.000 bytes gelijk aan één seconde. Bij WebRTC of SIP beheert de server de uitvoerbuffer zelf, weet deze wat is afgespeeld en kort automatisch in: u hoeft niets te sturen.

Waarom de respons inkorten?

Zonder inkorting zou de gespreksgeschiedenis de volledige respons van het model bevatten, terwijl de gebruiker slechts een deel heeft gehoord. Als de gebruiker vraagt: “Wat was het laatste wat je zei?”, denkt het model dat het alles heeft gezegd. Inkorten zorgt ervoor dat de geschiedenis overeenkomt met wat de gebruiker daadwerkelijk heeft gehoord. De documentatie noemt een beperking: inkorten snijdt de audio af en verwijdert de transcriptie van het niet-afgespeelde deel, maar levert geen woord-voor-woord ingekorte transcriptie.

Handmatige besturingsmodus

Voor bepaalde use-cases (IVR-menu’s, dicteren, quizzen) is automatische VAD niet geschikt. De handmatige modus geeft u volledige controle:

# VAD uitschakelen
await ws.send(json.dumps({
    "type": "session.update",
    "session": {"type": "realtime", "audio": {"input": {"turn_detection": None}}},
}))

# Knop ingedrukt: als agent nog spreekt, annuleer dan de respons en kort niet-afgespeelde audio in
await ws.send(json.dumps({"type": "response.cancel"}))

# Knop losgelaten: audio is verzonden via input_audio_buffer.append, bevestig de beurt...
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))

# ...en trigger vervolgens de respons
await ws.send(json.dumps({"type": "response.create"}))

Zonder VAD gebeurt er niets automatisch: hier komt response.cancel van pas, wanneer een respons loopt terwijl de gebruiker de controle terugneemt. Tussen beurten leegt input_audio_buffer.clear de invoerbuffer.

Er bestaat een tussenweg: houd VAD ingeschakeld zodat het beurten blijft segmenteren en events uitzendt, maar stel create_response en interrupt_response in op False. Er wordt geen respons verzonden zonder uw expliciete response.create, waardoor u tijd heeft om de invoer te verifiëren of te verrijken (moderatie, documentophaling), ten koste van enige latentie.

Use-cases voor handmatige modus

  • IVR-menu: Wacht op een DTMF-toon of specifiek trefwoord voordat u reageert
  • Dicteren: Verzamel lange audiofragmenten zonder onderbreking
  • Bevestiging: Wacht op een expliciet “ja” of “nee”
  • Push-to-talk: Gebruiker drukt op een knop om te spreken

Architectuur voor statusbeheer

Voor robuust beurtbeheer onderhoudt u een statusmachine:

from enum import Enum

class ConversationState(Enum):
    IDLE = "idle"                    # Wachten
    USER_SPEAKING = "user_speaking"  # Gebruiker spreekt
    PROCESSING = "processing"        # Model verwerkt
    AGENT_SPEAKING = "agent_speaking" # Agent antwoordt
    INTERRUPTED = "interrupted"       # Onderbreking bezig

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

Belangrijkste punten

  • VAD (server_vad standaard) wordt geconfigureerd in session.audio.input.turn_detection
  • semantic_vad segmenteert op basis van betekenis; eagerness regelt het geduld
  • Met VAD annuleert de server de onderbroken respons; stop bij WebSocket het afspelen en kort in met conversation.item.truncate (automatisch bij WebRTC en SIP)
  • Handmatige modus (turn_detection ingesteld op None) is geschikt voor push-to-talk, IVR-menu’s en dicteren
  • Een expliciete statusmachine voorkomt inconsistent gedrag in randgevallen