AutoProtocol AI

Локальный MVP для подготовки черновика протокола по записи совещания. Приложение распознаёт речь, показывает реплики с временными отметками и метками говорящих, выделяет возможные поручения, формирует краткое содержание и скачивает результат в DOCX или PDF.

Что реализовано

• Веб-интерфейс для загрузки аудио и видеофайлов (WAV, MP3, M4A, MP4, MOV, WEBM, OGG, FLAC).
• Локальное распознавание речи моделью faster-whisper. Язык определяет сама модель; доступны русский, казахский и смешанная речь, но качество зависит от аудио и размера модели.
• Локальная диаризация через pyannote.audio при включённой настройке. Если она выключена или модель недоступна, все реплики помечаются как «Говорящий 1».
• Структурированный JSON-ответ API с транскриптом, временными метками, языком, саммари и поручениями.
• Черновое извлечение поручений по русским и казахским ключевым словам. В таблице есть задача, ответственный, срок, исходная реплика и говорящий.
• Скачивание DOCX и PDF с саммари, таблицей поручений и транскриптом.
• Демо-сценарий без модели и аудиозаписи: заранее подготовленный русский/казахский транскрипт и поручения явно помечены как демонстрационные. Он нужен, чтобы показать интерфейс и экспорт, если веса модели ещё не скачаны.
• Запись удаляется с диска после обработки. Результат хранится в памяти процесса до перезапуска сервера.

Быстрый запуск без Docker

Нужен Python 3.10–3.12 и установленный FFmpeg, доступный в PATH. На Windows FFmpeg можно установить отдельно; для контейнера он уже установлен.

py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item .env.example .env
python -m uvicorn app:app --reload

Откройте http://localhost:8000. При первом запуске faster-whisper скачает выбранную модель из Hugging Face. Для первой загрузки нужен интернет; далее кэшированная модель может работать без сети. Начните с WHISPER_MODEL=small для более высокого качества или выберите base/tiny для более лёгкого демо.

Запуск через Docker

Из корня репозитория выполните одну команду (файл .env не обязателен):

docker compose up --build

Затем откройте http://localhost:8000. Контейнер настроен на CPU и устанавливает FFmpeg при сборке. docker-compose.yml задаёт рабочие значения по умолчанию, поэтому первый запуск не блокируется отсутствием .env. Сборка контейнера и загрузка весов требуют сетевого доступа к пакетному реестру/источнику модели. Чтобы сразу показать интерфейс и результат без скачивания весов, нажмите «Показать демонстрационный пример без модели».

Проверка на тестовой записи

1. Подготовьте короткую запись на русском или казахском длительностью 30–90 секунд. Для проверки поручений произнесите явные фразы вроде «Айжан, подготовь отчёт до пятницы» или «Ертеңге дейін ұсынысты жіберіңіз».
2. Откройте веб-страницу, перетащите файл в область загрузки и нажмите «Подготовить протокол».
3. Убедитесь, что появились транскрипт, определённый язык, блок краткого содержания и таблица поручений. Сверьте имя, дату и исходную реплику с аудио.
4. Нажмите DOCX и PDF и проверьте, что файлы открываются и содержат саммари, таблицу и транскрипт.
5. Быстрая проверка API: curl http://localhost:8000/api/health должен вернуть {"status":"ok","service":"AutoProtocol AI"}. POST /api/process принимает файл в multipart-поле file и возвращает JSON.

Образец аудиозаписи не включён в репозиторий. Лучше тестировать собственную запись с согласия участников. Сгенерированный речевой тест не проверит точность распознавания.

Диаризация

По умолчанию ENABLE_DIARIZATION=false: приложение не скачивает отдельную gated-модель и помечает все распознанные реплики как «Говорящий 1». Демонстрационный пример содержит вручную расставленные метки двух говорящих и прямо помечен в интерфейсе; это не результат диаризации. Чтобы включить реальное разделение говорящих:

1. Примите условия доступа к pyannote/speaker-diarization-3.1 на Hugging Face.
2. Создайте локальный .env, установите ENABLE_DIARIZATION=true и задайте HF_TOKEN с правом скачать модель.
3. Установите дополнительную зависимость командой python -m pip install -r requirements-diarization.txt и запустите обработку с доступом к сети для первоначальной загрузки. Для закрытого контура заранее скачайте и проверьте веса на разрешённой машине, затем настройте локальный путь в DIARIZATION_MODEL и перенесите кэш согласно правилам вашей инфраструктуры.

Пакет pyannote.audio требует PyTorch и может быть тяжёлым для установки, поэтому он отделён от основных зависимостей и Docker MVP. В случае ошибки диаризации транскрипт всё равно будет возвращён с одной меткой говорящего; текст ответа API содержит статус/причину.

Архитектура

• frontend/ — адаптивная страница загрузки и результата; она обращается к тому же FastAPI-серверу.
• backend/main.py — UI, health-check, приём файла, ограничение размера и endpoint экспорта.
• backend/pipeline.py — faster-whisper, необязательная локальная pyannote-диаризация, эвристическое извлечение поручений и сбор результата.
• backend/reports.py — формирование DOCX через python-docx и PDF через ReportLab.
• data/uploads/ — временная область приёма; оригинальный файл удаляется после обработки.

API результата

POST /api/process возвращает JSON с полями id, filename, language, model, summary, transcript[], tasks[], diarization_status, notes. У реплики есть start, end, text, speaker. У поручения есть task, responsible, deadline, source, speaker, timestamp. Ссылки экспорта: /api/results/{id}/protocol.docx и /api/results/{id}/protocol.pdf.

Ограничения прототипа

• Извлечение поручений и заполнение ответственного/срока основаны на простых правилах, а не на языковой модели. Возможны пропуски и ложные срабатывания; поля «Не определён» и «Не указан» нужно проверять.
• Для загруженной записи саммари сейчас является началом транскрипта (до 700 символов), а не семантическим резюме всей встречи. В демо-режиме показывается фиксированный пример саммари.
• Точность русского, казахского и смешанного распознавания зависит от акустики, акцента, качества записи и выбранной модели. Модель может нормализовать или пропускать код-свитчинг.
• Диаризация отключена по умолчанию; даже включённая модель может путать похожие голоса и не знает реальных имён. Отображаемые номера говорящих не являются идентификацией личности.
• Результаты хранятся в памяти одного процесса и исчезают при рестарте; нет учётных записей, очереди задач, авторизации или постоянного хранилища.
• Для production в закрытом контуре необходимо отдельно подготовить и проверить веса моделей и пакеты, отключить исходящий сетевой доступ, задать локальные пути моделей и добавить авторизацию, аудит, очередь, хранение и политику удаления. Сетевые загрузки моделей нужны только на этапе подготовки/первого запуска.

Конфигурация

Скопируйте .env.example в .env. Ключевые параметры: WHISPER_MODEL, WHISPER_DEVICE, WHISPER_COMPUTE_TYPE, MAX_UPLOAD_MB, ENABLE_DIARIZATION, DIARIZATION_MODEL. Секреты храните только в локальном окружении, не коммитьте .env.