Istunnot, tapahtumat ja elinkaari
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äysdupleksista ääntä varten GPT-Live 1 on ollut saatavilla API:ssa 10. syyskuuta 2026 lähtien.
Korjattu 3. marraskuuta 2026. Syötteen litterointi käytti mallia
gpt-live-transcribe, joka toimii vain litterointi-istunnossa eikä tueserver_vad- eikäsemantic_vad-toimintoja. Tämän kaltaisessa keskusteluistunnossa, jossa VAD vahvistaa jokaisen vuoron, dokumentaatio määrää käyttämään malliagpt-transcribe, joka litteroi vahvistetut vuorot ja käyttää edellisiä vuoroja kontekstina. Lähteet: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Istunnot, tapahtumat ja elinkaari
Jokainen WebSocket-yhteys Realtime API:hun luo istunnon. Tämä istunto on hallinnan perusyksikkö: se kapseloi mallin konfiguraation, keskusteluhistorian, käytettävissä olevat työkalut ja vuorovaikutuksen nykytilan. Sen elinkaaren ymmärtäminen on välttämätöntä robustien ääniagenttien rakentamiseksi.
Istunnon elinkaari
Heti kun WebSocket-yhteys on muodostettu, palvelin lähettää session.created-tapahtuman. Istunto käy läpi useita vaiheita:
Yhteys → session.created
Palvelin vahvistaa istunnon uniikilla tunnisteella ja oletusasetuksilla.
Konfiguraatio → session.update
Lähetät session.update-määrityksen määritelläksesi ohjeet, äänen, työkalut ja modaliteetit.
Aktiivinen keskustelu
Ääni- ja tekstiviestien vaihto asiakkaan ja palvelimen välillä.
Sulkeminen → WebSocket disconnect
Istunto tuhoutuu, kun yhteys katkeaa. Palvelimelle ei jää mitään tilaa talteen.
Istunnon konfigurointi
session.created-tapahtuman jälkeen lähetä session.update-tapahtuma määritelläksesi mallin toiminnan. Käyttäjän puheen litterointi (audio.input.transcription) on valinnaista: ilman sitä vastaanotat äänen mutta et tekstiä. languages määrittää odotetut kielet ja parantaa tunnistusta:
import asyncio
import websockets
import json
async def configure_session():
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(URL, additional_headers=headers) as ws:
# Odota session.created-tapahtumaa
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Konfiguroi istunto
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "You are a French-speaking voice assistant. "
"Respond concisely and naturally.",
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000},
"transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"prefix_padding_ms": 300,
"silence_duration_ms": 500
}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000},
"voice": "marin"
}
},
"tools": []
}
}))
# Odota vahvistusta (muut tapahtumat voivat saapua ensin)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Session updated")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Keskeiset istuntoparametrit
| Parametri | Kuvaus | Suositeltu arvo |
|---|---|---|
| output_modalities | Lähtömodaliteetit | ["audio"] (tai ["text"]) |
| audio.output.voice | Synteesiääni | marin, cedar, alloy, echo jne. |
| audio.input.turn_detection | Puheen lopun tunnistus | server_vad, kynnysarvo 0.5 |
| audio.input.format | Saapuvan äänen formaatti | {"type": "audio/pcm", "rate": 24000} |
Tapahtumajärjestelmä
Realtime API on täysin tapahtumalähtöinen. Jokainen vaihdettu viesti on JSON-objekti, jossa on type-kenttä, joka määrittää sen luonteen. Tapahtumat jakautuvat kahteen kategoriaan:
Asiakastapahtumat (sinä → palvelin)
# Tärkeimmät lähettämäsi tapahtumat
client_events = {
"session.update": "Muuta konfiguraatiota",
"input_audio_buffer.append": "Lähetä äänipala",
"input_audio_buffer.commit": "Vahvista äänipuskuri",
"input_audio_buffer.clear": "Tyhjennä äänipuskuri",
"conversation.item.create": "Lisää viesti manuaalisesti",
"conversation.item.truncate": "Lyhennä vastausta",
"conversation.item.delete": "Poista viesti",
"response.create": "Käynnistä vastaus",
"response.cancel": "Peruuta nykyinen vastaus",
}
Palvelintapahtumat (palvelin → sinä)
# Tärkeimmät vastaanottamasi tapahtumat
server_events = {
"session.created": "Istunto alustettu",
"session.updated": "Konfiguraatio sovellettu",
"input_audio_buffer.speech_started": "Puhe havaittu",
"input_audio_buffer.speech_stopped": "Hiljaisuus havaittu",
"conversation.item.created": "Uusi viesti historiassa",
"response.created": "Generointi aloitettu",
"response.output_audio.delta": "Vastauksen äänipala",
"response.output_audio_transcript.delta": "Litterointipala",
"response.done": "Vastaus valmis",
"error": "Virhe",
}
Virheenkäsittely
Virheet lähetetään error-tyyppisenä tapahtumana. Sinun on aina siepattava ne:
async def handle_events(ws):
async for raw_message in ws:
event = json.loads(raw_message)
event_type = event["type"]
if event_type == "error":
error = event["error"]
print(f"Error [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Konfiguraatiovirhe, korjaa ja yritä uudelleen
pass
elif error["type"] == "server_error":
# Ongelma OpenAI:n puolella, muodosta yhteys uudelleen
pass
elif event_type == "session.updated":
print("Configuration applied successfully")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Tokens used: {usage}")
Keskeiset asiat
- Istunto luodaan automaattisesti WebSocket-yhteyden muodostuessa ja tuhoutuu yhteyden katketessa
session.updatekonfiguroi istunnonsession.created-tapahtuman jälkeen; odotasession.updated-tapahtumaa ennen kuin luotat uuteen konfiguraatioon- Litteroidaksesi syötteen keskusteluistunnossa käytä
gpt-transcribe-mallia;gpt-live-transcribeon varattu litterointi-istunnoille - Protokolla on puhtaasti tapahtumalähtöinen: jokaisella viestillä on
type, joka määrittää sen käsittelyn - Asiakastapahtumat ohjaavat vuorovaikutusta; palvelintapahtumat raportoivat tuloksia
- Virheenkäsittely on kriittistä: kuuntele aina
error-tapahtumia