Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Timmustra l-avvenimenti ta' WebSocket

Lezzjoni 4 / 14 Aġġornat 29 ta’ Lulju 2026 Livell Medju
F'din il-paġna
  1. Konversazzjoni magħmula minn avvenimenti JSON
  2. X’tibgħat l-app tiegħek
  3. X’jibgħat lura s-server
  4. L-istruttura ta’ klijent
  5. Il-parti diffiċli: l-interruzzjonijiet
  6. Punti Ewlenin

Konversazzjoni magħmula minn avvenimenti JSON

Fil-qalba tagħha, skambju vuwkali mal-Aġent Vuwkali huwa sempliċiment fluss ta’ messaġġi JSON li jgħaddu fiż-żewġ direzzjonijiet fuq il-konnessjoni WebSocket. Kull messaġġ għandu qasam type li jgħidlek x’inhu. Sakemm ma tkunx taf dan il-vokabolarju, il-klijent tiegħek jaħdem bix-xorti. Meta tkun tafu, tkun taf eżattament fejn tidħol biex taqta’ tweġiba, turi transkrizzjoni, jew tirkupra minn żball.

L-avvenimenti jaqgħu f’żewġ familji, skont id-direzzjoni li jieħdu. Dawk li tibgħat inti jmexxu s-sessjoni; dawk li tirċievi jgħidulek x’qed jiġri fuq is-server.

X’tibgħat l-app tiegħek

Il-messaġġi li tibgħat barra jkopru erba’ ħtiġijiet: konfigurazzjoni tas-sessjoni, forniment tal-buffer tal-awdjo, ġestjoni tal-istorja tal-konversazzjoni, u kontroll tal-ġenerazzjoni tat-tweġibiet.

AvvenimentGħan
session.updateJikkonfigura jew jikkonfigura mill-ġdid is-sessjoni (vuċi, struzzjonijiet, għodod, VAD, format tal-awdjo)
input_audio_buffer.appendJibgħat biċċa awdjo kodifikata f’base64, kontinwament waqt li l-utent ikun qed jitkellem
input_audio_buffer.commitJikkonferma l-kontenut attwali tal-buffer bħala l-messaġġ tal-utent; meħtieġ biss fil-modalità manwali
input_audio_buffer.clearJibattal il-buffer tal-awdjo mingħajr ma jipproċessah
conversation.item.createIżid oġġett fil-konversazzjoni: messaġġ testwali, storja preċedenti, jew riżultat ta’ sejħa ta’ funzjoni
conversation.item.deleteIħassar oġġett tal-konversazzjoni bl-ID tiegħu
response.createJitlob lill-mudell biex jiġġenera tweġiba; awtomatiku fil-modalità VAD, espliċitu fil-modalità manwali
response.cancelJikkanċella tweġiba li qed tiġi ġġenerata

Żewġ messaġġi minn dawn jistħoqqilhom ħarsa eqreb. conversation.item.create huwa kif tinjetta l-kuntest: dan huwa dak li tuża biex tirrestawra l-istorja ta’ sejħa preċedenti fil-bidu ta’ sessjoni ġdida. Għal input_audio_buffer.clear, dan jiġi utli meta l-utent b’mod ċar ma qal xejn li jiswa l-ipproċessar (pereżempju, sogħla maqbuda minn mikrofonu sensittiv wisq) u tippreferi tibda mill-ġdid minn buffer nadif milli tħalli lill-mudell jinterpreta storbju.

X’jibgħat lura s-server

Il-fluss li jidħol huwa aktar imħaddem, peress li jagħti kummentarju kontinwu fuq kull pass tal-ipproċessar.

AvvenimentTifsira
session.createdIs-sessjoni miftuħa
session.updatedAġġornament tal-konfigurazzjoni ġie applikat
conversation.createdIl-konversazzjoni hija stabbilita
input_audio_buffer.speech_startedIl-VAD jinduna li l-utent beda jitkellem
input_audio_buffer.speech_stoppedIl-VAD jinduna li l-utent waqaf jitkellem
input_audio_buffer.committedIl-buffer tal-awdjo ġie kkonfermat, mill-VAD jew manwalment
response.createdTweġiba qed tiġi ġġenerata
response.output_audio.deltaBiċċa mill-awdjo tat-tweġiba, f’base64
response.output_audio.doneL-awdjo tat-tweġiba huwa sħiħ
response.output_audio_transcript.deltaIt-transkrizzjoni testwali tal-awdjo, trasmessa b’mod kontinwu
response.doneIt-tweġiba lesta kompletament
conversation.item.input_audio_transcription.completedIt-transkrizzjoni tal-messaġġ tal-utent hija disponibbli
response.text.deltaTest trasmess b’mod kontinwu, għal tweġibiet mhux vukali
response.function_call_arguments.deltaL-argumenti ta’ sejħa ta’ funzjoni, trasmessi b’mod kontinwu
response.function_call_arguments.doneIs-sejħa tal-funzjoni hija kompluta u lesta biex tiġi eżegwita
errorSeħħ żball; ħafna żbalji huma rikuperabbli

