Как определить язык аудио в Deepgram и проверить language_confidence

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

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

• Функция выключена по умолчанию и включается detect_language=true.
• В ответе канала появляются detected_language и language_confidence.
• Для multichannel определяется один язык на каждый канал.
• Русский ru входит в официальный список поддерживаемых языков определения.

Эти параметры решают разные задачи. Модель распознаёт речь, 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. Сравните результат с эталоном: На русской контрольной записи каждый ожидаемый канал возвращает detected_language ru; confidence сохраняется как измерение, а низкое значение переводит файл на ручную проверку.
7. Проведите отрицательный тест: испорченный ключ, неподдерживаемая комбинация, неверный формат либо контрольный секрет. Ожидаемая ошибка должна быть обработана явно.

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

curl -sS -H "Authorization: Token $DEEPGRAM_API_KEY" \
 -H 'Content-Type: audio/wav' --data-binary @russian-control.wav \
 'https://api.deepgram.com/v1/listen?model=nova-3&detect_language=true' \
 -o language.json
jq '.results.channels[] | {detected_language,language_confidence}' language.json

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

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

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

Ожидаемый результат: На русской контрольной записи каждый ожидаемый канал возвращает detected_language ru; confidence сохраняется как измерение, а низкое значение переводит файл на ручную проверку.

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

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

• код языка есть
• число каналов совпало
• confidence записан
• смешанная речь протестирована
• fallback задан

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