Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Keskeytykset ja vuoronhallinta

Oppitunti 5 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Keskeytykset ja vuoronhallinta
  2. Puheen havaitseminen (VAD)
  3. Keskeytysten käsittely
  4. Manuaalinen ohjaustila
  5. Tilanhallinnan arkkitehtuuri
  6. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on poistettu käytöstä: tts-1, tts-1-hd ja gpt-4o-mini-tts lakkaavat toimimasta 6. tammikuuta 2027 (korvaaja: gpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tuetun /v1/audio/speech-päätepistettä: puheentuotto siirtyy Realtime API:hun); gpt-realtime, gpt-4o-realtime ja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. helmikuuta 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Täysdupleksinen ääni, GPT-Live 1, on ollut saatavilla API:ssa 10. syyskuuta 2026 lähtien.

Korjattu 3. marraskuuta 2026. session.update-tapahtumat sijoittivat aiemmin turn_detection-asetuksen istunnon juurelle, mikä oli vanhan beta-version muoto: nykyisessä Realtime API:ssa asetus sijaitsee kohdassa session.audio.input.turn_detection, ja istunnolla on "type": "realtime". Keskeytysten käsittely lähetti aiemmin response.cancel-komentoa, mutta VAD:n kanssa palvelin peruuttaa vastauksen itse, ja koodi käytti määrittelemätöntä muuttujaa. Tämä oppitunti käsittelee nyt semantic_vad-tilaa, create_response- ja interrupt_response-asetuksia sekä erottaa WebSocketin ja WebRTC:n. Tapahtumien muodot on varmistettu openai SDK -tyyppien 3.42.1 mukaan. Lähteet: Puheen havaitseminen (Voice activity detection) · Reaaliaikaiset keskustelut.

Keskeytykset ja vuoronhallinta

Luonnollisessa keskustelussa ihmiset keskeyttävät toisensa, puhuvat päällekkäin ja katkaisevat toistensa lauseita. Ääniagentti, joka ei pysty käsittelemään näitä tilanteita, vaikuttaa robotimaiselta ja turhauttavalta. Realtime API tarjoaa kaksi mekanismia vuoronhallintaan: automaattisen puheen havaitsemisen (VAD) ja manuaalisen ohjauksen.

Puheen havaitseminen (VAD)

VAD on oletusarvoisesti käytössä äänikeskusteluistunnossa toimien server_vad-tilassa: palvelin analysoi jatkuvasti saapuvaa ääntä, segmentoi sen hiljaisuuden perusteella ja signaloi käyttäjän puheen alun ja lopun. Määrität sen kohdassa 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,      # vastaa heti vuoron päätyttyä
                    "interrupt_response": True,   # katkaise agentti, jos käyttäjä puhuu
                }
            }
        },
    },
}))

VAD-parametrit

Parametri Kuvaus Vaikutus
threshold Havaintokynnys (0.0–1.0) Korkea = vähemmän herkkä, Matala = herkempi
prefix_padding_ms Ennen havaintoa säilytetty ääni Estää sanojen alun katkeamisen
silence_duration_ms Vuoron päättymiseen vaadittava hiljaisuuden kesto Lyhyt = nopea reagointi, Pitkä = kärsivällinen

Liian lyhyt silence_duration_ms laukaisee vastauksen käyttäjän puheen luonnollisten taukojen aikana; liian pitkä taas saa agentin vaikuttamaan hitaalta. OpenAI ei julkaise kielikohtaisia oletusarvoja: aloita dokumentaation esimerkillä (500 ms) ja säädä arvoa käyttäjiesi äänitteiden perusteella. Korkeampi threshold vaatii kovempaa ääntä laukaisemiseen, mikä auttaa meluisissa ympäristöissä.

Semanttinen VAD

Toinen tila, semantic_vad, ei luota hiljaisuuteen vaan sanoihin: luokitin arvioi, onko käyttäjä päättänyt lauseensa. Keskeneräinen lause antaa enemmän aikaa kuin selkeä väittämä, ja malli keskeyttää harvemmin. Sen eagerness-asetus voi olla low (anna käyttäjän ottaa aikansa), medium, high (vastaa niin pian kuin mahdollista) tai auto, joka on oletusarvo ja vastaa arvoa medium:

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

Keskeytysten käsittely

Kun käyttäjä puhuu agentin vastatessa, palvelin lähettää tapahtuman input_audio_buffer.speech_started. Kun VAD ja interrupt_response ovat käytössä, palvelin peruuttaa nykyisen vastauksen: se lähettää sitten response.done-tapahtuman tilalla cancelled. Sinun on kuitenkin tehtävä kaksi asiaa omassa päässäsi WebSocket-yhteydellä, jossa toistat ääntä:

  1. Pysäytä toisto välittömästi ja hylkää kaikki jonossa oleva ääni merkiten muistiin, kuinka monta millisekuntia käyttäjä ehti kuulla.
  2. Lyhennä agentin kohde (item) tähän kestoon käyttämällä conversation.item.truncate-komentoa.

