API потокового распознавания речи (gRPC)

Обновлено 24 мая 2023

Используется, если требуется распознавать речь в процессе ее записи, например, протоколы телефонии или запись аудио на мобильном устройстве.

Возможно отображение промежуточных результатов и автоматическое определение конца фразы.

Максимальный размер аудио – 1 Гб. Для многоканального аудио распознается только первый канал.

Запросы на распознавание передаются на адрес:

smartspeech.sber.ru

Заголовки запросов и ответов для всех шагов одинаковы:

Заголовки запроса

authorization required

string <Bearer <Access token>> Информация об аутентификации с помощью Access Token, переданная через OAuth 2.0. Пример: Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw

{

• "authorization": "string"

}

Заголовки ответа

x-request-id required

string Уникальный идентификатор запроса, генерируемый сервером. 36 символов. Пример: 22345200-abe8-4f60-90c8-0d43c5f6c0f6

{

• "x-request-id": "string"

}

Создание приложения

Для работы с сервисом распознавания речи SaluteSpeech вам необходимо создать клиентское приложение. Вы можете использовать любой язык программирования, который есть в библиотеке для работы с gRPC.

При написании приложения используйте proto-файл.

Подробную инструкцию по написанию клиентских приложений для gRPC с примерами вы найдете в официальной документации gRPC (английский язык).

Передача параметров распознавания

При обращении по gRPC-протоколу с запросом распознавания речи клиентское приложение использует метод Recognize. В первом сообщении клиент должен отправить опции распознавания в сообщении типа RecognitionOptions. Параметры этого сообщения:

audio_encoding	enum (AudioEncoding) Аудиокодек. Возможные значения смотрите в разделе Доступные кодировки аудио
sample_rate	int32 Частота дискретизации. Зависит от значения audio_encoding, подробнее читайте в разделе Доступные кодировки аудио
enable_profanity_filter	boolean Фильтр обсценной лексики. Возможные значения: true и false. Значение по умолчанию — false
enable_multi_utterance	boolean Распознавание либо одного, либо нескольких предложений. Возможные значения: true и false. Значение по умолчанию — false
enable_partial_results	boolean Отправка промежуточных гипотез распознавания речи. Возможные значения: true и false. Значение по умолчанию — false
hypotheses_count	int32 Количество сообщаемых альтернативных гипотез распознанной речи. Любое число от 0 до 10. Значение по умолчанию — 1
model	string Имя акустической модели для распознавания речи. Подробнее читайте в разделе Акустические модели
no_speech_timeout	Duration Интервал ожидания речи пользователя. Любое число от 2 до 20. По умолчанию – 7 секунд
max_speech_timeout	Duration Определение максимальной длины высказывания до форсированного EOU. Любое число от 0,5 до 20. По умолчанию – 20 секунд
channels_count	int32 Количество каналов в многоканальном аудио. Об ограничениях читайте в разделе Доступные кодировки аудио
Hints	array (составной тип, см. ниже — Hints) Хинты
Hints.words	repeated string Список слов или фраз, распознавание которых мы хотим усилить. Здесь можно перечислить слова, которые с высокой вероятностью будет произносить пользователь
Hints.enable_letters	boolean Модель коротких фраз, улучшающая распознавание отдельных букв и коротких слов. Возможные значения: true и false. Значение по умолчанию — false
Hints.eou_timeout	Duration Настройка распознавания конца фразы (End of Utterance — eou). Такое распознавание будет ожидаться после конца фразы столько секунд, сколько установлено в этом параметре. Возможные значения от 0.5 до 5 секунд. По умолчанию распознавание конца фразы срабатывает после 1 секунды
SpeakerSeparationOptions	array (составной тип, см. ниже — SpeakerSeparationOptions) Параметры разделения спикеров для фрагментов одновременной речи
SpeakerSeparationOptions.enable	boolean Включение функции разделения спикеров. Возможные значения: true и false. Значение по умолчанию — false
SpeakerSeparationOptions.enable_only_main_speaker	boolean Возвращение только главного спикера. Главный находится по max(main_speaker_confidence). Возможные значения: true и false. Значение по умолчанию — false
SpeakerSeparationOptions.count	int32 Масимальное число спикеров. В текущей реализации распознаются записи с двумя спикерами
force_cyrillic	boolean Принудительный перевод латиницы в кириллицу. Возможные значения: true и false. Значение по умолчанию — false
insights_model	repeated string Модели SaluteSpeech Insights для анализа удовлетворенности клиентов. Единственное возможное значение: call_features

{

• "audio_encoding": null,
• "sample_rate": null,
• "enable_profanity_filter": true,
• "enable_multi_utterance": true,
• "enable_partial_results": true,
• "hypotheses_count": null,
• "model": "string",
• "no_speech_timeout": null,
• "max_speech_timeout": null,
• "channels_count": null,
• "Hints": null,
• "Hints.words": null,
• "Hints.enable_letters": true,
• "Hints.eou_timeout": null,
• "SpeakerSeparationOptions": null,
• "SpeakerSeparationOptions.enable": true,
• "SpeakerSeparationOptions.enable_only_main_speaker": true,
• "SpeakerSeparationOptions.count": null,
• "force_cyrillic": true,
• "insights_model": null

}

