Munkamenetek, események és életciklus
Ezen az oldalon
Frissítve: 2026. november 2. – Hangmodellek. A tanfolyam több modellje elavult: a
tts-1,tts-1-hdés agpt-4o-mini-ttsmodellek 2027. január 6-án megszűnnek működési (helyettesítőjük:gpt-realtime-2.1-mini, amelyet az OpenAI TTS útmutatója szerint nem támogat a/v1/audio/speech: a beszédszintézis migrációja a Realtime API-ra helyeződik át); agpt-realtime,gpt-4o-realtimeés a régi hangmodellek 2027. január 20-án válnak elavulttá (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5); awhisper-1,gpt-4o-transcribeés a/v1/audio/translationsvégpontok 2027. február 26-án szűnnek meg (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). A teljes duplex hangalapú kommunikációhoz a GPT-Live 1 már 2026. szeptember 10. óta elérhető az API-ban.
Helyesbítve: 2026. november 3. A bemeneti átírás korábban a
gpt-live-transcribemodellt használta, amely kizárólag átírási munkamenetben működik, és nem támogatja sem aserver_vad, sem asemantic_vadfunkciót. Egy ilyen beszélgetési munkamenetben, ahol a VAD (Voice Activity Detection) minden fordulót érvényesít, a dokumentáció agpt-transcribehasználatát írja elő; ez a modell az érvényesített fordulókat írja át, és a korábbi fordulókat kontextusként kezeli. Források: Realtime átírás · GPT-Transcribe · GPT-Live-Transcribe.
Munkamenetek, események és életciklus
Minden WebSocket-kapcsolat a Realtime API-val létrehoz egy munkamenetet (session). Ez a munkamenet a kezelés alapvető egysége: ez foglalja magában a modellkonfigurációt, a beszélgetés előzményeit, az elérhető eszközöket és az interakció aktuális állapotát. Életciklusának megértése elengedhetetlen a robusztus hangalapú ügynökök fejlesztéséhez.
A munkamenet életciklusa
Amint a WebSocket-kapcsolat létrejön, a szerver kibocsát egy session.created eseményt. A munkamenet több fázison megy keresztül:
Kapcsolódás → session.created
A szerver egy egyedi azonosítóval és alapértelmezett konfigurációval erősíti meg a munkamenetet.
Konfigurálás → session.update
Küldj egy session.update eseményt az utasítások, a hang, az eszközök és a modalitások meghatározásához.
Aktív beszélgetés
Hang- és szövegesemények cseréje a kliens és a szerver között.
Lezárás → WebSocket bontás
A munkamenet megsemmisül, amikor a kapcsolat megszakad. A szerver nem őriz meg állapotot.
Munkamenet konfigurálása
A session.created esemény után küldj egy session.update eseményt a modell viselkedésének beállításához. A felhasználó beszédének átírása (audio.input.transcription) opcionális: enélkül csak a hangot kapod meg, a szöveget nem. A languages paraméter meghatározza a várt nyelveket, és javítja a felismerés pontosságát:
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:
# Várakozás a session.created eseményre
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Munkamenet létrehozva: {session_id}")
# Munkamenet konfigurálása
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "Te egy francia nyelvű hangalapú asszisztens vagy. "
"Válaszolj tömören és természetesen.",
"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": []
}
}))
# Várakozás a megerősítésre (más események érkezhetnek előbb)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Munkamenet frissítve")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Főbb munkamenet-paraméterek
| Paraméter | Leírás | Ajánlott érték |
|---|---|---|
| output_modalities | Kimeneti modalitások | ["audio"] (vagy ["text"]) |
| audio.output.voice | Szintetizált hang | marin, cedar, alloy, echo stb. |
| audio.input.turn_detection | Beszédvég-észlelés | server_vad 0.5-ös küszöbértékkel |
| audio.input.format | Bejövő hangformátum | {"type": "audio/pcm", "rate": 24000} |
Az eseményrendszer
A Realtime API teljes mértékben eseményvezérelt. Minden váltott üzenet egy JSON-objektum, amely tartalmaz egy type mezőt; ez határozza meg az üzenet jellegét. Az események két kategóriába sorolhatók:
Kliens események (te → szerver)
# A főbb események, amelyeket küldesz
client_events = {
"session.update": "Konfiguráció módosítása",
"input_audio_buffer.append": "Hangrészlet küldése",
"input_audio_buffer.commit": "Hangpuffer véglegesítése",
"input_audio_buffer.clear": "Hangpuffer törlése",
"conversation.item.create": "Üzenet manuális hozzáadása",
"conversation.item.truncate": "Válasz csonkolása",
"conversation.item.delete": "Üzenet törlése",
"response.create": "Válasz generálásának indítása",
"response.cancel": "Aktuális válasz megszakítása",
}
Szerver események (szerver → te)
# A főbb események, amelyeket kapsz
server_events = {
"session.created": "Munkamenet inicializálva",
"session.updated": "Konfiguráció alkalmazva",
"input_audio_buffer.speech_started": "Beszéd észlelve",
"input_audio_buffer.speech_stopped": "Csend észlelve",
"conversation.item.created": "Új üzenet az előzményekben",
"response.created": "Generálás elindult",
"response.output_audio.delta": "Válasz hangrészlete",
"response.output_audio_transcript.delta": "Átírási részlet",
"response.done": "Válasz befejeződött",
"error": "Hiba",
}
Hibakezelés
A hibákat egy error típusú esemény bocsátja ki. Ezeket mindig el kell csípned:
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"Hiba [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Konfigurációs hiba, javítsd és próbáld újra
pass
elif error["type"] == "server_error":
# Probléma az OpenAI oldalán, csatlakozz újra
pass
elif event_type == "session.updated":
print("Konfiguráció sikeresen alkalmazva")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Felhasznált tokenek: {usage}")
Főbb megállapítások
- A munkamenet automatikusan létrejön a WebSocket-kapcsolódáskor, és a kapcsolat bontásakor megsemmisül
- A
session.updateasession.createdután konfigurálja a munkamenetet; várj asession.updatedeseményre, mielőtt az új konfigurációra támaszkodnál - Beszélgetési munkamenetben a bemenet átírásához használd a
gpt-transcribemodellt; agpt-live-transcribekizárólag átírási munkamenetekre van fenntartva - A protokoll tisztán eseményvezérelt: minden üzenet rendelkezik egy
typemezővel, amely meghatározza a kezelését - A kliens események vezérlik az interakciót; a szerver események jelentik az eredményeket
- A hibakezelés kritikus fontosságú: mindig figyeld az
erroreseményeket