Как расшифровать аудио через Deepgram API и проверить точность результата

Перед запуском проверьте страницу Models and Languages: доступные языки, голоса и сочетания функций меняются. Зафиксируйте endpoint, model id, язык, формат входа и версию SDK в журнале теста. Постоянный ключ храните только на backend как DEEPGRAM_API_KEY; не помещайте его в браузер, мобильный пакет, репозиторий или скриншот.

Факты из официальной документации

• Локальный WAV передаётся бинарным телом с корректным Content-Type, а удалённый файл — JSON-объектом с полем url.
• Официальный пример вызывает POST https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true.
• Текст находится в results.channels[0].alternatives[0].transcript; слова содержат start, end и confidence.
• Максимальный размер предзаписанного файла — 2 ГБ; Deepgram советует извлекать аудиодорожку из больших видео.

Эти параметры решают разные задачи. Модель распознаёт речь, formatter меняет представление текста, diarization присваивает словам номера говорящих, а utterances формирует смысловые сегменты. Включение одной функции не означает автоматическое включение остальных, кроме явно документированных связей.

Подготовка контрольных данных

1. Сделайте короткую синтетическую запись без персональных данных. Запишите точный эталон текста и ожидаемые границы реплик.
2. Измерьте реальный контейнер, кодек, sample rate и число каналов через ffprobe; расширение файла само по себе ничего не гарантирует.
3. Для сравнения функций используйте один и тот же файл. Меняйте ровно один query parameter, иначе нельзя объяснить разницу.
4. Определите машинные проверки до запроса: непустое поле, допустимый язык, отсутствие секрета, множество speaker id или совпадение ключевого термина.
5. Храните исходный JSON целиком вместе с request id. Производный TXT или субтитры не заменяют ответ API.

Пример карточки входа:

file: control.wav
container: wav
codec: pcm_s16le
sample_rate: 16000
channels: 1
expected_phrase: "контрольная фраза"
contains_real_personal_data: false

Не копируйте характеристики этого шаблона вслепую: значения обязаны совпадать с вашим файлом. Для streaming добавьте размер audio chunk, частоту отправки и момент намеренного разрыва соединения.

Пошаговая настройка

1. Создайте отдельный ключ для тестовой среды и экспортируйте DEEPGRAM_API_KEY. Не выводите переменную командой, которая попадёт в общие логи.
2. Сверьте поддержку функции для выбранных модели, языка и batch/streaming режима. Особенно внимательно проверяйте языковые ограничения intelligence и redaction.
3. Выполните минимальный запрос ниже без собственных retry и middleware. Так видны исходные HTTP-код, заголовки и тело ошибки.
4. Проверьте Content-Type входа и фактический формат байтов. Для URL-входа удостоверьтесь, что ссылка доступна серверу и отдаёт именно медиа.
5. Разберите документированное поле ответа; не ищите текст рекурсивно и не подставляйте пустую строку вместо отсутствующего объекта.
6. Сравните результат с эталоном: Для контрольной записи «Заказ сорок два готов к выдаче» JSON содержит непустой transcript, слова с временными метками и request_id; номер и ключевая фраза сверяются с эталоном.
7. Проведите отрицательный тест: испорченный ключ, неподдерживаемая комбинация, неверный формат либо контрольный секрет. Ожидаемая ошибка должна быть обработана явно.

Рабочий шаблон

curl --request POST \
  --header "Authorization: Token $DEEPGRAM_API_KEY" \
  --header "Content-Type: audio/wav" \
  --data-binary @control.wav \
  --url 'https://api.deepgram.com/v1/listen?model=nova-3&language=ru&smart_format=true' \
  --output result.json
jq -e '.results.channels[0].alternatives[0].transcript | length > 0' result.json

Шаблон не содержит настоящего ключа. Файлы и model id должны быть проверены в текущей документации. Команда jq -e важна: она завершает сценарий ошибкой, когда бизнес-условие ложно, даже если транспортный запрос прошёл.

Контрольный вход и ожидаемый результат

Используйте запись с заранее известным текстом, а не случайный подкаст. Для терминов подготовьте несколько произнесений разными дикторами; для diarization — известный порядок двух голосов; для redaction — только синтетические номера. Оценка на одном красивом примере не показывает устойчивость.

Ожидаемый результат: Для контрольной записи «Заказ сорок два готов к выдаче» JSON содержит непустой transcript, слова с временными метками и request_id; номер и ключевая фраза сверяются с эталоном.

Для распознавания посчитайте word error rate или хотя бы долю совпавших обязательных фраз. Для сегментации проверьте временной порядок и потерянные слова. Для TTS техническая валидность файла не заменяет прослушивание. Для summary отдельно проверяйте факты: модель может создать связный, но неточный пересказ.

Критерии приёмки

• HTTP 200 и JSON
• request_id сохранён
• transcript не пуст
• ключевая фраза совпала
• низкоуверенные слова отмечены

Также сохраняйте HTTP-код, request id, model metadata, длительность исходного аудио и время обработки. Порог качества определяйте на своей размеченной выборке. Универсальное число confidence не гарантирует правильности бренда, суммы или фамилии.