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

Автоматизировать взаимодействие с клиентами, но при этом общаться с ними человеческим голосом, транскрибировать речь в текст и, наоборот, озвучивать продукты для слабовидящих — с этим и многим другим вашему бизнесу помогут справиться ML-технологии SpeechKit.
Всех, кто использует SpeechKit, мы называем разработчиками. Даже если вы взаимодействуете с сервисом через URL и вызываете простой запрос — вы всё равно разработчик, потому что используете сервис напрямую и предоставляете решения другим пользователям.
В этой статье расскажем, как подключиться к SpeechKit по API: что важно знать новичкам и помнить опытным разработчикам, как выбрать правильный API и оптимальный способ аутентификации. Do’s, Dont’s и возможности сервиса разберём на примере самых популярных задач: распознавание речи и её синтез.
- Выбирайте правильный API SpeechKit для своей задачи
- Распознавание речи
- Синтез речи
- Несколько слов о SpeechKit Brand Voice
- Учитывайте квоты, лимиты и требования к форматам исходных данных сервиса
- Используйте оптимальный способ аутентификации в API сервиса
Что важно знать, если вы разработчик 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.
Распознавание аудио в любом режиме состоит из трёх этапов:
- Выделение слов. SpeechKit выдвигает несколько гипотез для каждого слова из аудиозаписи.
- Распознавание слов. Языковая модель проверяет гипотезы: оценивает, как новое слово согласуется с предыдущими.
- Обработка распознанного текста. 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 позволяет этот процесс упростить:
- Подготовьте набор шаблонов и примеров их произношения.
- Передайте готовый набор файлов команде сервиса.
- Получите уникальный голос для вашего бизнеса. Его параметры можно передавать в payload.
- Для получения синтезированной фразы при вызове 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 и диагностике ошибок — в нашей документации.