HackAlem AI — локальное автопротоколирование совещаний

Для проверки проекта скачайте HackAlem-jury-submission.zip. Внутри находится актуальный рабочий проект: исходный код, Docker-конфигурация, подробный README.md и RUNBOOK.md для запуска и демонстрации.

Архив не содержит записей, .env, токенов и весов моделей. Для полноценного прогона подготовьте их локально по инструкции внутри архива.

Архивный каркас

Прототип локального автопротоколирования по PLAN.MD. Сейчас работает путь загрузка → сохранение → проверка длительности → подготовка WAV → готово к локальным моделям. Распознавание и генерация протокола ещё не подключены.

Что уже сделано

• FastAPI и Pydantic: контракты встречи, файла, задачи, реплики, говорящего, темы, показателя, проблемы, поручения и экспорта.
• SQLite: десять таблиц, внешние ключи, каскадное удаление связанных строк, ограничение одной задачи preparing_audio. SQL-модели находятся в backend/app/schema.sql; ORM не используется.
• Реальная загрузка MP4/M4A/MP3/WAV/WebM: UUID встречи, нормализация исходного имени, техническое имя файла, серверный лимит 200 МиБ (209715200 байт). Пустой или неподдерживаемый файл отклоняется; частичная загрузка очищается.
• FFprobe проверяет аудиодорожку и длительность до 900 секунд; FFmpeg создаёт WAV mono, 16 кГц, PCM 16-bit. Выходной WAV проверяется повторно. Ошибки безопасно сохраняются в задаче, stderr программ не логируется.
• FastAPI BackgroundTasks последовательно выполняет подготовку в одном процессе. Статусы: queued, preparing_audio, ready_for_models, failed. ready_for_models не означает готовый транскрипт.
• React отправляет файл, показывает ошибки сервера и опрашивает статус раз в 2 секунды до завершения. На экране результата — честная карточка об отсутствии моделей. Нет демонстрационных транскриптов и поручений.
• Удаление завершённой/ошибочной встречи удаляет её каталог и строки SQLite. Для queued/preparing_audio возвращается 409. Пути из БД не используются для удаления; ссылки и Windows junction запрещены.
• Собранный frontend раздаётся FastAPI. Запуск через python -m backend.app привязан к 127.0.0.1; access log отключён.
• sources отвечает за загрузку, processing/audio.py — за переиспользуемую подготовку локального аудио; exporting остаётся заглушкой.

Подготовка и запуск

Нужны Python 3.12, Node.js 22.12+ (проверено на 24.19), pnpm 11 и локальные FFmpeg/FFprobe. GPU и модели для этого этапа не нужны. Первичная установка зависимостей требует сети; рабочий тракт использует только локальные файлы. Запускайте команды из корня репозитория.

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend/requirements-dev.txt
Copy-Item .env.example .env
Set-Location frontend
pnpm install --frozen-lockfile
pnpm build
Set-Location ..
.\.venv\Scripts\python.exe -m backend.app

Если .env уже существует, сохраните его настройки и не выполняйте повторное копирование. До запуска укажите пути к установленным программам, например:

FFMPEG_PATH=C:/Tools/ffmpeg/bin/ffmpeg.exe
FFPROBE_PATH=C:/Tools/ffmpeg/bin/ffprobe.exe

Оба файла должны существовать. Пути с пробелами допустимы: команды передаются списком аргументов без shell. Проверка установки в PowerShell:

& 'C:/Tools/ffmpeg/bin/ffmpeg.exe' -version
& 'C:/Tools/ffmpeg/bin/ffprobe.exe' -version

Без этих программ сервер и UI запускаются, но загруженная задача завершается failed с кодом ffmpeg_missing или ffprobe_missing и понятным сообщением. После настройки перезапустите сервер и загрузите запись заново.

Linux / Brev:

python3.12 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements-dev.txt
cp .env.example .env
cd frontend
pnpm install --frozen-lockfile
pnpm build
cd ..
.venv/bin/python -m backend.app

Откройте http://127.0.0.1:8000. Сборку нужно выполнить до запуска backend; после первой сборки перезапустите сервер. Без сборки корневой URL возвращает 503 с пояснением. OpenAPI доступен на /openapi.json; Swagger/ReDoc отключены, чтобы не подгружать скрипты с CDN.

Для разработки frontend: в каталоге frontend выполните pnpm dev, оставив backend запущенным. Vite слушает 127.0.0.1:5173, /api проксируется на 127.0.0.1:8000. При изменении порта backend поправьте proxy в frontend/vite.config.ts.

