Подключение SpeechKit API к своему сервису сводится к четырём решениям: способ авторизации, формат аудио, режим обработки и журнал ошибок. Остальное зависит от задачи: расшифровка звонков, голосовой ответ в боте или озвучка текстов. Интерфейс описан в документации Yandex как gRPC на основе Protocol Buffers, поэтому разработчику понадобится клиент нужного языка и привычка проверять формат записи до первого вызова.
Что вызывает сервис
По документации, SpeechKit API распознаёт и синтезирует речь, поддерживает форматы LPCM, OggOpus и MP3 и работает в трёх режимах распознавания: синхронном, потоковом и асинхронном. Авторизация идёт по API-ключу или IAM-токену, причём для сервисного аккаунта каталог в запросе указывать незачем.
Функции сервиса и сценарии, где он выгоден, мы разбирали в статье про Yandex SpeechKit для бизнеса. Здесь уровень ниже: что должен сделать код вашего сервиса, чтобы звук превратился в текст и обратно, и как убедиться, что цепочка работает.
Документация предупреждает об особенности интерфейса: он построен без ресурсно-ориентированного подхода, а его запросы неидемпотентны. Практический вывод: повторный вызов после сбоя считается отдельным решением. Повтор синтеза или распознавания означает ещё один запрос, и учёт расхода растёт вместе с числом попыток.
Перед началом откройте описание API SpeechKit: версии интерфейса, поддерживаемые языки и ограничения обновляются, и актуальные значения лучше брать оттуда. Вопросы оплаты и доступа из России мы разбирали в материале про оплату Yandex Cloud для нейросетей.
Ключ и каталог
Подключение начинается с технической учётной записи для сервиса. Работа через личный аккаунт сотрудника создаёт риск: человек уйдёт, доступ пропадёт, и интеграция остановится.
- Создайте сервисную учётную запись в нужном каталоге облака и выдайте ей только роль, необходимую для вызова речевых функций.
- Выберите способ авторизации: API-ключ проще для серверного приложения, а IAM-токен живёт ограниченное время и требует обновления, зато безопаснее при утечке.
- Сохраните ключ в хранилище секретов сервера, а код и репозиторий от него держите свободными.
- Передайте ключ в заголовке Authorization (для API-ключа формат Api-Key, для IAM-токена Bearer). Идентификатор каталога в заголовке x-folder-id нужен, когда вы входите под обычным аккаунтом, а с сервисным аккаунтом его опускают: сервис берёт каталог, где аккаунт создан.
- Запишите, кто владеет ключом, где он используется и когда его меняют: без этой записи через полгода забудется, что от него зависит.
Договоритесь о границе ответственности. Сервис отвечает за вызов и журнал, продуктовая команда за качество текстов и голоса, служба безопасности за ключи и хранение записей. Когда границы описаны на одной странице, разбор сбоя занимает минуты, а споры о том, кто виноват, теряют почву.
Права сервисной записи проверяйте тем же способом, каким проверяют любой доступ: попробуйте вызвать то, что запрещено, и убедитесь в отказе. Роль с лишними правами в облаке однажды пригодится злоумышленнику, а выдать её заново с нужным набором прав занимает минуты. Ключ без срока действия и без владельца считайте дефектом процесса и закрывайте при ближайшем разборе.
Для разных сред заводите разные ключи: тестовый и рабочий. Тогда эксперименты разработчика остаются вне рабочего расхода, а отзыв тестового ключа проходит для клиентов незаметно.
Аудио на входе
Большинство сбоев распознавания возникает до обращения к модели: звук записан в неподходящем формате или с плохим качеством. Поэтому формат записи проверяют первым делом.
| Режим | Когда применять | Что проверить |
|---|---|---|
| Синхронный | Короткие реплики, команды, голосовые сообщения | Лимит по документации: до 30 секунд и 1 МБ, одноканальный звук |
| Потоковый | Живой разговор, субтитры, голосовой помощник | Лимит по документации: до 5 минут и 10 МБ за сеанс; частота передачи кусков звука, обрыв, повторное подключение |
| Асинхронный | Длинные записи: встречи, звонки, подкасты | Лимит по документации: до 4 часов и 1 ГБ, поддерживается многоканальный звук; как приходит результат и где хранится идентификатор операции |
| Синтез речи | Озвучка ответов бота и текстов | Выбранный голос, произношение терминов, формат выходного файла |
Служба поддержки хочет расшифровывать звонки за день и искать в них жалобы. Записи приходят из телефонии в своём формате, и сервис сначала конвертирует их в поддерживаемый, затем отправляет в асинхронном режиме и сохраняет идентификатор операции. Утром сервис забирает готовые тексты, помечает сомнительные и складывает их в очередь на проверку. Каждый шаг проверяется отдельно, и поэтому сбой легко найти.
Форматы LPCM и OggOpus отличаются по размеру и способу передачи. LPCM — несжатый звук без заголовка WAV, и параметры записи указывают явно: по документации, это частота 8, 16 или 48 кГц и 16 бит со знаком, порядок байтов от младшего. Ошибка в них даёт шум вместо текста. OggOpus сжат и удобнее для передачи по сети. Телефонные записи часто приходят в своих форматах, и их конвертируют перед отправкой.
Проверьте и качество источника. Запись с шумом, эхом или двумя говорящими одновременно ухудшает результат любой модели. Для звонков раздельные дорожки собеседников дают лучшее распознавание, чем одна смешанная. Как оценивать результат распознавания в работе, описано в статье про ИИ для звонков.
Журнал ошибок
Речевой вызов может упасть по десятку причин: сеть, ключ, формат, перегрузка, неподдерживаемый язык. Без журнала причину приходится угадывать, а пользователь видит только молчание.
- Идентификатор запроса: связывает запись в вашем журнале с обращением в поддержку и с логами сервиса.
- Режим и параметры: какой режим, формат, язык и голос использованы, без самих аудиоданных.
- Код и текст ошибки: ответ сервиса целиком, чтобы отличать ошибку авторизации от ошибки формата.
- Длительность вызова: от отправки до результата, отдельно для распознавания и синтеза.
- Размер входа: длина записи или текста, потому что многие сбои связаны с ограничениями на объём.
Оповещение о сбоях настраивайте по доле ошибок за период. Одиночный отказ может быть случайностью, зато десять подряд сигнализируют о проблеме с ключом, форматом или сетью. Порог выбирают по вашему трафику, и первую неделю его корректируют, чтобы сообщения приходили вовремя и сохраняли ценность.
Сами записи разговоров в журнал ни к чему писать: там персональные данные, и срок их хранения регулируется отдельно. Достаточно метаданных, а сырой звук хранится в защищённом хранилище с ограниченным сроком и доступом. Повторные попытки ограничивайте числом и паузой, учитывая, что каждый вызов неидемпотентен и расходует ресурсы.
Какие записи ваш сервис будет отправлять на распознавание?
Приёмка связки
Возьмите десять записей реальной работы: чистую, шумную, телефонную, с терминами и числами. Распознайте их, сверьте текст со звуком и посчитайте, сколько фраз потребовали правки. Эта доля и есть ваша стартовая метрика качества.
Для синтеза речи проверка похожая: прослушайте десять типовых ответов бота и отметьте неверные ударения, числа и названия. Исправлять произношение удобнее правкой текста: записывайте слова так, как их читают вслух, и ведите словарь замен проекта.
Две чистые записи в наушниках доказывают очень мало: реальный поток приносит шум, перебивания и телефонное качество, и результат оказывается заметно хуже. Закладывайте в план этап сверки на реальных данных и повторяйте его после каждого изменения формата или настроек.
Если речь нужна как часть процесса, например расшифровка звонков с последующей оценкой, соберите цепочку целиком вместе с владельцем и регламентом. Как собрать такую цепочку, показывает страница про автоматизацию бизнес-процессов.