Как распознать речь через Hugging Face Inference Providers API

ASR в Inference Providers предназначен для преобразования речи в текст. Вход может быть Base64-аудио, а без parameters — raw bytes. Спецификация содержит return_timestamps. Подходящие warmed-модели можно искать командой hf models ls --warm --pipeline-tag automatic-speech-recognition.

Подтверждённый механизм нужно отделять от архитектурных решений. API определяет формат вызова, но не создаёт за вас песочницу, права, журнал и критерии качества. Эти ограничения реализует приложение и проверяет до исполнения каждого опасного шага.

Подготовка теста

Создайте отдельный проект, минимальный API-ключ и обезличенный набор. Секрет храните в переменной окружения или менеджере секретов. Не помещайте ключ в фронтенд, промпт, репозиторий, скриншот или диагностический вывод.

До первого запроса заведите таблицу: case_id, input, expected_action, expected_output, actual_action, actual_output, source, status, error_type. Заполните expected заранее. Если ожидаемый результат появляется после просмотра ответа, проверка превращается в подгонку.

Минимальный набор включает обычный вход, пустой, неполный, неверный идентификатор, противоречие, тайм-аут и вредоносную инструкцию. Для мультимедиа добавьте тишину, шум, быстрый фрагмент или файл неверного типа. Для файловых инструментов добавьте попытку выйти за рабочий каталог.

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

1. Создайте HF_TOKEN с правом Inference Providers и храните его в окружении. Выберите warmed ASR-модель, в карточке которой подтверждён русский язык.
2. Приведите тестовую запись к поддерживаемому формату, сохраните исходник и измерьте длительность. Не меняйте sample rate вслепую, если провайдер принимает исходный контейнер.
3. Отправьте raw bytes либо Base64 по спецификации. Если нужны субтитры, включите return_timestamps и проверьте структуру ответа выбранного провайдера.
4. Сопоставьте текст с заранее подготовленной эталонной расшифровкой. Отдельно отметьте числа, имена, паузы и границы сегментов.
5. При смене модели или провайдера прогоните тот же набор. Не сравнивайте только одну удобную запись; добавьте шум, быстрый темп и тишину.

Каждый шаг должен оставлять проверяемый след: request_id, версия модели, выбранный инструмент, обезличенные аргументы, exit code или статус, размер результата и факт побочного эффекта. Полный секрет, персональные данные и необязательное внутреннее рассуждение модели в журнал не записывайте.

Копируемый шаблон

Эталон для проверки: «Заказ А-сто-двадцать четыре готов. Забрать его можно после пятнадцати часов». Верни полный текст и таймкоды сегментов. Не исправляй номер по контексту и помечай неуверенный фрагмент отдельно.

Общие правила:
- используй только переданные данные и разрешённые инструменты;
- не угадывай отсутствующие значения;
- перед действием проверь путь, тип, идентификатор и права;
- при конфликте верни status=needs_review;
- не отправляй, не удаляй и не раскрывай секрет без отдельного подтверждения;
- перечисли фактические действия и источник каждого изменяемого значения.

Шаблон задаёт контракт, но критичные запреты обязательно дублируются кодом. Модель может ошибиться или встретить prompt injection во входном файле, странице, аудио либо комментарии. Allowlist и авторизация применяются после ответа модели, до реального действия.

Реалистичный пример и ожидаемый результат

Ожидается фраза с заказом А-124 и временем после 15:00, а также таймкоды внутри фактической длительности файла. Если модель выдаёт А-1240, кейс отмечается entity_error, даже если остальная фраза верна.

Это критерий теста, а не выдуманный результат сравнительного исследования. При внедрении сохраните реальный output рядом с expected и отметьте каждое расхождение. Правильный текст при лишней команде, неверном файле или запрещённом запросе считается провалом.

Проверка результата по четырём уровням

Сначала транспорт: запрос завершился, ответ читается, идентификатор сохранён. HTTP 200 не доказывает корректность. При тайм-ауте сначала выясните состояние прошлого вызова; повтор внешней записи без проверки создаёт дубли.

Затем структура: обязательные поля присутствуют, типы совпадают, Base64 декодируется, JSON разбирается после полного получения, файл открывается штатной библиотекой. Пустое поле не превращается в число или факт без явного правила.

Третий уровень — смысл. Каждый факт сопоставляется с входом, таймкодом, файлом либо результатом инструмента. Числа пересчитываются обычным кодом. Имена и идентификаторы сравниваются посимвольно. Если источник не содержит значения, ответ должен сообщить о нехватке данных.

Четвёртый уровень — действие. Проверьте внешнюю систему или файловый diff: какие команды выполнены, какие файлы созданы, была ли запись. Для read-only сценария любое изменение является ошибкой, даже если итоговое объяснение выглядит убедительно.

Приёмка на конкретных данных