Sessjonijiet, avvenimenti, u ċ-ċiklu tal-ħajja
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026 — Mudelli tal-awdjo. Diversi mudelli f’dan il-kors huma skaduti:
tts-1,tts-1-hd, ugpt-4o-mini-ttsse 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/translationsfis-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ġġjaxserver_vadjewsemantic_vad. F’sessjoni ta’ konversazzjoni bħal din, fejn il-VAD jivvalida kull dawra, id-dokumentazzjoni tispeċifikagpt-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:
Konnessjoni → session.created
Is-server jikkonferma s-sessjoni b'ID uniku u konfigurazzjoni predefinita.
Konfigurazzjoni → session.update
Tibgħat session.update biex tiddefinixxi struzzjonijiet, leħen, għodod, u modalitajiet.
Konversazzjoni attiva
Skambju ta' avvenimenti tal-awdjo u t-test bejn il-klijent u s-server.
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.updatetikkonfigura s-sessjoni warasession.created; stennasession.updatedqabel ma tiddependi fuq il-konfigurazzjoni l-ġdida- Biex tittraskrivi l-input f’sessjoni ta’ konversazzjoni, uża
gpt-transcribe;gpt-live-transcribehija riżervata għal sessjonijiet ta’ traskrizzjoni - Il-protokoll huwa purament ibbażat fuq l-avvenimenti: kull messaġġ għandu
typeli 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