Хаттама

Локальный помощник для подготовки протоколов совещаний на русском, казахском и смешанном языке.

Загрузите аудио, получите расшифровку с говорящими, проверьте поручения и сохраните протокол в DOCX. У каждого поручения есть исходные реплики, а правки человека сохраняются отдельно от результата модели.

Быстрый запуск · Веса моделей · Как пользоваться · Архитектура · Документация

Модели уже в репозитории. Все 3,08 ГБ весов находятся в models/ и скачиваются вместе с проектом. Сборка частей выполняется локально с проверкой SHA-256. Git LFS, GitHub CLI и доступ к исходной ссылке Hugging Face для этого не нужны.

Что получаете

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

Быстрый запуск

1. Подготовьте окружение

2. Скачайте проект

git clone --depth 1 https://github.com/BAITC-Hacks/hack-37d3e924-bbc.git
cd hack-37d3e924-bbc

Уже есть копия проекта? Обновите её через git pull. Все команды ниже выполняются из корня репозитория.

3. Выберите свою систему

Windows · PowerShell

Установка создаёт единое окружение .venv в корне проекта и собирает интерфейс и веса:

.\setup-windows.cmd
.\start-windows.cmd

Запуск собирает модели из models/, проверяет зависимости и выбирает доступную PyTorch CUDA либо CPU. Выбранное устройство печатается в терминале. Явный запуск на CPU: .\start-windows.cmd -Device cpu.

.\setup-windows.cmd -Device cuda
.\.venv\Scripts\python.exe scripts/manage.py doctor --profile windows --device cuda
.\start-windows.cmd -Device cuda

Mac · Apple Silicon

make setup PROFILE=mac
make up PROFILE=mac

Используется Python 3.12 и MLX. При запуске веса из models/ собираются и проверяются автоматически. Для Intel Mac этот профиль не предназначен.

Откройте http://127.0.0.1:8000. Терминал оставьте открытым; Ctrl+C останавливает приложение и worker вместе.

py -3.14 scripts/manage.py setup --profile fixture
py -3.14 scripts/manage.py run --profile fixture

make setup PROFILE=fixture
make up PROFILE=fixture

make setup PROFILE=cuda
# Подготовьте локальные веса и задайте AI_* в .env по .env.example.
make up PROFILE=cuda

Как пользоваться

1. Добавьте запись. Поддерживаются WAV, MP3, M4A и FLAC; стандартный предел загрузки — 100 МиБ.
2. Укажите контекст. Введите реальную дату и время совещания, часовой пояс и известных участников. Это нужно, в частности, для относительных сроков вроде «к завтрашнему дню».
3. Дождитесь обработки. Интерфейс показывает реальные этапы: подготовка, распознавание, разделение по голосам и извлечение результатов.
4. Проверьте протокол. Сопоставьте голоса с участниками, проверьте саммари, исполнителей и сроки по исходным репликам. Неизвестные значения требуют уточнения.
5. Сохраните правки и скачайте DOCX. Экспорт использует сохранённую версию. Исходный результат модели остаётся доступным отдельно.

Для ручного поручения нужны исходные реплики. Несохранённые правки блокируют экспорт, а одновременные изменения защищены номером версии. Неудачную обработку можно повторить из интерфейса. Хранятся машинный оригинал и последняя редакция; полной истории редакций пока нет. Одновременно обрабатывается одна запись; удаление работающего задания заблокировано.

Веса моделей

Одна и та же исходная модель используется на Mac и Windows; различается движок выполнения.

Большие файлы разбиты на части до 48 МиБ. На Mac их использует MLX; на Windows — адаптер mlx_torch, который читает исходные упакованные веса через PyTorch.

Ручная сборка и проверка, если не запускаете приложение сразу:

python3 scripts/prepare_repo_models.py
python3 scripts/prepare_repo_models.py --verify-only

На Windows используйте py вместо python3. Сборка работает без сети, проверяет каждую часть и готовый файл и пропускает уже собранные исправные модели. Исходные части остаются в репозитории.

Закреплённые размеры и SHA-256 · Происхождение и атрибуция · Лицензии

Архитектура

