WebSocketi arhitektuur ja reaalaja API
Sellel lehel
Uuendatud 2. novembril 2026 – helimudelid. Selles kursuses on mitu mudelit aegunud:
tts-1,tts-1-hdjagpt-4o-mini-ttslõpetavad töö 6. jaanuaril 2027 (asendaja:gpt-realtime-2.1-mini, mida OpenAI TTS-i juhend kirjeldab kui mittetoetatud lõpppunkti/v1/audio/speechpoolt: kõnesünteesi migratsioon viiakse üle reaalaja API-le);gpt-realtime,gpt-4o-realtimeja vanad helimudelid 20. jaanuaril 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeja/v1/audio/translations26. veebruaril 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Täisdupleksseks kõneks on GPT-Live 1 olnud API-s saadaval alates 10. septembrist 2026. Lisand 3. novembril 2026: jagu OpenAI kolme kõnearhitektuuri kohta (GPT-Live, reaalaja API, töötlemisahel) ja transpordi valikust (WebRTC, WebSocket, SIP), põhinedes juhistele Hääleagendid, Heli ja hääl ning Reaalaja API kasutuselevõtt; seansi maksimaalne kestus: 60 minutit (Reaalaja vestlused).
WebSocketi arhitektuur ja reaalaja API
OpenAI reaalaja API tähistab fundamentaalset pööret selles, kuidas sa keelemudelitega suhtled. Erinevalt traditsioonilistest REST API-dest, mis töötavad päring-vastus tsüklis, kasutab reaalaja API WebSocketi protokolli, et luua püsiv kahepoolne ühendus sinu rakenduse ja mudeli vahel.
See arhitektuur võimaldab heli reaalajas vahetada: sa saadad heli, mudel töötleb seda ja vastab häälega väikese viitega, jättes vahepealsed transkriptsiooni või tekst-kõneks sammud vahele. See on üks vestlevate hääleagentide põhikomponente ja selle kursuse süda.
Kolm kõnearhitektuuri aastal 2026
Enne WebSocketi ühenduse loomist paiguta reaalaja API konteksti koos OpenAI teiste lahendustega. Hääleagentide juhend eristab kolme lähenemist:
| Arhitektuur | Parimaks | Miks valida |
|---|---|---|
| GPT-Live | Täisduplekssed vestlused eraldi taustsüsteemiga | Häälemudel kuulab rääkimise ajal ja delegeerib arutluse ning tööriistade kasutamise sinu valitud taustsüsteemile; säilitab sinu olemasoleva tekstipõhise agendi muutumatuna |
| Reaalaja API | Kõne, arutlus ja tööriistad ühes seansis | Üks mudel tõlgendab heli, otsustab, mida teha, ja hääldab vastuse |
| Töötlemisahel | Iga sammu granulaarne kontroll | Transkriptsioon, seejärel tekstiagent, seejärel kõnesüntees: saad teksti sammude vahel kontrollida või teisendada ja iga komponenti sõltumatult vahetada |
Uute kõnevestluse rakenduste jaoks soovitab OpenAI Heli ja hääl leht alustada GPT-Live-iga. Reaalaja API jääb õigeks lähtepunktiks, kui agent peab mahtuma ühte seanssi, toetades kasutaja katkestamist, kiiret esimest helivastust, loomulikku kõnevahetust ja otsest tööriistade kutsumist. Töötlemisahel toimib kõige paremini siis, kui iga samm peab jääma nähtavaks: transkriptsioonide säilitamine, reeglite jõustamine enne agendi vastamist või hääle väljastamine alles pärast vastuse valideerimist.
See kursus keskendub reaalaja API-le ja töötlemisahelale, mille komponente (transkriptsioon, kõnesüntees) käsitletakse järgmistes osades.
WebRTC, WebSocket või SIP
Sinu transpordivalik sõltub sellest, kust heli pärineb. Vastavalt dokumentatsioonile: kasuta WebRTC-d brauseriheli jaoks, kus sinu server genereerib lühiajalise kliendi saladuse; WebSocketi serveripoolsete helitorustike jaoks; SIP-i telefonikõnede jaoks. Serveripoolne juhtühendus võimaldab usaldusväärsel taustsüsteemil ka jälgida ja suunada meediaseanssi. See tund käsitleb WebSocketit kui lihtsaimat viisi vahetatavate sündmuste mõistmiseks; brauseris eelista WebRTC-d. Reaalaja seanss kestab maksimaalselt 60 minutit.
WebSocket vs REST: miks see valik?
Traditsioonilises REST-arhitektuuris nõuab iga interaktsioon terviklikku HTTP-päringut: TCP-ühenduse avamine, TLS-läbirääkimised, päiste saatmine, vastuse ootamine ja ühenduse sulgemine. Reaalaja heli jaoks on see koormus lubamatu.
| Kriteerium | REST (Responses API) | WebSocket (Reaalaja API) |
|---|---|---|
| Viide | 200–500 ms päringu kohta | < 50 ms pärast ühenduse loomist |
| Suund | Ainult klient → server | Samaaegne kahepoolne |
| Ühendus | Uus iga päringu jaoks | Püsiv (seanss) |
| Heli | Nõutav täielik fail | Tükiviisi voogedastus |
WebSocketi protokoll hoiab kanali pidevalt avatuna. Kui ühendus on loodud, saavad klient ja server sõnumeid saata igal ajal, ootamata, et teine pool lõpetaks.
WebSocketi ühenduse loomine
Siin on näide, kuidas luua ühendus reaalaja API-ga Pythonis:
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())
Ühenduse URL sisaldab mudelit päringuparameetrina. Alates API üldkasutatavaks muutumisest on nõutav ainult autentimispäis – beetaversiooni faasi päis OpenAI-Beta: realtime=v1 on eemaldatud.
Liides märgitud 5. augustil 2026 – Reaalaja API areneb (mudelid, sündmuste nimed, seansi formaat): kahtluse korral kontrolli ametlikku dokumentatsiooni.
Reaalaja rakenduse arhitektuur
Reaalaja API-t kasutav rakendus järgib kihiline arhitektuuri:
Helikiht (salvestus/esitus)
Salvestab mikrofoni, esitab helivastuseid. Kasutab PyAudio-t, sounddevice'i või brauseris Web Audio API-t.
WebSocketi kiht (transport)
Haldab püsivat ühendust, kodeerib/dekodeerib JSON-sündmusi, haldab uuesti ühendumist.
Rakenduse kiht (äriloogika)
Orkestreerib vestlust, haldab konteksti, kutsub tööriistu, töötleb tulemusi.
Serverikiht (valikuline proksi)
Tootmiskeskkonnas kaitseb vahepealne server API-võtit ja lisab serveripoolset äriloogikat.
Proksi-serveri roll
Arenduse ajal saad ühendada oma rakenduse otse reaalaja API-ga. Tootmiskeskkonnas on proksi-server hädavajalik, et:
- Kaitsta sinu API-võtit – ära kunagi avalda seda kliendipoolses koodis
- Autentida kasutajaid – kontrolli tokeneid enne seansi avamist
- Kontrollida kulusid – piira seansi kestust ja tokenite kasutust
- Logida interaktsioone – silumise ja nõuetele vastavuse tagamiseks
# Lihtsustatud näide WebSocketi proksist FastAPI-ga
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())
Peamised punktid
- OpenAI-l on kolm kõnearhitektuuri: GPT-Live (soovitatud uute vestlusrakenduste jaoks), reaalaja API (kõne, arutlus ja tööriistad ühes seansis) ning ahel transkriptsioon → agent → süntees
- WebRTC brauseriheli jaoks, WebSocket serveritorustike jaoks, SIP telefonia jaoks; seansid kestavad maksimaalselt 60 minutit
- Reaalaja API kasutab väikese viitega kahepoolseks suhtluseks WebSocketit
- Ühendus on püsiv: üks avamine kogu vestlusseansi vältel
- Kihiline arhitektuur eraldab heli, transpordi, äriloogika ja serveri proksi
- Tootmiskeskkonnas on proksi-server hädavajalik turvalisuse ja kulude kontrolli jaoks
- Protokoll on sündmustepõhine: iga sõnum on JSON-objekt väljaga
type