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

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

Обновлено 10 декабря 2024

Асинхронное распознавание по протоколу gRPC проходит в несколько шагов:

  1. Создание клиентского приложения.
  2. Загрузка файла для распознавания.
  3. Создание задачи на асинхронное распознавание.
  4. Проверка статуса задачи.
  5. Скачивание результата.

Запросы к API передаются на адрес:

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-протоколу клиентское приложение отправляет аудиофайл с помощью метода Upload. Аудиофайл отправляется в виде чанков в сообщении UploadRequest.file_chunk типа bytes.

Сервис вернет сообщение UploadResponse с идентификатором загруженного файла в параметре request_file_id.

Протокол взаимодействия смотрите по ссылке.

Создание задачи

С помощью метода AsyncRecognize клиентское приложение передает идентификатор загруженного файла и параметры распознавания. В ответе сервис вернет уникальный идентификатор задачи на распознавание.

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

Получение статуса задачи

Клиентское приложение передает идентификатор задачи на распознавание с помощью метода Task. Если задача готова, в ответе придет объект Task со статусом DONE и идентификатор файла с результатом распознавания в параметре response_file_id. При статусе ERROR описание ошибки будет отображаться в параметре error.

Пример структуры Task для gRPC можно посмотреть по ссылке.

Отмена задачи

Если при проверке статуса сервис вернул объект Task со статусом NEW, задачу можно отменить. Клиентское приложение передает идентификатор задачи с помощью метода CancelTask. В ответе сервис вернет объект Task со статусом CANCELED.

Пример структуры Task для gRPC можно посмотреть по ссылке.

Скачивание результата

Клиентское приложение передает идентификатор файла с результатом распознавания с помощью метода Download. Значение передается в параметре response_file_id сообщения DownloadRequest. Сервис вернет результат распознавания в виде чанков в сообщении DownloadResponse.

Параметры ответа

results
array (составной тип, см. ниже — Results)

Список гипотез распознавания речи. Гипотезы отсортированы по убыванию вероятности

Results.text
string

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

Results.normalized_text
string

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

Results.start
string

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

Results.end
string

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

Results.word_alignments
array (составной тип, см. ниже — WordAlignments)

Время начала и окончания каждого слова

Results.WordAlignments.word
string

Слово

Results.WordAlignments.start
string

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

Results.WordAlignments.end
string

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

eou
boolean

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

emotions_result
array (составной тип, см. ниже — EmotionsResult)

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

EmotionsResult.positive
float

Вероятность позитивной эмоциональной окраски речи — диапазон от 0 до 1

EmotionsResult.neutral
float

Вероятность нейтральной эмоциональной окраски речи — диапазон от 0 до 1

EmotionsResult.negative
float

Вероятность негативной эмоциональной окраски речи — диапазон от 0 до 1

processed_audio_start
string

Время начала обработанного аудио

processed_audio_end
string

Время конца обработанного аудио

backend_info
array (составной тип, см. ниже — BackendInfo)

Модель ASR

BackendInfo.model_name
string

Название модели

BackendInfo.model_version
string

Версия модели

BackendInfo.server_version
string

Версия сервера

channel
int32

Номер канала в двухканальных аудио. Для Insights надо, чтоб оператор был 0, а клиент — 1

speaker_info
array (составной тип, см. ниже — SpeakerInfo)

Параметры разделения спикеров

SpeakerInfo.speaker_id
int32

Идентификатор результата распознавания:

  • –1 — результат с речью обоих спикеров,
  • 1 — результат с речью одного спикера,
  • 2 — результат с речью другого спикера
SpeakerInfo.main_speaker_confidence
float

Маркер главного спикера

eou_reason
string

Причина окончания чанка. Возможные значения:

  • UNSPECIFIED — нет чанка.
  • ORGANIC — чанк закончился.
  • NO_SPEECH_TIMEOUT — в чанке не было речи в течение времени, указанного в параметре no_speech_timeout.
  • MAX_SPEECH_TIMEOUT — речь в чанке шла непрерывно в течение времени, указанного в параметре max_speech_timeout
insight_result
array (составной тип, см. ниже — InsightResult)

Результаты анализа Insights модели

