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

Проект для HackAlem AI. Вы загружаете запись совещания, а JazAI на вашем компьютере:

• распознаёт речь и делит её на реплики разных людей с таймкодами;
• находит поручения, ответственных, сроки и составляет краткое саммари;
• к каждому поручению прикладывает цитату из записи, по клику она проигрывается;
• даёт всё проверить и исправить, затем выгружает протокол в Word (DOCX).

Распознавание и анализ выполняют локальные модели, без облачных API. Полная проверка закрытого контура при запрете внешней сети на уровне ОС пока не завершена.

---

Как запустить — 3 шага

Шаг 1. Скачайте проект

Нажмите зелёную кнопку Code → Download ZIP вверху этой страницы и распакуйте архив. Или через терминал:

git clone https://github.com/BAITC-Hacks/hack-9e0cb6e2-y.git

Шаг 2. Запустите файл для своей системы

Система	Что сделать
Windows	Дважды щёлкните start-windows.bat
macOS	Дважды щёлкните start-macos.command. Если macOS не даёт открыть файл, нажмите на него правой кнопкой → Открыть
Linux	Откройте терминал в папке проекта и выполните bash start-linux.sh

Скрипт установит Python 3.11 и библиотеки, скачает модели. Для автоматической установки FFmpeg на Windows нужен winget, на macOS — Homebrew, на Linux — поддерживаемый пакетный менеджер и права установки. Если FFmpeg и ffprobe уже доступны, этот шаг пропускается.

Шаг 3. Один раз откройте доступ к модели на Hugging Face

Модель, которая различает голоса (pyannote), бесплатная. Но её авторы выдают её только после согласия с условиями. Скрипт остановится и подскажет, что делать:

1. Откроется страница модели. Войдите или зарегистрируйтесь на Hugging Face, это бесплатно.
2. Заполните короткую форму и примите условия.
3. Вернитесь в окно скрипта и нажмите Enter.
4. Скрипт попросит войти в тот же аккаунт. Следуйте подсказке в окне: откройте ссылку и подтвердите вход.

Готово. Когда всё скачается, браузер откроется сам на странице JazAI. Обычно это адрес http://127.0.0.1:8000.

⏱ На первый запуск ориентировочно заложите 15–40 минут или больше. Нужно скачать несколько ГБ; время и объём зависят от системы, скорости интернета и уже установленных компонентов. Для следующих запусков используйте тот же файл. Готовые модели скачивать заново не нужно; время открытия зависит от компьютера и состояния окружения. Не закрывайте окно скрипта, пока пользуетесь приложением. Чтобы остановить, нажмите Ctrl+C или закройте окно.

---

Что нужно компьютеру

	Требование
Система	Windows 10/11 (x64), macOS 14+ на Apple Silicon (M1 и новее), Linux x86_64 или ARM64 (Ubuntu 22.04+, Debian 12+, Fedora и похожие)
Память	16 ГБ RAM: на такой машине проект проверен
Диск	~12 ГБ свободного места
Интернет	Нужен только при первом запуске
Видеокарта	Не нужна, всё работает на процессоре
Аккаунт	Бесплатный аккаунт Hugging Face

Особенности систем:

• Windows: если FFmpeg ещё не установлен, нужен winget из приложения «Установщик приложений» (App Installer). Если winget отсутствует, установите его или FFmpeg вручную по подробному руководству.
• macOS: для установки FFmpeg нужен Homebrew. Если его нет, скрипт подскажет. Intel Mac не поддерживается, потому что PyTorch для них больше не выпускается.
• Linux: при установке FFmpeg система может спросить пароль администратора (sudo).

---

Как проверить основной сценарий

