Keskeytykset ja vuoronhallinta
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on poistettu käytöstä:
tts-1,tts-1-hdjagpt-4o-mini-ttslakkaavat 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-realtimeja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeja/v1/audio/translations26. 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 aiemminturn_detection-asetuksen istunnon juurelle, mikä oli vanhan beta-version muoto: nykyisessä Realtime API:ssa asetus sijaitsee kohdassasession.audio.input.turn_detection, ja istunnolla on"type": "realtime". Keskeytysten käsittely lähetti aiemminresponse.cancel-komentoa, mutta VAD:n kanssa palvelin peruuttaa vastauksen itse, ja koodi käytti määrittelemätöntä muuttujaa. Tämä oppitunti käsittelee nytsemantic_vad-tilaa,create_response- jainterrupt_response-asetuksia sekä erottaa WebSocketin ja WebRTC:n. Tapahtumien muodot on varmistettuopenaiSDK -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ä:
- Pysäytä toisto välittömästi ja hylkää kaikki jonossa oleva ääni merkiten muistiin, kuinka monta millisekuntia käyttäjä ehti kuulla.
- 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 kohdassasession.audio.input.turn_detection semantic_vadsegmentoi merkityksen perusteella;eagernessohjaa 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_detectionasetettu arvoonNone) sopii paina-puhu-toimintoon, IVR-valikoihin ja saneluun - Nimenomainen tilakone estää epäjohdonmukaisen käyttäytymisen reunaehdoissa