Seansai, įvykiai ir gyvavimo ciklas
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. — Garso modeliai. Keli šio kurso modeliai yra pasenę:
tts-1,tts-1-hdirgpt-4o-mini-ttsnustos veikti 2027 m. sausio 6 d. (pakaitalas:gpt-realtime-2.1-mini, kuris, kaip nurodo „OpenAI“ TTS gidas, nepalaikomas per/v1/audio/speech: kalbos sintezės migracija perkeliama į „Realtime API“);gpt-realtime,gpt-4o-realtimeir senieji garso modeliai nustos veikti 2027 m. sausio 20 d. (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeir/v1/audio/translationsnustos veikti 2027 m. vasario 26 d. (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pilno dublekso (full-duplex) balsui „GPT-Live 1“ API yra prieinamas nuo 2026 m. rugsėjo 10 d.
Ištaisyta 2026 m. lapkričio 3 d. Įvesties transkripcijai buvo naudojamas
gpt-live-transcribe, kuris veikia tik transkripcijos seanse ir nepalaiko neiserver_vad, neisemantic_vad. Pokalbio seanse, kaip šis, kuriame VAD patvirtina kiekvieną repliką, dokumentacijoje nurodoma naudotigpt-transcribe, kuris transkribuoja patvirtintas replikas ir naudoja ankstesnes replikas kaip kontekstą. Šaltiniai: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Seansai, įvykiai ir gyvavimo ciklas
Kiekvienas „WebSocket“ ryšys su „Realtime API“ sukuria seansą. Šis seansas yra pagrindinis valdymo vienetas: jame įtraukta modelio konfigūracija, pokalbių istorija, galimi įrankiai ir dabartinė sąveikos būsena. Norint kurti patikimus balso agentus, būtina suprasti jo gyvavimo ciklą.
Seanso gyvavimo ciklas
Kai tik užmezgamas „WebSocket“ ryšys, serveris išsiunčia session.created įvykį. Seansas pereina kelias fazes:
Ryšys → session.created
Serveris patvirtina seansą unikaliu ID ir numatytąja konfigūracija.
Konfigūracija → session.update
Siunči „session.update“, kad nustatytum instrukcijas, balsą, įrankius ir modalumus.
Aktyvus pokalbis
Garso ir teksto įvykių mainai tarp kliento ir serverio.
Uždarymas → WebSocket disconnect
Seansas sunaikinamas uždarus ryšį. Serveryje jokia būsena neišsaugoma.
Seanso konfigūravimas
Po session.created išsiųsk session.update įvykį modelio elgsenai konfigūruoti. Vartotojo sakomų žodžių transkripcija (audio.input.transcription) yra neprivaloma: jos nenaudojant gausite balsą, bet ne tekstą. Parametras languages nurodo tikėtinas kalbas ir pagerina atpažinimą:
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:
# Laukiama session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Konfigūruojamas seansas
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": []
}
}))
# Laukiama patvirtinimo (pirmiau gali atvykti kiti įvykiai)
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"])
Pagrindiniai seanso parametrai
| Parametras | Aprašymas | Rekomenduojama reikšmė |
|---|---|---|
| output_modalities | Išvesties modalumai | ["audio"] (arba ["text"]) |
| audio.output.voice | Sintezės balsas | marin, cedar, alloy, echo ir kt. |
| audio.input.turn_detection | Kalbos pabaigos aptikimas | server_vad su slenksčiu 0.5 |
| audio.input.format | Gaunamo garso formatas | {"type": "audio/pcm", "rate": 24000} |
Įvykių sistema
„Realtime API“ yra visiškai valdoma įvykių. Kiekviena išsiųsta žinutė yra JSON objektas su lauku type, kuris nulemia jos pobūdį. Įvykiai skirstomi į dvi kategorijas:
Kliento įvykiai (tu → serveris)
# Pagrindiniai tavo siunčiami įvykiai
client_events = {
"session.update": "Konfigūracijos keitimas",
"input_audio_buffer.append": "Garso fragmento siuntimas",
"input_audio_buffer.commit": "Garso buferio fiksavimas",
"input_audio_buffer.clear": "Garso buferio išvalymas",
"conversation.item.create": "Žinutės rankinis pridėjimas",
"conversation.item.truncate": "Atsakymo sutrumpinimas",
"conversation.item.delete": "Žinutės ištrynimas",
"response.create": "Atsakymo generavimo inicijavimas",
"response.cancel": "Dabartinio atsakymo atšaukimas",
}
Serverio įvykiai (serveris → tu)
# Pagrindiniai tavo gaunami įvykiai
server_events = {
"session.created": "Seansas inicializuotas",
"session.updated": "Konfigūracija pritaikyta",
"input_audio_buffer.speech_started": "Aptikta kalba",
"input_audio_buffer.speech_stopped": "Aptikta tyla",
"conversation.item.created": "Nauja žinutė istorijoje",
"response.created": "Generavimas pradėtas",
"response.output_audio.delta": "Atsakymo garso fragmentas",
"response.output_audio_transcript.delta": "Transkripcijos fragmentas",
"response.done": "Atsakymas baigtas",
"error": "Klaida",
}
Klaidų valdymas
Klaidos perduodamos per error tipo įvykį. Jas visada turi perimti:
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":
# Konfigūracijos klaida, reikia ištaisyti ir bandyti iš naujo
pass
elif error["type"] == "server_error":
# Problema „OpenAI“ pusėje, reikia prisijungti iš naujo
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}")
Svarbiausi punktai
- Seansas automatiškai sukuriamas užmezgus „WebSocket“ ryšį ir sunaikinamas jį nutraukus.
session.updatekonfigūruoja seansą posession.created; prieš pasikliaujant nauja konfigūracija, palauksession.updated.- Norint transkribuoti įvestį pokalbio seanse, naudok
gpt-transcribe;gpt-live-transcribeskirtas tik transkripcijos seansams. - Protokolas yra grynas įvykiais grįstas protokolas: kiekviena žinutė turi
type, kuris nulemia jos apdorojimą. - Kliento įvykiai valdo sąveiką; serverio įvykiai praneša apie rezultatus.
- Klaidų valdymas yra kritiškai svarbus: visada klausykis
errorįvykių.