Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Relácie, udalosti a životný cyklus

Lekcia 2 z 18 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Relácie, udalosti a životný cyklus
  2. Životný cyklus relácie
  3. Konfigurácia relácie
  4. Systém udalostí
  5. Spracovanie chýb
  6. Kľúčové poznatky

Aktualizované 2. novembra 2026 — Zvukové modely. Niekoľko modelov v tomto kurze je zastaraných: tts-1, tts-1-hd a gpt-4o-mini-tts prestanú fungovať 6. januára 2027 (náhrada: gpt-realtime-2.1-mini, ktorý podľa sprievodcu OpenAI TTS nie je podporovaný cez /v1/audio/speech: migrácia syntézy reči prechádza na Realtime API); gpt-realtime, gpt-4o-realtime a staršie zvukové modely 20. januára 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe a /v1/audio/translations 26. februára 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pre plnohodnotnú duplexnú hlasovú komunikáciu je GPT-Live 1 dostupné v API od 10. septembra 2026.

Opravené 3. novembra 2026. Prepis vstupného zvuku používal gpt-live-transcribe, ktorý funguje iba v relácii typu transcription a nepodporuje ani server_vad, ani semantic_vad. V konverzačnej relácii, ako je táto, kde VAD validuje každý obrat, dokumentácia špecifikuje použitie gpt-transcribe, ktorý prepisuje validované obraty a využíva predchádzajúce obraty ako kontext. Zdroje: Prepis v reálnom čase · GPT-Transcribe · GPT-Live-Transcribe.

Relácie, udalosti a životný cyklus

Každé pripojenie WebSocket k Realtime API vytvára reláciu. Táto relácia je základnou jednotkou správy: zapuzdruje konfiguráciu modelu, históriu konverzácie, dostupné nástroje a aktuálny stav interakcie. Pochopenie jej životného cyklu je nevyhnutné pre budovanie robustných hlasových agentov.

Životný cyklus relácie

Akonáhle sa nadviaže pripojenie WebSocket, server vyšle udalosť session.created. Relácia prechádza niekoľkými fázami:

1

Pripojenie → session.created

Server potvrdí reláciu jedinečným ID a predvolenou konfiguráciou.

2

Konfigurácia → session.update

Odošleš session.update na definovanie inštrukcií, hlasu, nástrojov a modalít.

3

Aktívna konverzácia

Výmena zvukových a textových udalostí medzi klientom a serverom.

4

Ukončenie → odpojenie WebSocket

Relácia sa zničí po uzavretí pripojenia. Na serveri sa neuchováva žiadny stav.

Konfigurácia relácie

Po udalosti session.created odošli udalosť session.update na nastavenie správania modelu. Prepis toho, čo používateľ hovorí (audio.input.transcription), je voliteľný: bez neho dostaneš hlas, ale nie text. Parameter languages špecifikuje očakávané jazyky a zlepšuje rozpoznávanie:

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čkaj na session.created
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Relácia vytvorená: {session_id}")

        # Nakonfiguruj reláciu
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "Si hlasový asistent hovoriaci po francúzsky. "
                                "Odpovedaj stručne a prirodzene.",
                "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čkaj na potvrdenie (najprv môžu prísť iné udalosti)
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "session.updated":
                print("Relácia aktualizovaná")
                break
            if event["type"] == "error":
                raise RuntimeError(event["error"]["message"])

Kľúčové parametre relácie

Parameter Popis Odporúčaná hodnota
output_modalities Výstupné modality ["audio"] (alebo ["text"])
audio.output.voice Hlas syntézy marin, cedar, alloy, echo atď.
audio.input.turn_detection Detekcia konca reči server_vad s prahom 0.5
audio.input.format Formát prichádzajúceho zvuku {"type": "audio/pcm", "rate": 24000}

Systém udalostí

Realtime API je úplne riadené udalosťami. Každá vymenená správa je objekt JSON s poľom type, ktoré určuje jej povahu. Udalosti spadajú do dvoch kategórií:

Udalosti klienta (ty → server)

# Hlavné udalosti, ktoré odosielaš
client_events = {
    "session.update":              "Úprava konfigurácie",
    "input_audio_buffer.append":   "Odoslanie časti zvuku",
    "input_audio_buffer.commit":   "Potvrdenie zvukovej vyrovnávacej pamäte",
    "input_audio_buffer.clear":    "Vyčistenie zvukovej vyrovnávacej pamäte",
    "conversation.item.create":    "Manuálne pridanie správy",
    "conversation.item.truncate":  "Skrátenie odpovede",
    "conversation.item.delete":    "Vymazanie správy",
    "response.create":             "Spustenie odpovede",
    "response.cancel":             "Zrušenie aktuálnej odpovede",
}

Udalosti servera (server → ty)

# Hlavné udalosti, ktoré dostávaš
server_events = {
    "session.created":             "Relácia inicializovaná",
    "session.updated":             "Konfigurácia aplikovaná",
    "input_audio_buffer.speech_started":  "Zistená reč",
    "input_audio_buffer.speech_stopped":  "Zistené ticho",
    "conversation.item.created":   "Nová správa v histórii",
    "response.created":            "Generovanie začalo",
    "response.output_audio.delta":        "Časť zvuku odpovede",
    "response.output_audio_transcript.delta": "Časť prepisu",
    "response.done":               "Odpoveď dokončená",
    "error":                       "Chyba",
}

Spracovanie chýb

Chyby sa vysielať prostredníctvom udalosti typu error. Vždy ich musíš zachytiť:

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"Chyba [{error['type']}]: {error['message']}")

            if error["type"] == "invalid_request_error":
                # Chyba konfigurácie, oprav a skús znova
                pass
            elif error["type"] == "server_error":
                # Problém na strane OpenAI, znovu sa pripoj
                pass

        elif event_type == "session.updated":
            print("Konfigurácia úspešne aplikovaná")

        elif event_type == "response.done":
            usage = event["response"].get("usage", {})
            print(f"Použité tokeny: {usage}")

Kľúčové poznatky

  • Relácia sa vytvorí automaticky pri pripojení WebSocket a zničí sa pri odpojení
  • session.update konfiguruje reláciu po session.created; pred použitím novej konfigurácie počkaj na session.updated
  • Na prepis vstupu v konverzačnej relácii použij gpt-transcribe; gpt-live-transcribe je vyhradený pre relácie typu transcription
  • Protokol je čisto riadený udalosťami: každá správa má type, ktorý určuje jej spracovanie
  • Udalosti klienta riadia interakciu; udalosti servera hlásia výsledky
  • Spracovanie chýb je kritické: vždy počúvaj na udalosti error