Przejdź do głównej treści
Polski— Wybierz język
Menu

Sesje, zdarzenia i cykl życia

Lekcja 2 z 18 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Sesje, zdarzenia i cykl życia
  2. Cykl życia sesji
  3. Konfigurowanie sesji
  4. System zdarzeń
  5. Obsługa błędów
  6. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie jest przestarzałych: tts-1, tts-1-hd i gpt-4o-mini-tts przestaną działać 6 stycznia 2027 (zastąpienie: gpt-realtime-2.1-mini, który zgodnie z przewodnikiem OpenAI TTS nie jest obsługiwany przez /v1/audio/speech: migracja syntezy mowy przechodzi do Realtime API); gpt-realtime, gpt-4o-realtime i starsze modele audio 20 stycznia 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe i /v1/audio/translations 26 lutego 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). W przypadku głosu pełnodupleksowego, GPT-Live 1 jest dostępny w API od 10 września 2026.

Skorygowano 3 listopada 2026. Transkrypcja wejścia używała gpt-live-transcribe, który działa tylko w sesji transkrypcji i nie obsługuje ani server_vad, ani semantic_vad. W sesji konwersacyjnej, takiej jak ta, gdzie VAD waliduje każdą turę, dokumentacja wskazuje gpt-transcribe, który transkrybuje zwalidowane tury i wykorzystuje poprzednie tury jako kontekst. Źródła: Transkrypcja w czasie rzeczywistym · GPT-Transcribe · GPT-Live-Transcribe.

Sesje, zdarzenia i cykl życia

Każde połączenie WebSocket z Realtime API tworzy sesję. Sesja jest podstawową jednostką zarządzania: inkapsuluje konfigurację modelu, historię rozmowy, dostępne narzędzia oraz bieżący stan interakcji. Zrozumienie jej cyklu życia jest kluczowe dla budowania niezawodnych agentów głosowych.

Cykl życia sesji

Gdy tylko połączenie WebSocket zostanie nawiązane, serwer emituje zdarzenie session.created. Sesja przechodzi przez kilka faz:

1

Połączenie → session.created

Serwer potwierdza sesję, przypisując unikalny identyfikator i domyślną konfigurację.

2

Konfiguracja → session.update

Wysyłasz session.update, aby zdefiniować instrukcje, głos, narzędzia i modalności.

3

Aktywna rozmowa

Wymiana zdarzeń audio i tekstowych między klientem a serwerem.

4

Zamknięcie → rozłączenie WebSocket

Sesja jest niszczona po zamknięciu połączenia. Żaden stan nie jest przechowywany na serwerze.

Konfigurowanie sesji

Po otrzymaniu session.created wyślij zdarzenie session.update, aby skonfigurować zachowanie modelu. Transkrypcja wypowiedzi użytkownika (audio.input.transcription) jest opcjonalna: bez niej otrzymasz głos, ale nie tekst. Parametr languages określa oczekiwane języki i poprawia rozpoznawanie:

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

        # Skonfiguruj sesję
        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": []
            }
        }))

        # Poczekaj na potwierdzenie (inne zdarzenia mogą nadejść wcześniej)
        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"])

Kluczowe parametry sesji

Parametr Opis Zalecana wartość
output_modalities Modalności wyjściowe ["audio"] (lub ["text"])
audio.output.voice Głos syntezy marin, cedar, alloy, echo itd.
audio.input.turn_detection Wykrywanie końca wypowiedzi server_vad z progiem 0.5
audio.input.format Format przychodzącego audio {"type": "audio/pcm", "rate": 24000}

System zdarzeń

Realtime API działa w pełni w oparciu o zdarzenia. Każda wymieniana wiadomość to obiekt JSON z polem type, które określa jej charakter. Zdarzenia dzielą się na dwie kategorie:

Zdarzenia klienta (ty → serwer)

# Główne zdarzenia wysyłane przez Ciebie
client_events = {
    "session.update":              "Modyfikacja konfiguracji",
    "input_audio_buffer.append":   "Wysłanie fragmentu audio",
    "input_audio_buffer.commit":   "Zatwierdzenie bufora audio",
    "input_audio_buffer.clear":    "Wyczyszczenie bufora audio",
    "conversation.item.create":    "Ręczne dodanie wiadomości",
    "conversation.item.truncate":  "Skrócenie odpowiedzi",
    "conversation.item.delete":    "Usunięcie wiadomości",
    "response.create":             "Uruchomienie generowania odpowiedzi",
    "response.cancel":             "Anulowanie bieżącej odpowiedzi",
}

Zdarzenia serwera (serwer → ty)

# Główne zdarzenia otrzymywane przez Ciebie
server_events = {
    "session.created":             "Inicjalizacja sesji",
    "session.updated":             "Zastosowanie konfiguracji",
    "input_audio_buffer.speech_started":  "Wykrycie mowy",
    "input_audio_buffer.speech_stopped":  "Wykrycie ciszy",
    "conversation.item.created":   "Nowa wiadomość w historii",
    "response.created":            "Rozpoczęcie generowania",
    "response.output_audio.delta":        "Fragment audio odpowiedzi",
    "response.output_audio_transcript.delta": "Fragment transkrypcji",
    "response.done":               "Zakończenie odpowiedzi",
    "error":                       "Błąd",
}

Obsługa błędów

Błędy są emitowane jako zdarzenia typu error. Musisz je zawsze перехwytywać:

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":
                # Błąd konfiguracji, napraw i spróbuj ponownie
                pass
            elif error["type"] == "server_error":
                # Problem po stronie OpenAI, połącz ponownie
                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}")

Kluczowe wnioski

  • Sesja jest tworzone automatycznie po nawiązaniu połączenia WebSocket i niszczona po rozłączeniu
  • session.update konfiguruje sesję po session.created; poczekaj na session.updated, zanim zaczniesz polegać na nowej konfiguracji
  • Aby transkrybować dane wejściowe w sesji konwersacyjnej, użyj gpt-transcribe; gpt-live-transcribe jest zarezerwowany dla sesji transkrypcji
  • Protokół jest czysto zdarzeniowy: każda wiadomość posiada type, który determinuje sposób jej obsługi
  • Zdarzenia klienta sterują interakcją; zdarzenia serwera raportują wyniki
  • Obsługa błędów jest kluczowa: zawsze nasłuchuj zdarzeń error