Realtime API:n WebSocket-arkkitehtuuri
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on poistettu käytöstä:
tts-1,tts-1-hdjagpt-4o-mini-ttslakkaavat toimimasta 6. tammikuuta 2027 (korvaaja:gpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tuetun/v1/audio/speech-päätepistettä: puheentuotto siirtyy Realtime API:hin);gpt-realtime,gpt-4o-realtimeja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeja/v1/audio/translations26. helmikuuta 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Täysdupleksista ääntä varten GPT-Live 1 on ollut saatavilla API:ssa 10. syyskuuta 2026 lähtien. Lisäys 3. marraskuuta 2026: osio OpenAI:n kolmesta ääniarkkitehtuurista (GPT-Live, Realtime API, käsittelyketju) ja kuljetusprotokollan valinnasta (WebRTC, WebSocket, SIP) perustuen oppaisiin Voice agents, Audio and voice ja Getting started with the Realtime API; istunnon enimmäiskesto on 60 minuuttia (Realtime conversations).
Realtime API:n WebSocket-arkkitehtuuri
OpenAI:n Realtime API edustaa perustavanlaatuista muutosta siinä, miten olet vuorovaikutuksessa kielimallien kanssa. Toisin kuin perinteiset REST-APIt, jotka toimivat pyyntö-vastaus-syklillä, Realtime API käyttää WebSocket-protokollaa luodakseen pysyvän, kaksisuuntaisen yhteyden sovelluksesi ja mallin välille.
Tämä arkkitehtuuri mahdollistaa reaaliaikaisen äänen vaihdon: lähetät ääntä, malli käsittelee sen ja vastaa puheella pienellä viiveellä ohittaen välivaiheet kuten transkription tai tekstistä puheeksi -muunnoksen. Tämä on yksi keskeisimmistä rakennuspalikoista keskusteleville ääniagenteille ja tämän kurssin ydin.
Kolme ääniarkkitehtuuria vuonna 2026
Ennen WebSocket-yhteyden avaamista on hyvä sijoittaa Realtime API kontekstiin OpenAI:n muiden ratkaisujen rinnalle. Voice agents -opas erottaa kolme lähestymistapaa:
| Arkkitehtuuri | Paras käyttötarkoitus | Miksi valita tämä |
|---|---|---|
| GPT-Live | Täysdupleksiset keskustelut erillisellä taustajärjestelmällä | Äänimalli kuuntelee puhuessaan ja delegoi päättelyn ja työkalujen käytön valitsemallesi taustajärjestelmälle; pitää olemassa olevan tekstiagenttisi ennallaan |
| Realtime API | Puhe, päättely ja työkalut yhdessä istunnossa | Yksi malli tulkitsee äänen, päättää mitä tehdä ja puhuu vastauksen |
| Käsittelyketju | Yksityiskohtainen hallinta jokaisessa vaiheessa | Transkriptio, sitten tekstiagentti, sitten puheentuotto: voit tarkastaa tai muuntaa tekstiä vaiheiden välillä ja vaihtaa jokaisen komponentin itsenäisesti |
Uusia äänikeskustelusovelluksia varten OpenAI:n Audio and voice -sivu suosittelee nyt aloittamaan GPT-Live:llä. Realtime API on edelleen oikea lähtökohta, kun agentin on mahduttava yhteen istuntoon tukien käyttäjän keskeytyksiä, nopeaa ensimmäistä äänivastetta, luontevaa vuorottelua ja suoria työkalukutsuja. Käsittelyketju toimii parhaiten, kun jokaisen vaiheen on pysyttävä näkyvissä: transkriptioiden säilyttäminen, sääntöjen valvonta ennen agentin vastausta tai äänen tuottaminen vasta vastauksen validoinnin jälkeen.
Tämä kurssi keskittyy Realtime API:hin ja käsittelyketjuun, joiden komponentteja (transkriptio, puheentuotto) käsitellään myöhemmissä osioissa.
WebRTC, WebSocket vai SIP?
Kuljetusprotokollan valinta riippuu siitä, mistä ääni on peräisin. Dokumentaation mukaan: käytä WebRTC:tä selaimen äänelle (palvelimesi generoi väliaikaisen asiakassalaisuuden); WebSocket:ia palvelinpuolen ääniputkille; SIP:iä puhelinsoitoille. Palvelinpuolen ohjausyhteys mahdollistaa myös luotetun taustajärjestelmän tarkkailla ja ohjata mediaistuntoa. Tämä oppitunti käsittelee WebSocketiä, joka on yksinkertaisin tapa ymmärtää vaihdettuja tapahtumia; selaimessa suosi kuitenkin WebRTC:tä. Realtime-istunto kestää enintään 60 minuuttia.
WebSocket vs. REST: Miksi tämä valinta?
Perinteisessä REST-arkkitehtuurissa jokainen vuorovaikutus vaatii täydellisen HTTP-pyynnön: TCP-yhteyden avaaminen, TLS-neuvottelu, otsakkeiden lähetys, vastauksen odottaminen ja yhteyden sulkeminen. Reaaliaikaiselle äänelle tämä kuorma on liian suuri.
| Kriteeri | REST (Responses API) | WebSocket (Realtime API) |
|---|---|---|
| Viive | 200–500 ms pyyntöä kohden | < 50 ms yhteyden muodostamisen jälkeen |
| Suunta | Vain asiakas → palvelin | Samanaikainen kaksisuuntainen |
| Yhteys | Uusi jokaista pyyntöä varten | Pysyvä (istunto) |
| Ääni | Koko tiedosto vaaditaan | Paloittainen suoratoisto |
WebSocket-protokolla pitää kanavan jatkuvasti auki. Kun yhteys on muodostettu, asiakas ja palvelin voivat lähettää viestejä milloin tahansa odottamatta toisen osapuolen valmistumista.
WebSocket-yhteyden muodostaminen
Näin muodostat yhteyden Realtime API:hin Pythonilla:
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")
# Vastaanota tervetulotapahtuma
response = await ws.recv()
event = json.loads(response)
print(f"Type: {event['type']}")
# → "session.created"
# Pidä yhteys auki
await asyncio.Future()
asyncio.run(connect_realtime())
Yhteys-URL sisältää mallin kyselyparametrina. Siitä lähtien, kun API saavutti yleisen saatavuuden, vain todennusotsake on vaadittu – beta-vaiheen OpenAI-Beta: realtime=v1 -otsake on poistettu.
Huomioitu käyttöliittymä 5. elokuuta 2026 — Realtime API kehittyy (mallit, tapahtumien nimet, istunnon muoto): epäselvissä tilanteissa tarkista virallinen dokumentaatio.
Realtime-sovelluksen arkkitehtuuri
Realtime API:ta käyttävä sovellus noudattaa kerrosarkkitehtuuria:
Äänikerros (kaappaus/toisto)
Kaappaa mikrofonin äänen, toistaa äänivastaukset. Käyttää PyAudioa, sounddevicea tai Web Audio API:ta selaimessa.
WebSocket-kerros (kuljetus)
Hallitsee pysyvää yhteyttä, koodaa/puraa JSON-tapahtumat ja hoitaa uudelleenyhteydenmuodostukset.
Sovelluskerros (liiketoimintalogiikka)
Orkestroi keskustelun, hallitsee kontekstia, kutsuu työkaluja ja käsittelee tulokset.
Palvelinkerros (valinnainen välityspalvelin)
Tuotannossa välipalvelin suojaa API-avainta ja lisää palvelinpuolen liiketoimintalogiikkaa.
Välityspalvelimen rooli
Kehitysvaiheessa voit yhdistää sovelluksesi suoraan Realtime API:hin. Tuotannossa välityspalvelin on välttämätön seuraaviin tehtäviin:
- API-avaimesi suojaaminen — älä koskaan paljasta sitä asiakaspuolella
- Käyttäjiesi todentaminen — varmista tunnisteet ennen istunnon avaamista
- Kustannusten hallinta — rajoita istunnon kestoa ja tokenien käyttöä
- Vuorovaikutusten lokitus — vianetsintää ja vaatimustenmukaisuutta varten
# Yksinkertaistettu esimerkki WebSocket-välityspalvelimesta FastAPI:lla
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())
Keskeiset asiat
- OpenAI:ssa on kolme ääniarkkitehtuuria: GPT-Live (suositeltu uusiin keskustelusovelluksiin), Realtime API (puhe, päättely ja työkalut yhdessä istunnossa) sekä transkriptio → agentti → synteesi -ketju
- WebRTC selaimen äänelle, WebSocket palvelinputkille, SIP puhelinkäyttöön; istunnot kestävät enintään 60 minuuttia
- Realtime API käyttää WebSocketiä matalan viiveen kaksisuuntaiseen viestintään
- Yhteys on pysyvä: yksi avaaminen koko keskusteluistunnon ajaksi
- Kerrosarkkitehtuuri erottaa toisistaan äänen, kuljetuksen, liiketoimintalogiikan ja palvelinvälityksen
- Tuotannossa välityspalvelin on välttämätön tietoturvan ja kustannusten hallinnan vuoksi
- Protokolla on tapahtumapohjainen: jokainen viesti on JSON-objekti, jossa on
type-kenttä