Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Realtime API:n WebSocket-arkkitehtuuri

Oppitunti 1 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Realtime API:n WebSocket-arkkitehtuuri
  2. Kolme ääniarkkitehtuuria vuonna 2026
  3. WebRTC, WebSocket vai SIP?
  4. WebSocket vs. REST: Miksi tämä valinta?
  5. WebSocket-yhteyden muodostaminen
  6. Realtime-sovelluksen arkkitehtuuri
  7. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on poistettu käytöstä: tts-1, tts-1-hd ja gpt-4o-mini-tts lakkaavat 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-realtime ja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. 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:

ArkkitehtuuriParas käyttötarkoitusMiksi valita tämä
GPT-LiveTä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 APIPuhe, päättely ja työkalut yhdessä istunnossaYksi malli tulkitsee äänen, päättää mitä tehdä ja puhuu vastauksen
KäsittelyketjuYksityiskohtainen hallinta jokaisessa vaiheessaTranskriptio, 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:

1

Äänikerros (kaappaus/toisto)

Kaappaa mikrofonin äänen, toistaa äänivastaukset. Käyttää PyAudioa, sounddevicea tai Web Audio API:ta selaimessa.

2

WebSocket-kerros (kuljetus)

Hallitsee pysyvää yhteyttä, koodaa/puraa JSON-tapahtumat ja hoitaa uudelleenyhteydenmuodostukset.

3

Sovelluskerros (liiketoimintalogiikka)

Orkestroi keskustelun, hallitsee kontekstia, kutsuu työkaluja ja käsittelee tulokset.

4

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ä