InsightResult.csi
array (составной тип, см. ниже — Csi)

Результаты анализа модели CSI

InsightResult.Csi.positive
float

Вероятность позитивной эмоциональной окраски речи — диапазон от 0 до 1

InsightResult.Csi.negative
float

Вероятность негативной эмоциональной окраски речи — диапазон от 0 до 1

InsightResult.Csi.prediction
int32

Предсказанная эмоция

InsightResult.call_features
array (составной тип)

Результаты анализа модели call_features. Описание параметров — в разделах Статистика по одному каналу и Сравнительная статистика

{
  • "results": null,
  • "Results.text": "string",
  • "Results.normalized_text": "string",
  • "Results.start": "string",
  • "Results.end": "string",
  • "Results.word_alignments": null,
  • "Results.WordAlignments.word": "string",
  • "Results.WordAlignments.start": "string",
  • "Results.WordAlignments.end": "string",
  • "eou": true,
  • "emotions_result": null,
  • "EmotionsResult.positive": null,
  • "EmotionsResult.neutral": null,
  • "EmotionsResult.negative": null,
  • "processed_audio_start": "string",
  • "processed_audio_end": "string",
  • "backend_info": null,
  • "BackendInfo.model_name": "string",
  • "BackendInfo.model_version": "string",
  • "BackendInfo.server_version": "string",
  • "channel": null,
  • "speaker_info": null,
  • "SpeakerInfo.speaker_id": null,
  • "SpeakerInfo.main_speaker_confidence": null,
  • "eou_reason": "string",
  • "insight_result": null,
  • "InsightResult.csi": null,
  • "InsightResult.Csi.positive": null,
  • "InsightResult.Csi.negative": null,
  • "InsightResult.Csi.prediction": null,
  • "InsightResult.call_features": null
}

Примеры ответа

[
    {
        "results": [
            {
                "text": "раз два три",
                "normalized_text": "1 2 3",
                "start": "0.760s",
                "end": "2s",
                "word_alignments": [
                    {
                        "word": "раз",
                        "start": "0.760s",
                        "end": "0.880s"
                    },
                    {
                        "word": "два",
                        "start": "1.340s",
                        "end": "1.460s"
                    },
                    {
                        "word": "три",
                        "start": "1.880s",
                        "end": "2s"
                    }
                ]
            }
        ],
        "eou": true,
        "emotions_result": {
            "positive": 0.017408885,
            "neutral": 0.7625851,
            "negative": 0.22000594
        },
        "processed_audio_start": "0s",
        "processed_audio_end": "2.447375104s",
        "backend_info": {
            "model_name": "general",
            "model_version": "M-01.018.00-general-01",
            "server_version": "01.017.00-04"
        },
        "channel": 0
    },
    {
        "results": [
            {
                "text": "раз два три",
                "normalized_text": "1 2 3",
                "start": "0.760s",
                "end": "2s",
                "word_alignments": [
                    {
                        "word": "раз",
                        "start": "0.760s",
                        "end": "0.880s"
                    },
                    {
                        "word": "два",
                        "start": "1.340s",
                        "end": "1.460s"
                    },
                    {
                        "word": "три",
                        "start": "1.880s",
                        "end": "2s"
                    }
                ]
            }
        ],
        "eou": true,
        "emotions_result": {
            "positive": 0.018223174,
            "neutral": 0.76795995,
            "negative": 0.2138168
        },
        "processed_audio_start": "0s",
        "processed_audio_end": "2.447375104s",
        "backend_info": {
            "model_name": "general",
            "model_version": "M-01.018.00-general-01",
            "server_version": "01.017.00-04"
        },
        "channel": 1
    }
]

Коды ошибок

Сервис SaluteSpeech сообщает об ошибках стандартными gRPC-статусами.

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

КодОписание

3

INVALID_ARGUMENT

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

5

NOT_FOUND

Не определена модель из запроса

7

PERMISSION_DENIED

Клиенту недоступно API

8

RESOURCE_EXHAUSTED: payment required

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

8

RESOURCE_EXHAUSTED

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

13

INTERNAL

Ошибка в работе сервиса

16

UNAUTHENTICATED

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

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