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

Architektura WebSocket interfejsu API Realtime

Lekcja 1 z 18 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Architektura WebSocket interfejsu API Realtime
  2. Trzy architektury głosowe w 2026 roku
  3. WebRTC, WebSocket czy SIP
  4. WebSocket kontra REST: dlaczego ten wybór?
  5. Nawiązywanie połączenia WebSocket
  6. Architektura aplikacji Realtime
  7. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 — Modele audio. Kilka modeli w tym kursie zostało wycofanych: tts-1, tts-1-hd oraz gpt-4o-mini-tts przestaną działać 6 stycznia 2027 (zamiennik: gpt-realtime-2.1-mini, który zgodnie z przewodnikiem OpenAI TTS nie jest obsługiwany przez /v1/audio/speech: migracja syntezy mowy przenosi się do interfejsu API Realtime); gpt-realtime, gpt-4o-realtime oraz starsze modele audio przestaną działać 20 stycznia 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe oraz /v1/audio/translations przestaną działać 26 lutego 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). W przypadku rozmów głosowych w trybie pełnodupleksowym, GPT-Live 1 jest dostępny w API od 10 września 2026. Dodatkowa uwaga z 3 listopada 2026: sekcja dotycząca trzech architektur głosowych OpenAI (GPT-Live, Realtime API, łańcuch przetwarzania) oraz wyboru transportu (WebRTC, WebSocket, SIP), oparta na przewodnikach Voice agents, Audio and voice oraz Getting started with the Realtime API; maksymalny czas trwania sesji: 60 minut (Realtime conversations).

Architektura WebSocket interfejsu API Realtime

Interfejs API Realtime od OpenAI stanowi fundamentalną zmianę paradygmatu w sposobie interakcji z modelami językowymi. W przeciwieństwie do tradycyjnych interfejsów REST działających w cyklu żądanie-odpowiedź, API Realtime wykorzystuje protokół WebSocket do nawiązania stałego, dwukierunkowego połączenia między Twoją aplikacją a modelem.

Ta architektura umożliwia wymianę dźwięku w czasie rzeczywistym: wysyłasz audio, model je przetwarza i odpowiada głosem z niskim opóźnieniem, pomijając pośrednie etapy transkrypcji czy syntezy mowy z tekstu. Jest to jeden z kluczowych elementów budujących konwersacyjnych agentów głosowych i sedno tego kursu.

Trzy architektury głosowe w 2026 roku

Zanim otworzysz połączenie WebSocket, umieść API Realtime w kontekście innych rozwiązań OpenAI. Przewodnik Voice agents wyróżnia trzy podejścia:

ArchitekturaNajlepsze zastosowanieDlaczego warto wybrać
GPT-LiveRozmowy pełnodupleksowe z oddzielnym backendemModel głosowy słucha podczas mówienia i deleguje rozumowanie oraz używanie narzędzi do wybranego przez Ciebie backendu; pozwala zachować istniejącego agenta tekstowego
Realtime APIMowa, rozumowanie i narzędzia w jednej sesjiPojedynczy model interpretuje audio, decyduje co zrobić i wypowiada odpowiedź
Łańcuch przetwarzaniaSzczegółowa kontrola nad każdym krokiemTranskrypcja, następnie agent tekstowy, potem synteza mowy: możesz inspekcjonować lub przekształcać tekst między krokami i niezależnie wymieniać każdy komponent

W przypadku nowych aplikacji do rozmów głosowych, strona Audio and voice od OpenAI rekomenduje obecnie rozpoczęcie pracy z GPT-Live. API Realtime pozostaje właściwym punktem startowym, gdy agent musi mieścić się w jednej sesji, obsługując przerwanie przez użytkownika, szybką pierwszą odpowiedź audio, naturalne przekazywanie głosu i bezpośrednie wywołania narzędzi. Łańcuch przetwarzania sprawdza się najlepiej, gdy każdy krok musi pozostać widoczny: zachowanie transkryptów, wymuszanie reguł przed odpowiedzią agenta lub emitowanie głosu dopiero po walidacji odpowiedzi.

Ten kurs skupia się na API Realtime oraz łańcuchu przetwarzania, których komponenty (transkrypcja, synteza mowy) są omówione w kolejnych sekcjach.

WebRTC, WebSocket czy SIP

Wybór transportu zależy od źródła dźwięku. Zgodnie z dokumentacją: użyj WebRTC dla dźwięku z przeglądarki, z efemerycznym sekretem klienta generowanym przez Twój serwer; WebSocket dla serwerowych potoków audio; SIP dla połączeń telefonicznych. Połączenie kontrolne po stronie serwera pozwala również zaufanemu backendowi obserwować i sterować sesją multimedialną. Ta lekcja szczegółowo opisuje WebSocket, jako najprostszy sposób na zrozumienie wymienianych zdarzeń; w przeglądarce preferuj WebRTC. Sesja Realtime trwa maksymalnie 60 minut.

WebSocket kontra REST: dlaczego ten wybór?

