Распознавание речи

Для распознавания речи мы используем HTTPS и gRPC протоколы.

Описание API распознавания через HTTPS

POST HTTP-запрос отправляется по адресу:

https://sberspeech.host.name/rest/v1/speech:recognize

Запрос

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

Наименование Описание

Authorization

Обязательное

Информация об аутентификации с помощью JWE, переданная через OAuth 2.0

Bearer JWE токен

Пример Bearer eyJhbGciOi.cCI6IkpXVCJ9.eyJzd.1hcnRzcG.KUkw

Content-Type

Обязательное

Формат данных, передаваемых в теле запроса

ASCII строка, одно из следующих значений:

  • "audio/x-wav;rate=8000",

  • "audio/x-wav;rate=16000",

  • "audio/ogg;codecs=opus",

  • "audio/x-pcm;bit=16;rate=8000",

  • "audio/x-pcm;bit=16;rate=16000"

Пример audio/x-wav;rate=8000

Параметры запроса

Наименование Описание

model

Название модели для распознавания речи

ASCII строка, любое значение из ["general", "media", "ivr", "callcenter"]

Значение по умолчанию general

language

Язык для распознавания речи

ASCII строка, пока доступно только значение ru-RU

enable_profanity_filter

Фильтр обсценной лексики

boolean, значение по умолчанию false

Описание Content-Type

Значение Описание формата

audio/x-wav;rate=8000

WAV 8bit LE signed вместе с заголовком, поддерживается только одноканальный звук

audio/x-wav;rate=16000

WAV 16bit LE signed вместе с заголовком, поддерживается только одноканальный звук

audio/ogg;codecs=opus

Opus в контейнере ogg, битрейт берётся из заголовка самого аудио кодека, поддерживается только одноканальный звук

"audio/x-pcm;bit=16;rate=8000

PCM 8bit LE signed вместе с заголовком, поддерживается только одноканальный звук

"audio/x-pcm;bit=16;rate=16000

PCM 16bit LE signed вместе с заголовком, поддерживается только одноканальный звук

Ответ

Тело HTTP-ответа содержит json с результатом распознавания речи, если запрос обработан успешно (код ответа 200).

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

Наименование Описание

X-Request-ID

Обязательное

Уникальный ID запроса, генерируемый сервером

ASCII строка, 36 символов

22345200-abe8-4f60-90c8-0d43c5f6c0f6

Content-Type

Обязательное для статуса 200

Формат тела ответа сервиса

application/json

Формат ответа при успешном запросе

При успешном запросе вы получаете HTTP-код 200.

{"result": ["предложение №1", "предложение №2", ...], "status": 200}

Формат ответа при неуспешном запросе

Если запрос неуспешен, вы получаете HTTP-код, отличный от 200, с расширенным описанием ошибки в JSON-формате.

Код Описание

400

Ошибка в параметрах запроса

