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

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

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

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

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

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

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-протоколу клиентское приложение отправляет аудиофайл с помощью метода 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": [
            {
                "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 в настройках своего браузера.