Как настроить streaming в Deepgram API без потери финальных реплик

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

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

• Поток подключается к WebSocket endpoint /v1/listen, а аудиобайты отправляются бинарными сообщениями.
• Промежуточные результаты нельзя безусловно записывать в итог: для фиксации сегмента проверяют is_final.
• Для незакрытого живого потока предусмотрены keep-alive и явные сообщения завершения/финализации.
• Неправильные encoding или sample_rate дают DATA/NET ошибки либо бессмысленный текст даже при успешном соединении.

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

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

# Псевдокод обработчика сообщений WebSocket
final_parts = []
for event in deepgram_events:
    alt = event['channel']['alternatives'][0]
    if event.get('is_final') and alt.get('transcript'):
        final_parts.append(alt['transcript'])
final_text = ' '.join(final_parts)
assert final_text.strip()
# После последнего audio chunk отправьте документированное сообщение CloseStream.

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

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

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

Ожидаемый результат: Во время фразы появляются interim-события, но итоговая строка содержит каждый подтверждённый сегмент ровно один раз; после закрытия приходит финальный результат, а клиент освобождает WebSocket.

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

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

• формат источника измерен
• is_final обработан
• дубли исключены
• закрытие явное
• обрыв воспроизведён

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