WebSocketi sündmuste valdamine
Sellel lehel
Vestlus, mis koosneb JSON-sündmustest
Telgitagustes on häälevahetus hääleagendiga lihtsalt JSON-sõnumite voog, mis liigub mõlemas suunas üle WebSocketi ühenduse. Igal sõnumil on väli type, mis määrab selle olemuse. Kuni sa seda sõnavara ei tunne, töötab sinu klient õnne najal. Kui aga tunned, tead täpselt, millal sekkuda, et vastus katkestada, transkripti kuvada või veast taastuda.
Sündmused jagunevad kahte perekonda sõltuvalt nende liikumissuunast. Need, mida sa saadad, juhivad seanssi; need, mida vastu võtad, annavad teada, mis serveris toimub.
Mida sinu rakendus saadab
Sinu väljuvad sõnumid katavad nelja vajadust: seansi konfigureerimine, helipuhvri toitmine, vestlusajaloo haldamine ja vastuse genereerimise juhtimine.
| Sündmus | Eesmärk |
|---|---|
session.update | Konfigureerib või rekonfigureerib seanssi (hääl, juhised, tööriistad, VAD, helivorming) |
input_audio_buffer.append | Saadab base64-kodeeritud helilõigu pidevalt, kui kasutaja räägib |
input_audio_buffer.commit | Kinnitab praeguse puhvri sisu kasutaja sõnumina; vajalik ainult käsitsi režiimis |
input_audio_buffer.clear | Tühjendab helipuhvri ilma seda töötlemata |
conversation.item.create | Lisab vestlusele elemendi: tekstisõnum, varasem ajalugu või funktsioonikutsu tulemus |
conversation.item.delete | Kustutab vestluse elemendi selle ID põhjal |
response.create | Palub mudelil vastust genereerida; automaatne VAD-režiimis, eksplitsiitne käsitsi režiimis |
response.cancel | Tühistab genereeritavat vastust |
Kaks neist sõnumitest väärivad lähemat pilku. conversation.item.create on viis konteksti sisestamiseks: seda kasutad eelmise kõne ajaloo taastamiseks uue seansi alguses. Mis puutub input_audio_buffer.cleari, siis see tuleb kasuks, kui kasutaja ei öelnud selgelt midagi töötlemist väärt (näiteks köhatamine, mille liiga tundlik mikrofon kinni püüdis), ja eelistad alustada puhtalt puhvrilt, kui lasta mudelil müra tõlgendada.
Mida server tagasi saadab
Sissetulev voog on tihedam, kuna see annab jooksvat kommentaari iga töötlemisetapi kohta.
| Sündmus | Tähendus |
|---|---|
session.created | Seanss on avatud |
session.updated | Konfiguratsiooni uuendus on rakendatud |
conversation.created | Vestlus on seadistatud |
input_audio_buffer.speech_started | VAD tuvastab, et kasutaja on rääkima hakanud |
input_audio_buffer.speech_stopped | VAD tuvastab, et kasutaja on rääkimise lõpetanud |
input_audio_buffer.committed | Helipuhver on kinnitatud, kas VAD-i või käsitsi poolt |
response.created | Vastust genereeritakse |
response.output_audio.delta | Vastuse helilõik base64-koodingus |
response.output_audio.done | Vastuse heli on täielik |
response.output_audio_transcript.delta | Heli tekstiline transkript, voogedastatuna |
response.done | Vastus on täielikult lõpetatud |
conversation.item.input_audio_transcription.completed | Kasutaja sõnumi transkript on saadaval |
response.text.delta | Voogedastatav tekst mitte-häälvastuste jaoks |
response.function_call_arguments.delta | Funktsioonikutsu argumendid, voogedastatuna |
response.function_call_arguments.done | Funktsioonikutsu on lõpetatud ja valmis käivitamiseks |
error | Tekkis viga; enamik vigu on taastatavad |
Viimane neist vajab hoiatust. error saamine ei tähenda, et seanss on kadunud. xAI referentsi kohaselt on enamik vigu taastatavad ja seanss jääb avatuks, nii et klient, mis sulgeb ühenduse esimese error peal, katkestab vestluse, mis oleks võinud jätkuda. Logi see, teavita kasutajat vajadusel, kuid hoia sokkel avatuna.
Kliendi luustik
Praktikas taandub kõik msg.type põhjal lülitusele. Siin on JavaScripti kliendi minimaalne kuju:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Saada session.update koos konfiguratsiooniga
break;
case "input_audio_buffer.speech_started":
// Kasutaja räägib: peata esitatav vastuse heli
break;
case "response.output_audio.delta":
// Dekodeeri base64 ja esita heli
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Käivita funktsioon ja saada tulemus tagasi
handleFunctionCall(msg);
break;
case "error":
console.error("Hääleagendi viga:", msg.error);
break;
}
};
Agenti käitamiseks piisab neljast harust: konfigureeri seansi avamisel, reageeri kasutaja rääkima hakkamisel, esita sissetulevat heli ja käivita funktsioone. Teised sündmused rikastavad liidest ja võivad oodata teist iteratsiooni.
Libe koht: katkestused
Barge-in, olukord, kus kasutaja hakkab rääkima ajal, kui agent veel vastab, on koht, kus hooletu implementatsioon end reedab. Server tühistab jooksva vastuse ise ja hakkab genereerima uut vastust selle põhjal, mida ta just kuulis. Kuid samal ajal kui server on saatmise lõpetanud, hoiab sinu rakendus väljundpuhvris endiselt mitu sekundit juba vastuvõetud heli.
Kui sa midagi ei tee, kuuleb kasutaja lauset, mida ta just katkestas, edasi, rääkides sellele peale, ja agent jätab mulje, nagu ei kuulaks. Seega niipea, kui saad speech_started, peata esitatav heli, tühjenda väljundpuhver, et vananenud heli ei esitataks, ja lase serveril uut sisendit töödelda. Need kaks sammu võtavad paar rida koodi ja teevad vahet agendi vahel, mida saab katkestada, ja sellise vahel, mis räägib tühjusesse.
Peamised punktid
- Kliendi sündmused katavad konfiguratsiooni, heli saatmist, vestluse haldamist ja vastuste juhtimist
- Serveri sündmused teavitavad kõne tuvastamisest, helilõikudest, transkriptidest ja funktsioonikutsetest
- VAD haldab katkestusi (barge-in) automaatselt
- Enamik
errorsündmusi on taastatavad: ära sulge ühendust, hinda viga - Käsitsi režiimis pead kutsuma
commitja seejärelresponse.createeksplitsiitselt