Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Seansid, sündmused ja elutsükkel

Õppetund 2 / 18 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Seansid, sündmused ja elutsükkel
  2. Seansi elutsükkel
  3. Seansi konfigureerimine
  4. Sündmuste süsteem
  5. Veakäsitlus
  6. Peamised punktid

Uuendatud 2. novembril 2026 – Helimudelid. Mitmed selles kursuses käsitletud mudelid on aegunud: tts-1, tts-1-hd ja gpt-4o-mini-tts lõ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-realtime ja vanad helimudelid 20. jaanuaril 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. 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 ei server_vad ega semantic_vad. Sellises vestlusseansis, kus VAD valideerib iga pöörde, määratleb dokumentatsioon kasutama gpt-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:

1

Ühendus → session.created

Server kinnitab seansi unikaalse ID ja vaikimisi konfiguratsiooniga.

2

Konfiguratsioon → session.update

Saadad sündmuse session.update, et määratleda juhised, hääl, tööriistad ja modaalsused.

3

Aktiivne vestlus

Heli- ja tekstisündmuste vahetus kliendi ja serveri vahel.

4

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.update konfigureerib seansi pärast session.created; enne uue konfiguratsiooni kasutamist oota sündmust session.updated
  • Sisendi transkribeerimiseks vestlusseansis kasuta gpt-transcribei; gpt-live-transcribe on 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 error sündmusi