Skip to main content

Руководство по распознаванию речи

Подготовка

В этом руководстве можно посмотреть, как и для каких целей используются методы распознавания речи с примерами.

Эндпоинт для распознавания — api.tinkoff.ai:443.

  1. Для авторизации в сервисах получаем ключи и вставляем их в переменные среды:

    export VOICEKIT_API_KEY="PUT_YOUR_API_KEY_HERE"
    export VOICEKIT_SECRET_KEY="PUT_YOUR_SECRET_KEY_HERE"
  2. Клонируем репозиторий с рабочими примерами:

    git clone https://opensource.tbank.ru/voicekit/docs.git
  3. Устанавливаем зависимости:

    # base.txt хватает для большинства примеров ниже
    python3 -m pip install -r docs/scenarios/requirements/base.txt
    # для примеров с микрофоном, MP3 или Opus нужен ещё all.txt (и системные пакеты для pyaudio)
    sudo apt-get install python3 python-pyaudio python3-pyaudio
    python3 -m pip install -r docs/scenarios/requirements/all.txt
    cd docs/scenarios/snippets/stt

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

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

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

Пример 1: метод Recognize() для LINEAR16

Самый простой режим запрос-ответ: аудио отправляется целиком одним сообщением RecognizeRequest, ответ приходит сразу.

В примере аудио берётся из «сырого» формата .s16 — в отличие от .wav, он не содержит метаинформации об аудио, поэтому частоту дискретизации и число каналов нужно указать явно в config:

request.config.encoding = stt_pb2.AudioEncoding.LINEAR16
request.config.sample_rate_hertz = 16000 # не хранится в самом файле .s16
request.config.num_channels = 1 # не хранится в самом файле .s16

Аудио целиком кладётся в request.audio.content. Ответ приходит в поле results — по каждой фразе доступны номер канала (channel), границы фразы во времени (start_time/end_time) и список альтернатив с текстом (alternatives[].transcript).

Готовый рабочий пример: stt_recognize_linear16_raw.py.

Потоковое распознавание речи

Кодеки и форматы файлов

Пример 2: переходим на метод StreamingRecognize()

В режиме StreamingRecognize() аудио отправляется не целиком, а по частям — это нужно для распознавания в реальном времени.

Первое сообщение в потоке — streaming_config с теми же полями config, что и в примере 1. Все последующие сообщения содержат сырые байты аудио в поле audio_content. Рекомендуемый размер одного чанка — примерно 100 мс аудио (при LINEAR16 16 кГц, 1 канал это 3200 байт): чанки крупнее увеличивают задержку до первых результатов, мельче — увеличивают сетевые издержки.

Результат — поток StreamingRecognitionResult; поля результата (channel, start_time/end_time, alternatives) лежат внутри recognition_result.

Готовый рабочий пример: stt_streaming_recognize_linear16_raw.py.

Пример 3: загружаем аудио из .wav-файла

В отличие от «сырого» .s16, контейнер RIFF WAVE (.wav) хранит частоту дискретизации и число каналов в заголовке файла — их можно прочитать через модуль wave (f.getframerate(), f.getnchannels()) и не задавать вручную, как в примере 2. Пример работает с .wav-файлом с аудио в формате PCM.

Готовый рабочий пример: stt_streaming_recognize_linear16_wav.py.

Пример 4: используем кодек A-Law

A-Law — кодек с квази-экспоненциальным кодированием амплитуды аудиоимпульса.

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

В основном применяется в телефонии. В нашем примере, как и в типичной конфигурации VoIP, используется частота в 8 KHz.

Мы также поддерживаем формат Mu-Law, но поскольку он является устаревшим аналогом A-Law с менее эффективным распределением кодируемых значений амплитуды аудиоимпульса, его использование оправданно только поддержкой совместимости.

Логика похожа на пример 2, только кодек и частота дискретизации другие, а размер отправляемого фрейма пересчитывается на 1 байт на сэмпл (100 мс при 8 KHz — это 800 байт):

request.streaming_config.config.encoding = stt_pb2.AudioEncoding.ALAW
request.streaming_config.config.sample_rate_hertz = 8000

Готовый рабочий пример: stt_streaming_recognize_alaw_raw.py.

Пример 5: распознаём MP3

MP3 поддерживается в формате контейнера с фиксированными количеством каналов и частотой дискретизации.

Как и в примере 3 с .wav, частоту дискретизации и число каналов не нужно указывать вручную — их можно прочитать из метаинформации файла, например через mutagen.mp3.MP3. Единственное отличие в конфиге — кодек:

request.streaming_config.config.encoding = stt_pb2.AudioEncoding.MPEG_AUDIO