Для удалённой машины используйте SSH-туннель с компьютера разработчика (замените USER и HOST):

ssh -N -L 127.0.0.1:8000:127.0.0.1:8000 USER@HOST

Не открывайте публичный порт и не создавайте публичную ссылку.

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

.env.example содержит только примеры, .env исключён из Git. Существующие переменные процесса имеют приоритет. Относительные пути разрешаются от корня репозитория.

Переменная	Назначение
DATA_DIR, DATABASE_PATH	Локальный каталог и SQLite; создаются при запуске
FRONTEND_DIST, PORT	Сборка интерфейса и порт backend; адрес запуска фиксирован на loopback
WHISPER_MODEL_PATH	Будущий локальный каталог faster-whisper large-v3
PYANNOTE_MODEL_PATH	Будущий локальный каталог speaker-diarization-community-1
OLLAMA_BASE_URL, OLLAMA_MODEL	Будущий локальный Ollama и qwen3:8b
FFMPEG_PATH, FFPROBE_PATH	Используемые локальные программы; имя в PATH либо абсолютный путь
LIBREOFFICE_PATH	Будущий локальный экспорт PDF
HF_TOKEN	Только подготовка весов; оставить пустым в рабочем окружении
HF_HUB_OFFLINE, TRANSFORMERS_OFFLINE	Флаги будущего офлайн-запуска моделей

Переменные моделей и LibreOffice пока документируют будущую конфигурацию: приложение не загружает модели и не обращается к Ollama. Команд загрузки моделей здесь ещё нет: они будут добавлены после реализации и проверки соответствующего этапа. До подготовки pyannote необходимо принять условия модели; токен не сохраняется в Git.

Все создаваемые пути хранения, включая DATABASE_PATH, должны находиться внутри DATA_DIR. При изменении DATA_DIR поправьте и DATABASE_PATH в .env; если переменная DATABASE_PATH не задана, база создаётся внутри выбранного DATA_DIR. Каталог встречи: DATA_DIR/<UUID>/source.<расширение>, подготовленное аудио: DATA_DIR/<UUID>/audio.wav; будущие результаты также должны храниться там. Временные multipart-файлы находятся в DATA_DIR/.uploads и закрываются после запроса. Ссылки и junction внутри хранилища не поддерживаются. Хранилище должно быть доступно на запись только доверенному локальному пользователю приложения.

При старте выполняется миграция старой таблицы задач без удаления встреч. Старые processing/ready становятся failed с кодом legacy_state, поскольку у них нет подтверждённого подготовленного WAV. Прерванные queued/preparing_audio становятся failed с кодом interrupted; автоматического повтора нет. Запускайте один экземпляр приложения, один Uvicorn worker, без --reload во время обработки.

API

PLAN.MD задаёт операции, но не URL. В каркасе выбраны следующие маршруты:

Метод и путь	Назначение / текущее поведение
GET /api/health	200: сервер работает, processing=audio_preparation, models=not_connected
POST /api/meetings	Multipart: file, title, необязательные meeting_date и timezone; 202 с meeting_id, ID задачи, status=queued
GET /api/meetings/{id}/status	200: статус, безопасные message и error_code; неизвестный ID — 404
GET /api/meetings/{id}/result	200: метаданные встречи, задача, models_connected=false; транскрипта нет
PATCH /api/meetings/{id}	Правки говорящих, реплик, поручений и флаг утверждения; 501
GET /api/meetings/{id}/exports/{format}	docx или pdf; 501
DELETE /api/meetings/{id}	Удаление встречи; 204, активная задача/небезопасный путь — 409, неизвестный ID — 404

Ошибки загрузки: пустой файл — 400, размер — 413, расширение — 415, неверные метаданные/multipart — 422, ошибка записи — 500. Проверка размера выполняется при чтении multipart без зависимости от Content-Length и повторяется при сохранении. Формат контейнера, аудиодорожка и длительность проверяются в фоне; ошибки видны через status/result с status=failed. Диагностика программ, приватные пути и содержимое записей в ответы не включаются. Неизвестные API-маршруты возвращают 404.

Проверка загрузки: откройте интерфейс, выберите разрешённую обезличенную запись и нажмите «Загрузить запись». При доступных программах ожидайте ready_for_models. Эквивалентный запрос из PowerShell (замените путь на существующий файл):

curl.exe -X POST http://127.0.0.1:8000/api/meetings -F "title=Проверка подготовки" -F "file=@C:/Recordings/approved.wav"

Возьмите meeting_id из ответа:

