Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Seje, dogodki in življenjski cikel

Lekcija 2 od 18 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Seje, dogodki in življenjski cikel
  2. Življenjski cikel seje
  3. Konfiguriranje seje
  4. Sistem dogodkov
  5. Obravnava napak
  6. Ključne ugotovitve

Posodobljeno 2. novembra 2026 — Zvočni modeli. Nekateri modeli v tem tečaju so opuščeni: tts-1, tts-1-hd in gpt-4o-mini-tts prenehajo delovati 6. januarja 2027 (nadomestilo: gpt-realtime-2.1-mini, ki ga vodnik za OpenAI TTS navaja kot nepodprt s strani /v1/audio/speech: selitev sinteze govora prehaja na Realtime API); gpt-realtime, gpt-4o-realtime in stari zvočni modeli 20. januarja 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe in /v1/audio/translations 26. februarja 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Za polno duplexni glas je GPT-Live 1 na voljo v API-ju od 10. septembra 2026.

Popravljeno 3. novembra 2026. Vnosni prepis je uporabljal gpt-live-transcribe, ki deluje le v seji za prepis in ne podpira niti server_vad niti semantic_vad. V pogovorni seji, kot je ta, kjer VAD potrjuje vsak obrat, dokumentacija določa uporabo gpt-transcribe, ki prepisuje potrjene obrate in uporablja prejšnje obrate kot kontekst. Viri: Prepis v realnem času · GPT-Transcribe · GPT-Live-Transcribe.

Seje, dogodki in življenjski cikel

Vsaka povezava WebSocket z Realtime API-jem ustvari sejo. Ta seja je osnovna enota upravljanja: zajema konfiguracijo modela, zgodovino pogovora, razpoložljiva orodja in trenutno stanje interakcije. Razumevanje njenega življenjskega cikla je ključno za gradnjo zanesljivih glasovnih agentov.

Življenjski cikel seje

Takoj ko je vzpostavljena povezava WebSocket, strežnik odda dogodek session.created. Seja prehaja skozi več faz:

1

Povezava → session.created

Strežnik potrdi sejo z edinstvenim ID-jem in privzeto konfiguracijo.

2

Konfiguracija → session.update

Pošlješ session.update za določitev navodil, glasu, orodij in modalitet.

3

Aktivni pogovor

Izmenjava zvočnih in besedilnih dogodkov med odjemalcem in strežnikom.

4

Zaključek → WebSocket disconnect

Seja se uniči, ko se povezava zapre. Na strežniku ne ostane nobeno stanje.

Konfiguriranje seje

Po dogodku session.created pošlji dogodek session.update za konfiguracijo obnašanja modela. Prepisovanje uporabnikovega govora (audio.input.transcription) je izbirno: brez tega prejmeš glas, ne pa tudi besedila. languages določa pričakovane jezike in izboljša prepoznavanje:

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:
        # Počakaj na session.created
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Session created: {session_id}")

        # Konfiguriraj sejo
        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": []
            }
        }))

        # Počakaj na potrditev (najprej lahko prispejo drugi dogodki)
        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"])

Ključni parametri seje

Parameter Opis Priporočena vrednost
output_modalities Izhodne modalitete ["audio"] (ali ["text"])
audio.output.voice Glas za sintezo marin, cedar, alloy, echo itd.
audio.input.turn_detection Zaznavanje konca govora server_vad s pragom 0.5
audio.input.format Vhodni zvočni format {"type": "audio/pcm", "rate": 24000}

Sistem dogodkov

Realtime API je v celoti usmerjen v dogodke. Vsako izmenjano sporočilo je objekt JSON s poljem type, ki določa njegovo naravo. Dogodki spadajo v dve kategoriji:

Dogodki odjemalca (ti → strežnik)

# Glavni dogodki, ki jih pošlješ
client_events = {
    "session.update":              "Spremeni konfiguracijo",
    "input_audio_buffer.append":   "Pošlji zvočni delček",
    "input_audio_buffer.commit":   "Potrdi zvočni medpomnilnik",
    "input_audio_buffer.clear":    "Počisti zvočni medpomnilnik",
    "conversation.item.create":    "Ročno dodaj sporočilo",
    "conversation.item.truncate":  "Okrajšaj odgovor",
    "conversation.item.delete":    "Izbriši sporočilo",
    "response.create":             "Sproži odgovor",
    "response.cancel":             "Prekliči trenutni odgovor",
}

Dogodki strežnika (strežnik → ti)

# Glavni dogodki, ki jih prejmeš
server_events = {
    "session.created":             "Seja inicializirana",
    "session.updated":             "Konfiguracija uporabljena",
    "input_audio_buffer.speech_started":  "Govor zaznan",
    "input_audio_buffer.speech_stopped":  "Tišina zaznana",
    "conversation.item.created":   "Novo sporočilo v zgodovini",
    "response.created":            "Generiranje začeto",
    "response.output_audio.delta":        "Zvočni delček odgovora",
    "response.output_audio_transcript.delta": "Delček prepisa",
    "response.done":               "Odgovor končan",
    "error":                       "Napaka",
}

Obravnava napak

Napake se oddajajo prek dogodka tipa error. Vedno jih moraš prestrezati:

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":
                # Napaka v konfiguraciji, popravi in poskusi znova
                pass
            elif error["type"] == "server_error":
                # Težava na strani OpenAI, ponovna povezava
                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}")

Ključne ugotovitve

  • Seja se samodejno ustvari ob vzpostavitvi povezave WebSocket in uniči ob prekinitvi
  • session.update konfigurira sejo po session.created; pred zanašanjem na novo konfiguracijo počakaj na session.updated
  • Za prepis vnosa v pogovorni seji uporabi gpt-transcribe; gpt-live-transcribe je rezerviran za seje za prepis
  • Protokol je izključno usmerjen v dogodke: vsako sporočilo ima type, ki določa njegovo obravnavo
  • Dogodki odjemalca poganjajo interakcijo; dogodki strežnika poročajo o rezultatih
  • Obravnava napak je ključna: vedno poslušaj dogodke error