SpeechKit для разработчиков: Do’s and Dont’s

Автоматизировать взаимодействие с клиентами, но при этом общаться с ними человеческим голосом, транскрибировать речь в текст и, наоборот, озвучивать продукты для слабовидящих — с этим и многим другим вашему бизнесу помогут справиться ML-технологии SpeechKit.

Всех, кто использует SpeechKit, мы называем разработчиками. Даже если вы взаимодействуете с сервисом через URL и вызываете простой запрос — вы всё равно разработчик, потому что используете сервис напрямую и предоставляете решения другим пользователям.

В этой статье расскажем, как подключиться к SpeechKit по API: что важно знать новичкам и помнить опытным разработчикам, как выбрать правильный API и оптимальный способ аутентификации. Do’s, Dont’s и возможности сервиса разберём на примере самых популярных задач: распознавание речи и её синтез.

Что важно знать, если вы разработчик SpeechKit: gRPC vs REST

Чтобы работать со SpeechKit, совсем не обязательно быть дата-сайентистом и разбираться в ML-методах. Самое главное — уметь обращаться с gRPC или REST.

Напомним, зачем нужны эти два API и чем они отличаются друг от друга.

REST

REST использует HTTP/1.1. Этот протокол ориентирован на унарный запрос клиента и ответ сервера: быстрый (голосовое управление, распознавание коротких голосовых сообщений в мессенджерах) или отложенный (транскрибация аудиозвонков и выступлений).

Таким образом, вся логика работы вашего приложения будет построена в режиме «запрос-ответ» через payload. SpeechKit обычно использует бинарные данные payload, которые в случае REST будут кодироваться в base64.

С одной стороны, это упрощает чтение протокола: всегда можно посмотреть, что происходит, при помощи отладчика. Но, с другой стороны, это значимо увеличивает payload.

Если вы только начинаете работать со SpeechKit, проверьте, можно ли решить вашу задачу с помощью REST API.

Если вам важно, чтобы сервис отвечал на запросы в режиме реального времени, или ваше приложение нагружено и использует двунаправленные потоки (как телефонные ассистенты) — попробуйте gRPC API.

gRPC

gRPC использует протокол HTTP/2, который поддерживает не только унарные запросы и ответы, но и двунаправленные потоковые способы взаимодействия с сервисом. Это значит, что с помощью gRPC вы сможете настроить потоковое распознавание: отдавать сервису текст, а в ответ получать аудио. Или наоборот.

Обратите внимание: gRPC использует формат Protobuf — он здорово сжимает данные, поэтому эффективен как транспорт. Чтобы воспользоваться gRPC, нужно создать файлы заголовков и сгенерировать их на вашем языке программирования. Иными словами, хотя gRPC обычно эффективнее, новичку проще начать с REST-вызовов. Вы можете выбрать любой вариант, но помните, что потоковое распознавание пока работает только с gRPC-вызовами.

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

Во всех примерах, о которых мы будем говорить дальше, используются заголовки протофайлов из SDK Yandex.Cloud.

Выбирайте правильный API SpeechKit для своей задачи

Выбор API в значительной степени определяется именно режимом работы сервиса. Рассмотрим два самых популярных класса задач: распознать аудио и синтезировать человеческий голос.

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

Технологии SpeechKit распознают речь тремя способами:

• Синхронное распознавание — для задач и сценариев, когда на запрос пользователя нужен быстрый ответ: виртуальные ассистенты, голосовое управление, распознавание коротких голосовых сообщений в мессенджерах. Работает исключительно с короткими одноканальными аудиозаписями: не дольше 30 секунд.
• Асинхронное распознавание — взаимодействие вида «запрос — отложенный ответ». Подойдёт для транскрибации аудиозвонков и выступлений, создания субтитров, контроля соблюдения и выявления успешных скриптов колл-центров, оценки качества работы операторов. Справляется с длинными и многоканальными аудиозаписями: максимальная длительность файла — четыре часа.
• Потоковое распознавание — речь обрабатывается в режиме реального времени: SpeechKit получает на вход короткие аудиофрагменты и отправляет в ответ результаты в рамках одного соединения. Это значит, что, в отличие от двух других способов распознавания, вы сможете получить промежуточный результат пока фраза ещё не закончена. Максимальная длительность аудиозаписи, переданной за всю сессию — пять минут.

Шаг 1

Выберите API. Для коротких аудио советуем использовать REST. Но если вы хотите эмулировать диалог с роботом синхронными REST-запросами, то payload должен быть как можно меньше: постарайтесь разбить аудиофайл на более мелкие. Если это невозможно, используйте gRPC и потоковый режим распознавания.

Какие языки и модели распознавания доступны для каждого из режимов — в нашей документации.

Шаг 2

Подготовьте данные. Конвертируйте их в правильный формат:

• LPCM без WAV-заголовка с частотой дискретизации 8, 16 или 48 кГц (по умолчанию). Разрядность квантования — 16 бит. Порядок байтов — обратный (little-endian).
• OggOpus — данные закодированы с помощью аудиокодека OPUS и упакованы в контейнер OGG.
• Частота дискретизации должна быть указана в payload, если отличается от значения по умолчанию (48 кГц).
• Если формат вашего файла не поддерживается, сконвертируйте его с помощью утилиты FFmpeg:

ffmpeg –i my-input-file.mp3 -acodec pcm_s16le -ac 1 -ar 16000 my-output-file.wav

Для транскрибации видео предварительно извлеките аудиодорожку:

ffmpeg -i my-input-file.mp4 -vn -acodec copy my-output-file.aac

Выгрузите данные в объектное хранилище.

