Valdykite WebSocket įvykius
Šiame puslapyje
Pokalbis, sudarytas iš JSON įvykių
Iš esmės balso mainai su „Voice Agent“ yra tiesiog JSON žinučių srautas, tekantis abiem kryptimis per WebSocket ryšį. Kiekviena žinutė turi lauką type, nurodantį, kas ji yra. Kol neišmoksi šios terminijos, tavo klientas veiks atsitiktinai. Kai ją įvaldysi, tiksliai žinosi, kur įsikišti, kad nutrauktum atsakymą, parodytum transkriptą arba atkurtum veikimą po klaidos.
Įvykiai skirstomi į dvi šeimas, priklausomai nuo jų krypties. Tie, kuriuos siunti tu, valdo sesiją; tie, kuriuos gauni, praneša, kas vyksta serveryje.
Ką siunčia tavo programa
Tavo siunčiamos žinutės tenkina keturis poreikius: sesijos konfigūravimą, garso buferio pildymą, pokalbio istorijos valdymą ir atsakymų generavimo kontrolę.
| Įvykis | Paskirtis |
|---|---|
session.update | Konfigūruoja arba perkonfigūruoja sesiją (balsą, instrukcijas, įrankius, VAD, garso formatą) |
input_audio_buffer.append | Siunčia base64 koduotą garso gabalėlį nuolat, kol vartotojas kalba |
input_audio_buffer.commit | Įtvirtina dabartinio buferio turinį kaip vartotojo žinutę; reikia tik rankiniu režimu |
input_audio_buffer.clear | Išvalo garso buferį jo neapdorojant |
conversation.item.create | Prideda elementą į pokalbį: teksto žinutę, ankstesnę istoriją arba funkcijos kvietimo rezultatą |
conversation.item.delete | Ištrina pokalbio elementą pagal jo ID |
response.create | Prašo modelio sugeneruoti atsakymą; automatinis VAD režimu, aiškus rankiniu režimu |
response.cancel | Atšaukia generuojamą atsakymą |
Dvi iš šių žinučių nusipelno dėmesio. conversation.item.create yra būdas įterpti kontekstą: tai naudojama atkurti ankstesnio skambučio istoriją naujos sesijos pradžioje. O input_audio_buffer.clear pravartu, kai vartotojas akivaizdžiai nepasakė nieko verto apdoroti (pvz., kosulys, kurį užfiksavo per jautrus mikrofonas) ir nori pradėti iš švaraus buferio, užuot leidęs modeliui interpretuoti triukšmą.
Ką siunčia serveris
Gaunamas srautas intensyvesnis, nes jis komentuoja kiekvieną apdorojimo žingsnį realiuoju laiku.
| Įvykis | Reikšmė |
|---|---|
session.created | Sesija atidaryta |
session.updated | Konfigūracijos atnaujinimas pritaikytas |
conversation.created | Pokalbis sukurtas |
input_audio_buffer.speech_started | VAD aptiko, kad vartotojas pradėjo kalbėti |
input_audio_buffer.speech_stopped | VAD aptiko, kad vartotojas nutilo |
input_audio_buffer.committed | Garso buferis įtvirtintas (automatiškai per VAD arba rankiniu būdu) |
response.created | Generuojamas atsakymas |
response.output_audio.delta | Atsakymo garso gabalėlis (base64) |
response.output_audio.done | Atsakymo garso srautas baigtas |
response.output_audio_transcript.delta | Tekstinis garso transkriptas, siunčiamas srautu |
response.done | Atsakymas visiškai baigtas |
conversation.item.input_audio_transcription.completed | Vartotojo žinutės transkriptas paruoštas |
response.text.delta | Srautinis tekstas atsakymams, kurie nėra balsiniai |
response.function_call_arguments.delta | Funkcijos kvietimo argumentai, siunčiami srautu |
response.function_call_arguments.done | Funkcijos kvietimas baigtas ir paruoštas vykdyti |
error | Įvyko klaida; daugumą klaidų galima ištaisyti |
Paskutiniam punktui reikia įspėjimo. Gavus error, sesija nebūtinai prarandama. Pagal xAI dokumentaciją, daugumą klaidų galima ištaisyti, o sesija lieka atidaryta, todėl klientas, uždarantis ryšį po pirmosios error, nutraukia pokalbį, kuris galėjo tęstis. Užfiksuok klaidą, prireikus informuok vartotoją, bet laikyk lizdą atvirą.
Kliento struktūra
Praktiškai viskas sumažėja iki msg.type perjungimo. Štai minimali JavaScript kliento struktūra:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Siųsti session.update su konfigūracija
break;
case "input_audio_buffer.speech_started":
// Vartotojas kalba: sustabdyti grojamą atsakymo garsą
break;
case "response.output_audio.delta":
// Iššifruoti base64 ir groti garsą
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Vykdyti funkciją ir siųsti rezultatą atgal
handleFunctionCall(msg);
break;
case "error":
console.error("Voice Agent error:", msg.error);
break;
}
};
Keturių šakų pakanka agentui valdyti: konfigūruoti atidarius sesiją, reaguoti, kai vartotojas pradeda kalbėti, groti gaunamą garsą ir vykdyti funkcijas. Kiti įvykiai praturtina sąsają ir gali palaukti antrosios iteracijos.
Sudėtinga dalis: pertraukimai
„Barge-in“ (kai vartotojas pradeda kalbėti agentui dar atsakant) – tai momentas, kai išryškėja netobulas įgyvendinimas. Serveris pats atšaukia dabartinį atsakymą ir pradeda generuoti naują pagal tai, ką ką tik išgirdo. Tačiau kol serveris nustojo siųsti, tavo programa vis dar turi kelias sekundes jau gauto garso išvesties buferyje.
Jei nieko nedarysi, vartotojas toliau girdės sakinį, kurį ką tik pertraukė, kalbėdamas jam per galvą, o agentas atrodys negirdintis. Todėl vos gavęs speech_started, nedelsdamas sustabdyk grojamą garsą, išvalyk išvesties buferį, kad negrobtum pasenusio garso, ir leisk serveriui apdoroti naują įvestį. Šie du veiksmai užtrunka keletą kodo eilučių, tačiau jie lemia skirtumą tarp agento, kurį galima pertraukti, ir to, kuris kalba į tuštumą.
Svarbiausi punktai
- Kliento įvykiai apima konfigūravimą, garso siuntimą, pokalbio valdymą ir atsakymų kontrolę
- Serverio įvykiai praneša apie kalbos aptikimą, garso gabalėlius, transkriptus ir funkcijų kvietimus
- VAD automatiškai valdo pertraukimus (barge-in)
- Dauguma
errorįvykių yra taisomi: neužverk ryšio, tvarkyk klaidą - Rankiniu režimu turi aiškiai iškviesti
commit, o tadaresponse.create