WebSocket-események elsajátítása
Ezen az oldalon
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ény | Cél |
|---|---|
session.update | Konfigurálja vagy újrakonfigurálja a munkamenetet (hang, utasítások, eszközök, VAD, hangformátum) |
input_audio_buffer.append | Base64-kódolt hangrészt küld folyamatosan, amíg a felhasználó beszél |
input_audio_buffer.commit | Rögzíti a jelenlegi puffer tartalmát felhasználói üzenetként; csak kézi módban szükséges |
input_audio_buffer.clear | Kiüríti a hangpuffert feldolgozás nélkül |
conversation.item.create | Hozzá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.delete | Töröl egy beszélgetési elemet az azonosítója alapján |
response.create | Kéri a modellt válasz generálására; VAD módban automatikus, kézi módban explicit |
response.cancel | Megszakí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ény | Jelentés |
|---|---|
session.created | A munkamenet megnyílt |
session.updated | Egy konfigurációs frissítés alkalmazásra került |
conversation.created | A beszélgetés beállítva |
input_audio_buffer.speech_started | A VAD érzékeli, hogy a felhasználó beszélni kezdett |
input_audio_buffer.speech_stopped | A VAD érzékeli, hogy a felhasználó abbahagyta a beszédet |
input_audio_buffer.committed | A hangpuffer rögzítve lett, VAD által vagy kézzel |
response.created | Válasz generálása folyamatban |
response.output_audio.delta | A válaszhang egy része, base64 formátumban |
response.output_audio.done | A válaszhang teljes |
response.output_audio_transcript.delta | A hang szöveges átírása, streamelve |
response.done | A válasz teljesen befejeződött |
conversation.item.input_audio_transcription.completed | A felhasználói üzenet átírása elérhető |
response.text.delta | Streamelt szöveg nem hangalapú válaszokhoz |
response.function_call_arguments.delta | Egy függvényhívás argumentumai, streamelve |
response.function_call_arguments.done | A függvényhívás teljes, és készen áll a futtatásra |
error | Hiba 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
erroresemé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 aresponse.create-ot