W tradycyjnej architekturze REST każda interakcja wymaga kompletnego żądania HTTP: otwarcia połączenia TCP, negocjacji TLS, wysłania nagłówków, oczekiwania na odpowiedź i zamknięcia połączenia. W przypadku dźwięku w czasie rzeczywistym ten narzut jest nie do przyjęcia.

Kryterium REST (Responses API) WebSocket (Realtime API)
Opóźnienie 200–500 ms na żądanie < 50 ms po nawiązaniu połączenia
Kierunek Tylko klient → serwer Jednoczesny dwukierunkowy
Połączenie Nowe dla każdego żądania Stałe (sesja)
Audio Wymagany pełny plik Strumieniowanie fragment po fragmencie

Protokół WebSocket utrzymuje kanał stale otwarty. Po nawiązaniu połączenia klient i serwer mogą wysyłać wiadomości w dowolnym momencie, nie czekając na zakończenie działania drugiej strony.

Nawiązywanie połączenia WebSocket

Oto jak nawiązać połączenie z API Realtime w Pythonie:

import asyncio
import websockets
import json

OPENAI_API_KEY = "sk-..."
URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"

async def connect_realtime():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}"
    }

    async with websockets.connect(URL, additional_headers=headers) as ws:
        print("Connected to Realtime API")

        # Odbierz zdarzenie powitalne
        response = await ws.recv()
        event = json.loads(response)
        print(f"Type: {event['type']}")
        # → "session.created"

        # Utrzymaj połączenie otwarte
        await asyncio.Future()

asyncio.run(connect_realtime())

Adres URL połączenia zawiera model jako parametr zapytania. Od momentu udostępnienia API do powszechnego użytku, wymagany jest tylko nagłówek uwierzytelniający – nagłówek OpenAI-Beta: realtime=v1 z fazy beta został usunięty.

Interfejs odnotowany 5 sierpnia 2026 — API Realtime ewoluuje (modele, nazwy zdarzeń, format sesji): w razie wątpliwości sprawdź oficjalną dokumentację.

Architektura aplikacji Realtime

Aplikacja korzystająca z API Realtime遵循uje architekturę warstwową:

1

Warstwa audio (przechwytywanie/odtwarzanie)

Przechwytuje mikrofon, odtwarza odpowiedzi audio. Wykorzystuje PyAudio, sounddevice lub Web Audio API w przeglądarce.

2

Warstwa WebSocket (transport)

Zarządza stałym połączeniem, koduje/dekoduje zdarzenia JSON, obsługuje ponowne łączenie.

3

Warstwa aplikacji (logika biznesowa)

Orkiestruje rozmowę, zarządza kontekstem, wywołuje narzędzia, przetwarza wyniki.

4

Warstwa serwera (opcjonalny serwer proxy)

W środowisku produkcyjnym serwer pośredni chroni klucz API i dodaje serwerową logikę biznesową.

Rola serwera proxy

Podczas rozwoju możesz połączyć swoją aplikację bezpośrednio z API Realtime. W środowisku produkcyjnym serwer proxy jest niezbędny, aby:

  • Chronić Twój klucz API — nigdy nie udostępniaj go po stronie klienta
  • Uwierzytelniać użytkowników — weryfikuj tokeny przed otwarciem sesji
  • Kontrolować koszty — ograniczaj czas trwania sesji i zużycie tokenów
  • Rejestrować interakcje — do celów debugowania i zgodności
# Uproszczony przykład proxy WebSocket z FastAPI
from fastapi import FastAPI, WebSocket
import websockets

app = FastAPI()

@app.websocket("/ws/realtime")
async def proxy_realtime(client_ws: WebSocket):
    await client_ws.accept()

    headers = {"Authorization": f"Bearer {OPENAI_API_KEY}"}

    async with websockets.connect(URL, additional_headers=headers) as openai_ws:
        async def forward_to_openai():
            async for message in client_ws.iter_text():
                await openai_ws.send(message)

        async def forward_to_client():
            async for message in openai_ws:
                await client_ws.send_text(message)

        await asyncio.gather(forward_to_openai(), forward_to_client())

Kluczowe wnioski

  • Trzy architektury głosowe w OpenAI: GPT-Live (rekomendowane dla nowych aplikacji konwersacyjnych), Realtime API (mowa, rozumowanie i narzędzia w jednej sesji) oraz łańcuch transkrypcja → agent → synteza
  • WebRTC dla audio z przeglądarki, WebSocket dla potoków serwerowych, SIP dla telefonii; sesje trwają maksymalnie 60 minut
  • API Realtime wykorzystuje WebSocket do niskoopóźnieniowej komunikacji dwukierunkowej
  • Połączenie jest stałe: jedno otwarcie na całą sesję konwersacyjną
  • Architektura warstwowa oddziela audio, transport, logikę biznesową i serwer proxy
  • W środowisku produkcyjnym serwer proxy jest niezbędny dla bezpieczeństwa i kontroli kosztów
  • Protokół jest sterowany zdarzeniami: każda wiadomość to obiekt JSON z polem type