1. Возьмите запись на 30–60 секунд, где говорят 2–3 человека (MP3 или WAV).
2. На странице JazAI введите название встречи, выберите файл и поставьте галочку согласия.
3. Нажмите «Загрузить и обработать» и дождитесь текста с разбивкой по говорящим. На короткой записи обработка может занять несколько минут; время зависит от процессора, свободной памяти и длительности записи.
4. Нажмите на таймкод любой реплики, и запись начнёт играть с этого места.
5. В блоке «Кто говорит» впишите известные вам имена вместо SPEAKER_00. Для каждого введённого имени отметьте «Подтверждаю соответствие имени этому голосу», затем нажмите «Сохранить изменения». Без подтверждения имя не сохранится; неизвестные имена оставьте пустыми.
6. Нажмите «Составить поручения и саммари» и дождитесь результата. Анализ на CPU может занять несколько минут или дольше; измеренные примеры приведены в отчёте.
7. Проверьте поручения, ответственных и сроки по цитатам-источникам. После исправлений или отметок проверки нажмите «Сохранить поручения и итоги» и дождитесь подтверждения сохранения. Пока есть несохранённые изменения, скачивание DOCX недоступно.
8. Выберите шаблон и нажмите «Скачать протокол DOCX». Файл открывается в Word или LibreOffice.

Своей записи нет? На Windows можно создать синтетическую командой .\scripts\synthesize_smoke.ps1. Подробности в руководстве.

---

Если что-то пошло не так

Что видите	Что сделать
Скрипт остановился с сообщением «ОШИБКА»	Прочитайте подсказку над ней и запустите тот же файл снова: готовые шаги повторно не выполняются
Оборвалось скачивание	Запустите файл ещё раз, загрузка продолжится
Ошибка 401/403 при скачивании pyannote	Условия модели приняты в другом аккаунте, не в том, куда выполнен вход. Выполните .venv/bin/hf auth login --force (Windows: .venv\Scripts\hf.exe auth login --force) и запустите файл снова
Windows: «Система Windows защитила ваш компьютер»	Нажмите Подробнее → Выполнить в любом случае
Браузер не открылся	Откройте адрес, который скрипт напечатал в окне, например http://127.0.0.1:8000
Порт 8000 занят	Ничего делать не нужно: скрипт сам возьмёт следующий свободный порт и напечатает адрес
Обработка идёт очень долго	Начните с короткой записи на 30–60 секунд. Ограничения: до 10 минут и до 250 МБ

Больше случаев описано в подробном руководстве.

---

Что работает и что ещё нет

Возможность	Статус
Загрузка аудио/видео через браузер	✅ проверены MP3, WAV и синтетическое MP4
Распознавание речи (Whisper small)	✅ русский язык проверен; казахский и смешанный ещё проверяются
Разделение говорящих (pyannote)	✅
Имена участников и ручные исправления с историей версий	✅
Поручения, ответственные, сроки, саммари с цитатами (Qwen3-4B)	✅ черновик, который проверяет человек
Экспорт протокола DOCX по двум шаблонам	✅
Экспорт PDF	❌ пока нет
Подключение к Zoom / Teams / Meet	❌ пока нет, вход — файл записи

Все выводы модели — черновик. Каждое поручение нужно проверить по цитате-источнику, прежде чем отправлять протокол.

Свежий полный проход «аудио → текст → поручение → ручная правка → оба DOCX» проверен на синтетической записи 17 секунд: 3 минуты 41 секунда на CPU. Для этого примера WER/CER равны 0%; качество настоящих встреч, KK и смешанной речи требует отдельной оценки. Измерения и команды повторной проверки.

Полностью проверенный путь — Windows 10 x64. Скрипты для macOS и Linux используют те же зафиксированные версии библиотек и моделей, но на этих системах полный прогон ещё не выполнялся.

---

Для технической проверки

• Подробное руководство: ручная установка по шагам, полный сценарий, настройки .env, API и измерения.
• Архитектура, модели и лицензии, фазы реализации.
• Отчёты о проверках: ML-прогоны, web-конвейер, поручения и саммари, редактор, экспорт DOCX.
• Сквозной прогон и качество: 158 тестов, обработка тишины, WER/CER и границы проверки сети.

Запустить тесты после установки:

uv run --frozen pytest -q
uv run --frozen ruff check .

Стек: Python 3.11, FastAPI, SQLite, faster-whisper, pyannote.audio, llama.cpp + Qwen3-4B, python-docx. Docker, Node.js и облачные ключи не нужны. Сервер слушает только 127.0.0.1 и недоступен из сети.