Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Relace, události a životní cyklus

Lekce 2 z 18 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Relace, události a životní cyklus
  2. Životní cyklus relace
  3. Konfigurace relace
  4. Systém událostí
  5. Zpracování chyb
  6. Klíčové poznatky

Aktualizováno 2. listopadu 2026 — Zvukové modely. Několik modelů v tomto kurzu je zastaralých: tts-1, tts-1-hd a gpt-4o-mini-tts přestanou fungovat 6. ledna 2027 (náhrada: gpt-realtime-2.1-mini, který podle průvodce OpenAI TTS není podporován endpointem /v1/audio/speech: migrace syntézy řeči přechází na Realtime API); gpt-realtime, gpt-4o-realtime a starší zvukové modely skončí 20. ledna 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe a /v1/audio/translations skončí 26. února 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pro plně duplexní hlas je GPT-Live 1 dostupné v API od 10. září 2026.

Opraveno 3. listopadu 2026. Přepis vstupu používal gpt-live-transcribe, který funguje pouze v relaci typu transcription a nepodporuje ani server_vad, ani semantic_vad. V konverzační relaci, jako je tato, kde VAD validuje každý obrat, dokumentace specifikuje použití gpt-transcribe, který přepisuje validované obraty a využívá předchozí obraty jako kontext. Zdroje: Přepis v reálném čase · GPT-Transcribe · GPT-Live-Transcribe.

Relace, události a životní cyklus

Každé připojení WebSocket k Realtime API vytvoří relaci. Tato relace je základní jednotkou správy: zapouzdřuje konfiguraci modelu, historii konverzace, dostupné nástroje a aktuální stav interakce. Porozumění jejímu životnímu cyklu je zásadní pro budování spolehlivých hlasových agentů.

Životní cyklus relace

Jakmile je navázáno připojení WebSocket, server vyšle událost session.created. Relace prochází několika fázemi:

1

Připojení → session.created

Server potvrdí relaci jedinečným ID a výchozí konfigurací.

2

Konfigurace → session.update

Odešleš session.update pro definování pokynů, hlasu, nástrojů a modalit.

3

Aktivní konverzace

Výměna zvukových a textových událostí mezi klientem a serverem.

4

Ukončení → odpojení WebSocket

Relace je zničena při uzavření připojení. Na serveru nezůstává žádný stav.

Konfigurace relace

Po události session.created odešli událost session.update pro nastavení chování modelu. Přepis toho, co uživatel říká (audio.input.transcription), je volitelný: bez něj obdržíš hlas, ale ne text. Parametr languages určuje očekávané jazyky a zlepšuje rozpoznávání:

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čkej na session.created
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Relace vytvořena: {session_id}")

        # Nakonfiguruj relaci
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "Jsi hlasový asistent mluvící francouzsky. "
                                "Odpovídej stručně a přirozeně.",
                "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čkej na potvrzení (nejdříve mohou přijít jiné události)
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "session.updated":
                print("Relace aktualizována")
                break
            if event["type"] == "error":
                raise RuntimeError(event["error"]["message"])

Klíčové parametry relace

Parametr Popis Doporučená hodnota
output_modalities Výstupní modality ["audio"] (nebo ["text"])
audio.output.voice Hlas syntézy marin, cedar, alloy, echo atd.
audio.input.turn_detection Detekce konce řeči server_vad s prahem 0.5
audio.input.format Formát příchozího zvuku {"type": "audio/pcm", "rate": 24000}

Systém událostí

Realtime API je zcela řízeno událostmi. Každá vyměněná zpráva je objekt JSON s polem type, které určuje její povahu. Události spadají do dvou kategorií:

Události klienta (ty → server)

# Hlavní události, které odesíláš
client_events = {
    "session.update":              "Úprava konfigurace",
    "input_audio_buffer.append":   "Odeslání části zvuku",
    "input_audio_buffer.commit":   "Potvrzení zvukové vyrovnávací paměti",
    "input_audio_buffer.clear":    "Vyčištění zvukové vyrovnávací paměti",
    "conversation.item.create":    "Ruční přidání zprávy",
    "conversation.item.truncate":  "Zkrácení odpovědi",
    "conversation.item.delete":    "Smazání zprávy",
    "response.create":             "Spuštění odpovědi",
    "response.cancel":             "Zrušení aktuální odpovědi",
}

Události serveru (server → ty)

# Hlavní události, které přijímáš
server_events = {
    "session.created":             "Relace inicializována",
    "session.updated":             "Konfigurace aplikována",
    "input_audio_buffer.speech_started":  "Detekována řeč",
    "input_audio_buffer.speech_stopped":  "Detekováno ticho",
    "conversation.item.created":   "Nová zpráva v historii",
    "response.created":            "Generování zahájeno",
    "response.output_audio.delta":        "Část odpovědi ve zvuku",
    "response.output_audio_transcript.delta": "Část přepisu",
    "response.done":               "Odpověď dokončena",
    "error":                       "Chyba",
}

Zpracování chyb

Chyby jsou vysílány prostřednictvím události typu error. Vždy je musíš zachytit:

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 konfigurace, oprav a zkus znovu
                pass
            elif error["type"] == "server_error":
                # Problém na straně OpenAI, znovu se připoj
                pass

        elif event_type == "session.updated":
            print("Konfigurace úspěšně aplikována")

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

Klíčové poznatky

  • Relace se vytvoří automaticky při připojení WebSocket a zničí se při odpojení.
  • session.update konfiguruje relaci po session.created; před použitím nové konfigurace počkej na session.updated.
  • Pro přepis vstupu v konverzační relaci použij gpt-transcribe; gpt-live-transcribe je vyhrazen pro relace typu transcription.
  • Protokol je čistě event-driven: každá zpráva má type, který určuje její zpracování.
  • Události klienta řídí interakci; události serveru hlásí výsledky.
  • Zpracování chyb je kritické: vždy naslouchej událostem error.