ym88659208ym87991671
gRPC API потокового распознавания речи сервиса SaluteSpeech | Документация для разработчиков

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

Обновлено 4 июня 2024

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

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

Максимальный размер аудио – 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, подробнее читайте в разделе Доступные форматы аудио

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

{
  • "audio_encoding": null,
  • "sample_rate": null,
  • "language": "string",
  • "enable_profanity_filter": true,
  • "enable_multi_utterance": true,
  • "enable_partial_results": true,
  • "hypotheses_count": null,
  • "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,
  • "insight_models": null
}

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

{
  • "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
}

Контракт взаимодействия описан в 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

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.