Κατανόηση των συμβάντων WebSocket
Σε αυτήν τη σελίδα
Μια συνομιλία αποτελούμενη από συμβάντα JSON
Στο παρασκήνιο, μια φωνητική ανταλλαγή με τον Voice Agent είναι απλώς μια ροή μηνυμάτων JSON που κινούνται και προς τις δύο κατευθύνσεις μέσω της σύνδεσης WebSocket. Κάθε μήνυμα διαθέτει ένα πεδίο type που προσδιορίζει τη φύση του. Μέχρι να μάθετε αυτό το λεξιλόγιο, ο πελάτης σας λειτουργεί στην τύχη. Μόλις το κατανοήσετε, γνωρίζετε ακριβώς πού να παρέμβετε για να διακόψετε μια απόκριση, να εμφανίσετε μια μεταγραφή ή να ανακάμψετε από ένα σφάλμα.
Τα συμβάντα χωρίζονται σε δύο κατηγορίες, ανάλογα με την κατεύθυνση μετάδοσής τους. Αυτά που στέλνετε εσείς καθοδηγούν τη συνεδρία· αυτά που λαμβάνετε σας ενημερώνουν για το τι συμβαίνει στον διακομιστή.
Τι στέλνει η εφαρμογή σας
Τα εξερχόμενα μηνύματά σας καλύπτουν τέσσερις ανάγκες: διαμόρφωση της συνεδρίας, τροφοδοσία του buffer ήχου, διαχείριση του ιστορικού συνομιλίας και έλεγχος της δημιουργίας αποκρίσεων.
| Συμβάν | Σκοπός |
|---|---|
session.update | Διαμορφώνει ή αναδιαμορφώνει τη συνεδρία (φωνή, οδηγίες, εργαλεία, VAD, μορφή ήχου) |
input_audio_buffer.append | Στέλνει ένα κομμάτι ήχου κωδικοποιημένο σε base64, συνεχώς όσο μιλάει ο χρήστης |
input_audio_buffer.commit | Οριστικοποιεί τα τρέχοντα περιεχόμενα του buffer ως μήνυμα του χρήστη· απαραίτητο μόνο σε χειροκίνητη λειτουργία |
input_audio_buffer.clear | Αδειάζει το buffer ήχου χωρίς να το επεξεργαστεί |
conversation.item.create | Προσθέτει ένα στοιχείο στη συνομιλία: ένα μήνυμα κειμένου, προηγούμενο ιστορικό ή το αποτέλεσμα κλήσης συνάρτησης |
conversation.item.delete | Διαγράφει ένα στοιχείο συνομιλίας βάσει του ID του |
response.create | Ζητά από το μοντέλο να δημιουργήσει μια απόκριση· αυτόματο σε λειτουργία VAD, ρητό σε χειροκίνητη λειτουργία |
response.cancel | Ακυρώνει μια απόκριση που βρίσκεται σε διαδικασία δημιουργίας |
Δύο από αυτά τα μηνύματα αξίζουν μια πιο προσεκτική ματιά. Το conversation.item.create είναι ο τρόπος με τον οποίο εισάγετε πλαίσιο: αυτό χρησιμοποιείτε για να επαναφέρετε το ιστορικό μιας προηγούμενης κλήσης στην αρχή μιας νέας συνεδρίας. Όσο για το input_audio_buffer.clear, φαντάζει χρήσιμο όταν ο χρήστης προφανώς δεν είπε κάτι άξιο επεξεργασίας (π.χ. ένα καθάρισμα λαιμού που κατέγραψε ένα υπερβολικά ευαίσθητο μικρόφωνο) και προτιμάτε να ξεκινήσετε ξανά από ένα καθαρό buffer αντί να αφήσετε το μοντέλο να ερμηνεύσει θόρυβο.
Τι στέλνει πίσω ο διακομιστής
Η εισερχόμενη ροή είναι πιο έντονη, καθώς παρέχει ένα συνεχές σχόλιο για κάθε βήμα επεξεργασίας.
| Συμβάν | Σημασία |
|---|---|
session.created | Η συνεδρία έχει ανοίξει |
session.updated | Έχει εφαρμοστεί μια ενημέρωση διαμόρφωσης |
conversation.created | Η συνομιλία έχει ρυθμιστεί |
input_audio_buffer.speech_started | Το VAD ανιχνεύει ότι ο χρήστης άρχισε να μιλά |
input_audio_buffer.speech_stopped | Το VAD ανιχνεύει ότι ο χρήστης σταμάτησε να μιλά |
input_audio_buffer.committed | Το buffer ήχου έχει οριστικοποιηθεί, είτε από το VAD είτε χειροκίνητα |
response.created | Μια απόκριση βρίσκεται σε διαδικασία δημιουργίας |
response.output_audio.delta | Ένα κομμάτι ήχου απόκρισης, σε base64 |
response.output_audio.done | Ο ήχος απόκρισης έχει ολοκληρωθεί |
response.output_audio_transcript.delta | Η μεταγραφή κειμένου του ήχου, σε ροή |
response.done | Η απόκριση έχει ολοκληρωθεί πλήρως |
conversation.item.input_audio_transcription.completed | Η μεταγραφή του μηνύματος του χρήστη είναι διαθέσιμη |
response.text.delta | Ροή κειμένου, για αποκρίσεις εκτός φωνής |
response.function_call_arguments.delta | Τα ορίσματα μιας κλήσης συνάρτησης, σε ροή |
response.function_call_arguments.done | Η κλήση συνάρτησης έχει ολοκληρωθεί και είναι έτοιμη για εκτέλεση |
error | Παρουσιάστηκε σφάλμα· τα περισσότερα σφάλματα είναι ανακτήσιμα |
Αυτό το τελευταίο χρειάζεται μια προειδοποίηση. Η λήψη του error δεν σημαίνει ότι η συνεδρία χάθηκε. Σύμφωνα με την αναφορά της xAI, τα περισσότερα σφάλματα είναι ανακτήσιμα και η συνεδρία παραμένει ανοιχτή, οπότε ένας πελάτης που κλείνει τη σύνδεση στο πρώτο error διακόπτει μια συνομιλία που θα μπορούσε να συνεχιστεί. Καταγράψτε το, ενημερώστε τον χρήστη αν χρειάζεται, αλλά κρατήστε την υποδοχή (socket) ανοιχτή.
Ο σκελετός ενός πελάτη
Στην πράξη, όλα ανάγονται σε έναν έλεγχο (switch) στο msg.type. Ορίστε η ελάχιστη δομή ενός πελάτη JavaScript:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Αποστολή session.update με τη διαμόρφωση
break;
case "input_audio_buffer.speech_started":
// Ο χρήστης μιλά: διακοπή του ήχου απόκρισης που αναπαράγεται
break;
case "response.output_audio.delta":
// Αποκωδικοποίηση του base64 και αναπαραγωγή του ήχου
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Εκτέλεση της συνάρτησης και αποστολή του αποτελέσματος πίσω
handleFunctionCall(msg);
break;
case "error":
console.error("Σφάλμα Voice Agent:", msg.error);
break;
}
};
Τέσσερις κλάδοι αρκούν για τη λειτουργία ενός πράκτορα: διαμόρφωση κατά το άνοιγμα της συνεδρίας, αντίδραση όταν ο χρήστης αρχίζει να μιλά, αναπαραγωγή του εισερχόμενου ήχου και εκτέλεση συναρτήσεων. Τα υπόλοιπα συμβάντα εμπλουτίζουν τη διεπαφή και μπορούν να περιμένουν για μια δεύτερη iteration.
Το δύσκολο κομμάτι: οι διακοπές
Το Barge-in, όταν ο χρήστης αρχίζει να μιλά ενώ ο πράκτορας απαντά ακόμα, είναι το σημείο όπου μια πρόχειρη υλοποίηση αποτυγχάνει. Ο διακομιστής ακυρώνει μόνος του την τρέχουσα απόκριση και αρχίζει να δημιουργεί μια νέα με βάση αυτό που μόλις άκουσε. Ωστόσο, ενώ ο διακομιστής έχει σταματήσει την αποστολή, η εφαρμογή σας κρατά ακόμα αρκετά δευτερόλεπτα ήδη ληφθέντος ήχου στο buffer εξόδου της.
Αν δεν κάνετε τίποτα, ο χρήστης συνεχίζει να ακούει την πρόταση που μόλις διέκοψε ενώ μιλάει από πάνω της, και ο πράκτορας φαίνεται ότι δεν ακούει. Επομένως, μόλις λάβετε το speech_started, σταματήστε τον ήχο που αναπαράγεται, καθαρίστε το buffer εξόδου ώστε να μην αναπαραχθεί παλιός ήχος και αφήστε τον διακομιστή να επεξεργαστεί τη νέα είσοδο. Αυτά τα δύο βήματα απαιτούν λίγες γραμμές κώδικα και κάνουν όλη τη διαφορά μεταξύ ενός πράκτορα που μπορείτε να διακόψετε και ενός που μιλάει στο κενό.
Βασικά σημεία
- Τα συμβάντα του πελάτη καλύπτουν τη διαμόρφωση, την αποστολή ήχου, τη διαχείριση της συνομιλίας και τον έλεγχο των αποκρίσεων
- Τα συμβάντα του διακομιστή αναφέρουν την ανίχνευση ομιλίας, κομμάτια ήχου, μεταγραφές και κλήσεις συναρτήσεων
- Το VAD διαχειρίζεται αυτόματα τις διακοπές (barge-in)
- Τα περισσότερα συμβάντα
errorείναι ανακτήσιμα: μην κλείνετε τη σύνδεση, χειριστείτε το σφάλμα - Σε χειροκίνητη λειτουργία, πρέπει να καλέσετε ρητά το
commitκαι στη συνέχεια τοresponse.create