curl.exe http://127.0.0.1:8000/api/meetings/MEETING_ID/status
curl.exe http://127.0.0.1:8000/api/meetings/MEETING_ID/result
curl.exe -X DELETE http://127.0.0.1:8000/api/meetings/MEETING_ID

Проверки

.\.venv\Scripts\python.exe -m unittest discover -s backend/tests -v
Set-Location frontend
pnpm test
pnpm build

На Linux замените путь Python на .venv/bin/python. Backend-тесты создают временную SQLite и искусственные байты/тишину без речи. Они проверяют сохранение, ограничения размера/формата/длительности, ошибки FFmpeg/FFprobe, параметры конвертации, статусы, сериализацию задач, миграцию и безопасное удаление. Настоящие FFmpeg, записи, GPU и модели для тестов не нужны: запуск программ подменяется. Это не проверка качества распознавания. React-тесты проверяют отправку файла, сообщения сервера, опрос/остановку/повтор, результат и удаление. Starlette закреплён в зависимостях, поскольку локальный ограниченный multipart-парсер расширяет его API.

Временные backend-фикстуры создаются и очищаются внутри игнорируемого data/.test-tmp. Если системный диск Windows заполнен и frontend-тесты падают с ENOSPC, перед их запуском задайте TEMP/TMP для текущего PowerShell из корня проекта:

New-Item -ItemType Directory -Force data/.test-tmp | Out-Null
$env:TEMP = (Resolve-Path data/.test-tmp).Path
$env:TMP = $env:TEMP

Это меняет окружение только текущего процесса PowerShell и его дочерних программ.

Следующие этапы

1. Подготовить локальные веса Whisper large-v3 в формате CTranslate2 для faster-whisper по WHISPER_MODEL_PATH, включая конфигурацию и токенизатор.
2. Подготовить полный локальный комплект pyannote/speaker-diarization-community-1 по PYANNOTE_MODEL_PATH: конфигурацию и все используемые веса. Принять условия модели на этапе подготовки; в рабочем тракте токен и сеть не нужны. Установить совместимые faster-whisper/CTranslate2, pyannote.audio/PyTorch и GPU runtime. Реализовать ASR и диаризацию с временными метками, объединение по времени и проверку работы без сети на согласованных русской, казахской и смешанной записях. Никаких live-адаптеров и WebSocket в первой версии.
3. Ollama: структурированные темы, факты, проблемы, поручения. Проверять ссылки на реплики, неоднозначности и сроки; говорящий и ответственный — отдельные сущности. Нормализовать относительный срок только при известной дате и часовом поясе, сохраняя исходную формулировку.
4. Реальное сохранение правок, сопоставление имён, утверждение и переход к месту записи; подключить UI к рабочим API.
5. DOCX через python-docx и PDF через локальный LibreOffice только из утверждённого состояния. Синие заголовки, светлые шапки таблиц, темы и приложение-транскрипт; проверить длинный текст, кириллицу и казахские символы.
6. Расширять миграции и тесты при подключении новых результатов. Удаление каталога встречи и связанных строк уже реализовано.
7. Проверить три согласованные обезличенные записи: русскую, казахскую, смешанную. При необходимости сравнить распознавание с локальной Sybyrla по плану.

Ограничения и закрытый контур

ASR, диаризация, LLM-анализ, редактирование и оба экспорта отсутствуют. Подготовка аудио требует установленного FFmpeg/FFprobe. Одна задача обрабатывается за раз; отдельной очереди и отмены нет. Тайм-аут FFprobe — 30 секунд, FFmpeg — 300 секунд. Список прошлых встреч и восстановление выбранной встречи в UI после обновления страницы пока отсутствуют; сохранённая встреча доступна по API с её UUID. Файловая система и SQLite не образуют общей транзакции: при ошибке удаления строка сохраняется, удаление можно повторить. При аварийном завершении процесса во время загрузки может потребоваться ручная очистка неполного каталога.

Для будущего полного тракта план требует GPU от 22 ГБ VRAM, RAM от 32 ГБ и 60 ГБ свободного диска (A10G/L4 или лучше). Проверки GPU и моделей в этой сессии не выполнялись. При нехватке VRAM этапы должны последовательно освобождать GPU.

Аудио, транскрипты, саммари и поручения не отправляются во внешние AI/API и не пишутся в логи. Brev — облачная демонстрационная среда, не закрытый контур заказчика; допускаются только обезличенные и согласованные записи. Для закрытого контура заранее подготовьте зависимости, веса и шрифты и проверьте работу при заблокированном исходящем доступе. Аутентификация, live-конференции, рассылки, СЭД, дашборд исполнения и голосовая идентификация не реализованы.