flowchart LR
    A["Аудиозапись"] --> B["React · загрузка"]
    B --> C["FastAPI · SQLite"]
    C --> D["Отдельный worker"]
    D --> E["Локальные модели"]
    E --> F["Исходный результат"]
    F --> G["Проверка и правки"]
    G --> H["Сохранённый DOCX"]

API принимает запись, сохраняет её и ставит задание в очередь. Отдельный worker вызывает ai.pipeline.run_pipeline; тяжёлые модели не загружаются в процесс API. Исходный результат и исправленная версия хранятся отдельно, а DOCX формируется из одной сохранённой версии.

frontend/                 React + TypeScript: загрузка, проверка, экспорт
backend/                  FastAPI, SQLite, очередь, worker и DOCX
ai/                       Распознавание, голоса, поручения и саммари
models/                   Веса, части, контрольные суммы и лицензии
contracts/                JSON-схемы входа и результата
scripts/                  Установка, запуск, сборка весов и проверки
data/                     Исходные материалы хакатона
.local/                   Локальные БД, аудио и отчёты; исключено из Git
.venv/                    Единое Python-окружение; исключено из Git

Основное приложение работает из корня на порту 8000. Запуск не зависит от prototypes/. На машине, где выполнен перенос, старый Streamlit с его локальными файлами сохранён в .local/legacy-prototype; этот архив не входит в Git. Архитектура подробнее.

Что проверено

В репозитории зафиксирован сквозной Windows-прогон на RTX 3050 Laptop 4 ГБ, 16 ГБ RAM с исходными моделями. Вход — синтетическая русская запись с двумя голосами.

Проверены также загрузка через приложение, исправление протокола, сохранение правок после перезапуска и экспорт DOCX. Это результат одного прогона, не оценка точности на реальных совещаниях. Модель пропустила относительный срок и ошиблась в саммари — проверка человеком остаётся обязательной.

Машиночитаемые результаты · Границы проверки

После переноса приложения в корень повторно проверены исходные модели: 6 реплик и 2 поручения; сохранение правок через браузер и DOCX с казахскими буквами. Прошёл 171 тест: 108 AI, 18 backend, 37 инструментов и 8 frontend; также прошли lint, TypeScript-проверка и production build. Число тестов относится к состоянию после переноса и интеграции запуска моделей.

Проверки проекта

После установки зависимостей:

make verify

На Windows:

.\.venv\Scripts\python.exe scripts/manage.py verify

Команда запускает тесты backend, AI и скриптов, затем тесты интерфейса, сборку TypeScript/Vite и проверку компиляции Python. Тестовые фикстуры и маленькие искусственные модели проверяют логику, а не качество распознавания.

Проверка выданных материалов хакатона без передачи содержимого наружу:

.\.venv\Scripts\python.exe scripts/check_data.py
# Дополнительно — настоящая локальная диаризация:
.\.venv\Scripts\python.exe scripts/check_data.py --diarize --models models

Базовая проверка прошла на двух аудиофайлах и двух DOCX из data/. Она проверяет декодирование, обработку DOCX и неизменность исходников, а не точность ASR/LLM. Технический отчёт без текста документов сохраняется в .local/data-smoke. Код выхода: 0 — успешно, 1 — ошибка, 2 — запрошенная диаризация заблокирована отсутствующими весами.

Границы текущей версии

• Результат — черновик для проверки. Имена, говорящие, сроки и поручения могут быть определены неверно. Качество казахской и смешанной речи требует отдельной оценки на реальных записях.
• Доступ локальный. Приложение слушает loopback; для общего сервера нужны аутентификация, защита сети и резервное копирование. Готовое публичное развёртывание и Docker Compose не поставляются.
• Offline-режим требует подготовки. Зависимости скачиваются при установке. Offline-флаги и блокировка сокетов AI дополняют сетевую изоляцию, но не заменяют проверку закрытого контура.
• Длинные записи требуют проверки. Разбиение на части и сверка поручений реализованы, но это не гарантия точности или производительности на любых совещаниях.

Документация

Лицензии и атрибуция сторонних моделей сохранены в models/NOTICE.md и models/licenses/.