Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

WebSocket-események elsajátítása

4. lecke 14 közül Frissítve 2026. július 29. Középhaladó
Ezen az oldalon
  1. JSON-eseményekből álló beszélgetés
  2. Amit az alkalmazásod küld
  3. Amit a szerver visszaküld
  4. Egy kliens váza
  5. A trükkös rész: megszakítások
  6. Főbb megállapítások

JSON-eseményekből álló beszélgetés

A motorháztető alatt a Voice Agenttel folytatott hangalapú beszélgetés nem más, mint JSON-üzenetek folyamatos áramlása oda-vissza a WebSocket-kapcsolaton keresztül. Minden üzenet tartalmaz egy type mezőt, amely meghatározza a típusát. Amíg nem ismered ezt a szókincset, a kliensed csak a szerencsére hagyatkozik. Ha viszont elsajátítod, pontosan tudni fogod, hol kell beavatkoznod egy válasz megszakításához, egy átírás megjelenítéséhez vagy egy hiba helyreállításához.

Az események két családba sorolhatók az utazásuk iránya alapján. Az általad küldöttek vezérlik a munkamenetet; a fogadottak pedig tájékoztatnak arról, mi történik a szerveren.

Amit az alkalmazásod küld

A kimenő üzeneteid négy igényt fednek le: a munkamenet konfigurálását, a hangpuffer feltöltését, a beszélgetési előzmények kezelését és a válaszgenerálás vezérlését.

EseményCél
session.updateKonfigurálja vagy újrakonfigurálja a munkamenetet (hang, utasítások, eszközök, VAD, hangformátum)
input_audio_buffer.appendBase64-kódolt hangrészt küld folyamatosan, amíg a felhasználó beszél
input_audio_buffer.commitRögzíti a jelenlegi puffer tartalmát felhasználói üzenetként; csak kézi módban szükséges
input_audio_buffer.clearKiüríti a hangpuffert feldolgozás nélkül
conversation.item.createHozzáad egy elemet a beszélgetéshez: szöveges üzenetet, korábbi előzményt vagy egy függvényhívás eredményét
conversation.item.deleteTöröl egy beszélgetési elemet az azonosítója alapján
response.createKéri a modellt válasz generálására; VAD módban automatikus, kézi módban explicit
response.cancelMegszakít egy generálás alatt álló választ

Két üzenet deserves külön figyelmet. A conversation.item.create a kontextus beillesztésének eszköze: ezzel állítod helyre egy korábbi hívás előzményeit egy új munkamenet elején. Az input_audio_buffer.clear pedig akkor jön jól, ha a felhasználó egyértelműen nem mondott semmi feldolgozásra érdemeset (például egy túl érzékeny mikrofon által felvett köhögés), és inkább tiszta lappal indítanád újra, mintsem hagynád, hogy a modell zajt értelmezzen.

Amit a szerver visszaküld

A bejövő folyamatos forgalmasabb, mivel minden feldolgozási lépésről futó kommentárt ad.

EseményJelentés
session.createdA munkamenet megnyílt
session.updatedEgy konfigurációs frissítés alkalmazásra került
conversation.createdA beszélgetés beállítva
input_audio_buffer.speech_startedA VAD érzékeli, hogy a felhasználó beszélni kezdett
input_audio_buffer.speech_stoppedA VAD érzékeli, hogy a felhasználó abbahagyta a beszédet
input_audio_buffer.committedA hangpuffer rögzítve lett, VAD által vagy kézzel
response.createdVálasz generálása folyamatban
response.output_audio.deltaA válaszhang egy része, base64 formátumban
response.output_audio.doneA válaszhang teljes
response.output_audio_transcript.deltaA hang szöveges átírása, streamelve
response.doneA válasz teljesen befejeződött
conversation.item.input_audio_transcription.completedA felhasználói üzenet átírása elérhető
response.text.deltaStreamelt szöveg nem hangalapú válaszokhoz
response.function_call_arguments.deltaEgy függvényhívás argumentumai, streamelve
response.function_call_arguments.doneA függvényhívás teljes, és készen áll a futtatásra
errorHiba történt; a legtöbb hiba helyreállítható

Az utolsónál egy figyelmeztetés szükséges. Az error fogadása nem azt jelenti, hogy elveszett a munkamenet. Az xAI referenciája szerint a legtöbb hiba helyreállítható, és a munkamenet nyitva marad, így egy olyan kliens, amely az első error esetén bezárja a kapcsolatot, megszakít egy olyan beszélgetést, amely folytatható lett volna. Naplózd, közöld a felhasználóval, ha szükséges, de tartsd nyitva a socketet.

Egy kliens váza

A gyakorlatban minden a msg.type szerinti elágazáson múlik. Íme egy JavaScript kliens minimális felépítése:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "session.created":
      // session.update küldése a konfigurációval
      break;

    case "input_audio_buffer.speech_started":
      // A felhasználó beszél: állítsd le a lejátszott válaszhangot
      break;

    case "response.output_audio.delta":
      // Dekódold a base64-et és játszd le a hangot
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Futtasd a függvényt és küldd vissza az eredményt
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Voice Agent hiba:", msg.error);
      break;
  }
};

Négy elágazás is elég egy ügynök futtatásához: konfigurálás a munkamenet megnyitásakor, reakció a felhasználó beszédkezdetére, a bejövő hang lejátszása és a függvények futtatása. A többi esemény gazdagítja a felületet, és ráérnek egy második iterációra.

A trükkös rész: megszakítások

A „barge-in“, amikor a felhasználó beszélni kezd, miközben az ügynök még válaszol, az a pont, ahol a hanyag implementáció lebukik. A szerver maga szakítja meg az aktuális választ, és elkezdi generálni az újat abból, amit éppen hallott. De míg a szerver abbahagyta a küldést, az alkalmazásod még mindig több másodpercnyi már megkapott hangot tart a kimeneti pufferében.

Ha nem csinálsz semmit, a felhasználó továbbra is hallja azt a mondatot, amit éppen megszakított, miközben beszél rá, és az ügynök úgy tűnik, mintha nem figyelne. Ezért amint megkapod a speech_started eseményt, állítsd le a lejátszott hangot, ürítsd ki a kimeneti puffert, hogy ne játssz le elavult hangot, és hagyd, hogy a szerver feldolgozza az új bemenetet. Ez a két lépés néhány sor kódot igényel, és ez teszi a különbséget egy megszakítható ügynök és egy olyan között, amely a levegőbe beszél.

Főbb megállapítások

  • A kliensesemények lefedik a konfigurálást, a hangküldést, a beszélgetés kezelését és a válaszok vezérlését
  • A szerveresemények jelentik a beszédészlelést, a hangrészeket, az átírásokat és a függvényhívásokat
  • A VAD automatikusan kezeli a megszakításokat (barge-in)
  • A legtöbb error esemény helyreállítható: ne zárd be a kapcsolatot, kezeld a hibát
  • Kézi módban expliciten meg kell hívnod a commit-ot, majd a response.create-ot