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

Istunnot, tapahtumat ja elinkaari

Oppitunti 2 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Istunnot, tapahtumat ja elinkaari
  2. Istunnon elinkaari
  3. Istunnon konfigurointi
  4. Tapahtumajärjestelmä
  5. Virheenkäsittely
  6. 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:hun); 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.

Korjattu 3. marraskuuta 2026. Syötteen litterointi käytti mallia gpt-live-transcribe, joka toimii vain litterointi-istunnossa eikä tue server_vad- eikä semantic_vad-toimintoja. Tämän kaltaisessa keskusteluistunnossa, jossa VAD vahvistaa jokaisen vuoron, dokumentaatio määrää käyttämään mallia gpt-transcribe, joka litteroi vahvistetut vuorot ja käyttää edellisiä vuoroja kontekstina. Lähteet: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Istunnot, tapahtumat ja elinkaari

Jokainen WebSocket-yhteys Realtime API:hun luo istunnon. Tämä istunto on hallinnan perusyksikkö: se kapseloi mallin konfiguraation, keskusteluhistorian, käytettävissä olevat työkalut ja vuorovaikutuksen nykytilan. Sen elinkaaren ymmärtäminen on välttämätöntä robustien ääniagenttien rakentamiseksi.

Istunnon elinkaari

Heti kun WebSocket-yhteys on muodostettu, palvelin lähettää session.created-tapahtuman. Istunto käy läpi useita vaiheita:

1

Yhteys → session.created

Palvelin vahvistaa istunnon uniikilla tunnisteella ja oletusasetuksilla.

2

Konfiguraatio → session.update

Lähetät session.update-määrityksen määritelläksesi ohjeet, äänen, työkalut ja modaliteetit.

3

Aktiivinen keskustelu

Ääni- ja tekstiviestien vaihto asiakkaan ja palvelimen välillä.

4

Sulkeminen → WebSocket disconnect

Istunto tuhoutuu, kun yhteys katkeaa. Palvelimelle ei jää mitään tilaa talteen.

Istunnon konfigurointi

session.created-tapahtuman jälkeen lähetä session.update-tapahtuma määritelläksesi mallin toiminnan. Käyttäjän puheen litterointi (audio.input.transcription) on valinnaista: ilman sitä vastaanotat äänen mutta et tekstiä. languages määrittää odotetut kielet ja parantaa tunnistusta:

import asyncio
import websockets
import json

async def configure_session():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}"
    }

    async with websockets.connect(URL, additional_headers=headers) as ws:
        # Odota session.created-tapahtumaa
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Session created: {session_id}")

        # Konfiguroi istunto
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "You are a French-speaking voice assistant. "
                                "Respond concisely and naturally.",
                "audio": {
                    "input": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
                        "turn_detection": {
                            "type": "server_vad",
                            "threshold": 0.5,
                            "prefix_padding_ms": 300,
                            "silence_duration_ms": 500
                        }
                    },
                    "output": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "voice": "marin"
                    }
                },
                "tools": []
            }
        }))

        # Odota vahvistusta (muut tapahtumat voivat saapua ensin)
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "session.updated":
                print("Session updated")
                break
            if event["type"] == "error":
                raise RuntimeError(event["error"]["message"])

Keskeiset istuntoparametrit

Parametri Kuvaus Suositeltu arvo
output_modalities Lähtömodaliteetit ["audio"] (tai ["text"])
audio.output.voice Synteesiääni marin, cedar, alloy, echo jne.
audio.input.turn_detection Puheen lopun tunnistus server_vad, kynnysarvo 0.5
audio.input.format Saapuvan äänen formaatti {"type": "audio/pcm", "rate": 24000}

Tapahtumajärjestelmä

Realtime API on täysin tapahtumalähtöinen. Jokainen vaihdettu viesti on JSON-objekti, jossa on type-kenttä, joka määrittää sen luonteen. Tapahtumat jakautuvat kahteen kategoriaan:

Asiakastapahtumat (sinä → palvelin)

# Tärkeimmät lähettämäsi tapahtumat
client_events = {
    "session.update":              "Muuta konfiguraatiota",
    "input_audio_buffer.append":   "Lähetä äänipala",
    "input_audio_buffer.commit":   "Vahvista äänipuskuri",
    "input_audio_buffer.clear":    "Tyhjennä äänipuskuri",
    "conversation.item.create":    "Lisää viesti manuaalisesti",
    "conversation.item.truncate":  "Lyhennä vastausta",
    "conversation.item.delete":    "Poista viesti",
    "response.create":             "Käynnistä vastaus",
    "response.cancel":             "Peruuta nykyinen vastaus",
}

Palvelintapahtumat (palvelin → sinä)

# Tärkeimmät vastaanottamasi tapahtumat
server_events = {
    "session.created":             "Istunto alustettu",
    "session.updated":             "Konfiguraatio sovellettu",
    "input_audio_buffer.speech_started":  "Puhe havaittu",
    "input_audio_buffer.speech_stopped":  "Hiljaisuus havaittu",
    "conversation.item.created":   "Uusi viesti historiassa",
    "response.created":            "Generointi aloitettu",
    "response.output_audio.delta":        "Vastauksen äänipala",
    "response.output_audio_transcript.delta": "Litterointipala",
    "response.done":               "Vastaus valmis",
    "error":                       "Virhe",
}

Virheenkäsittely

Virheet lähetetään error-tyyppisenä tapahtumana. Sinun on aina siepattava ne:

async def handle_events(ws):
    async for raw_message in ws:
        event = json.loads(raw_message)
        event_type = event["type"]

        if event_type == "error":
            error = event["error"]
            print(f"Error [{error['type']}]: {error['message']}")

            if error["type"] == "invalid_request_error":
                # Konfiguraatiovirhe, korjaa ja yritä uudelleen
                pass
            elif error["type"] == "server_error":
                # Ongelma OpenAI:n puolella, muodosta yhteys uudelleen
                pass

        elif event_type == "session.updated":
            print("Configuration applied successfully")

        elif event_type == "response.done":
            usage = event["response"].get("usage", {})
            print(f"Tokens used: {usage}")

Keskeiset asiat

  • Istunto luodaan automaattisesti WebSocket-yhteyden muodostuessa ja tuhoutuu yhteyden katketessa
  • session.update konfiguroi istunnon session.created-tapahtuman jälkeen; odota session.updated-tapahtumaa ennen kuin luotat uuteen konfiguraatioon
  • Litteroidaksesi syötteen keskusteluistunnossa käytä gpt-transcribe-mallia; gpt-live-transcribe on varattu litterointi-istunnoille
  • Protokolla on puhtaasti tapahtumalähtöinen: jokaisella viestillä on type, joka määrittää sen käsittelyn
  • Asiakastapahtumat ohjaavat vuorovaikutusta; palvelintapahtumat raportoivat tuloksia
  • Virheenkäsittely on kriittistä: kuuntele aina error-tapahtumia