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

Обновлено 19 февраля 2025

Этот протокол больше не поддерживается. Рекомендуем использовать API потокового распознавания двух каналов (gRPC v2).

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

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

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

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

smartspeech.sber.ru

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

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

authorization

Bearer <Access token>

required

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

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

x-request-id

string

required

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

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

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

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

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

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

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

audio_encoding

enum (AudioEncoding)

Аудиокодек.
Возможные значения смотрите в разделе Доступные форматы аудио

sample_rate

int32

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

language
string
Язык для распознавания речи.
Возможные значения:
• ru-RU — русский. Значение по умолчанию.
• en-US — английский.
• kk-KZ — казахский. Доступно по отдельной заявке, напишите на почту SaluteSpeech@sberbank.ru
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

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

insight_models

repeated string

Модель SaluteSpeech Insights для анализа удовлетворенности клиентов.
Единственное возможное значение: call_features

Контракт взаимодействия описан в proto-файле.

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

Клиент передает аудио в составе сообщений 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. Наибольшее значение обозначает главного спикера

Контракт взаимодействия описан в proto-файле.

Коды ошибок

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

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

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