A Realtime API WebSocket-architektúrája
Ezen az oldalon
Frissítve: 2026. november 2. – Hangmodellek. A tanfolyam több modellje elavult: a
tts-1,tts-1-hdés agpt-4o-mini-ttsmodellek 2027. január 6-án megszűnnek (helyettük agpt-realtime-2.1-minilép életbe, amelyet az OpenAI TTS-útmutatója szerint a/v1/audio/speechnem támogat: a beszédszintézis migrációja a Realtime API felé történik); agpt-realtime,gpt-4o-realtimeés a legacy hangmodellek 2027. január 20-án válnak használhatatlanná (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5); awhisper-1, agpt-4o-transcribeés a/v1/audio/translationsvégpontok pedig 2027. február 26-án szűnnek meg (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). A teljes duplex hangalapú kommunikációhoz a GPT-Live 1 már 2026. szeptember 10. óta elérhető az API-ban. Kiegészítés 2026. november 3.: szakasz az OpenAI három hangarchitektúrájáról (GPT-Live, Realtime API, feldolgozási lánc) és a transzport kiválasztásáról (WebRTC, WebSocket, SIP), a Voice agents, az Audio and voice és a Getting started with the Realtime API útmutatók alapján; maximális munkamenet-időtartam: 60 perc (Realtime conversations).
A Realtime API WebSocket-architektúrája
Az OpenAI Realtime API-ja alapvető paradigmaváltást jelent a nyelvi modellekkel való interakcióban. A hagyományos REST API-kkal ellentétben, amelyek kérés-válasz cikluson alapulnak, a Realtime API a WebSocket protokollt használja, hogy tartós, kétirányú kapcsolatot létesítsen az alkalmazásod és a modell között.
Ez az architektúra lehetővé teszi a valós idejű hangcserét: te küldöd a hangot, a modell feldolgozza azt, és alacsony késleltetéssel, hangban válaszol, kihagyva a közbenső átírási vagy szövegből-beszédbe (TTS) lépéseket. Ez a beszélgető hangalapú ügynökök egyik alapköve, és e tanfolyam szíve.
Három hangarchitektúra 2026-ban
Mielőtt WebSocket-kapcsolatot nyitnál, helyezd kontextusba a Realtime API-t az OpenAI egyéb megoldásaival. A Voice agents útmutató három megközelítést különböztet meg:
| Architektúra | Mire a legjobb | Miért válaszd ezt? |
|---|---|---|
| GPT-Live | Teljes duplex beszélgetések külön backenddel | A hangmodell hallgatás közben is beszél, és az érvelést valamint az eszközhasználatot egy általad választott backendre delegálja; így a meglévő szöveges ügynököd érintetlen marad |
| Realtime API | Beszéd, érvelés és eszközhasználat egyetlen munkamenetben | Egyetlen modell értelmezi a hangot, dönt a teendőkről, és kimondja a választ |
| Feldolgozási lánc | Minden lépés részletes szabályozása | Átírás, majd szöveges ügynök, majd beszédszintézis: lépésenként ellenőrizheted vagy átalakíthatod a szöveget, és minden komponenst függetlenül cserélhetsz |
Az új hangalapú beszélgető alkalmazásokhoz az OpenAI Audio and voice oldala most a GPT-Live használatát javasolja kezdésnek. A Realtime API akkor marad a helyes kiindulópont, ha az ügynöknek egyetlen munkamenetbe kell illeszkednie, támogatnia kell a felhasználói megszakítást, a gyors első hangválaszt, a természetes fordulóváltást és a közvetlen eszköz hívásokat. A feldolgozási lánc akkor működik a legjobban, ha minden lépésnek láthatónak kell maradnia: az átiratok megőrzése, szabályok érvényesítése a válasz előtt, vagy a hang kibocsátása csak a válasz validálása után.
Ez a tanfolyam a Realtime API-ra és a feldolgozási láncra fókuszál, amelyek komponenseit (átírás, beszédszintézis) a következő szakaszok tárgyalják.
WebRTC, WebSocket vagy SIP
A transzportválasztás attól függ, honnan származik a hang. A dokumentáció szerint: használj WebRTC-t böngészős hanghoz (a szervered által generált ephemeral client secrettel); WebSocket-et szerveroldali hangfolyamatokhoz; SIP-et telefonhívásokhoz. Egy szerveroldali vezérlőkapcsolat lehetővé teszi továbbá, hogy egy megbízott backend figyelje és irányítsa a média-munkamenetet. Ez a lecke a WebSocketet részletezi, mint az események megértésének legegyszerűbb módját; böngészőben azonban előnyben részesítsd a WebRTC-t. Egy Realtime munkamenet legfeljebb 60 percig tarthat.
WebSocket kontra REST: Miért ez a választás?
Egy hagyományos REST-architektúrában minden interakció teljes HTTP-kérést igényel: TCP-kapcsolat nyitása, TLS-tárgyalás, fejlécek küldése, várakozás a válaszra, majd a kapcsolat bontása. Valós idejű hang esetén ez a többletterhelés elfogadhatatlan.
| Szempont | REST (Responses API) | WebSocket (Realtime API) |
|---|---|---|
| Késleltetés | 200–500 ms kérésenként | < 50 ms a kapcsolat után |
| Irány | Csak Kliens → Szerver | Egyidejű kétirányú |
| Kapcsolat | Minden kéréshez új | Tartós (munkamenet) |
| Hang | Teljes fájl szükséges | Darabonkénti streamelés |
A WebSocket protokoll folyamatosan nyitva tart egy csatornát. Ha egyszer létrejött, a kliens és a szerver bármikor küldhet üzeneteket anélkül, hogy meg kellene várniuk a másik fél befejezését.
WebSocket-kapcsolat létesítése
Így hozhatsz létre kapcsolatot a Realtime API-val Pythonban:
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")
# Receive the welcome event
response = await ws.recv()
event = json.loads(response)
print(f"Type: {event['type']}")
# → "session.created"
# Keep the connection open
await asyncio.Future()
asyncio.run(connect_realtime())
A kapcsolati URL a modellt lekérdezési paraméterként tartalmazza. Mióta az API általános elérhetőséget (GA) ért el, csak a hitelesítési fejléc szükséges – a béta fázisból ismert OpenAI-Beta: realtime=v1 fejléc megszűnt.
Felület frissítve: 2026. augusztus 5. – A Realtime API fejlődik (modellek, eseménynevek, munkamenet formátum): ha bizonytalan vagy, mindig ellenőrizd a hivatalos dokumentációt.
Realtime alkalmazás-architektúra
Egy Realtime API-t használó alkalmazás rétegzett architektúrát követ:
Hangréteg (rögzítés/lejátszás)
Rögzíti a mikrofon bemenetét, lejátsza a hangválaszokat. Használja a PyAudio, sounddevice vagy a böngészőben a Web Audio API könyvtárakat.
WebSocket-réteg (transzport)
Kezeli a tartós kapcsolatot, kódolja/dekódolja a JSON eseményeket, és kezeli az újracsatlakozásokat.
Alkalmazásréteg (üzleti logika)
Orchesztrálja a beszélgetést, kezeli a kontextust, hívja az eszközöket és dolgozza fel az eredményeket.
Szerverréteg (opcionális proxy)
Éles környezetben egy köztes szerver védi az API-kulcsot, és szerveroldali üzleti logikát ad hozzá.
A proxy szerver szerepe
Fejlesztés során közvetlenül csatlakoztathatod az alkalmazásodat a Realtime API-hoz. Éles környezetben azonban egy proxy szerver elengedhetetlen a következőkhöz:
- Az API-kulcsod védelme – soha ne tedd ki klienoldalon
- Felhasználóid hitelesítése – ellenőrizd a tokeneket a munkamenet megnyitása előtt
- Költségek szabályozása – korlátozd a munkamenet időtartamát és a tokenfelhasználást
- Interakciók naplózása – hibakeresés és megfelelés céljából
# Egyszerűsített példa egy WebSocket proxyra FastAPI-val
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())
Főbb megállapítások
- Három hangarchitektúra az OpenAI-nál: GPT-Live (új beszélgető alkalmazásokhoz ajánlott), Realtime API (beszéd, érvelés és eszközök egy munkamenetben), valamint az átírás → ügynök → szintézis lánc
- WebRTC böngészős hanghoz, WebSocket szerveroldali folyamatokhoz, SIP telefonáláshoz; a munkamenetek legfeljebb 60 percig tarthatnak
- A Realtime API WebSocketet használ az alacsony késleltetésű, kétirányú kommunikációhoz
- A kapcsolat tartós: egyetlen megnyitás az egész beszélgetési munkamenet alatt
- A rétegzett architektúra szétválasztja a hangot, a transzportot, az üzleti logikát és a szerver proxyt
- Éles környezetben a proxy szerver elengedhetetlen a biztonság és a költségszabályozás érdekében
- A protokoll eseményvezérelt: minden üzenet egy JSON objektum, amely tartalmaz egy
typemezőt