Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Sessioni, eventi e ciclo di vita

Lezione 2 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Sessioni, eventi e ciclo di vita
  2. Il ciclo di vita di una sessione
  3. Configurazione di una sessione
  4. Il sistema di eventi
  5. Gestione degli errori
  6. Punti chiave

Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati: tts-1, tts-1-hd e gpt-4o-mini-tts smetteranno di funzionare il 6 gennaio 2027 (sostituzione: gpt-realtime-2.1-mini, che la guida OpenAI TTS definisce non supportata da /v1/audio/speech: la migrazione della sintesi vocale passa alle Realtime API); gpt-realtime, gpt-4o-realtime e i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe e /v1/audio/translations il 26 febbraio 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Per la voce full-duplex, GPT-Live 1 è disponibile nelle API dal 10 settembre 2026.

Corretto il 3 novembre 2026. La trascrizione dell’input utilizzava gpt-live-transcribe, che funziona solo in una sessione di trascrizione e non supporta né server_vad né semantic_vad. In una sessione di conversazione come questa, dove il VAD convalida ogni turno, la documentazione specifica gpt-transcribe, che trascrive i turni convalidati e utilizza i turni precedenti come contesto. Fonti: Trascrizione in tempo reale · GPT-Transcribe · GPT-Live-Transcribe.

Sessioni, eventi e ciclo di vita

Ogni connessione WebSocket alle Realtime API crea una sessione. Questa sessione è l’unità fondamentale di gestione: incapsula la configurazione del modello, la cronologia della conversazione, gli strumenti disponibili e lo stato corrente dell’interazione. Comprendere il suo ciclo di vita è essenziale per costruire agenti vocali robusti.

Il ciclo di vita di una sessione

Non appena la connessione WebSocket viene stabilita, il server emette un evento session.created. La sessione attraversa diverse fasi:

1

Connessione → session.created

Il server conferma la sessione con un ID univoco e una configurazione predefinita.

2

Configurazione → session.update

Invii session.update per definire istruzioni, voce, strumenti e modalità.

3

Conversazione attiva

Scambio di eventi audio e testo tra client e server.

4

Chiusura → disconnessione WebSocket

La sessione viene distrutta quando la connessione si chiude. Nessuno stato viene mantenuto sul server.

Configurazione di una sessione

Dopo session.created, invia un evento session.update per configurare il comportamento del modello. La trascrizione di ciò che dice l’utente (audio.input.transcription) è opzionale: senza di essa, ricevi la voce ma non il testo. languages specifica le lingue attese e migliora il riconoscimento:

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

        # Configura la sessione
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "Sei un assistente vocale di lingua francese. "
                                "Rispondi in modo conciso e naturale.",
                "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": []
            }
        }))

        # Attendi conferma (potrebbero arrivare prima altri eventi)
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "session.updated":
                print("Sessione aggiornata")
                break
            if event["type"] == "error":
                raise RuntimeError(event["error"]["message"])

Parametri chiave della sessione

Parametro Descrizione Valore consigliato
output_modalities Modalità di output ["audio"] (o ["text"])
audio.output.voice Voce di sintesi marin, cedar, alloy, echo, ecc.
audio.input.turn_detection Rilevamento fine discorso server_vad con soglia 0.5
audio.input.format Formato audio in ingresso {"type": "audio/pcm", "rate": 24000}

Il sistema di eventi

Le Realtime API sono interamente basate sugli eventi. Ogni messaggio scambiato è un oggetto JSON con un campo type che ne determina la natura. Gli eventi rientrano in due categorie:

Eventi client (tu → server)

# I principali eventi che invii
client_events = {
    "session.update":              "Modifica configurazione",
    "input_audio_buffer.append":   "Invia un chunk audio",
    "input_audio_buffer.commit":   "Conferma il buffer audio",
    "input_audio_buffer.clear":    "Svuota il buffer audio",
    "conversation.item.create":    "Aggiungi un messaggio manualmente",
    "conversation.item.truncate":  "Tronca una risposta",
    "conversation.item.delete":    "Elimina un messaggio",
    "response.create":             "Attiva una risposta",
    "response.cancel":             "Annulla la risposta corrente",
}

Eventi server (server → te)

# I principali eventi che ricevi
server_events = {
    "session.created":             "Sessione inizializzata",
    "session.updated":             "Configurazione applicata",
    "input_audio_buffer.speech_started":  "Discorso rilevato",
    "input_audio_buffer.speech_stopped":  "Silenzio rilevato",
    "conversation.item.created":   "Nuovo messaggio nella cronologia",
    "response.created":            "Generazione avviata",
    "response.output_audio.delta":        "Chunk audio della risposta",
    "response.output_audio_transcript.delta": "Chunk di trascrizione",
    "response.done":               "Risposta terminata",
    "error":                       "Errore",
}

Gestione degli errori

Gli errori vengono emessi tramite un evento di tipo error. Devi sempre intercettarli:

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

            if error["type"] == "invalid_request_error":
                # Errore di configurazione, correggi e riprova
                pass
            elif error["type"] == "server_error":
                # Problema lato OpenAI, riconnetti
                pass

        elif event_type == "session.updated":
            print("Configurazione applicata con successo")

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

Punti chiave

  • Una sessione viene creata automaticamente alla connessione WebSocket e distrutta alla disconnessione
  • session.update configura la sessione dopo session.created; attendi session.updated prima di fare affidamento sulla nuova configurazione
  • Per trascrivere l’input in una sessione di conversazione, usa gpt-transcribe; gpt-live-transcribe è riservato alle sessioni di trascrizione
  • Il protocollo è puramente basato sugli eventi: ogni messaggio ha un type che ne determina la gestione
  • Gli eventi client guidano l’interazione; gli eventi server riportano i risultati
  • La gestione degli errori è fondamentale: ascolta sempre gli eventi error