Arhitektura WebSocket v API-ju Realtime
Na tej strani
Posodobljeno 2. novembra 2026 — Zvočni modeli. Več modelov v tem tečaju je zastarelih:
tts-1,tts-1-hdingpt-4o-mini-ttsprenehajo delovati 6. januarja 2027 (zamenjava:gpt-realtime-2.1-mini, ki ga vodnik za OpenAI TTS označuje kot nepodprtega z/v1/audio/speech: selitev sinteze govora prehaja na API Realtime);gpt-realtime,gpt-4o-realtimein stari zvočni modeli 20. januarja 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribein/v1/audio/translations26. februarja 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Za polnodupleksni glas je GPT-Live 1 na voljo v API-ju od 10. septembra 2026. Dodatek z dne 3. novembra 2026: razdelek o treh glasovnih arhitekturah OpenAI (GPT-Live, API Realtime, veriga obdelave) in izbiri prenosa (WebRTC, WebSocket, SIP), ki temelji na vodnikih Voice agents, Audio and voice in Getting started with the Realtime API; največje trajanje seje: 60 minut (Realtime conversations).
Arhitektura WebSocket v API-ju Realtime
API Realtime podjetja OpenAI predstavlja temeljno spremembo paradigme v načinu interakcije z jezikovnimi modeli. Za razliko od tradicionalnih REST API-jev, ki delujejo po ciklu zahteva-odgovor, API Realtime uporablja protokol WebSocket za vzpostavitev stalne, dvosmerne povezave med tvojo aplikacijo in modelom.
Ta arhitektura omogoča izmenjavo zvoka v realnem času: pošlješ zvok, model ga obdela in glasovno odgovori z nizko zakasnitvijo, pri čemer preskoči vmesne korake prepisa ali pretvorbe besedila v govor. To je eden temeljnih gradnikov za pogovorne glasovne agente in srce tega tečaja.
Tri glasovne arhitekture leta 2026
Preden odpreš povezavo WebSocket, umesti API Realtime v kontekst ob drugih rešitvah podjetja OpenAI. Vodnik Voice agents razlikuje tri pristope:
| Arhitektura | Najboljše za | Zakaj izbrati |
|---|---|---|
| GPT-Live | Polnodupleksne pogovore z ločenim zaledjem | Glasovni model posluša med govorjenjem in delegira sklepanje ter uporabo orodij zaledju po tvoji izbiri; ohrani tvojega obstoječega besedilnega agenta nedotaknjenega |
| API Realtime | Govor, sklepanje in orodja v eni seji | En sam model interpretira zvok, se odloči, kaj storiti, in izgovori odgovor |
| Veriga obdelave | Granularen nadzor nad vsakim korakom | Prepis, nato besedilni agent, nato sinteza govora: med koraki pregleduješ ali preoblikuješ besedilo in vsako komponento neodvisno zamenjaš |
Za nove aplikacije za glasovne pogovore stran Audio and voice podjetja OpenAI zdaj priporoča začetek z GPT-Live. API Realtime ostaja prava izhodiščna točka, ko se mora agent prilegati v eno samo sejo, ki podpira uporabnikovo prekinjanje, hiter prvi zvočni odziv, naravno izmenjavo besede in neposredne klice orodij. Veriga obdelave najbolje deluje, ko mora ostati vsak korak viden: ohranjanje prepisov, uveljavljanje pravil pred odgovorom agenta ali oddajanje glasu šele po potrditvi odgovora.
Ta tečaj se osredotoča na API Realtime in verigo obdelave, katerih komponente (prepis, sinteza govora) so obravnavane v naslednjih razdelkih.
WebRTC, WebSocket ali SIP
Tvoja izbira prenosa je odvisna od izvora zvoka. Glede na dokumentacijo: uporabi WebRTC za zvok v brskalniku z enkratnim skrivnim ključem odjemalca, ki ga ustvari tvoje strežniško okolje; WebSocket za zvočne cevovode na strani strežnika; SIP za telefonske klice. Nadzorna povezava na strani strežnika prav tako omogoča zaupanemu zaledju opazovanje in usmerjanje medijske seje. Ta lekcija podrobneje obravnava WebSocket, ki je najpreprostejši način za razumevanje izmenjanih dogodkov; v brskalniku daj prednost WebRTC. Seja Realtime traja največ 60 minut.
WebSocket proti REST: zakaj ta izbira?
V tradicionalni arhitekturi REST vsaka interakcija zahteva popoln zahtevek HTTP: vzpostavitev povezave TCP, pogajanje TLS, pošiljanje glav, čakanje na odgovor in zaprtje povezave. Za zvok v realnem času so ti stroški prepovedljivi.
| Merilo | REST (API Responses) | WebSocket (API Realtime) |
|---|---|---|
| Zakasnitev | 200–500 ms na zahtevo | < 50 ms po vzpostavitvi povezave |
| Smer | Samo odjemalec → strežnik | Sočasno dvosmerno |
| Povezava | Nova za vsak zahtevek | Stalna (seja) |
| Zvok | Zahteva celotno datoteko | Pretakanje kos za kosom |
Protokol WebSocket nenehno ohranja kanal odprt. Ko je vzpostavljen, lahko odjemalec in strežnik kadar koli pošljeta sporočila, ne da bi čakala, da drugi konča.
Vzpostavitev povezave WebSocket
Tako vzpostaviš povezavo z API-jem Realtime v Pythonu:
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())
URL povezave vključuje model kot parameter poizvedbe. Od splošne razpoložljivosti API-ja je zahtevna samo glava za avtentikacijo – glava OpenAI-Beta: realtime=v1 iz beta faze je izginila.
Vmesnik zaznamovan 5. avgusta 2026 — API Realtime se razvija (modeli, imena dogodkov, format seje): v dvomih preveri uradno dokumentacijo.
Arhitektura aplikacije Realtime
Aplikacija, ki uporablja API Realtime, sledi slojni arhitekturi:
Zvočni sloj (zajem/predvajanje)
Zajame mikrofon, predvaja zvočne odgovore. Uporablja PyAudio, sounddevice ali Web Audio API v brskalniku.
Sloj WebSocket (prenos)
Upravlja stalno povezavo, kodira/dekodira dogodke JSON in obravnava ponovne povezave.
Aplikacijski sloj (poslovna logika)
Orkestrira pogovor, upravlja kontekst, kliče orodja in obdeluje rezultate.
Strežniški sloj (izbirni posrednik)
V proizvodnem okolju vmesni strežnik ščiti ključ API in dodaja poslovno logiko na strani strežnika.
Vloga posredniškega strežnika
Med razvojem se lahko tvoja aplikacija poveže neposredno z API-jem Realtime. V proizvodnem okolju je posredniški strežnik nujen za:
- Zaščito tvojega ključa API – nikoli ga ne izpostavljaj na strani odjemalca
- Avtentikacijo tvojih uporabnikov – preveri žetone pred odprtjem seje
- Nadzor stroškov – omeji trajanje seje in porabo žetonov
- Beleženje interakcij – za odpravljanje napak in skladnost
# Simplified example of a WebSocket proxy with 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())
Ključne ugotovitve
- Tri glasovne arhitekture pri OpenAI: GPT-Live (priporočljivo za nove pogovorne aplikacije), API Realtime (govor, sklepanje in orodja v eni seji) ter veriga prepis → agent → sinteza
- WebRTC za zvok v brskalniku, WebSocket za strežniške cevovode, SIP za telefonijo; seje trajajo največ 60 minut
- API Realtime uporablja WebSocket za dvosmerno komunikacijo z nizko zakasnitvijo
- Povezava je stalna: eno odprtje za celotno pogovorno sejo
- Slojna arhitektura ločuje zvok, prenos, poslovno logiko in strežniški posrednik
- V proizvodnem okolju je posredniški strežnik nujen za varnost in nadzor stroškov
- Protokol temelji na dogodkih: vsako sporočilo je objekt JSON s poljem
type