Овладяване на събитията в WebSocket
На тази страница
Разговор, изграден от JSON събития
В основата си гласовият обмен с Voice Agent е просто поток от JSON съобщения, циркулиращи в двете посоки през WebSocket връзката. Всяко съобщение съдържа поле type, което указва неговия вид. Докато не овладеете тази терминология, клиентът Ви работи на късмет. Щом я усвоите, ще знаете точно къде да вмешате, за да прекъснете отговор, да покажете транскрипция или да се възстановите след грешка.
Събитията се делят на две семейства в зависимост от посоката на движение. Тези, които изпращате, управляват сесията; тези, които получавате, Ви информират какво се случва на сървъра.
Какво изпраща Вашето приложение
Изходящите Ви съобщения покриват четири основни нужди: конфигуриране на сесията, подаване на аудио буфер, управление на историята на разговора и контрол върху генерирането на отговори.
| Събитие | Цел |
|---|---|
session.update | Конфигурира или преконфигурира сесията (глас, инструкции, инструменти, VAD, аудио формат) |
input_audio_buffer.append | Изпраща чанк аудио, кодиран в base64, непрекъснато докато потребителят говори |
input_audio_buffer.commit | Фиксира текущото съдържание на буфера като съобщение от потребителя; необходимо само в ръчен режим |
input_audio_buffer.clear | Изчиства аудио буфера без да го обработва |
conversation.item.create | Добавя елемент към разговора: текстово съобщение, предишна история или резултат от извикване на функция |
conversation.item.delete | Изтрива елемент от разговора по неговия ID |
response.create | Иска от модела да генерира отговор; автоматично във VAD режим, изрично в ръчен режим |
response.cancel | Отменя отговор, който се генерира в момента |
Две от тези съобщения заслужават по-внимателен поглед. conversation.item.create е механизмът, чрез който.injectирате контекст: това е инструментът, който използвате, за да възстановите историята от предишно обаждане в началото на нова сесия. Що се отнася до input_audio_buffer.clear, то е полезно, когато потребителят очевидно не е казал нищо стойностно за обработка (например прочистване на гърлото, уловено от свръхчувствителен микрофон) и предпочитате да започнете отново с чист буфер, вместо да оставите модела да интерпретира шум.
Какво изпраща сървърът в отговор
Входящият поток е по-натоварен, тъй като предоставя коментар в реално време за всяка стъпка от обработката.
| Събитие | Значение |
|---|---|
session.created | Сесията е отворена |
session.updated | Приложена е актуализация на конфигурацията |
conversation.created | Разговорът е настроен |
input_audio_buffer.speech_started | VAD открива, че потребителят е започнал да говори |
input_audio_buffer.speech_stopped | VAD открива, че потребителят е спрял да говори |
input_audio_buffer.committed | Аудио буферът е фиксиран, чрез 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, прекъсва разговор, който би могъл да продължи. Регистрирайте я, уведомете потребителя при необходимост, но запазете сокета отворен.
Скелетът на един клиент
На практика всичко се свежда до превключване (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 error:", msg.error);
break;
}
};
Четири клона са достатъчни за работа на агента: конфигуриране при отваряне на сесията, реакция при започване на говор от потребителя, възпроизвеждане на входящо аудио и изпълнение на функции. Останалите събития обогатяват интерфейса и могат да изчакат втора итерация.
Трудната част: прекъсванията
Barge-in, ситуацията в която потребителят започва да говори, докато агентът все още отговаря, е моментът, в който лошата имплементация личи най-ясно. Сървърът автоматично отменя текущия отговор и започва да генерира нов въз основа на току-що чутото. Но докато сървърът е спрял да изпраща, Вашето приложение все още държи няколко секунди вече получено аудио в изходния си буфер.
Ако не направите нищо, потребителят продължава да чува изречението, което току-що е прекъснал, докато говори върху него, и агентът създава впечатление, че не слуша. Затова веднага щом получите speech_started, спрете възпроизвежданото аудио, изчистете изходния буфер, за да не пуснете остарял звук, и позволете на сървъра да обработи новия вход. Тези две стъпки отнемат няколко реда код, но правят цялата разлика между агент, който може да бъде прекъснат, и такъв, който говори в празнотата.
Ключови изводи
- Събитията от клиента покриват конфигурацията, изпращането на аудио, управлението на разговора и контрола на отговорите
- Събитията от сървъра докладват откриване на реч, аудио чанкове, транскрипции и извиквания на функции
- VAD обработва прекъсванията (barge-in) автоматично
- Повечето събития
errorса възстановими: не затваряйте връзката, а обработете грешката - В ръчен режим трябва изрично да извикате
commit, последвано отresponse.create