Obvladovanje dogodkov WebSocket
Na tej strani
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.
| Dogodek | Namen |
|---|---|
session.update | Konfigurira ali ponovno konfigurira sejo (glas, navodila, orodja, VAD, format zvoka) |
input_audio_buffer.append | Pošlje kos zvoka, kodiran v base64, neprekinjeno, medtem ko uporabnik govori |
input_audio_buffer.commit | Potrdi trenutno vsebino medpomnilnika kot uporabnikovo sporočilo; potrebno le v ročnem načinu |
input_audio_buffer.clear | Izprazni medpomnilnik zvoka brez obdelave |
conversation.item.create | Doda element v pogovor: besedilno sporočilo, zgodnejšo zgodovino ali rezultat klica funkcije |
conversation.item.delete | Izbriše element pogovora po njegovem ID-ju |
response.create | Prosi model, naj ustvari odgovor; samodejno v načinu VAD, izrecno v ročnem načinu |
response.cancel | Preklič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.
| Dogodek | Pomen |
|---|---|
session.created | Seja je odprta |
session.updated | Posodobitev konfiguracije je bila uporabljena |
conversation.created | Pogovor je nastavljen |
input_audio_buffer.speech_started | VAD zazna, da je uporabnik začel govoriti |
input_audio_buffer.speech_stopped | VAD zazna, da je uporabnik prenehal govoriti |
input_audio_buffer.committed | Medpomnilnik zvoka je bil potrjen, s strani VAD ali ročno |
response.created | Odgovor se generira |
response.output_audio.delta | Kos odgovornega zvoka v base64 |
response.output_audio.done | Odgovorni zvok je končan |
response.output_audio_transcript.delta | Besedilni prepis zvoka, pretakan |
response.done | Odgovor je popolnoma končan |
conversation.item.input_audio_transcription.completed | Prepis uporabnikovega sporočila je na voljo |
response.text.delta | Pretok besedila za neodgovore, ki niso glasovni |
response.function_call_arguments.delta | Argumenti klica funkcije, pretokani |
response.function_call_arguments.done | Klic funkcije je končan in pripravljen za izvedbo |
error | Priš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
errorje odpravljivih: ne zapiraj povezave, obdelaj napako - V ročnem načinu moraš izrecno poklicati
commitin natoresponse.create