Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Obvladovanje dogodkov WebSocket

Lekcija 4 od 14 Posodobljeno 29. julij 2026 Srednje napredni
Na tej strani
  1. Pogovor, sestavljen iz dogodkov JSON
  2. Kaj pošilja tvoja aplikacija
  3. Kaj pošilja strežnik nazaj
  4. Okostje odjemalca
  5. Težaven del: prekinitve
  6. Ključne ugotovitve

Pogovor, sestavljen iz dogodkov JSON

V ozadju je glasovna izmenjava z glasovnim agentom le tok sporočil JSON, ki tečeta v obe smeri prek povezave WebSocket. Vsako sporočilo ima polje type, ki pove, za kaj gre. Dokler ne poznaš tega besedišča, tvoj odjemalec deluje po naključju. Ko ga enkrat spoznaš, točno veš, kje poseči, da prekineš odgovor, prikažeš prepis ali si opomoreš po napaki.

Dogodki spadajo v dve družini, odvisno od smeri potovanja. Tisti, ki jih pošlješ ti, poganjajo sejo; tisti, ki jih prejmeš, ti povedo, kaj se dogaja na strežniku.

Kaj pošilja tvoja aplikacija

Tvoja odhodna sporočila pokrivajo štiri potrebe: konfiguracijo seje, polnjenje medpomnilnika zvoka, upravljanje zgodovine pogovora in nadzor generiranja odgovorov.

DogodekNamen
session.updateKonfigurira ali ponovno konfigurira sejo (glas, navodila, orodja, VAD, format zvoka)
input_audio_buffer.appendPošlje kos zvoka, kodiran v base64, neprekinjeno, medtem ko uporabnik govori
input_audio_buffer.commitPotrdi trenutno vsebino medpomnilnika kot uporabnikovo sporočilo; potrebno le v ročnem načinu
input_audio_buffer.clearIzprazni medpomnilnik zvoka brez obdelave
conversation.item.createDoda element v pogovor: besedilno sporočilo, zgodnejšo zgodovino ali rezultat klica funkcije
conversation.item.deleteIzbriše element pogovora po njegovem ID-ju
response.createProsi model, naj ustvari odgovor; samodejno v načinu VAD, izrecno v ročnem načinu
response.cancelPrekliče odgovor, ki se generira

Dve od teh sporočil si zaslužita natančnejši pogled. conversation.item.create je način, kako vbrizgaš kontekst: to uporabiš za obnovitev zgodovine prejšnjega klica na začetku nove seje. Kar zadeva input_audio_buffer.clear, pride prav, ko uporabnik očitno ni rekel ničesar vrednega obdelave (na primer čiščenje grla, ki ga je zajel preobčutljiv mikrofon), in bi raje začel znova s čistim medpomnilnikom, kot da bi modelu dovolil interpretirati šum.

Kaj pošilja strežnik nazaj

Dohodni tok je bolj živahen, saj podaja tekoči komentar vsakega koraka obdelave.

DogodekPomen
session.createdSeja je odprta
session.updatedPosodobitev konfiguracije je bila uporabljena
conversation.createdPogovor je nastavljen
input_audio_buffer.speech_startedVAD zazna, da je uporabnik začel govoriti
input_audio_buffer.speech_stoppedVAD zazna, da je uporabnik prenehal govoriti
input_audio_buffer.committedMedpomnilnik zvoka je bil potrjen, s strani VAD ali ročno
response.createdOdgovor se generira
response.output_audio.deltaKos odgovornega zvoka v base64
response.output_audio.doneOdgovorni zvok je končan
response.output_audio_transcript.deltaBesedilni prepis zvoka, pretakan
response.doneOdgovor je popolnoma končan
conversation.item.input_audio_transcription.completedPrepis uporabnikovega sporočila je na voljo
response.text.deltaPretok besedila za neodgovore, ki niso glasovni
response.function_call_arguments.deltaArgumenti klica funkcije, pretokani
response.function_call_arguments.doneKlic funkcije je končan in pripravljen za izvedbo
errorPrišlo je do napake; večino napak je mogoče odpraviti

Zadnji si zasluži opozorilo. Prejem error ne pomeni, da je seja izgubljena. Glede na referenčno dokumentacijo xAI je večino napak mogoče odpraviti in seja ostane odprta, zato odjemalec, ki ob prvem error zapre povezavo, prekine pogovor, ki bi se lahko nadaljeval. Zabeleži jo, obvesti uporabnika, če je potrebno, vendar ohrani vtičnico odprto.

Okostje odjemalca

V praksi se vse zreducira na stikalo msg.type. Tukaj je minimalna oblika odjemalca JavaScript:

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

  switch (msg.type) {
    case "session.created":
      // Pošlji session.update s konfiguracijo
      break;

    case "input_audio_buffer.speech_started":
      // Uporabnik govori: ustavi predvajanje odgovornega zvoka
      break;

    case "response.output_audio.delta":
      // Dekodiraj base64 in predvajaj zvok
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Izvedi funkcijo in pošlji rezultat nazaj
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Napaka glasovnega agenta:", msg.error);
      break;
  }
};

Štiri veje zadostujejo za zagon agenta: konfiguriraj ob odprtju seje, reagiraj, ko uporabnik začne govoriti, predvajaj dohodni zvok in izvajaj funkcije. Drugi dogodki obogatijo vmesnik in lahko počakajo na drugo iteracijo.

Težaven del: prekinitve

Barge-in, ko uporabnik začne govoriti, medtem ko agent še odgovarja, je trenutek, ko se pokaže površna izvedba. Strežnik samodejno prekliče trenutni odgovor in začne generirati novega na podlagi tega, kar je pravkar slišal. Toda medtem ko je strežnik prenehal pošiljati, tvoja aplikacija še vedno hrani več sekund že prejetega zvoka v svojem izhodnem medpomnilniku.

Če ne storiš ničesar, uporabnik še naprej sliši stavek, ki ga je pravkar prekinil, medtem ko govori čezenj, in agent deluje, kot da ne posluša. Zato takoj, ko prejmeš speech_started, ustavi predvajanje zvoka, izprazni izhodni medpomnilnik, da ne bi predvajal zastarelega zvoka, in dovoli strežniku obdelavo novega vhoda. Ta dva koraka zahtevata nekaj vrstic kode in naredita vso razliko med agentom, ki ga lahko prekineš, in tistim, ki govori v prazno.

Ključne ugotovitve

  • Dogodki odjemalca pokrivajo konfiguracijo, pošiljanje zvoka, upravljanje pogovora in nadzor odgovorov
  • Dogodki strežnika poročajo o zaznavi govora, kosih zvoka, prepisih in klicih funkcij
  • VAD samodejno obravnava prekinitve (barge-in)
  • Večina dogodkov error je odpravljivih: ne zapiraj povezave, obdelaj napako
  • V ročnem načinu moraš izrecno poklicati commit in nato response.create