Размер отправляемого за раз куска данных для MP3 не привязан к длительности аудио и выбирается произвольно, исходя из условий использования (в примере — 4096 байт за раз).

Готовый рабочий пример: stt_streaming_recognize_mp3.py.

Пример 6: кодируем в Opus на лету

На практике сжатие на лету удобно применять при работе с аудио-разговорами в реальном времени, при распознавании с микрофона и так далее.

На сегодняшний день Opus — наиболее эффективный кодек сжатия с потерями: по своим характеристикам он обходит как кодеки для разговоров — с небольшой задержкой декодирования, так и кодеки для хранения аудио-трэков — сжатые большими блоками для большего сжатия.

Задаем формат кодирования:

request.streaming_config.config.encoding = stt_pb2.AudioEncoding.RAW_OPUS

В режиме RAW_OPUS важно отправлять ровно по одному Opus-фрейму в запрос, так как сами фреймы не содержат информацию о длине фрейма — если сконкатенировать два фрейма в одно сообщение, невозможно будет понять, где заканчивается первый и начинается второй. Допустимая частота дискретизации — одна из 8000, 12000, 16000, 24000 или 48000 Гц; допустимая длина фрейма — 2.5, 5, 10, 20, 40 или 60 мс (в примере кодируется библиотекой opuslib, фреймами по 60 мс, последний неполный фрейм дополняется нулями до ближайшей допустимой длины).

Для хранения Opus-фреймов в файле используются контейнерные форматы, например Ogg — не путать с аудиокодеком Vorbis.

Готовый рабочий пример: stt_streaming_recognize_raw_opus_from_wav.py.

Ввод с микрофона

Пример 7: распознаём с микрофона

Для удобства тестирования сервиса можно делать запросы непосредственно с микрофона — источником потока байтов вместо файла становится устройство записи (в примере — библиотека pyaudio), а сам поток чанков в audio_content формируется так же, как в примере 2 (в примере — по 50 мс за раз).

Для работы примера нужны системные пакеты для pyaudio — см. раздел «Подготовка».

Готовый рабочий пример: stt_streaming_recognize_linear16_from_microphone.py.

Режимы и опции распознавания

Пример 8: получаем несколько гипотез

Сервис может генерировать несколько предположений о том, что хотел сказать автор. Чтобы их получить, задаём желаемое количество гипотез — они появятся в result.recognition_result.alternatives (уже знакомое поле из примера 2, только теперь в нём может быть больше одного элемента):

request.streaming_config.config.max_alternatives = 3

Готовый рабочий пример: stt_streaming_recognize_max_alternatives.py.

Пример 9: получаем промежуточные гипотезы

Так как сервис распознаёт текст на лету, можно получать промежуточные версии на лету. Чаще всего это применяется при надиктовывании текста в чат.

Включаем промежуточные гипотезы:

request.streaming_config.interim_results_config.enable_interim_results = True

После этого каждый результат нужно проверять на флаг result.is_final: False означает промежуточную гипотезу по ещё не закончившейся фразе (она будет уточняться следующими результатами с тем же временным диапазоном), True — финальную версию этой фразы.

Готовый рабочий пример: stt_streaming_recognize_interim_results.py.

Пример 10: кастомизируем VAD (Voice Activity Detection) для streaming_recognize

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

В реальном поведении также участвуют характеристики модели и внутреннее устройство сервиса.

Пример использования silence_min и silence_max:

request.streaming_config.config.vad_config.silence_prob_threshold = 0.2
request.streaming_config.config.vad_config.silence_min = 3.
request.streaming_config.config.vad_config.silence_max = 3.2

Готовый рабочий пример: stt_streaming_recognize_vad_customization.py.

Пример 11: кастомизируем VAD (Voice Activity Detection) для recognize

То же самое, что в примере 10, но для метода Recognize() — поле vad_config располагается прямо в config, а не во вложенном streaming_config.config, и называется иначе:

request.config.vad_config.silence_duration_threshold = 3.0
request.config.vad_config.silence_prob_threshold = 0.2

Готовый рабочий пример: stt_recognize_vad_customization.py.

Пример 12: режим завершения после первой фразы

Этот режим типичен в ситуациях, когда нет желания анализировать диалог целиком — хочется упростить логику сервиса. Например, в голосовом ассистенте: чтобы не следить за тем, что пользователь наговорил между запросами, а начать распознавать новый запрос с начала.

Выставляем соответствующий флаг:

request.streaming_config.single_utterance = True

Готовый рабочий пример: stt_streaming_recognize_single_utterance.py.

Пример 13: выключаем VAD

Если выключить VAD, мы распознаем аудиофрагмент как одну фразу.

Выставляем соответствующий флаг:

request.streaming_config.config.do_not_perform_vad = True