Dak tal-aħħar jeħtieġ twissija. Li tirċievi error ma tfissirx li s-sessjoni tintilfet. Skont ir-referenza ta’ xAI, ħafna żbalji huma rikuperabbli u s-sessjoni tibqa’ miftuħa, allura klijent li jagħlaq il-konnessjoni fl-ewwel error ikisser konversazzjoni li setgħet tkompli. Irreġistrah, għarraf lill-utent jekk ikun meħtieġ, iżda żomm is-socket miftuħ.

L-istruttura ta’ klijent

Fil-prattika, kollox jinżel għal switch fuq msg.type. Hawnhekk hija l-forma minima ta’ klijent JavaScript:

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

  switch (msg.type) {
    case "session.created":
      // Ibghat session.update bil-konfigurazzjoni
      break;

    case "input_audio_buffer.speech_started":
      // L-utent qed jitkellem: waqqaf l-awdjo tat-tweġiba li qed jindaqq
      break;

    case "response.output_audio.delta":
      // Dekodifika l-base64 u daqq l-awdjo
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Eżegwixxi l-funzjoni u ibgħat lura r-riżultat
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Żball fl-Aġent Vuwkali:", msg.error);
      break;
  }
};

Erba’ fergħat huma biżżejjed biex tħaddem aġent: ikkonfigura meta tiftaħ is-sessjoni, irreaġixxi meta l-utent jibda jitkellem, daqq l-awdjo li jkun qed jidħol, u eżegwixxi l-funzjonijiet. L-avvenimenti l-oħra jarricchixxu l-interfaċċja u jistgħu jistennew għal itterazzjoni sussegwenti.

Il-parti diffiċli: l-interruzzjonijiet

Il-”barge-in”, meta l-utent jibda jitkellem waqt li l-aġent għadu qed iwieġeb, huwa fejn tidher implementazzjoni mhux preċiża. Is-server jikkanċella t-tweġiba attwali waħdu u jibda jiġġenera waħda ġdida minn dak li għadu kemm sema’. Iżda waqt li s-server waqaf jibgħat, l-app tiegħek għadha żżomm diversi sekondi ta’ awdjo diġà rċevut fil-buffer tal-output tagħha.

Jekk ma tagħmel xejn, l-utent ikompli jisma’ s-sentenza li għadu kemm interrompa waqt li jkun qed jitkellem fuqha, u l-aġent jidher qisu ma jisimgħx. Għalhekk, hekk kif tirċievi speech_started, waqqaf l-awdjo li qed jindaqq, ibattal il-buffer tal-output biex ma tdaqqx ħoss antik, u ħalli lis-server jipproċessa d-dħul il-ġdid. Dawn iż-żewġ passi jieħdu ftit linji ta’ kodiċi u jagħmlu d-differenza kollha bejn aġent li tista’ tinterrompi u wieħed li jitkellem fil-vojt.

Punti Ewlenin

  • L-avvenimenti tal-klijent ikopru l-konfigurazzjoni, l-ibgħat tal-awdjo, il-ġestjoni tal-konversazzjoni, u l-kontroll tat-tweġibiet
  • L-avvenimenti tas-server jirrappurtaw id-detezzjoni tal-kliem, biċċiet tal-awdjo, transkrizzjonijiet, u sejħiet ta’ funzjonijiet
  • Il-VAD jimmaniġġja l-interruzzjonijiet (barge-in) awtomatikament
  • Ħafna avvenimenti error huma rikuperabbli: tagħlaqx il-konnessjoni, immaniġġja l-iżball
  • Fil-modalità manwali, trid isejjaħ commit u mbagħad response.create b’mod espliċitu