Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Sessjonijiet, avvenimenti, u ċ-ċiklu tal-ħajja

Lezzjoni 2 / 18 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Sessjonijiet, avvenimenti, u ċ-ċiklu tal-ħajja
  2. Iċ-ċiklu tal-ħajja ta’ sessjoni
  3. Konfigurazzjoni ta’ sessjoni
  4. Is-sistema tal-avvenimenti
  5. Ġestjoni tal-iżbalji
  6. Punti Ewlenin

Aġġornat fit-2 ta’ Novembru, 2026 — Mudelli tal-awdjo. Diversi mudelli f’dan il-kors huma skaduti: tts-1, tts-1-hd, u gpt-4o-mini-tts se jieqfu jaħdmu fis-6 ta’ Jannar, 2027 (sostituzzjoni: gpt-realtime-2.1-mini, li l-gwida tat-TTS ta’ OpenAI tiddikjara li mhix appoġġjata minn /v1/audio/speech: il-migrazzjoni tas-sinteżi tal-kelma timxi lejn ir-Realtime API); gpt-realtime, gpt-4o-realtime, u mudelli tal-awdjo antiki fis-20 ta’ Jannar, 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe, u /v1/audio/translations fis-26 ta’ Frar, 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Għal-leħen full-duplex, GPT-Live 1 kien disponibbli fl-API mill-10 ta’ Settembru, 2026.

Ikkoreġut fit-3 ta’ Novembru, 2026. It-traskrizzjoni tal-input kienet qed tuża gpt-live-transcribe, li taħdem biss f’sessjoni ta’ traskrizzjoni u ma tappoġġjax server_vad jew semantic_vad. F’sessjoni ta’ konversazzjoni bħal din, fejn il-VAD jivvalida kull dawra, id-dokumentazzjoni tispeċifika gpt-transcribe, li tittraskrivi d-dawriet ivvalidati u tuża d-dawriet preċedenti bħala kuntest. Sorsi: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Sessjonijiet, avvenimenti, u ċ-ċiklu tal-ħajja

Kull konnessjoni WebSocket mar-Realtime API toħloq sessjoni. Din is-sessjoni hija l-unità fundamentali tal-ġestjoni: tinkapsula l-konfigurazzjoni tal-mudell, l-istorja tal-konversazzjoni, l-għodod disponibbli, u l-istat attwali tal-interazzjoni. Li tifhem iċ-ċiklu tal-ħajja tagħha huwa essenzjali biex tibni aġenti tal-leħen robusti.

Iċ-ċiklu tal-ħajja ta’ sessjoni

Hekk kif tiġi stabbilita l-konnessjoni WebSocket, is-server jemetti avveniment session.created. Is-sessjoni tgħaddi minn diversi fażijiet:

1

Konnessjoni → session.created

Is-server jikkonferma s-sessjoni b'ID uniku u konfigurazzjoni predefinita.

2

Konfigurazzjoni → session.update

Tibgħat session.update biex tiddefinixxi struzzjonijiet, leħen, għodod, u modalitajiet.

3

Konversazzjoni attiva

Skambju ta' avvenimenti tal-awdjo u t-test bejn il-klijent u s-server.

4

Għeluq → WebSocket disconnect

Is-sessjoni tinqered meta l-konnessjoni tingħalaq. L-ebda stat ma jinżamm fuq is-server.

Konfigurazzjoni ta’ sessjoni

Wara session.created, ibgħat avveniment session.update biex tikkonfigura l-imġiba tal-mudell. It-traskrizzjoni ta’ dak li jgħid l-utent (audio.input.transcription) hija għażla: mingħajrha, tirċievi l-leħen iżda mhux it-test. languages tispeċifika l-lingwi mistennija u ttejjeb ir-rikonoxximent:

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

        # Ikkonfigura s-sessjoni
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "Int assistent tal-leħen li jitkellem bil-Franċiż. "
                                "Wieġeb b'mod konċiż u naturali.",
                "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": []
            }
        }))

        # Stenna l-konferma (avvenimenti oħra jistgħu jaslu l-ewwel)
        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"])

Parametri ewlenin tas-sessjoni

Parametru Deskrizzjoni Valur rakkomandat
output_modalities Modalitajiet tal-output ["audio"] (jew ["text"])
audio.output.voice Leħen tas-sinteżi marin, cedar, alloy, echo, eċċ.
audio.input.turn_detection Rilevament tat-tmiem tal-kelma server_vad b'threshold 0.5
audio.input.format Format tal-awdjo li jidħol {"type": "audio/pcm", "rate": 24000}

Is-sistema tal-avvenimenti

Ir-Realtime API hija kompletament ibbażata fuq l-avvenimenti. Kull messaġġ skambjat huwa oġġett JSON b’qasam type li jiddetermina n-natura tiegħu. L-avvenimenti jaqgħu f’żewġ kategoriji:

Avvenimenti tal-klijent (inti → server)

# L-avvenimenti ewlenin li tibgħat
client_events = {
    "session.update":              "Immodifika l-konfigurazzjoni",
    "input_audio_buffer.append":   "Ibgħat biċċa awdjo",
    "input_audio_buffer.commit":   "Ikkonferma l-buffer tal-awdjo",
    "input_audio_buffer.clear":    "Neħħi l-buffer tal-awdjo",
    "conversation.item.create":    "Żid messaġġ manwalment",
    "conversation.item.truncate":  "Aqta' rispons qasir",
    "conversation.item.delete":    "Ħassar messaġġ",
    "response.create":             "Ibbotta rispons",
    "response.cancel":             "Ikkanċella r-rispons attwali",
}

Avvenimenti tas-server (server → inti)

# L-avvenimenti ewlenin li tirċievi
server_events = {
    "session.created":             "Sessjoni inizjalizzata",
    "session.updated":             "Konfigurazzjoni applikata",
    "input_audio_buffer.speech_started":  "Kelma nnutata",
    "input_audio_buffer.speech_stopped":  "Silenzju nnutat",
    "conversation.item.created":   "Messaġġ ġdid fl-istorja",
    "response.created":            "Ġenerazzjoni bdiet",
    "response.output_audio.delta":        "Biċċa awdjo tar-rispons",
    "response.output_audio_transcript.delta": "Biċċa traskrizzjoni",
    "response.done":               "Rispons lest",
    "error":                       "Żball",
}

Ġestjoni tal-iżbalji

L-iżbalji jiġu emessi permezz ta’ avveniment tat-tip error. Trid dejjem tinterċettahom:

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":
                # Żball fil-konfigurazzjoni, irranġa u erġa' pprova
                pass
            elif error["type"] == "server_error":
                # Problema fuq in-naħa ta' OpenAI, erġa' għaqqad
                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}")

Punti Ewlenin

  • Sessjoni tinħoloq awtomatikament mal-konnessjoni WebSocket u tinqered mad-disconnessione
  • session.update tikkonfigura s-sessjoni wara session.created; stenna session.updated qabel ma tiddependi fuq il-konfigurazzjoni l-ġdida
  • Biex tittraskrivi l-input f’sessjoni ta’ konversazzjoni, uża gpt-transcribe; gpt-live-transcribe hija riżervata għal sessjonijiet ta’ traskrizzjoni
  • Il-protokoll huwa purament ibbażat fuq l-avvenimenti: kull messaġġ għandu type li jiddetermina kif jiġi ttrattat
  • L-avvenimenti tal-klijent imexxu l-interazzjoni; l-avvenimenti tas-server jirrapportaw ir-riżultati
  • Il-ġestjoni tal-iżbalji hija kritika: dejjem isma’ għal avvenimenti error