Отправьте запрос SpeechKit, чтобы создать задачу распознавания аудиофайла.

Шаг 3

Запустите распознавание. В ответ на запрос из предыдущего шага SpeechKit пришлёт ID задания. По этому идентификатору вы сможете получить результат обработки аудиофайла. Чтобы узнать статус задания, отправьте SpeechKit запрос с его ID: если обработка завершена, в payload вернётся значение done.

Распознавание аудио в любом режиме состоит из трёх этапов:

1. Выделение слов. SpeechKit выдвигает несколько гипотез для каждого слова из аудиозаписи.
2. Распознавание слов. Языковая модель проверяет гипотезы: оценивает, как новое слово согласуется с предыдущими.
3. Обработка распознанного текста. SpeechKit преобразует числительные в цифры и расставляет некоторые знаки препинания. Готовый текст отправляется автору запроса.

Напоминаем про приложения и библиотеки с открытым кодом, которые облегчат работу со SpeechKit:

• Batch recognizer — охватывает популярный сценарий распознавания больших информационных архивов. Выгрузите исходные аудиофайлы в объектное хранилище Yandex.Cloud — можно создать иерархию папок внутри бакета объектного хранилища. Далее Batch recognizer использует сценарий распознавания длинных аудиофайлов за два прохода и вернёт вам текстовый результат.
• Steaming ASR Client. Асинхронное дуплексное распознавание — пример потокового API. Умеет обрабатывать входящие потоки информации, превышающие ограничения. Если сессия разрывается, чтобы не перерасходовать бюджет через пять минут или 10 мегабайт, можно обработать это событие и создать новое соединение, как показано в коде Streaming ASR. То есть фактически — сделать retry pattern, чтобы клиент вашего приложения даже не почувствовал, что что-то прерывалось.
• ASR Transcoder. С помощью известного C++ фреймворка Gstreamer, можно обрабатывать данные даже в формате видео. Под капотом — всё то же асинхронное распознавание аудиофайлов, но, чтобы запустить транскрибирование, достаточно загрузить видео: дальше Gstreamer сделает всё сам.

Шаг 4

Результаты распознавания вы получите в payload. Их можно улучшить либо с помощью автотюнинга, либо дообучив модель.

Готово!

Синтез речи

Шаг 1

Вызовите REST или gRPC API с описанием параметров синтеза. Выбор API зависит от длины текста:

• для синтеза фраз до 250 символов выберите gRPC API;
• для синтеза текста до 5000 символов выберите REST API.

Шаг 2

Синтезированный аудиофрагмент вернётся в payload в структуре API.

SpeechKit не склеивает предзаписанные фрагменты речи, а обучает акустическую ML-модель на речи диктора. Благодаря использованию нейронных сетей синтезированная речь получается плавной, а интонации — естественными.

Любой текст можно озвучить на нескольких языках. При этом вы можете управлять параметрами речи и выбрать голос. Или даже создать уникальный голос с помощью SpeechKit Brand Voice.

Несколько слов о SpeechKit Brand Voice

Создание своего голоса — довольно сложное и дорогостоящее мероприятие. А Brand Voice Adaptive позволяет этот процесс упростить:

1. Подготовьте набор шаблонов и примеров их произношения.
2. Передайте готовый набор файлов команде сервиса.
3. Получите уникальный голос для вашего бизнеса. Его параметры можно передавать в payload.
4. Для получения синтезированной фразы при вызове gRPC API укажите шаблон с параметрами TextTemplate (шаблон), AudioVariable и TextVariable (переменные части шаблона).

Доступные версии модели:

• general — основная версия;
• general: rc — версия-кандидат для релиза, которую вы можете тестировать;
• general: deprecated — предыдущая версия модели, к которой при случае можно откатиться;
• deferred-general — доступна только для распознавания длинных аудио. Задание выполняется в течение 24 часов в самое незагруженное время. Позволяет распознавать большие объёмы данных.

Учитывайте квоты, лимиты и требования к форматам исходных данных сервиса

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

Если вы заметили, что можете выйти за лимиты, реализуя свой сценарий, пожалуйста, добавьте в приложение логику обработки ошибок, завершения времени сессии или ограничения объёма переданных данных. Пример можно подсмотреть в SpeechKit adoption pack.

Примерно 60% обращений в техническую поддержку сегодня связаны с тем, что на вход сервиса подаются данные в неверных форматах. SpeechKit принимает на вход всего два формата: LPCM и Ogg-кодек Opus. Не забудьте проверить ваши данные перед загрузкой.

Больше о квотах и лимитах читайте в нашей документации.

Используйте оптимальный способ аутентификации в API сервиса

Вы не сможете пользоваться сервисом, пока не аутентифицируетесь в API Speechkit. Существует два способа это сделать: используйте либо IAM-токен, либо API-ключи.

С точки зрения разработчика, самый простой способ аутентификации — API-ключи: их можно создать один раз и пользоваться сколько угодно долго. Но длительное время жизни API-ключа может стать потенциальной уязвимостью, критической, если вы храните его прямо в приложении: если ключ будет скомпрометирован, злонамеренные пользователи получат неограниченный доступ к вашему сервису. Советуем держать API-ключи в специальных хранилищах (например, Lockbox) и ротировать, если необходимо.

API-ключи можно использовать только для сервисных аккаунтов.

IAM-токены подходят и для сервисных, и для федеративных аккаунтов, а также аккаунтов в Яндексе. В отличие от API-ключей токены живут 12 часов: не забудьте добавить в приложение логику для повторного запроса IAM-токена.

Всё об аутентификации в API и диагностике ошибок — в нашей документации.