WebSocket-tapahtumien hallinta
Tällä sivulla
JSON-tapahtumista koostuva keskustelu
Konepellin alla äänikeskustelu Voice Agentin kanssa on pelkkä JSON-viestien virta, joka kulkee molempiin suuntiin WebSocket-yhteyden yli. Jokaisessa viestissä on type-kenttä, joka kertoo viestin luonteen. Ilman tätä sanastoa asiakasohjelmasi toimii onnenkaupalla. Kun hallitset sen, tiedät tarkasti, missä vaiheessa puuttua asiaan keskeyttääksesi vastauksen, näyttääksesi litteroinnin tai palautuaksesi virhetilanteesta.
Tapahtumat jakautuvat kahteen perheeseen suunnan perusteella. Lähettämäsi viestit ohjaavat istuntoa; vastaanottamasi viestit kertovat, mitä palvelimella tapahtuu.
Mitä sovelluksesi lähettää
Lähtevät viestisi kattavat neljä tarvetta: istunnon määrittämisen, äänipuskurin syöttämisen, keskusteluhistorian hallinnan ja vastauksen generoinnin ohjaamisen.
| Tapahtuma | Tarkoitus |
|---|---|
session.update | Määrittää tai uudelleenmäärittää istunnon (ääni, ohjeet, työkalut, VAD, äänimuoto) |
input_audio_buffer.append | Lähettää base64-koodatun äänipalan jatkuvasti käyttäjän puhuessa |
input_audio_buffer.commit | Vahvistaa puskurin nykyisen sisällön käyttäjän viestinä; tarvitaan vain manuaalitilassa |
input_audio_buffer.clear | Tyhjentää äänipuskurin käsittelemättä sitä |
conversation.item.create | Lisää kohteen keskusteluun: tekstiviestin, aiemman historian tai funktiokutsun tuloksen |
conversation.item.delete | Poistaa keskustelukohteen sen ID:n perusteella |
response.create | Pyytää mallia generoimaan vastauksen; automaattinen VAD-tilassa, eksplisiittinen manuaalitilassa |
response.cancel | Peruuttaa generoitavan vastauksen |
Kaksi näistä viesteistä ansaitsee tarkemman tarkastelun. conversation.item.create on tapa syöttää kontekstia: sen avulla palautat aiemman puhelun historian uuden istunnon alussa. input_audio_buffer.clear puolestaan on hyödyllinen, kun käyttäjä ei selvästi sanonut mitään käsittelemisen arvoista (esim. liian herkän mikrofonin sieppaama kurkun selvittely), ja haluat mieluummin aloittaa puhtaalta pöydältä kuin antaa mallin tulkita kohinaa.
Mitä palvelin lähettää takaisin
Saapuva virta on vilkkaampi, koska se tarjoaa reaaliaikaista kommentointia jokaisesta käsittelyvaiheesta.
| Tapahtuma | Merkitys |
|---|---|
session.created | Istunto on avattu |
session.updated | Kokoonpanopäivitys on otettu käyttöön |
conversation.created | Keskustelu on asetettu |
input_audio_buffer.speech_started | VAD havaitsee käyttäjän alkaneen puhua |
input_audio_buffer.speech_stopped | VAD havaitsee käyttäjän lopettaneen puhumisen |
input_audio_buffer.committed | Äänipuskuri on vahvistettu (VAD:n tai manuaalisesti) |
response.created | Vastausta generoidaan |
response.output_audio.delta | Pala vastausääntä base64-muodossa |
response.output_audio.done | Vastausääni on valmis |
response.output_audio_transcript.delta | Äänen tekstilitterointi suoratoistona |
response.done | Vastaus on täysin päättynyt |
conversation.item.input_audio_transcription.completed | Käyttäjän viestin litterointi on saatavilla |
response.text.delta | Suoratoistettu teksti ei-äänivastauksille |
response.function_call_arguments.delta | Funktiokutsun argumentit suoratoistona |
response.function_call_arguments.done | Funktiokutsu on valmis ja odottaa suorittamista |
error | Tapahtui virhe; useimmat virheet ovat korjattavissa |
Viimeinen kohta vaatii varoituksen. error-tapahtuman vastaanottaminen ei tarkoita istunnon menettämistä. xAI:n referenssin mukaan useimmat virheet ovat korjattavissa ja istunto pysyy auki, joten asiakasohjelma, joka sulkee yhteyden ensimmäisestä error-tapahtumasta, katkaisee keskustelun, joka olisi voinut jatkua. Kirjaa virhe, ilmoita siitä käyttäjälle tarvittaessa, mutta pidä socket auki.
Asiakasohjelman runko
Käytännössä kaikki tiivistyy kytkentään msg.type:n perusteella. Tässä on JavaScript-asiakasohjelman minimaalinen rakenne:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Lähetä session.update kokoonpanolla
break;
case "input_audio_buffer.speech_started":
// Käyttäjä puhuu: pysäytä toistettava vastausääni
break;
case "response.output_audio.delta":
// Pura base64 ja toista ääni
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Suorita funktio ja lähetä tulos takaisin
handleFunctionCall(msg);
break;
case "error":
console.error("Voice Agent -virhe:", msg.error);
break;
}
};
Neljä haaraa riittää agentin pyörittämiseen: määritä istunnon avautuessa, reagoi käyttäjän puhumaan alkaessa, toista saapuva ääni ja suorita funktiot. Muut tapahtumat rikastuttavat käyttöliittymää ja voivat odottaa toista iterointia.
Haastava kohta: keskeytykset
Barge-in, eli tilanne jossa käyttäjä alkaa puhua agentin vielä vastatessa, on kohta jossa huolimaton toteutus paljastuu. Palvelin peruuttaa nykyisen vastauksen itsestään ja alkaa generoida uutta kuulemansa perusteella. Mutta vaikka palvelin on lopettanut lähettämisen, sovelluksellasi on edelleen useita sekunteja jo vastaanotettua ääntä lähtöpuskurissaan.
Jos et tee mitään, käyttäjä kuulee edelleen lausetta, jonka hän juuri keskeytti, puhuen sen päälle, ja agentti vaikuttaa siltä ettei se kuuntele. Siksi heti kun vastaanotat speech_started-tapahtuman, pysäytä toistettava ääni, tyhjennä lähtöpuskuri vanhentuneen äänen soittamisen estämiseksi ja anna palvelimen käsitellä uusi syöte. Nämä kaksi vaihetta vievät vain muutaman rivin koodia, mutta tekevät eron agentin, jonka voi keskeyttää, ja agentin, joka puhuu tyhjiin.
Keskeiset asiat
- Asiakastapahtumat kattavat kokoonpanon, äänen lähettämisen, keskustelun hallinnan ja vastausten ohjaamisen
- Palvelintapahtumat raportoivat puheen havaitsemisesta, äänipaloista, litteroinneista ja funktiokutsuista
- VAD hoitaa keskeytykset (barge-in) automaattisesti
- Useimmat
error-tapahtumat ovat korjattavissa: älä sulje yhteyttä, vaan käsittele virhe - Manuaalitilassa sinun on kutsuttava
commitja sen jälkeenresponse.createeksplisiittisesti