Пример {"status": 400, "message: <описание ошибки входящих параметров>}

401

Не предоставлен токен для аутентификации

Пример {"status": 401, "message": "Unauthorized"}

413

Превышен максимальный размер входных данных

Пример {"status": 413, "message": "Payload too large"}

429

Слишком много запросов

Пример {"status": 429, "message": "Too Many Requests"}

500

Внутренняя ошибка сервиса

Пример {"status": 500, "message": "Internal Server Error"|<описание ошибки ASR>"}

Описание API распознавания через gRPC

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

smartspeech.sber.ru

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

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

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

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

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

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

Параметр Описание

audio_encoding

enum (AudioEncoding)

Аудио-кодек

pcm16_se (16-битный PCM-поток с одним аудио-каналом, закодированный знаковыми целыми числами) или opus (ogg-поток с аудио-кодеком opus внутри)

sample_rate

int32

Частота дискретизации

Параметр поддерживается только для pcm-потока, значение по умолчанию — 16000Гц, частота дискретизации должна быть 16000Гц для моделей general и media, 8000Гц для моделей ivr и callcenter

language

string

Международный код языка для распознавания речи

На данный момент поддерживается только русский язык — ru-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

Количество сообщаемых альтернативных гипотез распознанной речи

Любое число больше нуля и до 10, по умолчанию 1

model

string

Имя языковой модели для распознавания речи

general, ivr, callcenter, media

Модели general и media имеют частоту дискретизации 16000 Гц, модели ivr и callcenter имеют частоту дискретизации 8000 Гц и предназначены для телефонии

no_speech_timeout

Duration

Интервал ожидания речи пользовател

Возможные значения от 2 до 20 секунд. По умолчанию стоит 7 секунд

max_speech_timeout

Duration

Определение максимальной длины высказывания до форсированного EOU

По умолчанию стоит максимальное значение — 20 секунд

Hints

Hints — составной тип, описан ниже

Hints.words

repeated string

Список слов или фраз, распознавание которых мы хотим усилить. Здесь можно перечислить слова, которые с высокой вероятностью будет произносить пользователь

Hints.enable_letters

boolean

Модель коротких фраз, улучшающая распознавание отдельных букв и коротких слов

true/false, значение по умолчанию — false

Hints.eou

Duration

Настройка распознавания конца фразы (End of Utterance — eou). Такое распознавание будет ожидаться после конца фразы столько секунд, сколько установлено в этом параметре

Возможные значения от 0.5 до 5 секунд. По умолчанию распознавание конца фразы срабатывает после 1 секунды

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

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

Поле Описание

eou

boolean

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

true/false

result

Hypothesis (составной тип, см. ниже)

Список гипотез распознавания речи

Гипотезы отсортированы по убыванию вероятности

Hypothesis.text

string

Не нормализованный результат распознавания (например, "сто двадцать три")

Hypothesis.normalized_text

string

Нормализованный результат распознавания (например, "123")

Hypothesis.start

google.protobuf.Duration

Время от начала аудио-записи до начала данной гипотезы в ней

Hypothesis.end

google.protobuf.Duration

Время от начала аудио-записи до конца данной гипотезы в ней

emotions_result

Emotions (составной тип, см. ниже)

Список эмоций ответа пользователя

Значения эмоционального окраса ответа пользователя приходят в виде коэффициентов в диапазоне от 0 до 1, где 1 — наиболее вероятная эмоция ответа, а 0 — наименее вероятная.

Значения заполняются только, если eou=true

Emotions.positive

float

Позитивный оттенок ответа пользователя

Emotions.neutral

float

Нейтральный оттенок ответа пользователя

Emotions.negative

float

Негативный оттенок ответа пользователя

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

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

Сообщения об ошибках

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

Код Описание

3

INVALID_ARGUMENT

Клиент неправильно заполнил параметры распознавания речи

7

PERMISSION_DENIED

Клиенту недоступно API распознавания речи

9

RESOURCE_EXHAUSTED

Клиент превысил квоту на распознавание речи

13

INTERNAL

Ошибка в работе сервиса распознавания речи

16

UNAUTHENTICATED

Клиент не предоставил, либо предоставил истекший/невалидный JWE-токен в заголовке Authorization

Для каждого из сообщений подробное описание произошедшей ошибки указывается в поле message.

Как получить текст из аудио

Для полноценной работы с распознаванием речи необходимо клиентское приложение. При его разработке используйте описание API для распознавания речи. Клиентское приложение общается с сервисом SmartSpeech. Сам процесс распознавания в зависимости от настроек выглядит следующим образом:

  1. Приложение отправляет gRPC-запрос к методу Recognize сервиса SmartSpeech. В сообщениях рекомендуется отправлять следующие опции распознавания:
  2. В заголовке — информация для аутентификации.
  3. В первом сообщении — сообщение RecognitionOptions с описанием параметров распознавания.
  4. В последующих сообщениях — чанки звука для распознавания.
  5. Аудио поток передаётся в сообщениях RecognitionRequest.audio_chunk.
  6. В ответ приходят сообщения RecognitionResponse, содержащие нормализованный и ненормализованный текст в полях Hypothesis.normalized_text и Hypothesis.text.

Как улучшить распознавание

Хинты

Распознавание речи можно сильно улучшить использованием хинтов. Хинты — это одноразовые подсказки для сервиса распознавания речи, помогающие правильно понять речь пользователя в определённый момент времени. Например, когда приложение ожидает от пользователя конкретный ответ, этот ответ заранее придёт в сервис в виде хинтов. Подсказка работает только для следующего ответа пользователя. После использования хинтов процесс распознавания речи пользователя возвращается к её обработке без подсказок.

Виды хинтов

Хинты могут быть не только списком слов или фраз. Существуют следующие виды хинтов:

  • words — позволяет использовать список слов или фраз, распознавание которых мы хотим усилить. Здесь можно перечислить слова, которые с высокой вероятностью будет произносить пользователь, отвечая ассистенту в приложении.
  • enable_letters — позволяет включить модель коротких фраз, тем самым улучшить распознавание отдельных букв и коротких слов.
  • eou — меняет настройку распознавания конца фразы (End of Utterance - eou). Такое распознавание будет ожидаться после конца фразы столько секунд, сколько установлено в этом параметре. Возможные значения от 0.5 до 5 секунд. По умолчанию распознавание конца фразы срабатывает после 1 секунды.

Передача хинтов

Хинты передаются в типе сообщения Hints. Само сообщение Hints включается в параметры сообщения RecognitionOptions и передаётся однократно в первом сообщении на старте распознавания.

message Hints {
  repeated string words = 1;
  bool enable_letters = 2;
  google.protobuf.Duration eou = 3;
}

Пример клиентского приложения на Python

Мы подготовили пример клиентского приложения на Python в GitHub. Следите за нашей страницей на GitHub, скоро там появятся примеры клиентского приложения на других популярных языках программирования.

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней