Seansid, sündmused ja elutsükkel
Sellel lehel
Uuendatud 2. novembril 2026 – Helimudelid. Mitmed selles kursuses käsitletud mudelid on aegunud:
tts-1,tts-1-hdjagpt-4o-mini-ttslõpetavad töö 6. jaanuaril 2027 (asendaja:gpt-realtime-2.1-mini, mida OpenAI TTS-i juhendi kohaselt ei toeta/v1/audio/speech: kõnesünteesi migratsioon viiakse üle Realtime API-le);gpt-realtime,gpt-4o-realtimeja vanad helimudelid 20. jaanuaril 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeja/v1/audio/translations26. veebruaril 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Täisdupleksse kõne jaoks on GPT-Live 1 olnud API-s saadaval alates 10. septembrist 2026.
Parandatud 3. novembril 2026. Sisendi transkriptsioon kasutas
gpt-live-transcribei, mis toimib ainult transkriptsiooni seansis ega toeta eiserver_vadegasemantic_vad. Sellises vestlusseansis, kus VAD valideerib iga pöörde, määratleb dokumentatsioon kasutamagpt-transcribei, mis transkribeerib valideeritud pöördeid ja kasutab eelmisi pöördeid kontekstina. Allikad: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Seansid, sündmused ja elutsükkel
Iga WebSocket-ühendus Realtime API-ga loob seansi. See seanss on halduse põhiüksus: see kapseldab mudeli konfiguratsiooni, vestluse ajaloo, saadaolevad tööriistad ja interaktsiooni praeguse oleku. Selle elutsükli mõistmine on hädavajalik töökindlate häälagentide loomiseks.
Seansi elutsükkel
Niipea kui WebSocket-ühendus on loodud, edastab server sündmuse session.created. Seanss läbib mitu faasi:
Ühendus → session.created
Server kinnitab seansi unikaalse ID ja vaikimisi konfiguratsiooniga.
Konfiguratsioon → session.update
Saadad sündmuse session.update, et määratleda juhised, hääl, tööriistad ja modaalsused.
Aktiivne vestlus
Heli- ja tekstisündmuste vahetus kliendi ja serveri vahel.
Sulgemine → WebSocket disconnect
Seanss hävitatakse ühenduse katkemisel. Serveris olekut ei säilitata.
Seansi konfigureerimine
Pärast session.created saada seansi käitumise konfigureerimiseks sündmus session.update. Kasutaja öeldu transkribeerimine (audio.input.transcription) on valikuline: ilma selleta saad ainult hääle, mitte teksti. languages määratleb oodatavad keeled ja parandab äratundmist:
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:
# Oota session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Konfigureeri seanss
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": []
}
}))
# Oota kinnitust (muud sündmused võivad saabuda varem)
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"])
Seansi põhiparameetrid
| Parameeter | Kirjeldus | Soovitatav väärtus |
|---|---|---|
| output_modalities | Väljundi modaalsused | ["audio"] (või ["text"]) |
| audio.output.voice | Sünteesi hääl | marin, cedar, alloy, echo jne |
| audio.input.turn_detection | Kõne lõpu tuvastamine | server_vad lävendiga 0.5 |
| audio.input.format | Siseneva heli formaat | {"type": "audio/pcm", "rate": 24000} |
Sündmuste süsteem
Realtime API on täielikult sündmustepõhine. Iga vahetatud sõnum on JSON-objekt väljaga type, mis määrab selle olemuse. Sündmused jagunevad kahte kategooriasse:
Kliendi sündmused (sina → server)
# Peamised sündmused, mida saadad
client_events = {
"session.update": "Muuda konfiguratsiooni",
"input_audio_buffer.append": "Saada helilõik",
"input_audio_buffer.commit": "Kinnita helipuhver",
"input_audio_buffer.clear": "Tühjenda helipuhver",
"conversation.item.create": "Lisa sõnum käsitsi",
"conversation.item.truncate": "Lühenda vastust",
"conversation.item.delete": "Kustuta sõnum",
"response.create": "Käivita vastus",
"response.cancel": "Tühista praegune vastus",
}
Serveri sündmused (server → sina)
# Peamised sündmused, mida vastu võtad
server_events = {
"session.created": "Seanss initsialiseeritud",
"session.updated": "Konfiguratsioon rakendatud",
"input_audio_buffer.speech_started": "Kõne tuvastatud",
"input_audio_buffer.speech_stopped": "Vaikus tuvastatud",
"conversation.item.created": "Uus sõnum ajaloos",
"response.created": "Generatsioon alanud",
"response.output_audio.delta": "Vastuse helilõik",
"response.output_audio_transcript.delta": "Transkriptsiooni lõik",
"response.done": "Vastus lõpetatud",
"error": "Viga",
}
Veakäsitlus
Vead edastatakse tüübiga error sündmuse kaudu. Sa pead need alati перехватima:
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":
# Konfiguratsiooniviga, paranda ja proovi uuesti
pass
elif error["type"] == "server_error":
# Probleem OpenAI poolel, ühenda uuesti
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}")
Peamised punktid
- Seanss luuakse automaatselt WebSocket-ühenduse loomisel ja hävitatakse ühenduse katkemisel
session.updatekonfigureerib seansi pärastsession.created; enne uue konfiguratsiooni kasutamist oota sündmustsession.updated- Sisendi transkribeerimiseks vestlusseansis kasuta
gpt-transcribei;gpt-live-transcribeon reserveeritud transkriptsiooniseanssidele - Protokoll on puhtalt sündmustepõhine: igal sõnumil on
type, mis määrab selle töötlemise - Kliendi sündmused juhivad interaktsiooni; serveri sündmused teavitavad tulemustest
- Veakäsitlus on kriitilise tähtsusega: kuula alati
errorsündmusi