Älä odota response.done-tapahtumaa kummankaan tekemiseen.

async def handle_interruption(ws, event: dict, player, item_id: str | None, ms_played: int) -> None:
    """Käsittelee käyttäjän puhumisen agentin puhuessa (WebSocket)."""
    if event["type"] != "input_audio_buffer.speech_started":
        return

    # 1. Pysäytä toisto ja tyhjennä jonossa oleva äänipuskuri
    player.stop_stream()

    # 2. Poista historiasta osa, jota käyttäjä ei kuullut
    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. Avaa toisto uudelleen seuraavaa vastausta varten
    player.start_stream()

Laske ms_played sen perusteella, mitä todella lähetit kaiuttimelle: 16-bittisessä mono-PCM-formaatissa 24 kHz:n taajuudella 48 000 tavua vastaa yhtä sekuntia. WebRTC:ssä tai SIP:ssä palvelin hallitsee itse lähtöpuskuria, tietää mitä on toistettu ja lyhentää automaattisesti: sinun ei tarvitse lähettää mitään.

Miksi vastaus kannattaa lyhentää?

Ilman lyhentämistä keskusteluhistoria sisältäisi mallin koko vastauksen, vaikka käyttäjä kuuli siitä vain osan. Jos käyttäjä kysyy: “Mitä sanoit viimeksi?”, malli luulisi sanoneensa kaiken. Lyhentäminen synkronoi historian sen kanssa, mitä käyttäjä todella kuuli. Dokumentaatio mainitsee rajoituksen: lyhentäminen katkaisee äänen ja poistaa toistamattoman osan transkription, mutta se ei tarjoa sana sanalta lyhennettyä transkriptiota.

Manuaalinen ohjaustila

Tietyissä käyttötarkoituksissa (IVR-valikot, sanelu, visat) automaattinen VAD ei sovellu. Manuaalinen tila antaa sinulle täyden kontrollin:

# Poista VAD käytöstä
await ws.send(json.dumps({
    "type": "session.update",
    "session": {"type": "realtime", "audio": {"input": {"turn_detection": None}}},
}))

# Painike painettu: jos agentti puhuu edelleen, peruuta sen vastaus ja lyhennä toistamaton ääni
await ws.send(json.dumps({"type": "response.cancel"}))

# Painike vapautettu: ääni lähetettiin input_audio_buffer.appendilla, sitoudu vuoroon...
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))

# ...ja käynnistä vastaus
await ws.send(json.dumps({"type": "response.create"}))

Ilman VAD:ta mikään ei ole automaattista: tässä response.cancel tulee käyttöön, kun vastaus on käynnissä ja käyttäjä ottaa kontrollin takaisin. Vuorojen välillä input_audio_buffer.clear tyhjentää syöttöpuskurin.

Väliratkaisukin on mahdollinen: pidä VAD käytössä, jotta se jatkaa vuorojen segmentointia ja tapahtumien lähettämistä, mutta aseta create_response ja interrupt_response arvoksi False. Vastausta ei lähetetä ilman nimenomaista response.create-komentoasi, mikä antaa aikaa tarkistaa tai rikastaa syötettä (moderointi, dokumenttien haku), mutta lisää viivettä.

Manuaalisen tilan käyttötarkoituksia

  • IVR-valikko: Odota DTMF-ääntä tai tiettyä avainsanaa ennen vastaamista
  • Sanelu: Kerää pitkiä äänijaksoja ilman keskeytyksiä
  • Varmistus: Odota nimenomaista “kyllä” tai “ei” -vastausta
  • Paina-puhu (Push-to-talk): Käyttäjä painaa painiketta puhuakseen

Tilanhallinnan arkkitehtuuri

Vankkaa vuoronhallintaa varten ylläpidä tilakonetta:

from enum import Enum

class ConversationState(Enum):
    IDLE = "idle"                    # Odottaa
    USER_SPEAKING = "user_speaking"  # Käyttäjä puhuu
    PROCESSING = "processing"        # Malli käsittelee
    AGENT_SPEAKING = "agent_speaking" # Agentti vastaa
    INTERRUPTED = "interrupted"       # Keskeytys käynnissä

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

Keskeiset asiat

  • VAD (oletuksena server_vad) määritetään kohdassa session.audio.input.turn_detection
  • semantic_vad segmentoi merkityksen perusteella; eagerness ohjaa sen kärsivällisyyttä
  • VAD:n kanssa palvelin peruuttaa keskeytetyn vastauksen; WebSocketissa pysäytä toisto ja lyhennä komennolla conversation.item.truncate (automaattista WebRTC:ssä ja SIP:ssä)
  • Manuaalinen tila (turn_detection asetettu arvoon None) sopii paina-puhu-toimintoon, IVR-valikoihin ja saneluun
  • Nimenomainen tilakone estää epäjohdonmukaisen käyttäytymisen reunaehdoissa