Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Seansai, įvykiai ir gyvavimo ciklas

Paskaita 2 iš 18 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Seansai, įvykiai ir gyvavimo ciklas
  2. Seanso gyvavimo ciklas
  3. Seanso konfigūravimas
  4. Įvykių sistema
  5. Klaidų valdymas
  6. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 2 d. — Garso modeliai. Keli šio kurso modeliai yra pasenę: tts-1, tts-1-hd ir gpt-4o-mini-tts nustos veikti 2027 m. sausio 6 d. (pakaitalas: gpt-realtime-2.1-mini, kuris, kaip nurodo „OpenAI“ TTS gidas, nepalaikomas per /v1/audio/speech: kalbos sintezės migracija perkeliama į „Realtime API“); gpt-realtime, gpt-4o-realtime ir senieji garso modeliai nustos veikti 2027 m. sausio 20 d. (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ir /v1/audio/translations nustos veikti 2027 m. vasario 26 d. (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pilno dublekso (full-duplex) balsui „GPT-Live 1“ API yra prieinamas nuo 2026 m. rugsėjo 10 d.

Ištaisyta 2026 m. lapkričio 3 d. Įvesties transkripcijai buvo naudojamas gpt-live-transcribe, kuris veikia tik transkripcijos seanse ir nepalaiko nei server_vad, nei semantic_vad. Pokalbio seanse, kaip šis, kuriame VAD patvirtina kiekvieną repliką, dokumentacijoje nurodoma naudoti gpt-transcribe, kuris transkribuoja patvirtintas replikas ir naudoja ankstesnes replikas kaip kontekstą. Šaltiniai: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Seansai, įvykiai ir gyvavimo ciklas

Kiekvienas „WebSocket“ ryšys su „Realtime API“ sukuria seansą. Šis seansas yra pagrindinis valdymo vienetas: jame įtraukta modelio konfigūracija, pokalbių istorija, galimi įrankiai ir dabartinė sąveikos būsena. Norint kurti patikimus balso agentus, būtina suprasti jo gyvavimo ciklą.

Seanso gyvavimo ciklas

Kai tik užmezgamas „WebSocket“ ryšys, serveris išsiunčia session.created įvykį. Seansas pereina kelias fazes:

1

Ryšys → session.created

Serveris patvirtina seansą unikaliu ID ir numatytąja konfigūracija.

2

Konfigūracija → session.update

Siunči „session.update“, kad nustatytum instrukcijas, balsą, įrankius ir modalumus.

3

Aktyvus pokalbis

Garso ir teksto įvykių mainai tarp kliento ir serverio.

4

Uždarymas → WebSocket disconnect

Seansas sunaikinamas uždarus ryšį. Serveryje jokia būsena neišsaugoma.

Seanso konfigūravimas

Po session.created išsiųsk session.update įvykį modelio elgsenai konfigūruoti. Vartotojo sakomų žodžių transkripcija (audio.input.transcription) yra neprivaloma: jos nenaudojant gausite balsą, bet ne tekstą. Parametras languages nurodo tikėtinas kalbas ir pagerina atpažinimą:

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:
        # Laukiama session.created
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Session created: {session_id}")

        # Konfigūruojamas seansas
        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": []
            }
        }))

        # Laukiama patvirtinimo (pirmiau gali atvykti kiti įvykiai)
        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"])

Pagrindiniai seanso parametrai

Parametras Aprašymas Rekomenduojama reikšmė
output_modalities Išvesties modalumai ["audio"] (arba ["text"])
audio.output.voice Sintezės balsas marin, cedar, alloy, echo ir kt.
audio.input.turn_detection Kalbos pabaigos aptikimas server_vad su slenksčiu 0.5
audio.input.format Gaunamo garso formatas {"type": "audio/pcm", "rate": 24000}

Įvykių sistema

„Realtime API“ yra visiškai valdoma įvykių. Kiekviena išsiųsta žinutė yra JSON objektas su lauku type, kuris nulemia jos pobūdį. Įvykiai skirstomi į dvi kategorijas:

Kliento įvykiai (tu → serveris)

# Pagrindiniai tavo siunčiami įvykiai
client_events = {
    "session.update":              "Konfigūracijos keitimas",
    "input_audio_buffer.append":   "Garso fragmento siuntimas",
    "input_audio_buffer.commit":   "Garso buferio fiksavimas",
    "input_audio_buffer.clear":    "Garso buferio išvalymas",
    "conversation.item.create":    "Žinutės rankinis pridėjimas",
    "conversation.item.truncate":  "Atsakymo sutrumpinimas",
    "conversation.item.delete":    "Žinutės ištrynimas",
    "response.create":             "Atsakymo generavimo inicijavimas",
    "response.cancel":             "Dabartinio atsakymo atšaukimas",
}

Serverio įvykiai (serveris → tu)

# Pagrindiniai tavo gaunami įvykiai
server_events = {
    "session.created":             "Seansas inicializuotas",
    "session.updated":             "Konfigūracija pritaikyta",
    "input_audio_buffer.speech_started":  "Aptikta kalba",
    "input_audio_buffer.speech_stopped":  "Aptikta tyla",
    "conversation.item.created":   "Nauja žinutė istorijoje",
    "response.created":            "Generavimas pradėtas",
    "response.output_audio.delta":        "Atsakymo garso fragmentas",
    "response.output_audio_transcript.delta": "Transkripcijos fragmentas",
    "response.done":               "Atsakymas baigtas",
    "error":                       "Klaida",
}

Klaidų valdymas

Klaidos perduodamos per error tipo įvykį. Jas visada turi perimti:

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":
                # Konfigūracijos klaida, reikia ištaisyti ir bandyti iš naujo
                pass
            elif error["type"] == "server_error":
                # Problema „OpenAI“ pusėje, reikia prisijungti iš naujo
                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}")

Svarbiausi punktai

  • Seansas automatiškai sukuriamas užmezgus „WebSocket“ ryšį ir sunaikinamas jį nutraukus.
  • session.update konfigūruoja seansą po session.created; prieš pasikliaujant nauja konfigūracija, palauk session.updated.
  • Norint transkribuoti įvestį pokalbio seanse, naudok gpt-transcribe; gpt-live-transcribe skirtas tik transkripcijos seansams.
  • Protokolas yra grynas įvykiais grįstas protokolas: kiekviena žinutė turi type, kuris nulemia jos apdorojimą.
  • Kliento įvykiai valdo sąveiką; serverio įvykiai praneša apie rezultatus.
  • Klaidų valdymas yra kritiškai svarbus: visada klausykis error įvykių.