Как улучшить распознавание терминов в Deepgram через keyterm

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

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

• Можно передать до 100 важных терминов; документация советует фокусироваться на 20–50 и оставаться ниже лимита 500 токенов.
• Несколько терминов задают повторением параметра: keyterm=a&keyterm=b.
• Многословную фразу кодируют %20 или +; запятые и точки с запятой не разделяют термины.
• Веса и intensifier у keyterm не поддерживаются: форма term:0.15 молча рассматривается как буквальный термин.

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

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

curl -sS -G 'https://api.deepgram.com/v1/listen' \
 -H "Authorization: Token $DEEPGRAM_API_KEY" \
 -H 'Content-Type: audio/wav' --data-binary @catalog.wav \
 --data-urlencode 'model=nova-3' \
 --data-urlencode 'language=ru' \
 --data-urlencode 'keyterm=TNWS' \
 --data-urlencode 'keyterm=векторная база' -o terms.json

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

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

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

Ожидаемый результат: На размеченном наборе из 30 произнесений считается recall каждого целевого термина до и после keyterm; улучшение принимается по агрегату, а не по одному удачному слову.

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

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

• термины раздельны
• фразы закодированы
• датасет размечен
• baseline сохранён
• recall посчитан

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