Готовый рабочий пример: stt_streaming_recognize_vad_disabled.py.

Пример 14: включаем пунктуацию

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

Выставляем соответствующий флаг:

request.streaming_config.config.enable_automatic_punctuation = True

Готовый рабочий пример: stt_streaming_recognize_enable_automatic_punctuation.py.

Пример 15: включаем фильтр ненормативной лексики

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

Выставляем соответствующий флаг:

request.streaming_config.config.profanity_filter = True

Готовый рабочий пример: stt_streaming_recognize_profanity_filter.py.

Пример 16: задаём контекст

Для задания контекста передаём соответствующие фразы, повышая вероятность их распознавания (например, редкие имена или термины) через score:

request.streaming_config.config.speech_contexts.append(stt_pb2.SpeechContext(phrases = [
stt_pb2.SpeechContextPhrase(text = "мюллер", score = 10.0),
]))

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

Готовый рабочий пример: stt_streaming_recognize_context.py.

Пример 17: включаем определения пола спикера

Выставляем соответствующий флаг:

request.streaming_config.config.enable_gender_identification = True

Готовый рабочий пример: stt_streaming_recognize_gender_identification.py.

Пример 18: включаем определение эмоций

Этот флаг работает с методом Recognize() (а не StreamingRecognize()):

request.config.enable_sentiment_analysis = True

Готовый рабочий пример: stt_recognize_sentiment_analysis.py.

Отложенное распознавание речи

Пример 19: загрузка аудио для отложенной обработки и получение результата через циклический опрос

Метод LongRunningRecognize принимает на вход параметры, аналогичные Recognize (запрос строится так же, как в примере 1) — но возвращает не результат распознавания, а объект операции (id, state) с идентификатором, за ходом обработки которой можно следить. Этот режим удобен, когда результаты распознавания не нужны сразу.

Когда operation.state == DONE, результат распознавания (RecognizeResponse, как в примере 1) можно достать из operation.response через Unpack.

Для получения информации по статусам операций используется отдельный сервис — Operations, поэтому и авторизационные метаданные для него нужны отдельные — для scope tinkoff.cloud.longrunning, а не tinkoff.cloud.stt.

Самый простой способ дождаться завершения операции — периодически (например, раз в секунду) запрашивать её статус методом GetOperation по id, пока state не станет DONE или FAILED. Это не самый эффективный способ (см. пример 20 с WatchOperations для группы операций), но он самый простой для демонстрации.

Готовый рабочий пример: stt_long_running_recognize_single_audio.py.

Пример 20: загрузка пачки аудио для отложенной обработки и получение результата через нотификации

Вместо того чтобы постоянно опрашивать API в цикле и запоминать идентификаторы каждой операции, можно объединить их в группы и получать результаты обработки через метод WatchOperations.

Чтобы избежать путаницы между наборами аудио, загружаемыми при повторных запусках, организуем их в группы — название группы может быть произвольной строкой (например, текущей датой) и указывается прямо в запросе на распознавание, в поле group:

request.group = group_name

После того как все операции группы созданы, подписываемся на их статусы методом WatchOperations, указав группу в filter.exact_group и выставив listen_for_updates = True (по умолчанию False), чтобы после отправки текущего состояния операций сервис продолжил присылать уведомления об изменениях:

request.filter.exact_group = group_name
request.listen_for_updates = True

Ответы WatchOperations приходят потоком: сперва initial_state с текущим состоянием всех операций группы, затем init_finished, и далее — update с изменившимися операциями. У каждой операции, как и в примере 19, есть state и (при DONE) результат распознавания в response.

Готовый рабочий пример: stt_long_running_recognize_audio_group.py.

Пример 21: загрузка пачки аудио для отложенной обработки с идентификацией задания через x-client-request-id

В этом примере нас интересует возможность передавать и затем получать локальный идентификатор запроса. В нашем случае это имя файла без расширения, но также это могут быть ID записи в базе данных и другие варианты.

Идентификатор передаётся не в самом запросе, а в метаданных gRPC-вызова LongRunningRecognize, отдельной парой рядом с авторизационными метаданными:

metadata.append(("x-client-request-id", os.path.basename(test_file)))

Позже это же значение можно прочитать из поля x_client_request_id у полученной операции — например, чтобы сохранить результат распознавания в файл с соответствующим названием.

Готовый рабочий пример: stt_long_running_recognize_audio_group_x_client_request_id.py.

openapi@tbank.ru

АО «ТБанк» использует файлы «cookie» с целью персонализации сервисов и повышения удобства пользования веб-сайтом. «Cookie» представляют собой небольшие файлы, содержащие информацию о предыдущих посещениях веб-сайта. Если вы не хотите использовать файлы «cookie», измените настройки браузера.