Stăpânirea evenimentelor WebSocket
Pe această pagină
O conversație compusă din evenimente JSON
În spatele scenei, un schimb vocal cu Voice Agent nu este decât un flux de mesaje JSON care circulă în ambele sensuri prin conexiunea WebSocket. Fiecare mesaj conține un câmp type care indică natura sa. Până nu cunoașteți acest vocabular, clientul dumneavoastră funcționează la noroc. Odată ce îl stăpâniți, știți exact unde să interveniți pentru a întrerupe un răspuns, a afișa o transcriere sau a vă recupera după o eroare.
Evenimentele se împart în două familii, în funcție de direcția lor de deplasare. Cele pe care le trimiteți pilotează sesiunea; cele pe care le primiți vă informează despre ce se întâmplă pe server.
Ce trimite aplicația dumneavoastră
Mesajele dumneavoastră de ieșire acoperă patru nevoi: configurarea sesiunii, alimentarea buffer-ului audio, gestionarea istoricului conversației și controlul generării răspunsurilor.
| Eveniment | Scop |
|---|---|
session.update | Configurează sau reconfigurează sesiunea (voce, instrucțiuni, instrumente, VAD, format audio) |
input_audio_buffer.append | Trimite un fragment audio codificat base64, continuu, cât timp utilizatorul vorbește |
input_audio_buffer.commit | Validează conținutul actual al buffer-ului ca mesaj al utilizatorului; necesar doar în modul manual |
input_audio_buffer.clear | Golește buffer-ul audio fără a-l procesa |
conversation.item.create | Adaugă un element la conversație: un mesaj text, un istoric anterior sau rezultatul unui apel de funcție |
conversation.item.delete | Șterge un element din conversație după ID-ul său |
response.create | Cere modelului să genereze un răspuns; automat în modul VAD, explicit în modul manual |
response.cancel | Anulează un răspuns care este în curs de generare |
Două dintre aceste mesaje merită o privire mai atentă. conversation.item.create este modul în care injectați contextul: este ceea ce utilizați pentru a restaura istoricul unui apel anterior la începutul unei noi sesiuni. În ceea ce privește input_audio_buffer.clear, acesta este util atunci când utilizatorul nu a spus nimic care să merite procesat (de exemplu, o dregere a glasului captată de un microfon prea sensibil) și preferați să o luați de la capăt cu un buffer curat, decât să lăsați modelul să interpreteze zgomotul.
Ce trimite serverul înapoi
Fluxul de intrare este mai aglomerat, deoarece oferă un comentariu în timp real pentru fiecare etapă de procesare.
| Eveniment | Semnificație |
|---|---|
session.created | Sesiunea este deschisă |
session.updated | O actualizare de configurare a fost aplicată |
conversation.created | Conversația este inițializată |
input_audio_buffer.speech_started | VAD detectează că utilizatorul a început să vorbească |
input_audio_buffer.speech_stopped | VAD detectează că utilizatorul a încetat să vorbească |
input_audio_buffer.committed | Buffer-ul audio a fost validat, de către VAD sau manual |
response.created | Un răspuns este în curs de generare |
response.output_audio.delta | Un fragment audio al răspunsului, în base64 |
response.output_audio.done | Audio-ul răspunsului este complet |
response.output_audio_transcript.delta | Transcrierea text a audio-ului, transmisă în flux |
response.done | Răspunsul este complet finalizat |
conversation.item.input_audio_transcription.completed | Transcrierea mesajului utilizatorului este disponibilă |
response.text.delta | Text transmis în flux, pentru răspunsuri non-vocale |
response.function_call_arguments.delta | Argumentele unui apel de funcție, transmise în flux |
response.function_call_arguments.done | Apelul de funcție este complet și gata de executare |
error | A apărut o eroare; majoritatea erorilor sunt recuperabile |
Acest ultim eveniment necesită o avertizare. Primirea unui error nu înseamnă că sesiunea este pierdută. Conform documentației de referință xAI, majoritatea erorilor sunt recuperabile și sesiunea rămâne deschisă, astfel încât un client care închide conexiunea la primul error întrerupe o conversație care ar fi putut continua. Înregistrați-l în jurnal, informați utilizatorul dacă este necesar, dar mențineți socket-ul deschis.
Scheletul unui client
În practică, totul se reduce la o structură switch bazată pe msg.type. Iată forma minimă a unui client JavaScript:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Trimiteți session.update cu configurația
break;
case "input_audio_buffer.speech_started":
// Utilizatorul vorbește: opriți redarea audio a răspunsului
break;
case "response.output_audio.delta":
// Decodați base64 și redați audio-ul
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Executați funcția și trimiteți rezultatul înapoi
handleFunctionCall(msg);
break;
case "error":
console.error("Eroare Voice Agent:", msg.error);
break;
}
};
Patru ramuri sunt suficiente pentru a rula un agent: configurați la deschiderea sesiunii, reacționați când utilizatorul începe să vorbească, redați audio-ul primit și executați funcțiile. Celelalte evenimente îmbogățesc interfața și pot aștepta o a doua iterație.
Partea delicată: întreruperile
„Barge-in“, momentul în care utilizatorul începe să vorbească în timp ce agentul răspunde încă, este punctul unde o implementare neglijentă se demască. Serverul anulează singur răspunsul curent și începe să genereze unul nou pe baza a ceea ce tocmai a auzit. Dar, în timp ce serverul a oprit trimiterea, aplicația dumneavoastră deține încă câteva secunde de audio deja primite în buffer-ul de ieșire.
Dacă nu faceți nimic, utilizatorul continuă să audă propoziția pe care tocmai a întrerupt-o în timp ce vorbește peste ea, iar agentul dă impresia că nu ascultă. Așadar, imediat ce primiți speech_started, opriți audio-ul care rulează, goliți buffer-ul de ieșire pentru a nu reda sunete învechite și lăsați serverul să proceseze noua intrare. Acești doi pași necesită câteva linii de cod și fac toată diferența dintre un agent pe care îl puteți întrerupe și unul care vorbește în gol.
Puncte cheie
- Evenimentele clientului acoperă configurarea, trimiterea audio, gestionarea conversației și controlul răspunsurilor
- Evenimentele serverului raportează detectarea vorbirii, fragmente audio, transcrieri și apeluri de funcție
- VAD gestionează automat întreruperile (barge-in)
- Majoritatea evenimentelor
errorsunt recuperabile: nu închideți conexiunea, gestionați eroarea - În modul manual, trebuie să apelați explicit
commitși apoiresponse.create