Pārvaldi WebSocket notikumus
Šajā lapā
Saruna, kas veidota no JSON notikumiem
Aizkulisēs balss apmaiņa ar Voice Agent ir vienkārši JSON ziņojumu plūsma abos virzienos caur WebSocket savienojumu. Katrai ziņai ir lauks type, kas norāda, kas tā ir. Kamēr nepārzini šo vārdu krājumu, tavs klients strādā uz veiksmes rēķina. Tiklīdz to apgūsti, tu precīzi zini, kur iejaukties, lai pārtrauktu atbildi, parādītu transkriptu vai atgūtos pēc kļūdas.
Notikumi iedalās divās grupās atkarībā no to virziena. Tie, kurus tu sūti, vada sesiju; tie, kurus tu saņem, informē par notiekošo serverī.
Ko tava lietotne sūta
Tavas izejošās ziņas sedz četras vajadzības: sesijas konfigurēšanu, audio bufera piepildīšanu, sarunas vēstures pārvaldību un atbilžu ģenerēšanas kontroli.
| Notikums | Mērķis |
|---|---|
session.update | Konfigurē vai rekonfigurē sesiju (balss, instrukcijas, rīki, VAD, audio formāts) |
input_audio_buffer.append | Nosūta base64 kodētu audio gabalu nepārtraukti, kamēr lietotājs runā |
input_audio_buffer.commit | Apstiprina pašreizējo bufera saturu kā lietotāja ziņojumu; nepieciešams tikai manuālajā režīmā |
input_audio_buffer.clear | Iztukšo audio buferi, to neapstrādājot |
conversation.item.create | Pievieno sarunai elementu: teksta ziņojumu, iepriekšēju vēsturi vai funkcijas izsaukuma rezultātu |
conversation.item.delete | Dzēš sarunas elementu pēc tā ID |
response.create | Pieprasa modelim ģenerēt atbildi; automātisks VAD režīmā, eksplicīts manuālajā režīmā |
response.cancel | Atceļ ģenerējamu atbildi |
Divas no šīm ziņām ir pelnījušas tuvāku aplūkojumu. conversation.item.create ir veids, kā ievadīt kontekstu: to izmanto, lai atjaunotu iepriekšējās zvana vēsturi jaunas sesijas sākumā. Savukārt input_audio_buffer.clear noder, ja lietotājs acīmredzami neteica neko vērtīgu apstrādei (piemēram, kakla tīrīšana, ko uztvēra pārāk jutīgs mikrofons), un tu vēlies sākt no jauna ar tīru buferi, nevis ļaut modelim interpretēt troksni.
Ko serveris sūta atpakaļ
Ienākošā plūsma ir aizņemtāka, jo tā sniedz komentārus par katru apstrādes soli.
| Notikums | Nozīme |
|---|---|
session.created | Sesija ir atvērta |
session.updated | Konfigurācijas atjauninājums ir piemērots |
conversation.created | Saruna ir izveidota |
input_audio_buffer.speech_started | VAD konstatē, ka lietotājs ir sācis runāt |
input_audio_buffer.speech_stopped | VAD konstatē, ka lietotājs ir beidzis runāt |
input_audio_buffer.committed | Audio bufers ir apstiprināts, izmantojot VAD vai manuāli |
response.created | Tiek ģenerēta atbilde |
response.output_audio.delta | Atbildes audio gabals base64 formātā |
response.output_audio.done | Atbildes audio ir pabeigts |
response.output_audio_transcript.delta | Audio teksta transkripts, straumēts |
response.done | Atbilde ir pilnībā pabeigta |
conversation.item.input_audio_transcription.completed | Lietotāja ziņojuma transkripts ir pieejams |
response.text.delta | Straumēts teksts atbildēm, kas nav balss |
response.function_call_arguments.delta | Funkcijas izsaukuma argumenti, straumēti |
response.function_call_arguments.done | Funkcijas izsaukums ir pabeigts un gatavs izpildei |
error | Radusies kļūda; lielākā daļa kļūdu ir labojamas |
Par pēdējo punktu jāsniedz brīdinājums. Saņemot error, tas nenozīmē, ka sesija ir zudusi. Saskaņā ar xAI atsauces dokumentāciju lielākā daļa kļūdu ir labojamas un sesija paliek atvērta, tāpēc klients, kas aizver savienojumu pie pirmās error ziņas, pārtrauc sarunu, kas varētu turpināties. Reģistrē kļūdu, informē lietotāju, ja nepieciešams, bet uzturi ligzdu atvērtu.
Klienta skelets
Praksē viss reducējas uz pārslēgšanu pēc msg.type. Lūk, minimālais JavaScript klienta veidols:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Nosūti session.update ar konfigurāciju
break;
case "input_audio_buffer.speech_started":
// Lietotājs runā: apturi atskaņojamo atbildes audio
break;
case "response.output_audio.delta":
// Atkodē base64 un atskaņo audio
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Izpildi funkciju un nosūti rezultātu atpakaļ
handleFunctionCall(msg);
break;
case "error":
console.error("Voice Agent kļūda:", msg.error);
break;
}
};
Četras zarošanās ir pietiekamas, lai darbinātu aģentu: konfigurē, atverot sesiju, reaģē, kad lietotājs sāk runāt, atskaņo ienākošo audio un izpildi funkcijas. Pārējie notikumi bagātina saskarni un var pagaidīt uz otro iterāciju.
Sarežģītākā daļa: pārtraukumi
Barge-in, kad lietotājs sāk runāt, kamēr aģents vēl atbild, ir brīdis, kad parādās neprecīza implementācija. Serveris pats atceļ pašreizējo atbildi un sāk ģenerēt jaunu, pamatojoties uz tikko dzirdēto. Taču, kamēr serveris ir pārtraucis sūtīšanu, tava lietotne joprojām glabā vairākas sekundes jau saņemta audio savā izejas buferī.
Ja tu neko nedarīsi, lietotājs turpinās dzirdēt teikumu, ko tikko pārtrauca, runājot tam pāri, un aģents izskatīsies tāds, kas neklausās. Tāpēc tiklīdz saņem speech_started, apturi atskaņojamo audio, iztukšo izejas buferi, lai neatskaņotu vecu skaņu, un ļauj serverim apstrādāt jauno ievadi. Šie divi soļi aizņem dažas koda rindiņas, taču tie rada milzīgu atšķirību starp aģentu, ko vari pārtraukt, un tādu, kas runā tukšumā.
Galvenās atziņas
- Klienta notikumi sedz konfigurāciju, audio sūtīšanu, sarunas pārvaldību un atbilžu kontroli
- Servera notikumi ziņo par runas noteikšanu, audio gabaliem, transkriptiem un funkciju izsaukumiem
- VAD automātiski apstrādā pārtraukumus (barge-in)
- Lielākā daļa
errornotikumu ir labojami: neaizver savienojumu, apstrādā kļūdu - Manuālajā režīmā tev ir eksplicīti jāizsauc
commitun pēc tamresponse.create