Премини към основното съдържание
Български— Изберете език
Меню

Овладяване на събитията в WebSocket

Урок 4 от 14 Обновен 29 юли 2026 г. Средно
На тази страница
  1. Разговор, изграден от JSON събития
  2. Какво изпраща Вашето приложение
  3. Какво изпраща сървърът в отговор
  4. Скелетът на един клиент
  5. Трудната част: прекъсванията
  6. Ключови изводи

Разговор, изграден от 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_startedVAD открива, че потребителят е започнал да говори
input_audio_buffer.speech_stoppedVAD открива, че потребителят е спрял да говори
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