Руководство по распознаванию речи
Подготовка
В этом руководстве можно посмотреть, как и для каких целей используются методы распознавания речи с примерами.
Эндпоинт для распознавания — api.tinkoff.ai:443.
Для авторизации в сервисах получаем ключи и вставляем их в переменные среды:
export VOICEKIT_API_KEY="PUT_YOUR_API_KEY_HERE"
export VOICEKIT_SECRET_KEY="PUT_YOUR_SECRET_KEY_HERE"Клонируем репозиторий с рабочими примерами:
git clone https://opensource.tbank.ru/voicekit/docs.gitУстанавливаем зависимости:
# 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 метода для распознавания речи:
Распознавание речи (Recognize). Работает по принципу «загружаем аудио целиком, получаем ответ». Полезен для распознавания аудиофайлов.
Потоковое распознавание речи (StreamingRecognize). Нужен для распознавания речи в реальном времени: телефонных звонков, голосовых ассистентов и так далее. Также в методе больше возможностей для распознавания файлов.
Отложенное распознавание речи (LongRunningRecognize). Работает по принципу «отправляем аудио целиком, а результат — когда он будет готов — забираем из отдельного интерфейса».
Потоковое распознавание речи с синхронным ответом в конце (StreamingUnaryRecognize). Используется, если:
- есть большие аудио, которые не укладываются в ограничения Recognize;
- нужен результат распознавания сразу после окончания аудиопотока, но без промежуточных результатов.
Распознавание речи
Пример 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.