Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Valdykite WebSocket įvykius

Paskaita 4 iš 14 Atnaujinta 2026 m. liepos 29 d. Vidutinis lygis
Šiame puslapyje
  1. Pokalbis, sudarytas iš JSON įvykių
  2. Ką siunčia tavo programa
  3. Ką siunčia serveris
  4. Kliento struktūra
  5. Sudėtinga dalis: pertraukimai
  6. Svarbiausi punktai

Pokalbis, sudarytas iš JSON įvykių

Iš esmės balso mainai su „Voice Agent“ yra tiesiog JSON žinučių srautas, tekantis abiem kryptimis per WebSocket ryšį. Kiekviena žinutė turi lauką type, nurodantį, kas ji yra. Kol neišmoksi šios terminijos, tavo klientas veiks atsitiktinai. Kai ją įvaldysi, tiksliai žinosi, kur įsikišti, kad nutrauktum atsakymą, parodytum transkriptą arba atkurtum veikimą po klaidos.

Įvykiai skirstomi į dvi šeimas, priklausomai nuo jų krypties. Tie, kuriuos siunti tu, valdo sesiją; tie, kuriuos gauni, praneša, kas vyksta serveryje.

Ką siunčia tavo programa

Tavo siunčiamos žinutės tenkina keturis poreikius: sesijos konfigūravimą, garso buferio pildymą, pokalbio istorijos valdymą ir atsakymų generavimo kontrolę.

ĮvykisPaskirtis
session.updateKonfigūruoja arba perkonfigūruoja sesiją (balsą, instrukcijas, įrankius, VAD, garso formatą)
input_audio_buffer.appendSiunčia base64 koduotą garso gabalėlį nuolat, kol vartotojas kalba
input_audio_buffer.commitĮtvirtina dabartinio buferio turinį kaip vartotojo žinutę; reikia tik rankiniu režimu
input_audio_buffer.clearIšvalo garso buferį jo neapdorojant
conversation.item.createPrideda elementą į pokalbį: teksto žinutę, ankstesnę istoriją arba funkcijos kvietimo rezultatą
conversation.item.deleteIštrina pokalbio elementą pagal jo ID
response.createPrašo modelio sugeneruoti atsakymą; automatinis VAD režimu, aiškus rankiniu režimu
response.cancelAtšaukia generuojamą atsakymą

Dvi iš šių žinučių nusipelno dėmesio. conversation.item.create yra būdas įterpti kontekstą: tai naudojama atkurti ankstesnio skambučio istoriją naujos sesijos pradžioje. O input_audio_buffer.clear pravartu, kai vartotojas akivaizdžiai nepasakė nieko verto apdoroti (pvz., kosulys, kurį užfiksavo per jautrus mikrofonas) ir nori pradėti iš švaraus buferio, užuot leidęs modeliui interpretuoti triukšmą.

Ką siunčia serveris

Gaunamas srautas intensyvesnis, nes jis komentuoja kiekvieną apdorojimo žingsnį realiuoju laiku.

ĮvykisReikšmė
session.createdSesija atidaryta
session.updatedKonfigūracijos atnaujinimas pritaikytas
conversation.createdPokalbis sukurtas
input_audio_buffer.speech_startedVAD aptiko, kad vartotojas pradėjo kalbėti
input_audio_buffer.speech_stoppedVAD aptiko, kad vartotojas nutilo
input_audio_buffer.committedGarso buferis įtvirtintas (automatiškai per VAD arba rankiniu būdu)
response.createdGeneruojamas atsakymas
response.output_audio.deltaAtsakymo garso gabalėlis (base64)
response.output_audio.doneAtsakymo garso srautas baigtas
response.output_audio_transcript.deltaTekstinis garso transkriptas, siunčiamas srautu
response.doneAtsakymas visiškai baigtas
conversation.item.input_audio_transcription.completedVartotojo žinutės transkriptas paruoštas
response.text.deltaSrautinis tekstas atsakymams, kurie nėra balsiniai
response.function_call_arguments.deltaFunkcijos kvietimo argumentai, siunčiami srautu
response.function_call_arguments.doneFunkcijos kvietimas baigtas ir paruoštas vykdyti
errorĮvyko klaida; daugumą klaidų galima ištaisyti

Paskutiniam punktui reikia įspėjimo. Gavus error, sesija nebūtinai prarandama. Pagal xAI dokumentaciją, daugumą klaidų galima ištaisyti, o sesija lieka atidaryta, todėl klientas, uždarantis ryšį po pirmosios error, nutraukia pokalbį, kuris galėjo tęstis. Užfiksuok klaidą, prireikus informuok vartotoją, bet laikyk lizdą atvirą.

Kliento struktūra

Praktiškai viskas sumažėja iki msg.type perjungimo. Štai minimali JavaScript kliento struktūra:

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

  switch (msg.type) {
    case "session.created":
      // Siųsti session.update su konfigūracija
      break;

    case "input_audio_buffer.speech_started":
      // Vartotojas kalba: sustabdyti grojamą atsakymo garsą
      break;

    case "response.output_audio.delta":
      // Iššifruoti base64 ir groti garsą
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Vykdyti funkciją ir siųsti rezultatą atgal
      handleFunctionCall(msg);
      break;

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

Keturių šakų pakanka agentui valdyti: konfigūruoti atidarius sesiją, reaguoti, kai vartotojas pradeda kalbėti, groti gaunamą garsą ir vykdyti funkcijas. Kiti įvykiai praturtina sąsają ir gali palaukti antrosios iteracijos.

Sudėtinga dalis: pertraukimai

„Barge-in“ (kai vartotojas pradeda kalbėti agentui dar atsakant) – tai momentas, kai išryškėja netobulas įgyvendinimas. Serveris pats atšaukia dabartinį atsakymą ir pradeda generuoti naują pagal tai, ką ką tik išgirdo. Tačiau kol serveris nustojo siųsti, tavo programa vis dar turi kelias sekundes jau gauto garso išvesties buferyje.

Jei nieko nedarysi, vartotojas toliau girdės sakinį, kurį ką tik pertraukė, kalbėdamas jam per galvą, o agentas atrodys negirdintis. Todėl vos gavęs speech_started, nedelsdamas sustabdyk grojamą garsą, išvalyk išvesties buferį, kad negrobtum pasenusio garso, ir leisk serveriui apdoroti naują įvestį. Šie du veiksmai užtrunka keletą kodo eilučių, tačiau jie lemia skirtumą tarp agento, kurį galima pertraukti, ir to, kuris kalba į tuštumą.

Svarbiausi punktai

  • Kliento įvykiai apima konfigūravimą, garso siuntimą, pokalbio valdymą ir atsakymų kontrolę
  • Serverio įvykiai praneša apie kalbos aptikimą, garso gabalėlius, transkriptus ir funkcijų kvietimus
  • VAD automatiškai valdo pertraukimus (barge-in)
  • Dauguma error įvykių yra taisomi: neužverk ryšio, tvarkyk klaidą
  • Rankiniu režimu turi aiškiai iškviesti commit, o tada response.create