Lähe põhisisu juurde
Eesti— Vali keel
Menüü

WebSocketi sündmuste valdamine

Õppetund 4 / 14 Värskendatud 29. juuli 2026 Kesktase
Sellel lehel
  1. Vestlus, mis koosneb JSON-sündmustest
  2. Mida sinu rakendus saadab
  3. Mida server tagasi saadab
  4. Kliendi luustik
  5. Libe koht: katkestused
  6. Peamised punktid

Vestlus, mis koosneb JSON-sündmustest

Telgitagustes on häälevahetus hääleagendiga lihtsalt JSON-sõnumite voog, mis liigub mõlemas suunas üle WebSocketi ühenduse. Igal sõnumil on väli type, mis määrab selle olemuse. Kuni sa seda sõnavara ei tunne, töötab sinu klient õnne najal. Kui aga tunned, tead täpselt, millal sekkuda, et vastus katkestada, transkripti kuvada või veast taastuda.

Sündmused jagunevad kahte perekonda sõltuvalt nende liikumissuunast. Need, mida sa saadad, juhivad seanssi; need, mida vastu võtad, annavad teada, mis serveris toimub.

Mida sinu rakendus saadab

Sinu väljuvad sõnumid katavad nelja vajadust: seansi konfigureerimine, helipuhvri toitmine, vestlusajaloo haldamine ja vastuse genereerimise juhtimine.

SündmusEesmärk
session.updateKonfigureerib või rekonfigureerib seanssi (hääl, juhised, tööriistad, VAD, helivorming)
input_audio_buffer.appendSaadab base64-kodeeritud helilõigu pidevalt, kui kasutaja räägib
input_audio_buffer.commitKinnitab praeguse puhvri sisu kasutaja sõnumina; vajalik ainult käsitsi režiimis
input_audio_buffer.clearTühjendab helipuhvri ilma seda töötlemata
conversation.item.createLisab vestlusele elemendi: tekstisõnum, varasem ajalugu või funktsioonikutsu tulemus
conversation.item.deleteKustutab vestluse elemendi selle ID põhjal
response.createPalub mudelil vastust genereerida; automaatne VAD-režiimis, eksplitsiitne käsitsi režiimis
response.cancelTühistab genereeritavat vastust

Kaks neist sõnumitest väärivad lähemat pilku. conversation.item.create on viis konteksti sisestamiseks: seda kasutad eelmise kõne ajaloo taastamiseks uue seansi alguses. Mis puutub input_audio_buffer.cleari, siis see tuleb kasuks, kui kasutaja ei öelnud selgelt midagi töötlemist väärt (näiteks köhatamine, mille liiga tundlik mikrofon kinni püüdis), ja eelistad alustada puhtalt puhvrilt, kui lasta mudelil müra tõlgendada.

Mida server tagasi saadab

Sissetulev voog on tihedam, kuna see annab jooksvat kommentaari iga töötlemisetapi kohta.

SündmusTähendus
session.createdSeanss on avatud
session.updatedKonfiguratsiooni uuendus on rakendatud
conversation.createdVestlus on seadistatud
input_audio_buffer.speech_startedVAD tuvastab, et kasutaja on rääkima hakanud
input_audio_buffer.speech_stoppedVAD tuvastab, et kasutaja on rääkimise lõpetanud
input_audio_buffer.committedHelipuhver on kinnitatud, kas VAD-i või käsitsi poolt
response.createdVastust genereeritakse
response.output_audio.deltaVastuse helilõik base64-koodingus
response.output_audio.doneVastuse heli on täielik
response.output_audio_transcript.deltaHeli tekstiline transkript, voogedastatuna
response.doneVastus on täielikult lõpetatud
conversation.item.input_audio_transcription.completedKasutaja sõnumi transkript on saadaval
response.text.deltaVoogedastatav tekst mitte-häälvastuste jaoks
response.function_call_arguments.deltaFunktsioonikutsu argumendid, voogedastatuna
response.function_call_arguments.doneFunktsioonikutsu on lõpetatud ja valmis käivitamiseks
errorTekkis viga; enamik vigu on taastatavad

Viimane neist vajab hoiatust. error saamine ei tähenda, et seanss on kadunud. xAI referentsi kohaselt on enamik vigu taastatavad ja seanss jääb avatuks, nii et klient, mis sulgeb ühenduse esimese error peal, katkestab vestluse, mis oleks võinud jätkuda. Logi see, teavita kasutajat vajadusel, kuid hoia sokkel avatuna.

Kliendi luustik

Praktikas taandub kõik msg.type põhjal lülitusele. Siin on JavaScripti kliendi minimaalne kuju:

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

  switch (msg.type) {
    case "session.created":
      // Saada session.update koos konfiguratsiooniga
      break;

    case "input_audio_buffer.speech_started":
      // Kasutaja räägib: peata esitatav vastuse heli
      break;

    case "response.output_audio.delta":
      // Dekodeeri base64 ja esita heli
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Käivita funktsioon ja saada tulemus tagasi
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Hääleagendi viga:", msg.error);
      break;
  }
};

Agenti käitamiseks piisab neljast harust: konfigureeri seansi avamisel, reageeri kasutaja rääkima hakkamisel, esita sissetulevat heli ja käivita funktsioone. Teised sündmused rikastavad liidest ja võivad oodata teist iteratsiooni.

Libe koht: katkestused

Barge-in, olukord, kus kasutaja hakkab rääkima ajal, kui agent veel vastab, on koht, kus hooletu implementatsioon end reedab. Server tühistab jooksva vastuse ise ja hakkab genereerima uut vastust selle põhjal, mida ta just kuulis. Kuid samal ajal kui server on saatmise lõpetanud, hoiab sinu rakendus väljundpuhvris endiselt mitu sekundit juba vastuvõetud heli.

Kui sa midagi ei tee, kuuleb kasutaja lauset, mida ta just katkestas, edasi, rääkides sellele peale, ja agent jätab mulje, nagu ei kuulaks. Seega niipea, kui saad speech_started, peata esitatav heli, tühjenda väljundpuhver, et vananenud heli ei esitataks, ja lase serveril uut sisendit töödelda. Need kaks sammu võtavad paar rida koodi ja teevad vahet agendi vahel, mida saab katkestada, ja sellise vahel, mis räägib tühjusesse.

Peamised punktid

  • Kliendi sündmused katavad konfiguratsiooni, heli saatmist, vestluse haldamist ja vastuste juhtimist
  • Serveri sündmused teavitavad kõne tuvastamisest, helilõikudest, transkriptidest ja funktsioonikutsetest
  • VAD haldab katkestusi (barge-in) automaatselt
  • Enamik error sündmusi on taastatavad: ära sulge ühendust, hinda viga
  • Käsitsi režiimis pead kutsuma commit ja seejärel response.create eksplitsiitselt