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

Локальный конвейер: аудио → Kazakh/Russian STT → NeMo-диаризация → llama.cpp (Gemma Q4_K_S) → поручения, сводка статусов и классификация → JSON, PDF или DOCX. Исходные записи и расшифровки не отправляются во внешние сервисы: LLAMA_URL должен указывать на ваш локальный сервер.

Установка с нуля в Windows

Нужны Windows с поддержкой WSL2 и NVIDIA GPU с установленным в Windows драйвером для CUDA в WSL. Распознавание и диаризация требуют CUDA; CPU-режим для них не предусмотрен. Во время установки нужен интернет: зависимости и модели занимают несколько ГБ.

1. Поместите заранее скачанный gemma-4-12b-it-Q4_K_S.gguf в models/llm/. Если файл уже лежит в другом месте, укажите его путь в LLAMA_MODEL_PATH в .env. Установщик не скачивает GGUF.

2. Откройте install.cmd двойным щелчком или выполните из корня проекта:

   .\install.cmd
   

   Если Ubuntu-24.04 ещё нет, скрипт запустит её установку через WSL. Следуйте сообщениям: при необходимости запустите установку от администратора, перезагрузите Windows и повторно откройте install.cmd.

3. Дождитесь успешной проверки и запустите start.cmd.

Установщик создаёт Linux-окружение Python 3.12, устанавливает FFmpeg, системные библиотеки и Python-зависимости, проверяет CUDA, скачивает модели STT/NeMo и подготавливает llama.cpp. В конце он проверяет готовность через launcher --check, не запуская серверы. Существующий .env сохраняется; если его нет, создаётся копия .env.example. Настройка LOCAL_MODELS_DIR из .env учитывается при подготовке моделей.

install.cmd и start.cmd используют одинаковые переменные окружения Windows: QORIT_WSL_DISTRO (по умолчанию Ubuntu-24.04) и QORIT_PYTHON (по умолчанию /opt/qorit-nemo/bin/python; нужен абсолютный Linux-путь к виртуальному окружению, заканчивающийся на /bin/python). Для повторного запуска из терминала без ожидания нажатия клавиши используйте install.cmd --no-pause; справка — install.cmd --help.

Запуск одной командой в Windows

Для настроенного окружения Ubuntu-24.04 / WSL2 откройте start.cmd двойным щелчком или выполните из корня проекта в PowerShell:

.\start.cmd

Он запускает Gemma 4 12B IT Q4_K_S и HTTP API с веб-интерфейсом в одном WSL-окружении. PowerShell-скрипты и изменение Execution Policy не нужны. Дождитесь сообщения Ready и откройте http://localhost:8000. Оставьте окно открытым; Ctrl+C останавливает оба сервера.

В .env укажите LLAMA_MODEL_PATH — путь к уже скачанному gemma-4-12b-it-Q4_K_S.gguf. Подходит Windows-путь вида C:/ollama/models/gemma-4-12b-it-Q4_K_S.gguf или путь внутри WSL. При первом запуске launcher подготавливает CPU-сборку llama.cpp b11125 в .runtime/llama/: если архив отсутствует, скачивает его с GitHub (около 17 МБ) и проверяет SHA-256. Веса модели не скачиваются. Для собственной Linux-сборки задайте LLAMA_SERVER_BINARY; по умолчанию Gemma работает на CPU, оставляя GPU для STT/NeMo.

