Salt la conținutul principal
Română— Alege o limbă
Meniu

Sesiuni, evenimente și ciclu de viață

Lecția 2 din 18 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Sesiuni, evenimente și ciclu de viață
  2. Ciclul de viață al unei sesiuni
  3. Configurarea unei sesiuni
  4. Sistemul de evenimente
  5. Gestionarea erorilor
  6. Puncte cheie

Actualizat la 2 noiembrie 2026 — Modele audio. Mai multe modele din acest curs sunt depreciate: tts-1, tts-1-hd și gpt-4o-mini-tts vor înceta să funcționeze la 6 ianuarie 2027 (înlocuitor: gpt-realtime-2.1-mini, pe care ghidul OpenAI TTS precizează că nu este suportat de /v1/audio/speech: migrarea sintezei vocale se mută în Realtime API); gpt-realtime, gpt-4o-realtime și modelele audio legacy la 20 ianuarie 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe și /v1/audio/translations la 26 februarie 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pentru voce full-duplex, GPT-Live 1 este disponibil în API din 10 septembrie 2026.

Corectat la 3 noiembrie 2026. Transcrierea inputului folosea gpt-live-transcribe, care funcționează doar într-o sesiune de transcriere și nu suportă nici server_vad, nici semantic_vad. Într-o sesiune de conversație ca aceasta, unde VAD validează fiecare intervenție, documentația specifică gpt-transcribe, care transcrie intervențiile validate și folosește intervențiile anterioare drept context. Surse: Transcriere în timp real · GPT-Transcribe · GPT-Live-Transcribe.

Sesiuni, evenimente și ciclu de viață

Fiecare conexiune WebSocket la Realtime API creează o sesiune. Această sesiune reprezintă unitatea fundamentală de gestionare: ea încapsulează configurarea modelului, istoricul conversației, instrumentele disponibile și starea curentă a interacțiunii. Înțelegerea ciclului său de viață este esențială pentru construirea unor agenți vocali robusti.

Ciclul de viață al unei sesiuni

Imediat ce conexiunea WebSocket este stabilită, serverul emite un eveniment session.created. Sesiunea parcurge mai multe faze:

1

Conexiune → session.created

Serverul confirmă sesiunea cu un ID unic și o configurație implicită.

2

Configurare → session.update

Trimiteți session.update pentru a defini instrucțiunile, vocea, instrumentele și modalitățile.

3

Conversație activă

Schimb de evenimente audio și text între client și server.

4

Închidere → deconectare WebSocket

Sesiunea este distrusă la închiderea conexiunii. Nicio stare nu este păstrată pe server.

Configurarea unei sesiuni

După session.created, trimiteți un eveniment session.update pentru a configura comportamentul modelului. Transcrierea a ceea ce spune utilizatorul (audio.input.transcription) este opțională: fără aceasta, primiți vocea, dar nu și textul. languages specifică limbile așteptate și îmbunătățește recunoașterea:

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:
        # Așteptați session.created
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Sesiune creată: {session_id}")

        # Configurați sesiunea
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "Ești un asistent vocal care vorbește franceză. "
                                "Răspunde concis și natural.",
                "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": []
            }
        }))

        # Așteptați confirmarea (alte evenimente pot sosi mai întâi)
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "session.updated":
                print("Sesiune actualizată")
                break
            if event["type"] == "error":
                raise RuntimeError(event["error"]["message"])

Parametri cheie ai sesiunii

Parametru Descriere Valoare recomandată
output_modalities Modalități de ieșire ["audio"] (sau ["text"])
audio.output.voice Voce de sinteză marin, cedar, alloy, echo etc.
audio.input.turn_detection Detectarea sfârșitului vorbirii server_vad cu pragul 0.5
audio.input.format Format audio de intrare {"type": "audio/pcm", "rate": 24000}

Sistemul de evenimente

Realtime API este integral bazat pe evenimente. Fiecare mesaj schimbat este un obiect JSON cu un câmp type care îi determină natura. Evenimentele se împart în două categorii:

Evenimente client (dumneavoastră → server)

# Principalele evenimente pe care le trimiteți
client_events = {
    "session.update":              "Modifică configurația",
    "input_audio_buffer.append":   "Trimite un fragment audio",
    "input_audio_buffer.commit":   "Confirmă bufferul audio",
    "input_audio_buffer.clear":    "Golește bufferul audio",
    "conversation.item.create":    "Adaugă un mesaj manual",
    "conversation.item.truncate":  "Trunchiază un răspuns",
    "conversation.item.delete":    "Șterge un mesaj",
    "response.create":             "Declanșează un răspuns",
    "response.cancel":             "Anulează răspunsul curent",
}

Evenimente server (server → dumneavoastră)

# Principalele evenimente pe care le primiți
server_events = {
    "session.created":             "Sesiune inițializată",
    "session.updated":             "Configurație aplicată",
    "input_audio_buffer.speech_started":  "Vorbire detectată",
    "input_audio_buffer.speech_stopped":  "Silent detectat",
    "conversation.item.created":   "Mesaj nou în istoric",
    "response.created":            "Generare începută",
    "response.output_audio.delta":        "Fragment audio de răspuns",
    "response.output_audio_transcript.delta": "Fragment de transcriere",
    "response.done":               "Răspuns terminat",
    "error":                       "Eroare",
}

Gestionarea erorilor

Erorile sunt emise printr-un eveniment de tip error. Trebuie să le interceptați întotdeauna:

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

            if error["type"] == "invalid_request_error":
                # Eroare de configurare, remediați și reîncercați
                pass
            elif error["type"] == "server_error":
                # Problemă din partea OpenAI, reconectați-vă
                pass

        elif event_type == "session.updated":
            print("Configurație aplicată cu succes")

        elif event_type == "response.done":
            usage = event["response"].get("usage", {})
            print(f"Tokeni utilizați: {usage}")

Puncte cheie

  • O sesiune este creată automat la conectarea WebSocket și distrusă la deconectare
  • session.update configurează sesiunea după session.created; așteptați session.updated înainte de a vă baza pe noua configurație
  • Pentru a transcrie inputul într-o sesiune de conversație, folosiți gpt-transcribe; gpt-live-transcribe este rezervat sesiunilor de transcriere
  • Protocolul este pur bazat pe evenimente: fiecare mesaj are un type care determină modul de tratare
  • Evenimentele client conduc interacțiunea; evenimentele server raportează rezultatele
  • Gestionarea erorilor este critică: ascultați întotdeauna evenimentele error