Процесс распознавания речи

Клиент передает аудио в составе сообщений RecognitionRequest.audio_chunk типа bytes, которые заполняет чанками (кусочек потокового аудио) бинарного потока аудио, и закрывает со своей стороны соединение на запись, если знает, что поток аудио на этом чанке прерывается.

Размер одного сообщения — не более 4 Мб. Длительность одного чанка — не более 2 секунд.

Пауза между сообщениями не должна превышать 5 секунд. Оптимально, чтобы длина паузы совпадала с длиной следующего чанка. Если такое ограничение не подходит, используйте асинхронное распознавание.

В режиме enable_multi_utterance=false распознавание подаваемого клиентом потока звука продолжается до тех пор, пока сервис распознавания речи не определит конец предложения и не оповестит клиента об этом. Клиенту при этом передается финальный результат распознавания с проставленным флагом eou=true. Далее сервер закрывает соединение, все оставшиеся чанки звука будут проигнорированы.

В режиме enable_multi_utterance=true распознавание речи не останавливается с окончанием очередного предложения, которое будет отмечено в потоке ответов финальной гипотезой с флагом eou=true. После распознавания финальной фразы сервер закрывает соединение со статусом 0.

Заголовки ответа

В качестве заголовка в ответе передаются метаданные. Подробнее о читайте в официальной документации gRPC.

Содержимое ответа

Сервис в ответ асинхронно передает клиенту сообщения RecognitionResponse со следующими параметрами:

eou	boolean Признак окончания распознанного предложения. Если true, то данный результат распознавания можно считать финальным. Если false, то возможно уточнение распознавания в следующих сообщениях
results	array (составной тип, см. ниже — Hypothesis) Список гипотез распознавания речи. Гипотезы отсортированы по убыванию вероятности
Hypothesis.text	string Не нормализованный результат распознавания (например, сто двадцать три)
Hypothesis.normalized_text	string Нормализованный результат распознавания (например, 123)
Hypothesis.start	google.protobuf.Duration Время от начала аудиозаписи до начала данной гипотезы в ней
Hypothesis.end	google.protobuf.Duration Время от начала аудиозаписи до конца данной гипотезы в ней
emotions_result	array (составной тип, см. ниже — Emotions) Список эмоций ответа пользователя. Значения эмоционального окраса ответа пользователя приходят в виде коэффициентов в диапазоне от 0 до 1, где 1 — наиболее вероятная эмоция ответа, а 0 — наименее вероятная. Значения заполняются только, если eou=true
Emotions.positive	float Позитивный оттенок ответа пользователя
Emotions.neutral	float Нейтральный оттенок ответа пользователя
Emotions.negative	float Негативный оттенок ответа пользователя
backend_info	array (составной тип, см. ниже — BackendInfo) Информация об использованных версиях модели и сервера
BackendInfo.model_name	string Наименование модели, использованной для распознавания
BackendInfo.model_version	string Версия модели, использованной для распознавания
BackendInfo.server_version	string Версия сервера, использованного для распознавания
processed_audio_start	google.protobuf.Duration Время начала обработанного фрагмента аудио
processed_audio_end	google.protobuf.Duration Время окончания обработанного фрагмента аудио
SpeakerInfo	array (составной тип, см. ниже — SpeakerInfo) Информация о разделении спикеров
SpeakerInfo.speaker_id	int32 Идентификатор результата распознавания. У результата с обоими спикерами он всегда -1
SpeakerInfo.main_speaker_confidence	float Маркер главного спикера. Может принимать значения от 0 до 1. Наибольшее значение обозначает главного спикера

{

• "eou": true,
• "results": null,
• "Hypothesis.text": "string",
• "Hypothesis.normalized_text": "string",
• "Hypothesis.start": null,
• "Hypothesis.end": null,
• "emotions_result": null,
• "Emotions.positive": null,
• "Emotions.neutral": null,
• "Emotions.negative": null,
• "backend_info": null,
• "BackendInfo.model_name": "string",
• "BackendInfo.model_version": "string",
• "BackendInfo.server_version": "string",
• "processed_audio_start": null,
• "processed_audio_end": null,
• "SpeakerInfo": null,
• "SpeakerInfo.speaker_id": null,
• "SpeakerInfo.main_speaker_confidence": null

}

Коды ошибок

Сервис SaluteSpeech сообщает об ошибках стандартными gRPC-статусами, про которые можно подробно прочесть в официальной документации.

Некоторые коды и описание ошибок:

Код	Описание
3	INVALID_ARGUMENT Клиент неправильно заполнил параметры распознавания речи
7	PERMISSION_DENIED Клиенту недоступно API распознавания речи
9	RESOURCE_EXHAUSTED Клиент превысил квоту на распознавание речи
13	INTERNAL Ошибка в работе сервиса распознавания речи
16	UNAUTHENTICATED Клиент не предоставил, либо предоставил истекший/невалидный Access Token в заголовке Authorization