Launcher проверяет зависимости, CUDA и локальные модели, ждёт готовности Gemma и API. Адрес llama.cpp для API задаётся автоматически через LLAMA_PORT (по умолчанию http://127.0.0.1:8080). Настройка шлюза WSL для связи между этими процессами не требуется. Журналы: results/launcher/llama.log и results/launcher/api.log. Проверка установленного окружения без запуска серверов: start.cmd --check.

start.cmd использует Ubuntu-24.04 и /opt/qorit-nemo/bin/python; другие значения задаются переменными окружения Windows QORIT_WSL_DISTRO и QORIT_PYTHON. Ниже — подготовка окружения и ручной запуск.

Ручной запуск API в готовом окружении

Для уже настроенного распознавания в Ubuntu 24.04 / WSL2, из корня проекта:

/opt/qorit-nemo/bin/python -m pip install -r requirements-server.txt
# Если .env ещё нет:
cp -n .env.example .env

Gemma 4 12B IT Q4_K_S через llama.cpp (local_llama)

Приложение обращается к отдельно запущенному llama-server по /v1/chat/completions. Python не загружает GGUF самостоятельно; llama-cpp-python устанавливать не требуется. Настройки в .env:

LLM_PROVIDER=local_llama
LLAMA_URL=http://127.0.0.1:8080
LLAMA_MODEL=gemma-4-12b-it-Q4_K_S
LLAMA_TIMEOUT=600

Используется локальный файл gemma-4-12b-it-Q4_K_S.gguf. Для ручного запуска из WSL укажите пути к Linux-сборке llama-server и скачанной модели:

/path/to/llama-server -m /mnt/c/ollama/models/gemma-4-12b-it-Q4_K_S.gguf --alias gemma-4-12b-it-Q4_K_S --host 127.0.0.1 --port 8080 --jinja -c 8192 -np 1 -ngl 0

Квантование определяется файлом GGUF, выбранным через -m, а LLAMA_MODEL должен совпадать с --alias. -ngl 0 оставляет модель на CPU; для GPU нужна CUDA-сборка llama.cpp и запас VRAM для STT/NeMo. LLAMA_TIMEOUT задаёт время ожидания одного фрагмента в секундах. Дождитесь ответа {"status":"ok"} на curl http://127.0.0.1:8080/health.

Запуск HTTP API и интерфейса

В другом терминале WSL, из корня проекта:

/opt/qorit-nemo/bin/python server.py

Из PowerShell, находясь в корне проекта:

wsl -d Ubuntu-24.04 -- /opt/qorit-nemo/bin/python server.py

Сервер использует Waitress, по умолчанию слушает 0.0.0.0:8000. HOST и PORT настраиваются в .env. Сервер читает .env, переменные окружения имеют приоритет. Для декодирования нужен FFmpeg, для PDF — DejaVu Sans, Liberation Sans или Arial с русскими и казахскими символами. В Ubuntu:

sudo apt-get install ffmpeg fonts-dejavu-core

API обработки аудио

Все принимают POST multipart/form-data с одинаковыми полями:

Поле	Обязательное	Описание
audio	Да	MP3, WAV, FLAC, OGG, M4A или WebM
meeting_date	Нет	Дата совещания YYYY-MM-DD для слов «завтра», «в пятницу» и т. п. По умолчанию текущая дата, с предупреждением в результате
diarize	Нет	true / false; по умолчанию STT_DIARIZE=true
num_speakers	Нет	Число говорящих от 1 до 100; только при diarize=true

Маршрут	Ответ
/process-audio	application/json
/process-audio-pdf	application/pdf, файл meeting-report.pdf
/process-audio-docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document, файл meeting-report.docx

Примеры PowerShell; используйте именно curl.exe:

curl.exe --fail-with-body -X POST http://localhost:8000/process-audio -F "audio=@media/Совещание №1.mp3" -F "meeting_date=2026-09-23"
curl.exe --fail-with-body -X POST http://localhost:8000/process-audio-pdf -F "audio=@media/Совещание №1.mp3" -F "meeting_date=2026-09-23" -o meeting-report.pdf
curl.exe --fail-with-body -X POST http://localhost:8000/process-audio-docx -F "audio=@media/Совещание №1.mp3" -F "meeting_date=2026-09-23" -o meeting-report.docx

В Linux замените curl.exe на curl. Каждый запрос заново распознаёт и анализирует переданную запись; идентификатора сохранённого отчёта и кэша нет. PDF/DOCX используют ту же схему анализа, что и JSON; они содержат сводку, все поручения с цитатами, предупреждения и полный текст расшифровки. Файлы для скачивания формируются в памяти; временное аудио удаляется после запроса.

Кнопки DOCX и «Печать / PDF» в веб-интерфейсе не вызывают эти два экспортных маршрута: они создают документ из уже полученного и отредактированного протокола в браузере. Для PDF пользователь выбирает «Сохранить как PDF» в диалоге печати. Это сохраняет правки и не запускает повторное распознавание.

Кроме POST-маршрутов, сервер отдаёт GET / и /index.html, фиксированный список CSS/JS-ресурсов и GET /api/config. Последний возвращает только max_upload_bytes, max_audio_seconds, default_diarize. Содержимое .env, адрес/настройки llama.cpp, Python-исходники, модели, записи и результаты через раздачу статических файлов недоступны. /api/config не запускает модели и не является проверкой готовности всего конвейера.

Пример структуры JSON (иллюстрация, не результат реальной записи):

{
  "filename": "meeting.wav",
  "meeting_date": "2026-09-23",
  "as_of": "2026-09-23",
  "timezone": "Asia/Qyzylorda",
  "generated_at": "2026-09-23T10:00:00+00:00",
  "analysis_method": "local_llama:gemma-4-12b-it-Q4_K_S",
  "transcript": {
    "text": "айгуль подготовьте отчет до завтра",
    "segments": [],
    "duration": 3.2
  },
  "tasks": [{
    "id": "task-0001",
    "title": "Подготовить отчёт",
    "assignee": "айгуль",
    "deadline": "2026-09-24",
    "deadline_text": "до завтра",
    "status": "in_progress",
    "urgency": "high",
    "direction": "finance",
    "source_quote": "айгуль подготовьте отчет до завтра",
    "source_speaker": null,
    "needs_review": false
  }],
  "dashboard": {
    "total": 1,
    "by_status": {"in_progress": 1, "overdue": 0, "completed": 0},
    "by_urgency": {"high": 1, "medium": 0, "low": 0},
    "by_direction": {"finance": 1},
    "needs_review": 0
  },
  "warnings": [
    "Статусы отражают расшифровку и дату отчета; последующие изменения не отслеживаются."
  ]
}

transcript сохраняет дополнительные данные STT: words, segments, speakers, speaker_turns и timestamps_approximate, если они доступны.

Правила анализа и дашборд

Локальная Gemma выделяет поручения из русской, казахской и смешанной речи, включая распознавание без пунктуации. Python проверяет JSON и наличие цитат в исходном тексте. Ошибки llama.cpp возвращаются клиенту; демонстрационные результаты или скрытый переход на другой анализатор не используются.

Если модель пропустила целые реплики внутри цитаты, сервер восстанавливает полный непрерывный фрагмент оригинала, только когда все слова совпадают и место цитаты однозначно. Пропуск отдельных слов внутри реплики или выдуманный текст так не исправляются; восстановленные поручения помечаются needs_review=true. Если цитату или срок всё ещё нельзя подтвердить, сервер один раз запрашивает уточнение только этих цитат в пределах фрагмента. Уже проверенные поручения сохраняются, а уточнённые цитаты снова сверяются с расшифровкой. Такие поручения получают needs_review=true. Если подтверждение снова не найдено, API возвращает ошибку, а не выдуманный результат.

• assignee=null, если имя/роль нельзя подтвердить цитатой. Имя сохраняется в форме из записи. SPEAKER_00 — голос, а не личность.
• deadline=null, если срок отсутствует или явно неопределён. Относительные даты считаются от meeting_date. Поддерживаемые календарные выражения перепроверяются кодом; прочие интерпретации модели помечаются needs_review=true.
• completed / «Выполнено» — только при явном сообщении о выполнении в записи. Обещание выполнить, отрицание или частичная готовность не означают выполнение.
• overdue / «Просрочено» — невыполненное поручение со сроком раньше as_of. Срок сегодня ещё не просрочен. Остальные поручения — in_progress / «В работе». Сроки учитываются до календарного дня, не до часа.
• Срочность: high, medium, low. Просроченные и невыполненные задачи со сроком в ближайшие два дня получают high.
• Направления: finance (финансы), legal (юридическое), procurement (закупки), production (производство), safety (безопасность), hr (персонал), it (ИТ), general (прочее).
• dashboard — готовые счётчики для интерфейса, рассчитанные по tasks. Отсутствующие направления не включаются в by_direction. ID поручений действуют только внутри одного отчёта.

Это снимок на дату обработки. API не хранит базу поручений и не отслеживает выполнение после совещания. Для исторических записей передавайте реальную дату. Длинные расшифровки обрабатываются фрагментами с перекрытием: точные повторы убираются, смысловые повторы и связи между удалёнными фрагментами требуют проверки. Качество извлечения зависит от ASR и выбранной модели; needs_review не заменяет проверку протокола человеком.

Интерфейс использует серверные поручения без повторного извлечения правилами. Он сохраняет дату срока, статус, срочность, направление, цитату и метку говорящего. Неизвестный ответственный остаётся неизвестным: автор реплики не назначается исполнителем автоматически. Метки голосов можно вручную сопоставить с именами на вкладке «Участники»; поручения всё равно требуют проверки.

Развёрнутое содержательное саммари backend сейчас не возвращает. Интерфейс показывает фактическую сводку полученного ответа и явно сообщает это ограничение. Кнопка «Разобрать текст по правилам» — отдельный локальный режим без запроса к llama.cpp. Она не является автоматической заменой серверного анализа при ошибке; смена режима заменяет текущий результат после подтверждения.

Фронтенд поддерживает правки, статусы, напоминания в открытой вкладке, добровольное сохранение черновика в браузере и перенос JSON. Это не серверное хранение или фоновая рассылка. API остаётся без CRUD-методов и аутентификации: используйте его внутри доверенной сети; доступ к общей сети должен ограничивать администратор. Для микрофона по LAN нужен HTTPS; HTTP-исключение браузеров для localhost не распространяется на адрес вида http://192.168.x.x:8000.

Ошибки и ограничения ресурсов

Ошибки приложения на всех трёх маршрутах возвращаются как JSON {"error": "..."}. Проверяйте HTTP-статус до сохранения скачанного файла. Отказ до входа в приложение (например, лимит тела запроса в Waitress или reverse proxy) может возвращаться обычным текстом, поэтому клиенту следует проверять также Content-Type.

Код	Причина
400	Нет файла, пустой файл/имя, неверная дата или параметры
413	Превышен размер запроса или длительность аудио
415	Неподдерживаемое расширение
422	Повреждённое/нечитаемое аудио или таймаут декодирования
502	Ошибка llama.cpp, JSON или проверки извлечённых поручений
503	Занят GPU-конвейер, нет FFmpeg, CUDA, моделей или зависимостей STT
500	Внутренняя ошибка обработки/экспорта; детали в журнале сервера

Лимиты в .env.example: MAX_UPLOAD_MB=256, MAX_AUDIO_SECONDS=7200, AUDIO_DECODE_TIMEOUT=300 и LLAMA_TIMEOUT=600 секунд на фрагмент. Часовой пояс статусов задаёт APP_TIMEZONE.

Во фронтенде ожидание ответа ограничено 30 минутами. «Прекратить ожидание» отменяет только клиентский запрос: у API нет остановки уже начатой обработки, сервер может продолжать занимать GPU. Автоматического повторного запроса нет. Ответы API допускают расшифровку до 2 000 000 символов; локальный разбор по правилам — до 200 000. JSON-черновик ограничен 20 МиБ; доступная квота локального хранилища браузера может быть меньше.

Запускайте один процесс сервера на GPU. Запросы распознавания/анализа не выполняются одновременно: второй получает 503 с Retry-After: 30. После ASR сервер освобождает модель и CUDA-кэш. Отдельный llama-server сохраняет модель в памяти между запросами: при использовании GPU оставьте VRAM для STT/NeMo или используйте -ngl 0 для LLM на CPU. Отдельно запущенные процессы STT/llama.cpp не координируются этим lock.

PDF использует встроенный Unicode TTF. Для нестандартной установки задайте REPORT_FONT_PATH и при необходимости REPORT_FONT_BOLD_PATH. DOCX использует то же семейство шрифта, но не встраивает файл шрифта: на компьютере читателя желательно установить этот шрифт.

Настройка распознавания с нуля

STT и NeMo работают на CUDA; CPU-fallback не предусмотрен. Для RTX 5050 requirements.txt использует согласованные torch==2.11.0+cu130 и torchaudio==2.11.0+cu130. Нативный Windows подходит для STT без диаризации; для NeMo используйте Linux/WSL2 и отдельный Linux Python 3.12.

wsl --install -d Ubuntu-24.04
# После первоначальной настройки Ubuntu, из корня проекта:
wsl -d Ubuntu-24.04 -u root -- bash ./setup_nemo_wsl.sh

Скрипт устанавливает зависимости и создаёт /opt/qorit-nemo. Не используйте Windows .venv из WSL. Проверка CUDA:

/opt/qorit-nemo/bin/python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

До автономной работы подготовьте локальные модели:

/opt/qorit-nemo/bin/python prepare_models.py --download
/opt/qorit-nemo/bin/python prepare_models.py --check

prepare_models.py использует публичные NVIDIA NGC / Hugging Face и уже имеющийся HF-кэш; --hf-cache позволяет указать другой кэш. Загрузка идёт во временный файл, архив проверяется, печатается SHA256. Вызовы распознавания ничего не скачивают.

models/
  asr/rukk/model.pt
  asr/rukk/tokens.lst
  diarization/marblenet.nemo
  diarization/titanet_large.nemo

Другой корень задаётся LOCAL_MODELS_DIR и --models-dir у подготовки. Относительные пути считаются от каталога проекта. CLI не читает .env; экспортируйте переменные в оболочке.

/opt/qorit-nemo/bin/python test.py --diarize --output-dir results/nemo
/opt/qorit-nemo/bin/python test.py --diarize --num-speakers 5
/opt/qorit-nemo/bin/python stt_kazakh_russian.py "media/Совещание №1.mp3" --diarize

Без --diarize распознаётся только текст. Python API:

from stt_kazakh_russian import transcribe, transcribe_diarized
text = transcribe("meeting.wav", chunk_seconds=10, overlap_seconds=1)
result = transcribe_diarized("meeting.wav", num_speakers=5)

ASR читает звук окнами, не загружая всю волну в VRAM; контекст по краям уменьшает потери на стыках. При CUDA OOM во время inference окно уменьшается до 1 секунды. OOM при загрузке весов требует освобождения VRAM. Диаризация использует всю запись в RAM. Таймкоды слов приблизительные; метки голосов действуют в пределах одной записи и не определяют имена.

Docker

Dockerfile.nemo сохраняет CLI-режим по умолчанию и включает модули API. Подготовьте образ, локальные модели и llama-server заранее:

docker build -f Dockerfile.nemo -t qorit-nemo .
docker run --rm --gpus all --network none -v "$PWD/models:/app/models:ro" -v "$PWD/media:/app/media:ro" -v "$PWD/results:/app/results" qorit-nemo
# API: llama-server должен быть доступен из контейнера, например на Docker Desktop:
docker run --rm --gpus all -p 8000:8000 --env-file .env -e LLAMA_URL=http://host.docker.internal:8080 -v "$PWD/models:/app/models:ro" qorit-nemo python server.py

В API-режиме не используйте --network none: нужен доступ к локальному llama-server. Для доступа из контейнера llama-server должен слушать доступный интерфейс хоста (например, --host 0.0.0.0 с ограничением доступа в Firewall). Dockerfile.nemo включает Python-модули и HTML/CSS/JS интерфейса. По умолчанию контейнер запускает CLI-диаризацию; переопределение команды на python server.py, как в примере выше, запускает страницу и API вместе. Сборка образа и запуск контейнера в рамках этой доработки не проверялись.

Проверки

Для сквозной проверки запустите start.cmd, дождитесь Ready, затем в другом терминале выполните (из PowerShell добавьте перед Python wsl -d Ubuntu-24.04 --):

/opt/qorit-nemo/bin/python -m pip install requests pypdf
/opt/qorit-nemo/bin/python check_api.py --audio "media/Совещание №1.mp3" --meeting-date 2026-09-23 --output-dir results/api-check

check_api.py отправляет настоящие multipart-запросы последовательно в три маршрута: JSON, PDF и DOCX. Каждый маршрут заново запускает STT/NeMo и Gemma, поэтому на CPU проверка может занять десятки минут. Подмен моделей нет. Результаты сохраняются как meeting-report.json, meeting-report.pdf, meeting-report.docx и transcript.txt; validation.json содержит HTTP-статусы, время, SHA-256 и проверки содержимого. Ошибки сохраняются отдельно в *-error.json; при неуспешной проверке скрипт возвращает код 1. Можно выбрать маршруты через --routes json или --routes pdf docx, а режим без разделения голосов — через --diarize false. Для другого экземпляра API задайте --base-url. Совпадение полного текста в независимых запросах проверяется отдельно: расхождение требует проверки и само по себе не доказывает ошибку экспорта.

Быстрые регрессионные тесты:

# pypdf нужен только для проверки содержимого PDF:
/opt/qorit-nemo/bin/python -m pip install pypdf
/opt/qorit-nemo/bin/python -m unittest discover -s tests -v
node --test tests/*.cjs
node --check app.js

Тесты API/анализа подменяют GPU и ответы llama.cpp, проверяют валидацию, статусы/даты/цитаты, структуру скачанных файлов, UTF-8 и очистку ресурсов. Отдельная проверка FFmpeg декодирует настоящие WAV и WebM. Для оценки качества модели нужен дополнительный запуск на реальных совещаниях. Проверки интерфейса дополнительно покрывают контракт JSON, формирование multipart-запроса, обработку ошибок, локальные черновики и экспорт. Подмены GPU/LLM в тестах не подтверждают качество реального распознавания и извлечения.

Ссылка на Gemma 4 12B Q4_K_S: https://huggingface.co/unsloth/gemma-4-12b-it-GGUF/tree/main