Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Sessioner, händelser och livscykel

Lektion 2 av 18 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Sessioner, händelser och livscykel
  2. En sessions livscykel
  3. Konfigurera en session
  4. Händelsesystemet
  5. Felhantering
  6. Viktiga punkter

Uppdaterat 2 november 2026 — Ljudmodeller. Flera modeller i denna kurs är avvecklade: tts-1, tts-1-hd och gpt-4o-mini-tts slutar fungera den 6 januari 2027 (ersättning: gpt-realtime-2.1-mini, vilket OpenAI:s TTS-guide anger inte stöds av /v1/audio/speech: migreringen av talgenerering flyttas till Realtime API); gpt-realtime, gpt-4o-realtime och äldre ljudmodeller den 20 januari 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe och /v1/audio/translations den 26 februari 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). För full-duplex-röst har GPT-Live 1 funnits tillgängligt i API:t sedan den 10 september 2026.

Korrigerat 3 november 2026. Inmatningstranskribering använde gpt-live-transcribe, vilket endast fungerar i en transkriberingssession och varken stöder server_vad eller semantic_vad. I en konversationssession som denna, där VAD validerar varje tur, specificerar dokumentationen gpt-transcribe, som transkriberar validerade turer och använder tidigare turer som kontext. Källor: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Sessioner, händelser och livscykel

Varje WebSocket-anslutning till Realtime API skapar en session. Denna session är den grundläggande enheten för hantering: den kapslar in modellkonfiguration, konversationshistorik, tillgängliga verktyg och det aktuella tillståndet för interaktionen. Att förstå dess livscykel är avgörande för att bygga robusta röstagenter.

En sessions livscykel

Så snart WebSocket-anslutningen är etablerad sänder servern en händelse session.created. Sessionen genomgår flera faser:

1

Anslutning → session.created

Servern bekräftar sessionen med ett unikt ID och standardkonfiguration.

2

Konfiguration → session.update

Du skickar session.update för att definiera instruktioner, röst, verktyg och modaliteter.

3

Aktiv konversation

Utbyte av ljud- och texthändelser mellan klient och server.

4

Avslutning → WebSocket disconnect

Sessionen förstörs när anslutningen stängs. Inget tillstånd behålls på servern.

Konfigurera en session

Efter session.created skickar du en händelse session.update för att konfigurera modellens beteende. Att transkribera vad användaren säger (audio.input.transcription) är valfritt: utan detta får du rösten men inte texten. languages specificerar de förväntade språken och förbättrar igenkänningen:

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

        # Konfigurera sessionen
        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": []
            }
        }))

        # Vänta på bekräftelse (andra händelser kan anlända först)
        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"])

Viktiga sessionsparametrar

Parameter Beskrivning Rekommenderat värde
output_modalities Utmatningsmodaliteter ["audio"] (eller ["text"])
audio.output.voice Syntesröst marin, cedar, alloy, echo, etc.
audio.input.turn_detection Detektering av talstopp server_vad med tröskelvärde 0.5
audio.input.format Inkommande ljudformat {"type": "audio/pcm", "rate": 24000}

Händelsesystemet

Realtime API är helt händelsestyrt. Varje utbytt meddelande är ett JSON-objekt med ett fält type som avgör dess natur. Händelser delas in i två kategorier:

Klienthändelser (du → server)

# De viktigaste händelserna du skickar
client_events = {
    "session.update":              "Ändra konfiguration",
    "input_audio_buffer.append":   "Skicka en ljudbit",
    "input_audio_buffer.commit":   "Bekräfta ljudbufferten",
    "input_audio_buffer.clear":    "Rensa ljudbufferten",
    "conversation.item.create":    "Lägg till ett meddelande manuellt",
    "conversation.item.truncate":  "Korta ner ett svar",
    "conversation.item.delete":    "Ta bort ett meddelande",
    "response.create":             "Utlös ett svar",
    "response.cancel":             "Avbryt det aktuella svaret",
}

Serverhändelser (server → du)

# De viktigaste händelserna du tar emot
server_events = {
    "session.created":             "Session initierad",
    "session.updated":             "Konfiguration tillämpad",
    "input_audio_buffer.speech_started":  "Tal detekterat",
    "input_audio_buffer.speech_stopped":  "Tystnad detekterad",
    "conversation.item.created":   "Nytt meddelande i historiken",
    "response.created":            "Generering startad",
    "response.output_audio.delta":        "Ljudbit i svar",
    "response.output_audio_transcript.delta": "Transkriberingsbit",
    "response.done":               "Svar avslutat",
    "error":                       "Fel",
}

Felhantering

Fel sänds via en händelse av typen error. Du måste alltid fånga upp dem:

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"Fel [{error['type']}]: {error['message']}")

            if error["type"] == "invalid_request_error":
                # Konfigurationsfel, åtgärda och försök igen
                pass
            elif error["type"] == "server_error":
                # Problem på OpenAI:s sida, återanslut
                pass

        elif event_type == "session.updated":
            print("Konfiguration tillämpad framgångsrikt")

        elif event_type == "response.done":
            usage = event["response"].get("usage", {})
            print(f"Använda tokens: {usage}")

Viktiga punkter

  • En session skapas automatiskt vid WebSocket-anslutning och förstörs vid frånkoppling
  • session.update konfigurerar sessionen efter session.created; vänta på session.updated innan du förlitar dig på den nya konfigurationen
  • För att transkribera inmatning i en konversationssession, använd gpt-transcribe; gpt-live-transcribe är reserverat för transkriberingssessioner
  • Protokollet är rent händelsestyrt: varje meddelande har en type som avgör hur det hanteras
  • Klienthändelser styr interaktionen; serverhändelser rapporterar resultat
  • Felhantering är avgörande: lyssna alltid efter error-händelser