Преобразование речи в текст (speech to text)
- Asia Khalitova (Unlicensed)
- Vladislav Isakov
- Ilya Titaev
- Evgeniy
Протестировать методы API можно на странице интерактивного обозревателя API и без написания кода
Некоторые ресурсы, описанные на странице, по умолчанию могут быть не доступны из-за типа приложения (см. Создание и авторизация приложений)
Преобразование речи в текст может быть двух видов:
Правило голосовой навигации (voice_helper) в голосовом меню.
Отправка распознанного текста событиями во время разговора.
Работает только при активированной функции speech_to_text в клиентской конфигурации (эта настройка доступна только администратору платформы)
Правило голосовой навигации в голосовом меню:
Перед заданием правил голосовой навигации администратором платформы должна быть включена возможность использования правила voice_helper голосового меню. В обратном случае правило не может быть создано, а при отключении функционала правило в настройках голосового меню будет проигнорировано. Права приложения API должны быть all (также включается администратором платформы). Настройка выполняется аналогично другим правилам голосового меню в опциях контекста, количество правил также не ограничено. В ходе распознавания доступен финальный результат распознавания и предположения (предположения доступны в случае прерывания распознавания по набору цифр либо по тайм-ауту).
Описание структур данных
Имя | Тип | Описание |
|---|---|---|
action | string | voice_helper – установить правило голосовой навигации. |
sound | integer | Идентификатор звукового файла, который необходимо проиграть, можно получить с помощью ресурса: GET /client/{client_id}/sound/ |
voice_helper_digits_max | integer | Количество цифр донабора, после которого заканчивается распознавание речи. Если на момент до набора нужного количества digits финальный результат распознавания недоступен, мы будем работать с предположениями |
voice_helper_rules | string | Список правил переадресации в виде массива { “to_option” : номер_опции, “transcription”: “распознанное слово” } |
voice_helper_timeout | integer | Время в миллисекундах, по истечении которого заканчивается распознавание речи. Если за это время финальный результат недоступен, мы будем работать с предположениями. Минимальное значение — 3000 |
voice_helper_classic_term | boolean | Разрешить либо запретить классический донабор с клавиатуры (по умолчанию запрещено и используется только как прерывание распознавания, см. параметр voice_helper_digits_max). |
max_pause_between_words | integer | Максимально допустимая пауза между словами клиента. Указывается в миллисекундах. Значения: 500 - минимальное 1500 - по умолчанию 10000 - максимальное |
language | string | Язык, который будет использоваться для распознавания речи. Если язык уже выбран в настройках клиента - будет установлен данный язык(только если он в доступном списке языков). Доступные значение: ru - Русский en - Английский (по умолчанию) |
voice_helper_long_speech_expected | boolean | Нужен для более точной работы перевода из голоса в текст. Если ожидается, что клиенты будут использовать короткие фразы/слова - лучше не устанавливать в значение True В ином случае, если клиентами будут использоваться объёмные предложения - установите в True |
Создание правила голосового меню
К примеру, вызов попадает на внутренний номер с extension_id 204 в контекст 1 на опцию “start“. Будем считать, что контекст пустой и правил в нем еще нет. Добавляем правило, отправляем запрос:
Ответ системы (остальные параметры не имеют значения и исключены из примера):
{
…
"voice_helper_sound": 52,
"voice_helper_timeout": 7000,
"id": 39,
"voice_helper_digits_max": "2",
"voice_helper_rules": [
{
"transcription": "привет|здравствуй|здарова",
"to_option": 1
},
{
"transcription": "прощай|пока",
"to_option": 2
}
],
"final": true,
"action": "voice_helper",
…
}В ответе на запрос будет содержаться идентификатор созданного правила: "id": 39. В результате указанного выше запроса будет создано правило голосовой навигации, по которому будет проиграна мелодия по умолчанию.
Опции to_option, куда попадут при сообщении слова из transcription, должны быть созданы (они не создаются автоматически). Параметр transcription может содержать как точное слово, так и часть слова.
Создание звукового приветствия
Если нужно задать конкретное звуковое приветствие, чтобы сообщить в нем, что от звонящего ожидается то или иное слово, нужно заранее подготовить звуковой файл. Ресурс “Звуковые файлы” позволит загрузить файл и узнать идентификатор этого файла. После этого нужно обновить параметры правила голосового помощника, задав идентификатор необходимого звукового файла.
Обновление параметров правила голосового помощника
Обновить любой параметр правила можно с помощью метода
PUT /api/ver1.0/extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/{rule_id}
К примеру, для задания актуального приветствия с указанием нужного идентификатора файла SOUND_ID нужно отправить вышеуказанный запрос с телом{"sound": SOUND_ID}
Аналогичным способом обновляется любой параметр правила voice_helper. Например, можно заменить правила voice_helper_rules с помощью запроса
PUT /api/ver1.0/extension/{extension_id}/ivr/context/{context_id}/options/{option_digits}/rules/{rule_id} с телом
{"voice_helper_rules": [
{
"to_option": 1,
"transcription": "продукты|еда"
},
{
"to_option": 2,
"transcription": "комиксы|комик|икс"
}
]
}Не рекомендуется задавать много условий в одном правиле voice_helper_rules (желательно не более 500).
Параметр to_option – это опции контекста (start, invalid, timeout, 1, 2, 3, 4 и т.д.). Правило voice_helper создано в опции start, а навигация голосом будет по опциям 1-10 (либо, к примеру, по 4-40).
Создание опций выполняется запросом
POST /api/ver1.0/extension/{extension_id}/ivr/context/{context_id}/options/ с телом
{"digits": "string"}где string – опции контекста start, invalid, timeout, 1, 2, 3, 4 и т.д.
Получение распознанных данных удаленным сервером
Существует возможность получить данные распознавания на своем удаленном сервере.
Функция “Call Interactive” позволяет в качестве действия опции контекста голосового меню (IVR) инициировать HTTP-запрос на заданный URL и обработать ответ на него. С запросом передается постоянный набор параметров, содержащий информацию о вызове в IVR. Для управления действиями после распознавания существуют опциональные параметры запроса функции Call Interactive:
voice_navigator_DTMF – донабор с телефонного терминала во время правила голосового меню action='voice_helper';
voice_navigator_STT – содержит распознавание голоса во время правила голосового меню action='voice_helper'.
Функция “Call interactive” запросом POST http://mysite.com/myscript?check_number возвращает нужное приветствие с указанием дополнительных параметров, помимо TTS (play_now="false", save_to_var="true"). В таком случае voice_helper c заданным параметром play_sound_from_variable проигнорирует установленное у себя приветствие.
Вызов попадает в стартовый контекст (start), где помимо стандартных опций контекста (start, timeout, invalid) настроены пользовательские опции, например: “1” – ‘call_interactive’, “2” – ‘voice_helper'. Система ожидает, когда звонящий скажет что-то либо донаберет опцию (это объявлено в правиле voice_helper). Например, если звонящий скажет “оператор” – попадет на опцию “0”, а если что-либо из заданных слов (например: "узнать, дату, дата, готовности, готовность, отгрузке, отгрузка, товар, счету, счет") либо наберет 1 – попадет на опцию “1”, где будет работать правило Call Interactive, по которому на сервер будет отправлен запрос POST http://mysite.com/myscript?check_stt_res , после чего сервером будут получены данные:voice_navigator_STT=%D1%85%D0%BE%D1%87%D1%83+%D1%83%D0%B7%D0%BD%D0%B0%D1%82%D1%8C+%D0%B4%D0%B0%D1%82%D1%83+%D0%B3%D0%BE%D1%82%D0%BE%D0%B2%D0%BD%D0%BE%D1%81%D1%82%D0%B8+%D0%BA+%D0%BE%D1%82%D0%B3%D1%80%D1%83%D0%B7%D0%BA%D0%B5+%D1%82%D0%BE%D0%B2%D0%B0%D1%80%D0%B0url decode voice_navigator_STT=хочу узнать дату готовности к отгрузке товара
либо voice_navigator_DTMF=1
Если в правиле voice_helper ни одна из опций не отработает (не донаберут или не скажут ни “0”, ни “1”), то в стартовом контексте будет звучать приветствие по умолчанию с предложением соединиться с оператором (“Скажите “оператор” или нажмите “0”). В таком случае можно добавить Call interactive с запросом запрос POST http://mysite.com/myscript?no_option_voice_helper, в котором если и будет voice_navigator_STT, то оно будет содержать значение, альтернативное опциям “0” и “1” (например, если звонящий спросит: "А куда я попал?”), после чего можно задавать другие действия как управлением из Call Interactive, так и статическими правилами в IVR.
События с распознанным текстом
Чтобы получить события с финальным распознанным текстом во время разговора, необходимо воспользоваться следующей схемой. По событию на внутреннем номере (dial-in для входящих вызовов в IVR, anwser для входящих и исходящих с внутреннего номера типа “телефонный терминал”) в зависимости от CallFlow события нужно запомнить extension_id (идентификатор внутреннего номера; если in — CalledExtensionID, если out — CallerExtensionID) и CallAPIID и воспользоваться ресурсом:
PUT /extension/{extension_id}/speech_to_text/{call_api_id}
Описание структур данных
Имя | Тип | Описание |
|---|---|---|
extension_id | string | Идентификатор внутреннего номера |
call_api_id | string | Идентификатор звонка, по которому начнется распознавание речи |
action | string | Действие, может принимать значения start или stop |
direction | string | Направление распознанной речи относительно extension_id: out — если голос идет от внутреннего номера, in — если голос идет к внутреннему номеру |
url | string | URL, куда будут отправляться события с распознанным из речи текстом |
При повторной попытке одного и того же action с одним и тем же direction на один и тот же разговор будет выдано сообщение об ошибке!
События выглядят подобным образом:
Длину контента можно считать по Content-Length.
Распознанный текст в читаемом виде – после url decode utf8.