Timmustra l-avvenimenti ta' WebSocket
F'din il-paġna
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.
| Avveniment | Għan |
|---|---|
session.update | Jikkonfigura jew jikkonfigura mill-ġdid is-sessjoni (vuċi, struzzjonijiet, għodod, VAD, format tal-awdjo) |
input_audio_buffer.append | Jibgħat biċċa awdjo kodifikata f’base64, kontinwament waqt li l-utent ikun qed jitkellem |
input_audio_buffer.commit | Jikkonferma l-kontenut attwali tal-buffer bħala l-messaġġ tal-utent; meħtieġ biss fil-modalità manwali |
input_audio_buffer.clear | Jibattal il-buffer tal-awdjo mingħajr ma jipproċessah |
conversation.item.create | Iżid oġġett fil-konversazzjoni: messaġġ testwali, storja preċedenti, jew riżultat ta’ sejħa ta’ funzjoni |
conversation.item.delete | Iħassar oġġett tal-konversazzjoni bl-ID tiegħu |
response.create | Jitlob lill-mudell biex jiġġenera tweġiba; awtomatiku fil-modalità VAD, espliċitu fil-modalità manwali |
response.cancel | Jikkanċ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.
| Avveniment | Tifsira |
|---|---|
session.created | Is-sessjoni miftuħa |
session.updated | Aġġornament tal-konfigurazzjoni ġie applikat |
conversation.created | Il-konversazzjoni hija stabbilita |
input_audio_buffer.speech_started | Il-VAD jinduna li l-utent beda jitkellem |
input_audio_buffer.speech_stopped | Il-VAD jinduna li l-utent waqaf jitkellem |
input_audio_buffer.committed | Il-buffer tal-awdjo ġie kkonfermat, mill-VAD jew manwalment |
response.created | Tweġiba qed tiġi ġġenerata |
response.output_audio.delta | Biċċa mill-awdjo tat-tweġiba, f’base64 |
response.output_audio.done | L-awdjo tat-tweġiba huwa sħiħ |
response.output_audio_transcript.delta | It-transkrizzjoni testwali tal-awdjo, trasmessa b’mod kontinwu |
response.done | It-tweġiba lesta kompletament |
conversation.item.input_audio_transcription.completed | It-transkrizzjoni tal-messaġġ tal-utent hija disponibbli |
response.text.delta | Test trasmess b’mod kontinwu, għal tweġibiet mhux vukali |
response.function_call_arguments.delta | L-argumenti ta’ sejħa ta’ funzjoni, trasmessi b’mod kontinwu |
response.function_call_arguments.done | Is-sejħa tal-funzjoni hija kompluta u lesta biex tiġi eżegwita |
error | Seħħ ż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
errorhuma rikuperabbli: tagħlaqx il-konnessjoni, immaniġġja l-iżball - Fil-modalità manwali, trid isejjaħ
commitu mbagħadresponse.createb’mod espliċitu